Skip to main content
Use one API to access paid tools, track costs, and manage customer balances. Metered calls accept 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 Node SDK. The reference pages provide 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 spending ceiling.
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 Connection; 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 Connection limits execution to its bound account and tools. Browser tokens authorize only their end user. Locus Pro self-serve accounts connect through MCP OAuth. Server management and widget APIs require Locus Pro Enterprise. Agent-native onboarding has a separate public registration flow.

​
Request conventions

  • Use decimal strings for money. Send "10.00" for an amount, preserving precision.
  • Reuse idempotency keys on retries. Paid calls and transfers require Idempotency-Key. A repeat returns the stored outcome; a changed request with the same key returns 409.
  • Read cost headers. Calls return X-Locus-Credits-Charged and X-Locus-Credits-Balance. Secret-key calls also return X-Locus-Cost-Usd.
  • 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. Accepted streams remain charged if the client later disconnects. See inference and streaming.