# Locus Docs

- [Locus Pro](https://docs.paywithlocus.com/index.md): One prepaid balance for 3,811 catalog services exposing 15,977 pay-per-use endpoints.
- [Account setup and sign-in](https://docs.paywithlocus.com/locus-pro/account-setup.md): Create a personal Locus Pro account, join an enterprise workspace, recover interrupted setup, and manage sign-in methods.
- [Quickstart](https://docs.paywithlocus.com/locus-pro/quickstart.md): Connect a personal agent with OAuth or make an enterprise metered API call.
- [Authentication and scopes](https://docs.paywithlocus.com/locus-pro/authentication-and-scopes.md): Choose the right Locus Pro credential, preflight its effective access, and handle authorization failures safely.
- [Credits & pricing](https://docs.paywithlocus.com/locus-pro/credits-and-pricing.md): Credit denomination, markup, and the exact charge math, with worked examples.
- [Funding & billing](https://docs.paywithlocus.com/locus-pro/funding-and-billing.md): Fund a Personal balance or manage enterprise wholesale credits, end-user top-ups, payout destinations, refunds, and ledger activity.
- [Commercial plans](https://docs.paywithlocus.com/locus-pro/commercial-plans.md): How personal connection plans, evaluations, contracted credit subscriptions, and enterprise agreements differ.
- [Activity and analytics](https://docs.paywithlocus.com/locus-pro/activity-and-analytics.md): Understand personal tool usage and enterprise workspace spend, transactions, margin, and attribution.
- [The catalog](https://docs.paywithlocus.com/locus-pro/catalog.md): Enable pay-per-use tools for personal agents or configure enterprise catalog access and markup.
- [Custom APIs](https://docs.paywithlocus.com/locus-pro/custom-apis.md): Expose your own HTTP services through the Locus catalog, MCP discovery, policy, and billing paths.
- [Capability routing](https://docs.paywithlocus.com/locus-pro/capability-routing.md): Search, research, or compare flights across providers through one metered Locus Pro request.
- [API directory](https://docs.paywithlocus.com/locus-pro/catalog-directory.md): The Locus Pro catalog: 3,811 services exposing 15,977 endpoints across Locus, partner, Parse, MPP, and x402 sources.
- [Parse API directory](https://docs.paywithlocus.com/locus-pro/parse-directory.md): All 3,290 Parse API listings and 15,204 endpoints available through Locus Pro, grouped by category.
- [Agent-native onboarding](https://docs.paywithlocus.com/locus-pro/agent-native-onboarding.md): Verify an agent through AgentID, activate a restricted Locus Pro account, fund it, and connect through MCP OAuth.
- [Locus CLI](https://docs.paywithlocus.com/locus-pro/cli.md): Install the official Locus CLI, authenticate, and call Locus Pro from a terminal or agent runtime.
- [Connect an agent](https://docs.paywithlocus.com/locus-pro/connect-agents.md): Use OAuth for an interactive MCP client or a scoped service credential for an unattended enterprise agent.
- [Framework integrations](https://docs.paywithlocus.com/locus-pro/frameworks.md): Connect Locus Pro to model SDKs, agent frameworks, coding clients, or a custom MCP runtime from one guide.
- [Widget](https://docs.paywithlocus.com/locus-pro/widget.md): Embed an end-user balance, transaction history, and top-up button in a few lines, as a React component or a plain script tag.
- [SDK reference](https://docs.paywithlocus.com/locus-pro/sdk.md): @withlocus/credits, the Node server SDK for metered calls, discovery, funding, balances, and agent connections.
- [Model inference](https://docs.paywithlocus.com/locus-pro/inference.md): Call model providers through Locus Pro with exact metering, streaming, idempotency, and scoped agent access.
- [Sandbox keys](https://docs.paywithlocus.com/locus-pro/sandbox.md): Test direct-call authentication, validation, idempotency, and billing headers without moving credits or calling providers.
- [Clean up enterprise integration tests](https://docs.paywithlocus.com/locus-pro/clean-up-integration-tests.md): Reset end-user policies and retire Locus Pro test identities without deleting financial history.
- [API reference](https://docs.paywithlocus.com/api-reference/introduction.md): The public Locus Pro HTTP API: documented endpoints, requests, and responses.
- [Validate an evaluation invitation](https://docs.paywithlocus.com/api-reference/tenants/validate-an-evaluation-invitation.md): Returns only the company, masked email, expiry and safe invitation state. The raw token is never returned or logged.
- [Create an evaluation account from a private invitation](https://docs.paywithlocus.com/api-reference/tenants/create-an-evaluation-account-from-a-private-invitation.md): Creates the exact invited Cognito identity and atomically provisions one evaluation tenant and exactly $25 promotional credit. Existing identities must authenticate instead; this token is never a password-reset credential.
- [Accept an invitation as the matching signed-in identity](https://docs.paywithlocus.com/api-reference/tenants/accept-an-invitation-as-the-matching-signed-in-identity.md): The live Cognito email must exactly match the invited email. Successful acceptance selects the returned tenant with X-Locus-Tenant-Id.
- [Read the platform or end-user balance](https://docs.paywithlocus.com/api-reference/tenants/read-the-platform-or-end-user-balance.md): Returns the authenticated tenant's platform balance. Send X-Locus-End-User to read one end-user balance instead. Amounts are exact decimal strings in USD and the tenant's credit denomination.
- [Get tenant profile](https://docs.paywithlocus.com/api-reference/tenants/get-tenant-profile.md)
- [Update tenant settings](https://docs.paywithlocus.com/api-reference/tenants/update-tenant-settings.md): Workspace owner/admin sessions and secret keys with tenant:write may update webhookUrl or feeMode. A new webhookUrl is queued for an isolated ownership challenge; the previously verified URL remains active until that challenge succeeds. Requests containing marginPayoutAddress or payoutMethod require…
- [Update tenant profile](https://docs.paywithlocus.com/api-reference/tenants/update-tenant-profile.md): Workspace owner/admin session or a secret key with tenant:write. Unknown fields are rejected atomically; recognized fields are never applied from a mixed known/unknown request. creditsPerDollar is immutable after provisioning and is rejected if supplied.
- [List API-key metadata and immutable execution policies](https://docs.paywithlocus.com/api-reference/tenants/list-api-key-metadata-and-immutable-execution-policies.md): Raw keys and hashes are never returned; every caller sees lifecycle metadata including createdBy (issuer subject). Dashboard (Cognito) sessions additionally receive createdByEmail (workspace member email when the issuer is still a member) and usage (current-UTC-month burn attribution: monthUsdc, mon…
- [Issue an independently scoped API key](https://docs.paywithlocus.com/api-reference/tenants/issue-an-independently-scoped-api-key.md): Creates an overlapping named credential. Requires the workspace owner with credentials:manage and MFA or passkey step-up completed in the last ten minutes. tools.enable narrows the tenant-enabled catalog for this key; pricing applies only to end-user calls and never widens tenant enablement. kind 's…
- [Rotate every active key of a kind (cutover)](https://docs.paywithlocus.com/api-reference/tenants/rotate-every-active-key-of-a-kind-cutover.md): Creates ONE replacement and supersedes ALL other active keys of that kind. Requires the workspace owner with credentials:manage and MFA or passkey step-up completed in the last ten minutes. For rotating a single key while its siblings keep working, use POST /credits/tenants/me/keys/{keyId}/rotate.
- [Read account spend and balance controls](https://docs.paywithlocus.com/api-reference/tenants/read-account-spend-and-balance-controls.md): The account's monthly spend ceiling, spend-email threshold, low-balance threshold, and live position in the current UTC calendar-month window. Available to Personal and enterprise accounts. Read this before raising a limit: committedUsd, not spentUsd, is the figure enforced against the ceiling.
- [Set or clear account spend and balance controls](https://docs.paywithlocus.com/api-reference/tenants/set-or-clear-account-spend-and-balance-controls.md): Sets the monthly hard ceiling, monthly spend-email threshold, and/or low-balance email threshold. Send at least one field; omitted fields keep their current value and an explicit null clears one. Amounts are positive USD with at most 6 decimal places, up to 1000000000, and alertThresholdUsd may not…
- [Revoke an API key](https://docs.paywithlocus.com/api-reference/tenants/revoke-an-api-key.md): Revokes one key immediately; it returns 401 on the next request. Use this as the final step of a rotation, after the new credential is confirmed working. Requires the workspace owner with MFA step-up completed in the last ten minutes.
- [Rename an API key](https://docs.paywithlocus.com/api-reference/tenants/rename-an-api-key.md): Metadata-only: the credential itself never changes. Appends a RENAMED credential audit event carrying the previous name. Requires the workspace owner with MFA step-up completed in the last ten minutes.
- [Credential lifecycle audit](https://docs.paywithlocus.com/api-reference/tenants/credential-lifecycle-audit.md): Issue, rotate, and revoke events for API keys, agent connections, end-user tokens, and webhook secrets, newest first. Raw credentials and key hashes are never returned.
- [Sensitive-mutation security audit](https://docs.paywithlocus.com/api-reference/tenants/sensitive-mutation-security-audit.md): Append-only record of sensitive workspace mutations with actor, auth method, request id, source IP, outcome, and before/after state. Written before the success response, so a failed audit write fails the mutation. Newest first.
- [Rotate ONE key; sibling keys of the same kind keep working](https://docs.paywithlocus.com/api-reference/tenants/rotate-one-key;-sibling-keys-of-the-same-kind-keep-working.md): The replacement inherits the target's name, scopes, endpoint allowlist, pricing, audience (legacy policy-bearing rows are normalized to the execution audience), and — unless expiresIn is passed — its expiry deadline. Only the target is superseded: with gracePeriodSeconds > 0 it keeps authenticating…
- [Resume interrupted self-serve workspace provisioning](https://docs.paywithlocus.com/api-reference/tenants/resume-interrupted-self-serve-workspace-provisioning.md): Recovery-only companion for a verified, authenticated Cognito identity. The token subject is the durable idempotency key: repeated calls return the same zero-credit workspace and cannot create another one.
- [Validate a workspace invitation](https://docs.paywithlocus.com/api-reference/workspace-members/validate-a-workspace-invitation.md): Returns a masked-email preview for a single-use invitation token. The token is read from the email URL fragment and submitted in JSON so it does not enter normal access logs or referrers.
- [Create the invited identity and join its workspace](https://docs.paywithlocus.com/api-reference/workspace-members/create-the-invited-identity-and-join-its-workspace.md): Creates an account only for the exact invited email and joins the existing workspace. This is not a public account-creation surface. Existing identities must use the authenticated acceptance route.
- [Join a workspace as the matching signed-in identity](https://docs.paywithlocus.com/api-reference/workspace-members/join-a-workspace-as-the-matching-signed-in-identity.md): The live Cognito email must exactly match the invited email. The response identifies the workspace to select with X-Locus-Tenant-Id.
- [List the signed-in person's workspace memberships](https://docs.paywithlocus.com/api-reference/workspace-members/list-the-signed-in-persons-workspace-memberships.md): This discovery route does not require X-Locus-Tenant-Id. Use the selected tenantId as that header on subsequent dashboard management calls when the person belongs to multiple workspaces.
- [List workspace members and pending invitations](https://docs.paywithlocus.com/api-reference/workspace-members/list-workspace-members-and-pending-invitations.md): Human Cognito sessions only. Tenant API keys cannot enumerate workspace member email addresses.
- [Invite people to a workspace](https://docs.paywithlocus.com/api-reference/workspace-members/invite-people-to-a-workspace.md): Requires owner membership, members:manage, and MFA or passkey step-up within the last ten minutes. Accepts at most 20 unique normalized email addresses.
- [Rotate and resend a pending workspace invitation](https://docs.paywithlocus.com/api-reference/workspace-members/rotate-and-resend-a-pending-workspace-invitation.md): Requires owner membership, members:manage, and recent MFA or passkey step-up. Rotating the token invalidates the previous email link.
- [Revoke a workspace invitation](https://docs.paywithlocus.com/api-reference/workspace-members/revoke-a-workspace-invitation.md): Requires owner membership, members:manage, and recent MFA or passkey step-up.
- [Remove a workspace member](https://docs.paywithlocus.com/api-reference/workspace-members/remove-a-workspace-member.md): Requires owner membership, members:manage, and recent MFA or passkey step-up. The original owner cannot be removed and a member cannot remove their own current membership.
- [Change a workspace member role](https://docs.paywithlocus.com/api-reference/workspace-members/change-a-workspace-member-role.md): Requires owner membership, members:manage, and recent MFA or passkey step-up. The original owner cannot be reassigned.
- [Inspect the current management credential](https://docs.paywithlocus.com/api-reference/authentication/inspect-the-current-management-credential.md): Returns only the authenticated credential kind, tenant, role, effective scopes, and current step-up state. It never returns raw keys, hashes, JWT claims, or secrets. Call this before attempting a scoped management operation.
- [List scoped Agent Connections](https://docs.paywithlocus.com/api-reference/authentication/list-scoped-agent-connections.md)
- [Create a scoped Agent Connection](https://docs.paywithlocus.com/api-reference/authentication/create-a-scoped-agent-connection.md): Creates a short-lived, least-privilege lcac_ credential for MCP and wrapped execution. A secret key may automate this route only when its stored scopes include credentials:manage. Human callers must be the workspace owner with fresh MFA/passkey step-up.
- [Read one scoped Agent Connection](https://docs.paywithlocus.com/api-reference/authentication/read-one-scoped-agent-connection.md)
- [Rotate a scoped Agent Connection credential](https://docs.paywithlocus.com/api-reference/authentication/rotate-a-scoped-agent-connection-credential.md): Immediately invalidates the prior lcac_ credential and returns its replacement once. A scoped secret key may automate this Agent Connection operation; human callers require owner step-up.
- [Revoke a scoped Agent Connection credential](https://docs.paywithlocus.com/api-reference/authentication/revoke-a-scoped-agent-connection-credential.md): Idempotently revokes the lcac_ credential. A scoped secret key may automate this Agent Connection operation; human callers require owner step-up.
- [Start a self-serve Locus Pro account](https://docs.paywithlocus.com/api-reference/authentication/start-a-self-serve-locus-pro-account.md): Creates an unconfirmed Cognito identity and sends a 6-digit email code. It does not provision a workspace or grant credits. Passwords require 8–256 characters with uppercase, lowercase, and numeric characters.
- [Verify email and create the self-serve workspace](https://docs.paywithlocus.com/api-reference/authentication/verify-email-and-create-the-self-serve-workspace.md): Confirms the email, proves knowledge of the chosen password, and atomically provisions one owner workspace tied to the Cognito subject. Replays return that same workspace. The workspace starts with exactly $0 and receives no free or promotional credits.
- [Resend a signup verification code](https://docs.paywithlocus.com/api-reference/authentication/resend-a-signup-verification-code.md): Always returns the same success shape for a syntactically valid email, whether or not an unconfirmed identity exists.
- [Read the latest webhook ownership challenge](https://docs.paywithlocus.com/api-reference/webhooks/read-the-latest-webhook-ownership-challenge.md): Polling this endpoint never reveals or consumes the webhook signing secret.
- [Reveal the first verified webhook signing secret once](https://docs.paywithlocus.com/api-reference/webhooks/reveal-the-first-verified-webhook-signing-secret-once.md): Workspace owner and MFA/passkey step-up protected. Status polling cannot consume this reveal. If it was already revealed, rotate the secret instead.
- [Rotate the webhook signing secret](https://docs.paywithlocus.com/api-reference/webhooks/rotate-the-webhook-signing-secret.md): Returns the new secret once. Requires the workspace owner with credentials:manage and MFA or passkey step-up completed in the last ten minutes. Deliveries contain signatures for both the current and previous secrets during a 24-hour overlap.
- [List durable webhook events](https://docs.paywithlocus.com/api-reference/webhooks/list-durable-webhook-events.md)
- [Inspect an event and every delivery attempt](https://docs.paywithlocus.com/api-reference/webhooks/inspect-an-event-and-every-delivery-attempt.md)
- [Replay a retained event](https://docs.paywithlocus.com/api-reference/webhooks/replay-a-retained-event.md): Creates one new attempt using the same stable event ID and current endpoint. Returns 409 while another attempt is pending.
- [Configure automatic balance reload](https://docs.paywithlocus.com/api-reference/top-ups/configure-automatic-balance-reload.md): Charges the saved card when the account's prepaid balance falls below thresholdUsd and credits amountUsd. Both fields must be positive and supplied together; send both as null to disable. Personal accounts call this auto-reload and require the account owner on a session authenticated within the last…
- [Quote a top-up (exact-decimal gross-up)](https://docs.paywithlocus.com/api-reference/top-ups/quote-a-top-up-exact-decimal-gross-up.md): Send exactly one exact decimal string: usd or credits. Numeric compatibility values are deprecated. Declare externalUserId when the eventual create targets an end user so the bonus fields match the create.
- [Get machine-readable top-up constraints](https://docs.paywithlocus.com/api-reference/top-ups/get-machine-readable-top-up-constraints.md)
- [Create a hosted checkout session](https://docs.paywithlocus.com/api-reference/top-ups/create-a-hosted-checkout-session.md): Canonical v2 contract. externalUserId present → end-user top-up. Absent → platform-pool self-top-up. Send exactly one exact-decimal usd or credits amount. There is no fixed or daily platform top-up ceiling. Evaluation funding does not activate a commercial agreement.
- [Get authoritative checkout state](https://docs.paywithlocus.com/api-reference/top-ups/get-authoritative-checkout-state.md)
- [Top-up and Stripe ingress health](https://docs.paywithlocus.com/api-reference/top-ups/top-up-and-stripe-ingress-health.md): Operational health for this workspace's card funding: signed-webhook inbox state and recent top-up activity. Use it to tell a stuck top-up apart from a delivery backlog.
- [List the account's payment history](https://docs.paywithlocus.com/api-reference/top-ups/list-the-accounts-payment-history.md): Returns only TOPUP ledger entries for the account's pooled balance, newest first. Available to Personal and enterprise accounts. Manual top-ups and automatic reloads are distinguished by entry metadata; this narrow history does not expose provider charges, end-user rows, or margin data.
- [List catalog with your effective prices](https://docs.paywithlocus.com/api-reference/catalog/list-catalog-with-your-effective-prices.md): Use the default view=compact for normal enterprise catalog browsing. Compact responses omit executable JSON Schemas and model inventories, page providers, carry a version/ETag, and are gzip-compressed when the client advertises gzip. view=dashboard is the Locus Pro dashboard projection; its first pa…
- [Set the workspace default markup](https://docs.paywithlocus.com/api-reference/catalog/set-the-workspace-default-markup.md): Sets the tenant-wide default percentage and flat markup applied to every endpoint that has no provider or endpoint override. This is the base of the three-level precedence endpoint over provider over global that GET /credits/pricing/explain reports as markupSource. Send either field alone to change…
- [Enable or disable a bounded provider batch](https://docs.paywithlocus.com/api-reference/catalog/enable-or-disable-a-bounded-provider-batch.md): Creates or updates up to 50 provider-level enablement rows in one transaction, and resets those providers' endpoint-level enablement overrides to inherit so the value you send is the whole answer for every endpoint of every named provider. Endpoint-level MARKUP overrides are preserved. Clients split…
- [Read the reviewed inference model contract](https://docs.paywithlocus.com/api-reference/catalog/read-the-reviewed-inference-model-contract.md): Returns Locus-supported model IDs, exact pricing dimensions, limits, route capabilities, request-field compatibility, deprecation state, and freshness metadata. This is a reviewed support boundary, not a pass-through of the provider's account-scoped model list.
- [Get one full provider catalog document](https://docs.paywithlocus.com/api-reference/catalog/get-one-full-provider-catalog-document.md): Fetches executable endpoint schemas and the reviewed model inventory only for the selected provider. For this operation, slug must be one provider ID. Use after the compact list, not as a polling endpoint.
- [Enable/disable or override markup](https://docs.paywithlocus.com/api-reference/catalog/enabledisable-or-override-markup.md): slug is `provider` (whole provider) or `provider/endpoint` (URL-encoded). Personal accounts must send exactly `{"enabled": boolean}` and receive only endpointSlug plus effective enabled state; markup fields and extra properties are rejected. Enterprise workspaces may update enablement and/or markup.…
- [Clear a catalog override](https://docs.paywithlocus.com/api-reference/catalog/clear-a-catalog-override.md): Removes a provider or endpoint override so pricing falls back to the next level up, ending at the workspace default. slug is provider (whole provider) or provider/endpoint (URL-encoded), the same forms PUT accepts. Idempotent: clearing something that has no override succeeds and reports cleared: fal…
- [Explain one endpoint's price](https://docs.paywithlocus.com/api-reference/catalog/explain-one-endpoints-price.md): Breaks one endpoint's price into base cost, percentage markup, flat markup, your margin, and the customer-visible effective price, and names which configuration level supplied each markup. Endpoints priced live per call return the honest variable shape with null money fields rather than a fabricated…
- [Search enabled executable tools](https://docs.paywithlocus.com/api-reference/catalog/search-enabled-executable-tools.md): REST counterpart to MCP search_apis. Searches only enabled tools in the authenticated principal's live, tenant-filtered catalog and returns compact execution contracts. Results honor tenant enablement, key endpoint allowlists, agent-connection scopes, and end-user policies. Use POST /credits/catalog…
- [Search the management catalog](https://docs.paywithlocus.com/api-reference/catalog/search-the-management-catalog.md): Searches the built-in account-visible management catalog, including endpoints that are currently disabled. Enterprise-owned Custom APIs remain available through the catalog listing and detail routes but are not included in this static search index. Returns price-free display metadata, desired enable…
- [Tenant usage analytics](https://docs.paywithlocus.com/api-reference/ledger/tenant-usage-analytics.md): Exact database rollups over captured BURN debits. Accepts either the legacy days=7|30|90 form or an explicit half-open from/to window, optionally bucketed and narrowed to one spender and/or one provider. The prior comparison covers the same elapsed span as the current period, including today's parti…
- [Tenant-wide ledger](https://docs.paywithlocus.com/api-reference/ledger/tenant-wide-ledger.md)
- [Margin earnings](https://docs.paywithlocus.com/api-reference/ledger/margin-earnings.md)
- [Commercial agreement and invoice history](https://docs.paywithlocus.com/api-reference/ledger/commercial-agreement-and-invoice-history.md): Read-only view of an activated enterprise agreement, the live estimate for the current period, and issued invoice history. Workspaces without a commercial agreement get the empty shape rather than an error.
- [Stripe Connect status for payouts](https://docs.paywithlocus.com/api-reference/ledger/stripe-connect-status-for-payouts.md): Whether this workspace is linked to a Stripe account for margin payouts, and whether Stripe currently permits payouts on it. Check this before switching payoutMethod to stripe.
- [Begin Stripe Connect onboarding](https://docs.paywithlocus.com/api-reference/ledger/begin-stripe-connect-onboarding.md): Returns the Stripe consent URL to send the workspace owner to. Dashboard-only: a tenant secret key cannot start this flow, and evaluation workspaces are refused until a commercial agreement is active. Requires the workspace owner with MFA step-up completed in the last ten minutes.
- [Stripe Connect OAuth redirect target](https://docs.paywithlocus.com/api-reference/ledger/stripe-connect-oauth-redirect-target.md): Stripe redirects the browser here after consent. Authorization comes from the signed state parameter rather than an Authorization header, so this route is deliberately public — do not call it yourself. It always answers with a 302 back to the dashboard, carrying connected=1 on success or connect_err…
- [Disconnect Stripe and revert to USDC payouts](https://docs.paywithlocus.com/api-reference/ledger/disconnect-stripe-and-revert-to-usdc-payouts.md): Unlinks the Stripe account and returns the workspace to USDC margin payouts. Dashboard-only, and requires the workspace owner with MFA step-up completed in the last ten minutes.
- [Ledger row counts for a filter](https://docs.paywithlocus.com/api-reference/ledger/ledger-row-counts-for-a-filter.md): Counts the rows GET /credits/ledger would page through under the same filters. Cursor pagination can report neither a total nor a per-category split, which the Activity pager and its type chips need.
- [List end-users with balances](https://docs.paywithlocus.com/api-reference/end-users/list-end-users-with-balances.md)
- [Retire a test or integration end user without deleting financial history](https://docs.paywithlocus.com/api-reference/end-users/retire-a-test-or-integration-end-user-without-deleting-financial-history.md): Workspace owner with fresh MFA/passkey step-up only. Fails closed unless the balance is zero and every reservation, top-up attempt, external purchase, and refund is terminal. Revokes end-user tokens and scoped agent credentials, cancels outstanding approvals, resets the operational policy, freezes t…
- [Mint an end-user token](https://docs.paywithlocus.com/api-reference/end-users/mint-an-end-user-token.md): Mint server-side only. Creates the tenant-scoped end-user record and credit account on first use. JWT claims are sub, tid, iss=locus-credits, aud=locus-credits-enduser, iat, exp, jti, and optional sid. The sid claim is a SHA-256 fingerprint, not the raw session value. Verification allows 30 seconds…
- [Read an immutable end user's execution policy](https://docs.paywithlocus.com/api-reference/end-users/read-an-immutable-end-users-execution-policy.md)
- [Create or replace an end user's execution policy](https://docs.paywithlocus.com/api-reference/end-users/create-or-replace-an-end-users-execution-policy.md): Workspace owner/admin session or a secret key with tokens:manage. Admission, counters, the credit hold, and the reservation commit atomically. Amounts use the tenant's exact credit denomination.
- [Reset an end user's execution policy to no policy](https://docs.paywithlocus.com/api-reference/end-users/reset-an-end-users-execution-policy-to-no-policy.md): Workspace owner/admin session or a secret key with tokens:manage. Deletes operational policy counters only after all live reservations have captured or released. The append-only policy decision journal remains queryable by account. Repeating a completed reset is safe and returns reset=false.
- [List policy allow, deny, capture, release, and reset decisions](https://docs.paywithlocus.com/api-reference/end-users/list-policy-allow-deny-capture-release-and-reset-decisions.md)
- [Allocate credits to an end-user](https://docs.paywithlocus.com/api-reference/end-users/allocate-credits-to-an-end-user.md): Atomic platform-pool → end-user transfer; both sides ledgered. Fails (402) if the pool cannot cover it — unfunded allocations are impossible. Amounts are exact decimal strings.
- [Reverse an allocation](https://docs.paywithlocus.com/api-reference/end-users/reverse-an-allocation.md)
- [Public JWKS for end-user tokens](https://docs.paywithlocus.com/api-reference/end-users/public-jwks-for-end-user-tokens.md): RS256 public keys for verifying end-user tokens yourself, keyed by the token's kid claim. Public and cacheable for 5 minutes. Revoked signing keys are never published, so a token signed by a retired key fails verification here exactly as it does server-side.
- [List an end user's minted tokens](https://docs.paywithlocus.com/api-reference/end-users/list-an-end-users-minted-tokens.md): Token metadata for one end user, newest first, capped at 200 records. Use it to audit what is outstanding and to find the tokenId to revoke. The tokens themselves are returned only at mint time and are never recoverable.
- [Revoke an end-user token](https://docs.paywithlocus.com/api-reference/end-users/revoke-an-end-user-token.md): Revokes one outstanding end-user token by its durable jti. Revocation takes effect immediately on the next use, which is the only way to cut a leaked token short — bearer tokens are otherwise replayable until they expire.
- [Own balance (end-user)](https://docs.paywithlocus.com/api-reference/widget/own-balance-end-user.md)
- [Discover APIs available to the authenticated end user](https://docs.paywithlocus.com/api-reference/widget/discover-apis-available-to-the-authenticated-end-user.md): Versioned cursor catalog. Returns only endpoints enabled by the tenant and allowed by this end user's current provider policy. Omitted endpoints do not reveal whether they are disabled, denied, or unknown. Tenant rules, base USD cost, markup, and margin are never returned; price.usd is the final cus…
- [Own ledger (end-user)](https://docs.paywithlocus.com/api-reference/widget/own-ledger-end-user.md): Returns newest-first transaction history for the end user encoded in the bearer token. The caller cannot select another externalUserId. Entries include charges, top-ups, allocations, refunds, and other posted balance movements. End-user responses redact base cost, markup, margin, tenant identifiers,…
- [Open a top-up for self (end-user)](https://docs.paywithlocus.com/api-reference/widget/open-a-top-up-for-self-end-user.md): Identity is derived only from the end-user token. externalUserId is rejected.
- [Get machine-readable top-up constraints](https://docs.paywithlocus.com/api-reference/widget/get-machine-readable-top-up-constraints.md)
- [Get authoritative state for this user's checkout](https://docs.paywithlocus.com/api-reference/widget/get-authoritative-state-for-this-users-checkout.md)
- [Per-tenant generated docs (markdown)](https://docs.paywithlocus.com/api-reference/burn/per-tenant-generated-docs-markdown.md): Enterprise workspace documentation for enabled endpoints and effective tenant pricing. Requires a management credential with tenant:read; personal accounts and end-user JWTs cannot use this route.
- [OpenAI-compatible metered chat completions](https://docs.paywithlocus.com/api-reference/burn/openai-compatible-metered-chat-completions.md): Accepts the OpenAI Chat Completions request shape. With stream=true, returns provider-native SSE without full-response buffering. Locus captures the fixed authorized charge before delivering the first byte.
- [Read authoritative stream state and final billing](https://docs.paywithlocus.com/api-reference/burn/read-authoritative-stream-state-and-final-billing.md)
- [Metered pay-per-use call](https://docs.paywithlocus.com/api-reference/burn/metered-pay-per-use-call.md): The response body is the RAW upstream response (byte-compatible with the provider SDK shape). Cost rides in response headers. `X-Locus-End-User` present (or an end-user token) charges that user's account at your effective price; a secret-key call without it charges your platform account at base pric…
- [Unsupported in stateless mode](https://docs.paywithlocus.com/api-reference/mcp/unsupported-in-stateless-mode.md)
- [Hosted MCP server (stateless Streamable HTTP)](https://docs.paywithlocus.com/api-reference/mcp/hosted-mcp-server-stateless-streamable-http.md): One MCP JSON-RPC request per POST, with an encoded JSON body limit of 4 MiB. OAuth 2.1 is the primary authentication path: initialize, discovery, and resource reads require mcp:read, while billed tools/call execution additionally requires mcp:execute. Tenant secret keys, end-user JWTs, and scoped ag…
- [Unsupported in stateless mode](https://docs.paywithlocus.com/api-reference/mcp/unsupported-in-stateless-mode-1.md)
- [Machine-readable MCP connection guide](https://docs.paywithlocus.com/api-reference/mcp/machine-readable-mcp-connection-guide.md): Public, cacheable description of the hosted MCP server: its URL, the OAuth discovery document locations, the scope model and token lifetimes, and ready-to-paste configuration for Claude Code, Codex, Cursor, VS Code, and Gemini CLI. Point an agent at this instead of hard-coding setup steps.
- [Discover the MCP protected resource (compatibility alias)](https://docs.paywithlocus.com/api-reference/mcp/discover-the-mcp-protected-resource-compatibility-alias.md): API-prefixed compatibility alias for the canonical RFC 9728 metadata path.
- [Discover the MCP authorization server (compatibility alias)](https://docs.paywithlocus.com/api-reference/mcp/discover-the-mcp-authorization-server-compatibility-alias.md): API-prefixed compatibility alias for the canonical RFC 8414 metadata path.
- [Start MCP OAuth authorization](https://docs.paywithlocus.com/api-reference/mcp/start-mcp-oauth-authorization.md): Starts the public-client Authorization Code flow. PKCE S256 and the exact MCP resource indicator are required; the browser is redirected to Locus consent and then back to the registered redirect URI.
- [Exchange or refresh an MCP OAuth token](https://docs.paywithlocus.com/api-reference/mcp/exchange-or-refresh-an-mcp-oauth-token.md): Public-client token endpoint. Client secrets and Authorization headers are not supported. Authorization-code exchange requires the PKCE verifier; device clients poll no faster than the returned interval and handle authorization_pending, slow_down, access_denied, and expired_token; refresh tokens rot…
- [Dynamically register an MCP OAuth client](https://docs.paywithlocus.com/api-reference/mcp/dynamically-register-an-mcp-oauth-client.md): RFC 7591 registration for public native or web clients. Register authorization_code with validated redirect URIs, the RFC 8628 device-code grant without redirect URIs, or both. refresh_token is optional; offline_access is grantable only when it is registered.
- [Read a dynamic MCP client registration](https://docs.paywithlocus.com/api-reference/mcp/read-a-dynamic-mcp-client-registration.md)
- [Replace a dynamic MCP client registration](https://docs.paywithlocus.com/api-reference/mcp/replace-a-dynamic-mcp-client-registration.md)
- [Delete a dynamic MCP client registration](https://docs.paywithlocus.com/api-reference/mcp/delete-a-dynamic-mcp-client-registration.md): Deletes the registration and revokes its active authorization and token families.
- [Revoke an MCP OAuth token family](https://docs.paywithlocus.com/api-reference/mcp/revoke-an-mcp-oauth-token-family.md): RFC 7009-style public-client revocation. Revoking an access or refresh token revokes its token family; unknown tokens still return success.
- [Discover the MCP protected resource](https://docs.paywithlocus.com/api-reference/mcp/discover-the-mcp-protected-resource.md): Canonical RFC 9728 path derived from the MCP resource identifier.
- [Discover the MCP authorization server](https://docs.paywithlocus.com/api-reference/mcp/discover-the-mcp-authorization-server.md): Canonical RFC 8414 path derived from the MCP OAuth issuer.
- [Read safe signed-out context for an MCP authorization](https://docs.paywithlocus.com/api-reference/mcp/read-safe-signed-out-context-for-an-mcp-authorization.md): Returns the non-sensitive client, scope, resource, expiry, and AgentID continuation URL for a pending OAuth request. Browserless agent-owned accounts use this endpoint after the MCP client starts Authorization Code + PKCE; it exposes no tenant or identity information.
- [Continue a pending MCP authorization with AgentID](https://docs.paywithlocus.com/api-reference/mcp/continue-a-pending-mcp-authorization-with-agentid.md): Builds the AgentID Authorization Code + PKCE request for a pending Locus MCP authorization and redirects to AgentID. AgentID is the resource-owner login for an already activated agent-owned account.
- [Read the Locus MCP AgentID client descriptor](https://docs.paywithlocus.com/api-reference/mcp/read-the-locus-mcp-agentid-client-descriptor.md)
- [Complete AgentID login for a pending MCP authorization](https://docs.paywithlocus.com/api-reference/mcp/complete-agentid-login-for-a-pending-mcp-authorization.md): Verifies the AgentID Authorization Code response, binds the already activated agent-owned account, enforces its active-client limit, and redirects an MCP authorization code to the exact registered client callback.
- [Start MCP device authorization](https://docs.paywithlocus.com/api-reference/mcp/start-mcp-device-authorization.md): RFC 8628 authorization for a headless public client registered with the device-code grant. Send the exact MCP resource. Locus returns a 15-minute device code, a human-readable user code, and a five-second initial polling interval. Do not send client authentication.
- [Read signed-out device authorization context](https://docs.paywithlocus.com/api-reference/mcp/read-signed-out-device-authorization-context.md): Returns only the pending client's public name, ID, requested scopes, resource, and expiry for a valid user code. It exposes no Locus identity, membership, or tenant data.
- [List memberships available to a device authorization](https://docs.paywithlocus.com/api-reference/mcp/list-memberships-available-to-a-device-authorization.md): Signed-in consent helper. Returns active Locus Pro memberships so a person with more than one account can make an explicit selection. It does not approve the device.
- [Read signed-in device consent context](https://docs.paywithlocus.com/api-reference/mcp/read-signed-in-device-consent-context.md): Returns the selected account, grantable scopes, connection capacity, resource, and expiry immediately before a human approves or denies the device. Requested scopes may be reduced to the member's effective authority.
- [Approve or deny an MCP device authorization](https://docs.paywithlocus.com/api-reference/mcp/approve-or-deny-an-mcp-device-authorization.md): Resolves one pending device request for the explicitly selected active membership. Approval reserves connection-plan capacity until the client exchanges the device code or the 15-minute request expires. A same-client retry by the same person supersedes its unfinished reservation.
- [Read the agent-native onboarding contract](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-the-agent-native-onboarding-contract.md): Public machine-readable flow for a headless agent. No existing Locus tenant is required. AgentID verification creates identity friction before any durable account exists; the human is needed only for an optional AgentMail OTP and the later Stripe funding handoff.
- [Begin or complete verified agent-owned signup](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/begin-or-complete-verified-agent-owned-signup.md): A first request creates only a 15-minute pending row and returns an AgentID authorization URL. After AgentID PKCE verification, replaying the same name and registrationToken creates or recovers one zero-balance personal account and returns its scoped connection credential. The verified provider/subj…
- [Read the agent-owned account](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-the-agent-owned-account.md): Returns only the authenticated self-registered account, its usable pooled balance, expiry, links, and next action. Tenant-managed agent connections are rejected.
- [Rotate the agent-owned credential](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/rotate-the-agent-owned-credential.md): Atomically replaces the account recovery digest and bearer credential from a newly generated 24-byte base64url token, then extends expiry by 365 days.
- [Search capabilities for an agent-owned account](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/search-capabilities-for-an-agent-owned-account.md): Searches the mutable catalog, including disabled capabilities, so a dashboardless agent can find exact provider/endpoint slugs before enabling them. System-managed virtual router endpoints are omitted because ordinary catalog controls cannot toggle them.
- [Enable or disable one agent-owned capability](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/enable-or-disable-one-agent-owned-capability.md): Changes only the enabled flag for one exact catalog slug on the self-registered account. It cannot change pricing or any other tenant setting.
- [Read agent funding constraints](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-agent-funding-constraints.md): Returns exact top-up limits and confirms that Checkout is Stripe-hosted, the payer does not become owner, and no reusable payment method is delegated to the agent.
- [Create a human funding handoff](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/create-a-human-funding-handoff.md): Creates an exact-amount, one-hour Stripe Checkout Session for the authenticated agent account. The payer card is not attached to the agent account for future use. Reuse the Idempotency-Key for retries of the same logical link.
- [Poll an agent funding handoff](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/poll-an-agent-funding-handoff.md): Returns ready only after the signed Stripe webhook has been durably consumed and the credit ledger balance is usable.
- [Read the payer-safe funding result](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-the-payer-safe-funding-result.md): Public status used by the Stripe return page. The opaque Checkout Session ID is the capability. The response contains only state, agent display name, and credited amount; it never returns payer details or agent credentials.
- [Read the Locus AgentID client descriptor](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/read-the-locus-agentid-client-descriptor.md)
- [Complete AgentID authorization-code verification](https://docs.paywithlocus.com/api-reference/agent-native-onboarding/complete-agentid-authorization-code-verification.md): Exchanges an AgentID authorization code with PKCE, verifies ES256 issuer, audience, nonce, stable subject, and live inbox, and marks the pending signup identity-verified. The callback never returns a Locus credential; the agent replays POST /credits/agent/register to receive it.
- [Read capability-router defaults and eligible providers](https://docs.paywithlocus.com/api-reference/capability-routing/read-capability-router-defaults-and-eligible-providers.md): Enterprise-only management read; requires tenant:read.
- [Update capability-router defaults](https://docs.paywithlocus.com/api-reference/capability-routing/update-capability-router-defaults.md): Enterprise-only management update. Legacy strategy is translated when mode is absent; legacy rails is accepted and ignored.
- [Enable a provider for capability routing](https://docs.paywithlocus.com/api-reference/capability-routing/enable-a-provider-for-capability-routing.md): Enterprise-only management update; requires catalog:write.
- [Preview the saved multi-provider web-search plan](https://docs.paywithlocus.com/api-reference/capability-routing/preview-the-saved-multi-provider-web-search-plan.md): Enterprise-only free preview; requires tenant:read.
- [Run multi-provider web search](https://docs.paywithlocus.com/api-reference/capability-routing/run-multi-provider-web-search.md): Searches eligible providers in parallel, canonicalizes and deduplicates URLs, fuses rankings, and returns per-result source provenance. The charge is the sum of successful underlying calls.
- [Preview multi-provider web search](https://docs.paywithlocus.com/api-reference/capability-routing/preview-multi-provider-web-search.md): Plans eligible providers and returns the current tenant-aware estimate without calling a provider or burning credits.
- [Run multi-provider web research](https://docs.paywithlocus.com/api-reference/capability-routing/run-multi-provider-web-research.md): Selects an exact structured catalog capability when one satisfies the requested outcome, otherwise falls back to multi-provider search. The charge is the sum of successful underlying calls.
- [Preview multi-provider web research](https://docs.paywithlocus.com/api-reference/capability-routing/preview-multi-provider-web-research.md): Plans eligible providers and returns the current tenant-aware estimate without calling a provider or burning credits.
- [Read capability-router endpoints and provider availability](https://docs.paywithlocus.com/api-reference/capability-routing/read-capability-router-endpoints-and-provider-availability.md): Returns the system-managed routing capabilities, saved settings, and current provider availability for the authenticated caller.
- [Read Okibi CLI credential bootstrap status](https://docs.paywithlocus.com/api-reference/okibi-identity/read-okibi-cli-credential-bootstrap-status.md): A real Okibi-protected resource used to verify the signed CLI release, active identity grant, durable Locus account binding, and current installation credential state. It never returns the raw native credential. Requires both mcp:read and mcp:execute from Okibi Identity.
- [Bootstrap a scoped Locus CLI credential from Okibi Identity](https://docs.paywithlocus.com/api-reference/okibi-identity/bootstrap-a-scoped-locus-cli-credential-from-okibi-identity.md): Exchanges a verified Okibi identity grant for one 24-hour Locus lcac_ execution credential bound to the Okibi identity, CLI installation, selected workspace, and explicit provider/endpoint allowlist. The server enables only those catalog slugs. Generate registrationToken locally from exactly 24 rand…
- [List custom API providers and actions](https://docs.paywithlocus.com/api-reference/custom-apis/list-custom-api-providers-and-actions.md): Available when enabled for the workspace. Enterprise management surface. Requires catalog:write. The raw upstream credential is never returned. Only a workspace owner whose credential also has credentials:manage receives the provider base URL and redacted authentication metadata; every other authori…
- [Create a custom API provider](https://docs.paywithlocus.com/api-reference/custom-apis/create-a-custom-api-provider.md): Creates one BYOK provider and optionally up to 50 actions atomically. Requires an enterprise workspace with Custom APIs enabled, the workspace owner, credentials:manage and catalog:write, plus MFA or passkey step-up completed in the last ten minutes. Locus validates the upstream URL against SSRF con…
- [Delete a custom API provider](https://docs.paywithlocus.com/api-reference/custom-apis/delete-a-custom-api-provider.md): Permanently removes the provider, its encrypted upstream credential, and its custom actions. Requires the same enterprise owner, scope, and recent step-up controls as creation.
- [Update a custom API provider](https://docs.paywithlocus.com/api-reference/custom-apis/update-a-custom-api-provider.md): Updates provider presentation, SSRF-checked base URL, authentication, or traffic protection. Supplying a new credential rotates the encrypted secret; type=none removes it. Requires the same enterprise owner, scope, and recent step-up controls as creation.
- [Create an action for a custom provider](https://docs.paywithlocus.com/api-reference/custom-apis/create-an-action-for-a-custom-provider.md): Creates one disabled-by-default or explicitly enabled action. Its input schema must describe an object, its example must validate, path placeholders must resolve to scalar schema properties, and the top-level names externalUserId, attribution, and _locus are reserved for Locus transport controls. Pu…
- [Delete a custom API action](https://docs.paywithlocus.com/api-reference/custom-apis/delete-a-custom-api-action.md): Permanently removes one custom action. Requires the enterprise owner with credentials:manage, catalog:write, and recent step-up.
- [Update a custom API action](https://docs.paywithlocus.com/api-reference/custom-apis/update-a-custom-api-action.md): Updates one action without changing its stable slug. Contract and pricing changes are revalidated; a pricing change increments pricingRevision. Requires the enterprise owner with credentials:manage, catalog:write, and recent step-up.
- [Plan a multi-provider flight search without dispatching](https://docs.paywithlocus.com/api-reference/travel-routing/plan-a-multi-provider-flight-search-without-dispatching.md): Available when enabled for the workspace. Locus Travel planning route. It validates the normalized search, applies credential and catalog restrictions, selects eligible providers, and returns the aggregate estimated charge. It does not contact travel providers or burn credits. estimateExact is false…
- [Search flights across selected providers](https://docs.paywithlocus.com/api-reference/travel-routing/search-flights-across-selected-providers.md): Available when enabled for the workspace. System-managed capability router. Locus plans eligible providers, executes them concurrently, normalizes and deduplicates itineraries, ranks offers, and returns aggregate billing. Use the preview route first when you need an estimate. A narrower request maxC…
- [Submit feedback for a completed flight search](https://docs.paywithlocus.com/api-reference/travel-routing/submit-feedback-for-a-completed-flight-search.md): Creates or replaces feedback for a completed run owned by the authenticated account. selectedItineraryId, when supplied, must belong to that run. End-user and Agent Connection access remains scoped exactly as it was for execution.
- [Welcome to Locus](https://docs.paywithlocus.com/agent-platform.md): Payment infrastructure for AI agents — one USDC balance for wallets, agent tools, deployments, checkout, and more.
- [Quick Start](https://docs.paywithlocus.com/quickstart.md): Get your agent set up with Locus on production
- [Platform Walkthrough](https://docs.paywithlocus.com/platform-walkthrough.md): A guided tour of the Locus platform
- [Request & Claim Credits](https://docs.paywithlocus.com/promo-credits.md): Get free promotional USDC credits to try Locus — via agent or human
- [Wallets](https://docs.paywithlocus.com/features/wallets.md): Smart wallet architecture for secure, gasless transactions on Base
- [USDC Transfers](https://docs.paywithlocus.com/features/send-types.md): Send USDC to wallet addresses or email recipients
- [Tasks](https://docs.paywithlocus.com/features/tasks.md): Let your agent hire human taskers across popular platforms
- [Laso Finance](https://docs.paywithlocus.com/features/laso.md): Order prepaid virtual debit cards using USDC
- [Agent tools](https://docs.paywithlocus.com/wrapped-apis/index.md): Give your agent governed, pay-per-use access to search, data, AI models, email, and more.
- [Use agent tools](https://docs.paywithlocus.com/wrapped-apis/for-agents.md): Authenticate, discover, quote, and call Locus-managed agent tools.
- [Agent tool catalog](https://docs.paywithlocus.com/wrapped-apis/providers.md): Current Locus-managed providers, callable namespaces, and generated endpoint references.
- [Machine Payments Protocol (MPP)](https://docs.paywithlocus.com/wrapped-apis/mpp.md): Pay for supported agent tools inline through HTTP 402 on Tempo.
- [Build with Locus](https://docs.paywithlocus.com/build/index.md): Deploy containerized services on demand
- [Getting Started](https://docs.paywithlocus.com/build/getting-started.md): Authenticate, check billing, and deploy your first service
- [Services & Deployments](https://docs.paywithlocus.com/build/services.md): Create services, choose deploy methods, and monitor deployments
- [Variables & Wiring](https://docs.paywithlocus.com/build/environment.md): Configure environment variables, wire services together, and use template references
- [Addons & Custom Domains](https://docs.paywithlocus.com/build/addons-and-domains.md): Provision managed databases, add custom domains, and configure DNS
- [MPP (Machine-Payable Protocol)](https://docs.paywithlocus.com/build/mpp.md): Sign up and pay for Locus services using Tempo blockchain and USDC
- [x402 (HTTP 402 Payment Required)](https://docs.paywithlocus.com/build/x402.md): Sign up and pay for Locus services using the x402 protocol on Polygon or Base
- [Agent Workflow](https://docs.paywithlocus.com/build/for-agents.md): How AI agents deploy and manage services on Build with Locus
- [Checkout with Locus](https://docs.paywithlocus.com/checkout/index.md): Accept USDC payments with a drop-in checkout experience
- [Example implementations](https://docs.paywithlocus.com/checkout/integrate.md): End-to-end examples for adding Locus Checkout to your app
- [Merchant Integration](https://docs.paywithlocus.com/checkout/for-merchants.md): Embed Locus Checkout in your app with the React SDK
- [Buyer & Agent Guide](https://docs.paywithlocus.com/checkout/for-buyers.md): How buyers and AI agents pay through Locus Checkout
- [Payment Router](https://docs.paywithlocus.com/checkout/payment-router.md): On-chain contract for external wallet checkout payments

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)