API Reference

Complete HTTP API documentation for the Amorce orchestrator.

Base URL

Standalone Mode: http://localhost:8080

Cloud Mode: https://your-orchestrator.run.app

Authentication

API Key (Optional in Standalone, Required in Cloud)

X-API-Key: sk-atp-your-orchestrator-key

Agent Signature (Always Required)

X-Agent-Signature: <base64-encoded-ed25519-signature>

Agent-to-Agent Transaction

Execute a secure transaction between two agents.

Headers

• Content-Type: application/json
• X-API-Key: sk-atp-... (cloud mode only)
• X-Agent-Signature: <signature> (required)

Request Body

{
  "consumer_agent_id": "agent-001",
  "service_id": "srv-greet",
  "payload": {
    "name": "Alice"
  },
  "transaction_id": "tx_123"
}

Response (Success)

{
  "transaction_id": "tx_123",
  "status": "success",
  "timestamp": "2025-12-05T17:00:00Z",
  "result": {
    "message": "Hello, Alice!"
  }
}

Response (Error)

{
  "transaction_id": "tx_123",
  "status": "error",
  "error": "Invalid signature",
  "timestamp": "2025-12-05T17:00:00Z"
}

Status Codes

Health Check

Check orchestrator health and status.

Response

{
  "status": "healthy",
  "mode": "standalone",
  "version": "1.0.0",
  "uptime_seconds": 3600
}

Human-in-the-Loop (HITL)

Create Approval Request

Request Body

{
  "approval_id": "apr_custom_id",
  "transaction_id": "tx_123",
  "summary": "Book restaurant for 4 guests at Le Petit Bistro",
  "details": {
    "restaurant": "Le Petit Bistro",
    "guests": 4,
    "date": "2025-12-05",
    "time": "19:00"
  },
  "timeout_seconds": 300
}

Response

{
  "approval_id": "apr_custom_id",
  "status": "pending",
  "created_at": "2025-12-02T17:00:00Z",
  "expires_at": "2025-12-02T17:05:00Z"
}

Get Approval Status

Response

{
  "approval_id": "apr_custom_id",
  "transaction_id": "tx_123",
  "status": "approved",
  "summary": "Book restaurant for 4 guests",
  "details": {...},
  "decision": "approve",
  "approved_by": "user@example.com",
  "approved_at": "2025-12-02T17:02:00Z",
  "comments": "Looks good"
}

Status values: pending, approved, rejected, expired

Submit Approval Decision

Request Body

{
  "decision": "approve",
  "approved_by": "user@example.com",
  "comments": "Approved for business lunch"
}

Response

{
  "approval_id": "apr_custom_id",
  "status": "approved",
  "approved_at": "2025-12-02T17:02:00Z"
}

Error Responses

All error responses follow this format:

{
  "error": "Error description",
  "code": "ERROR_CODE",
  "details": {...}
}

Common Error Codes

Rate Limiting

Response Headers

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1638360000

Limits (Cloud Mode)

• Per Agent: 20 requests/minute
• Burst: 5 requests/second
• Retry-After: Included in 429 response

SDK Usage

Python

from amorce import AmorceClient, IdentityManager

identity = IdentityManager.load_from_pem_file("./agent_private.pem")

client = AmorceClient(
    identity=identity,
    orchestrator_url="http://localhost:8080",
    agent_id="agent-001"
)

# Transaction
result = client.transact(
    service={"service_id": "srv-greet"},
    payload={"name": "Alice"}
)

# HITL approval
approval = client.request_approval(
    summary="Book restaurant",
    details={...},
    timeout_seconds=300
)

status = client.wait_for_approval(approval["approval_id"])

JavaScript

const { AmorceClient, IdentityManager } = require('@amorce/sdk');

const identity = IdentityManager.loadFromPemFile('./agent_private.pem');

const client = new AmorceClient({
  identity,
  orchestratorUrl: 'http://localhost:8080',
  agentId: 'agent-001'
});

// Transaction
const result = await client.transact({
  serviceId: 'srv-greet',
  payload: { name: 'Alice' }
});

// HITL approval
const approval = await client.requestApproval({
  summary: 'Book restaurant',
  details: {...},
  timeoutSeconds: 300
});

const status = await client.waitForApproval(approval.approvalId);