Skip to main content
The Locus Pro API is a predictable REST surface. Account setup, management, catalog, balances, top-ups, and end-user operations live under /api/credits/*; metered calls use /api/wrapped/credits/{provider}/{endpoint}. System-managed routes include router/* and locus-travel/*, and enterprise workspaces can add custom-* providers. The pages in this section are generated from the OpenAPI specification and include a live request playground.
Personal accounts use the dashboard and MCP OAuth. They do not receive tenant API keys, publishable keys, end-user tokens, or workspace-management APIs. Secret-key, end-user, widget, and team-management examples in this reference apply to enterprise workspaces.
Naming. The product is Locus Pro; the API keeps the internal credits identifiers: routes (/api/credits/*), key prefixes (lcr_, lcrpk_), and X-Locus-* headers. They’re stable contracts, so integrations don’t churn when the brand does.

​
Base URL

All requests go to:

​
Authentication

Enterprise server endpoints normally authenticate with a secret key as a Bearer token:
For enterprise browser-facing widget endpoints (/api/credits/me/*), the short-lived end-user token is the authorizing credential. You may also send X-Locus-Publishable-Key; when present, that key must belong to the token’s tenant. The published widget packages accept both the publishable key and token as configuration. The secret key never ships to a browser. Personal MCP clients use the server’s browser OAuth flow. Enterprise headless agents can instead use a scoped agent connection (lcac_…) for direct metered calls or service-authenticated MCP. It can call only its bound account and permitted endpoints, and it cannot access broad management routes. Locus returns the full credential only when the connection is created or rotated. Self-serve signup and the first agent-native onboarding steps are public by design. Human signup proves an email or configured external-provider identity before it activates a personal account. Agent-native registration first returns HTTP 202 with account.onboardingState: "identity_required" and an AgentID authorization URL at account.registration.authorizationUrl. After the AgentID browser approval, replay the exact registration request to activate the account and receive its restricted lcac_… compatibility credential. Use that credential for the documented agent-account REST routes and connect tools through MCP OAuth. Follow Account setup or Agent-native onboarding instead of treating these public routes as ordinary management APIs.

​
Conventions

  • Money and credits are decimal strings. Amounts such as usd, baseUsdc, amountUsdc, credits, and agent connection limits are strings, not floats, to preserve precision.
  • Idempotency. Calls and money-moving transfers require a unique Idempotency-Key header; a UUID is the simplest choice. Missing key → 400; the same key with a different body → 409. Retries replay the stored outcome with an Idempotent-Replay: true header, including failed outcomes, which replay as-is without re-executing.
  • Cost in headers. Metered calls return X-Locus-Credits-Charged, X-Locus-Credits-Balance, and (secret-key only) X-Locus-Cost-Usd.
  • Availability is separate from enablement. An unavailable endpoint returns a retryable 503 before dispatch and does not charge.
  • Attribution in a header. Pass X-Locus-Attribution with a JSON object (2 KB max) on any burn to tag the ledger row; filter later with attribution.<key>=<value>. The request body stays exactly upstream-shaped.
  • Non-streaming failures auto-refund. If an upstream provider fails before a successful non-streaming response, the credit reservation is released automatically; retry-safe failures carry X-Locus-Retry-Safe: true. Streaming captures after upstream acceptance and before the first response byte, so a later disconnect or stream failure remains charged. See inference and streaming.

​
Prefer a client?

Node SDK

@withlocus/credits wraps metered calls, discovery, balances, funding, ledger reads, and agent connections.

Connect an agent

Create a scoped connection and add it to an MCP client.

Framework integrations

Connect model SDKs and agent frameworks to Locus Pro.