SynapseDocumentation

Invoke a service

Invoke a service in one HTTP call. For fixed-price APIs, pass costUsdc — the price the agent saw in discovery. For serviceKind=llm / priceModel=token_metered, omit costUsdc and optionally pass maxCostUsdc; Gateway pre-authorizes, captures final Provider usage, and releases the rest.

POST/api/v1/agent/invokeAgent credentialIdempotent

For AI agents

Preferred invoke path. Fixed APIs use costUsdc price assertion. LLM services use token-metered pre-authorization and final usage billing.

Requires: Agent credential + serviceId from discovery

Next: On PRICE_MISMATCH (fixed APIs): re-call discover() and retry. On LLM usage/streaming errors, do not retry as a charged call until the Provider returns final usage.

Generated OpenAPI reference

POST/api/v1/agent/invoke

Authorization

agentCredential
X-Synapse-Agent-Credential<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

[key: string]?any

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://api-staging.synapse-network.ai/api/v1/agent/invoke" \  -H "Content-Type: application/json" \  -d '{    "serviceId": "svc_deepseek_chat",    "idempotencyKey": "job-001",    "maxCostUsdc": "0.010000",    "payload": {      "body": {        "model": "deepseek-chat",        "messages": [          {            "role": "user",            "content": "hello"          }        ],        "max_tokens": 512      }    }  }'
{
  "invocationId": "inv_abc",
  "status": "SUCCEEDED",
  "chargedUsdc": "0.000253",
  "usage": {
    "inputTokens": 1200,
    "outputTokens": 300,
    "totalTokens": 1500
  },
  "synapse": {
    "priceModel": "token_metered",
    "holdUsdc": "0.001000",
    "chargedUsdc": "0.000253",
    "releasedUsdc": "0.000747",
    "preAuthMode": "explicit"
  },
  "result": {
    "answer": "..."
  }
}
{
  "code": "LLM_AUTO_HOLD_LIMIT_EXCEEDED",
  "message": "Automatic hold exceeds service cap; pass maxCostUsdc explicitly"
}
{
  "code": "BUDGET_EXHAUSTED",
  "message": "Credential budget does not allow this invocation"
}
{
  "code": "SERVICE_NOT_FOUND",
  "message": "Service is not active"
}
{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "Idempotency key reused with different payload"
}
{
  "code": "PRICE_MISMATCH",
  "message": "Service price changed since discovery — re-discover and retry"
}
{
  "code": "UPSTREAM_ERROR",
  "message": "Provider service returned an error"
}
Back to API Reference