Skip to main content
Use one API to call paid tools, track costs, and manage customer balances. Metered calls take the provider’s request body and return its response, with the charge and remaining balance. For a first integration, start with the Enterprise quickstart or the Node SDK. The reference pages have request schemas, responses, and a live playground.

​
Base URL

API origin

​
Find and call a tool

1

Search

Call POST /api/credits/tools/search with a task, category, or Tool Pack.
2

Describe

Send the selected slug to POST /api/credits/tools/describe for its current inputs and access requirements.
3

Estimate when needed

Call POST /api/credits/tools/estimate for a quote, or send X-Locus-Max-Charge-Credits on the call to cap its charge.
4

Execute

Call POST /api/wrapped/credits/{provider}/{endpoint}. Reuse the same idempotency key for retries.
Search can include tools that need access approval. Discovery does not enable a tool or grant permission to call it.

​
Recipes and Workflows

Use each Recipe’s current input schema and credit ceiling. Workflow REST calls use an enterprise server key or scoped agent key; OAuth agents use MCP.

​
Agent setup

GET /api/credits/mcp/docs returns the MCP URL, OAuth metadata, plugin installation commands, and client configurations. The plugin uses the same MCP connection and permissions.

​
Authentication

Server credentials use a bearer header:
Authorization header
Keep secret keys on your server. An agent key limits execution to its bound account and tools. Browser tokens authorize only their end user. Locus Pro self-serve accounts connect through MCP OAuth, and can also create a secret key or an agent key for their own code. Team management, webhooks, custom APIs, and the widget require Locus Pro Enterprise. Agent-native onboarding has a separate public registration flow.

​
Request conventions

  • Use decimal strings for money. Send amounts like "10.00" to keep precision.
  • Reuse idempotency keys on retries. Paid calls and transfers require Idempotency-Key. A repeat returns the stored outcome, including a failed one, with Idempotent-Replay: true; a changed request with the same key returns 409. Locus keeps a key for 24 hours after its call finishes; after that, the same key starts a new call.
  • Read cost headers. Calls return X-Locus-Credits-Charged and X-Locus-Credits-Balance. Secret keys, sandbox keys, and platform-mode agent keys also receive X-Locus-Cost-Usd.
  • Keep the call ID. Metered calls return X-Locus-Api-Call-Id, and provider error bodies repeat it as apiCallId. Read the call later with GET /api/wrapped/credits/calls/{callId}.
  • Cap a charge. Send X-Locus-Max-Charge-Credits. If the call would cost more, Locus returns 409 with code charge_ceiling_exceeded and sends nothing to the provider.
  • Run long calls asynchronously. Send Prefer: respond-async on a non-streaming call. Once the provider request is out, Locus returns 202 with apiCallId, statusUrl, and resultUrl. Read the outcome with POST /api/wrapped/credits/calls/{callId}/result and { "waitSeconds": 0-45 }. Result reads are free.
  • Tag usage. Send X-Locus-Attribution as a JSON object to associate ledger entries with a customer, task, or project.
Non-streaming failures before success release the credit reservation. A provider error includes providerError.code when the provider sent one. Locus Pro routes send a provider 502 or 504 as 503, with the original status in X-Locus-Origin-Status, so the JSON error body reaches you. Chat is charged from the provider’s reported usage. A stream is charged when it ends and closes with a locus.billing event; a disconnect after the provider accepts the stream is charged the full hold. Streams are not replayed: reusing the key returns 409 with code stream_not_replayable. See inference and streaming.