{ "openapi": "3.1.0", "info": { "title": "Locus Pro API", "description": "Access paid tools, manage prepaid balances, and build usage billing. Send money as exact decimal strings and reuse Idempotency-Key on retries. Management routes require a scoped server key or authorized dashboard session. Sensitive workspace changes require an owner or admin with recent MFA or passkey verification, except where an operation documents a stricter boundary. Interactive agents use MCP OAuth; unattended agents use scoped Agent Connections. Browser widgets use end-user tokens.", "version": "0.7.0" }, "servers": [ { "url": "https://api.paywithlocus.com/api", "description": "Production" }, { "url": "https://api.stage.paywithlocus.com/api", "description": "Stage \u2014 evaluation and integration testing" } ], "security": [ { "secretKey": [] } ], "tags": [ { "name": "Authentication", "description": "Email-verified self-serve account creation and dashboard identity" }, { "name": "Tenants", "description": "Tenant profile, keys, and settings (dashboard session or secret key)" }, { "name": "Workspace members", "description": "Invite-only human workspace membership and role administration" }, { "name": "Catalog", "description": "Enable/disable APIs and set markups" }, { "name": "Custom APIs", "description": "Feature-gated enterprise BYOK providers and schema-backed custom actions" }, { "name": "End users", "description": "End-user accounts, tokens, and allocations" }, { "name": "Top-ups", "description": "Locus-hosted checkout top-ups and quotes" }, { "name": "Ledger", "description": "Burn/top-up history and earnings" }, { "name": "Webhooks", "description": "Signed events, delivery inspection, and replay" }, { "name": "Burn", "description": "Metered pay-per-use calls" }, { "name": "MCP", "description": "Stateless Streamable HTTP transport and MCP tool-result contracts" }, { "name": "Okibi Identity", "description": "Feature-gated Okibi identity verification and scoped native CLI credential bootstrap" }, { "name": "Widget", "description": "End-user JWT surface; a matching publishable key is optional" }, { "name": "Agent-native onboarding", "description": "Self-registration, human Stripe funding handoff, and restricted account setup for headless agents" }, { "name": "Hosted Workflows", "description": "Tenant-private TypeScript Workflow definitions, immutable versions, bounded runs, artifacts, and recovery" }, { "name": "Agent connections", "description": "Scoped, expiring, revocable credentials for agent execution" }, { "name": "Recipes", "description": "Search, research, extraction, enrichment, and travel outcomes across providers" } ], "paths": { "/credits/evaluation-invitations/validate": { "post": { "tags": [ "Tenants" ], "summary": "Validate an evaluation invitation", "description": "Returns only the company, masked email, expiry and safe invitation state. The raw token is never returned or logged.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^lpei_" } } } } } }, "responses": { "200": { "description": "Safe masked preview" }, "404": { "description": "Invalid, expired or revoked" } } } }, "/credits/evaluation-invitations/accept": { "post": { "tags": [ "Tenants" ], "summary": "Create an evaluation account from a private invitation", "description": "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.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "password" ], "properties": { "token": { "type": "string", "pattern": "^lpei_" }, "name": { "type": "string", "maxLength": 100 }, "password": { "type": "string", "minLength": 8, "maxLength": 256, "format": "password", "writeOnly": true } } } } } }, "responses": { "201": { "description": "Evaluation tenant provisioned" }, "409": { "description": "Concurrent provisioning or existing account must sign in" } } } }, "/credits/evaluation-invitations/accept-existing": { "post": { "tags": [ "Tenants" ], "summary": "Accept an invitation as the matching signed-in identity", "description": "The live Cognito email must exactly match the invited email. Successful acceptance selects the returned tenant with X-Locus-Tenant-Id.", "security": [ { "dashboardSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^lpei_" } } } } } }, "responses": { "200": { "description": "Evaluation tenant selected or provisioned" }, "403": { "description": "Signed-in email does not match" } } } }, "/credits/member-invitations/validate": { "post": { "tags": [ "Workspace members" ], "summary": "Validate a workspace invitation", "description": "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.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^lpmi_", "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Safe invitation preview", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "invitation" ], "properties": { "invitation": { "$ref": "#/components/schemas/WorkspaceInvitationPreview" } } } } } } } }, "404": { "description": "Invitation is invalid, expired, revoked, or already consumed" } } } }, "/credits/member-invitations/accept": { "post": { "tags": [ "Workspace members" ], "summary": "Create the invited identity and join its workspace", "description": "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.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token", "name", "password" ], "properties": { "token": { "type": "string", "pattern": "^lpmi_", "maxLength": 128 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "password": { "type": "string", "minLength": 8, "maxLength": 256, "format": "password", "writeOnly": true } } } } } }, "responses": { "201": { "description": "Account created and workspace membership activated" }, "409": { "description": "Existing identity must sign in, or provisioning is already active" } } } }, "/credits/member-invitations/accept-existing": { "post": { "tags": [ "Workspace members" ], "summary": "Join a workspace as the matching signed-in identity", "description": "The live Cognito email must exactly match the invited email. The response identifies the workspace to select with X-Locus-Tenant-Id.", "security": [ { "dashboardSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "token" ], "properties": { "token": { "type": "string", "pattern": "^lpmi_", "maxLength": 128 } } } } } }, "responses": { "200": { "description": "Previously completed invitation selected idempotently" }, "201": { "description": "Workspace membership activated" }, "403": { "description": "Signed-in email does not match the invitation" }, "409": { "description": "Invitation is invalid, expired, already in progress for another identity, or the signed-in identity is already a member" } } } }, "/credits/tenants": { "get": { "tags": [ "Workspace members" ], "summary": "List the signed-in person's workspace memberships", "description": "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.", "security": [ { "dashboardSession": [] } ], "responses": { "200": { "description": "Memberships visible to the signed-in identity", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "memberships" ], "properties": { "success": { "const": true }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMembership" } } } } } } } } } }, "/credits/members": { "get": { "tags": [ "Workspace members" ], "summary": "List workspace members and pending invitations", "description": "Human Cognito sessions only. Tenant API keys cannot enumerate workspace member email addresses.", "security": [ { "dashboardSession": [] } ], "responses": { "200": { "description": "Workspace members and active invitations", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "members", "invitations" ], "properties": { "success": { "const": true }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMember" } }, "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceInvitation" } } } } } } }, "403": { "description": "A non-human credential attempted to enumerate workspace membership" } } } }, "/credits/member-invitations": { "post": { "tags": [ "Workspace members" ], "summary": "Invite people to a workspace", "description": "Requires owner or admin membership, members:manage, and MFA or passkey step-up within the last ten minutes. Accepts at most 20 unique normalized email addresses.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "emails", "role" ], "properties": { "emails": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "format": "email", "maxLength": 254 } }, "role": { "$ref": "#/components/schemas/InvitableWorkspaceRole" } } } } } }, "responses": { "201": { "description": "Invitation records persisted and immediate delivery attempted" }, "403": { "description": "Missing owner/admin role, scope, or recent step-up" } } } }, "/credits/member-invitations/{invitationId}/resend": { "post": { "tags": [ "Workspace members" ], "summary": "Rotate and resend a pending workspace invitation", "description": "Requires owner or admin membership, members:manage, and recent MFA or passkey step-up. Rotating the token invalidates the previous email link.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "200": { "description": "Invitation token rotated and delivery attempted" }, "403": { "description": "Missing authorization or step-up" }, "404": { "description": "Invitation not found" } } } }, "/credits/member-invitations/{invitationId}": { "delete": { "tags": [ "Workspace members" ], "summary": "Revoke a workspace invitation", "description": "Requires owner or admin membership, members:manage, and recent MFA or passkey step-up.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "204": { "description": "Invitation revoked" }, "403": { "description": "Missing authorization or step-up" }, "404": { "description": "Invitation not found" } } } }, "/credits/members/{memberId}": { "patch": { "tags": [ "Workspace members" ], "summary": "Change a workspace member role", "description": "Requires owner or admin membership, members:manage, and recent MFA or passkey step-up. The original owner cannot be reassigned and a member cannot change their own role.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "role" ], "properties": { "role": { "$ref": "#/components/schemas/InvitableWorkspaceRole" } } } } } }, "responses": { "200": { "description": "Role updated" }, "403": { "description": "Missing authorization or step-up" }, "404": { "description": "Member not found" }, "409": { "description": "The original owner cannot be reassigned, or the acting member tried to change their own role" } } }, "delete": { "tags": [ "Workspace members" ], "summary": "Remove a workspace member", "description": "Requires owner or admin 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.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "memberId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "204": { "description": "Member removed" }, "403": { "description": "Missing authorization or step-up" }, "404": { "description": "Member not found" }, "409": { "description": "The original owner or acting member cannot be removed" } } } }, "/credits/auth/credential": { "get": { "tags": [ "Authentication" ], "summary": "Inspect the current management credential", "description": "Returns only the authenticated credential kind, tenant, role, effective scopes, and current step-up state. Owner and admin dashboard sessions are step-up eligible; developer, billing, viewer, and secret-key principals are not. It never returns raw keys, hashes, JWT claims, or secrets. Call this before attempting a scoped management operation.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Effective authorization context", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "credential" ], "properties": { "success": { "const": true }, "credential": { "type": "object", "required": [ "auth", "tenantId", "role", "credentialId", "scopes", "stepUpEligible", "stepUpFresh" ], "properties": { "auth": { "type": "string", "enum": [ "secret_key", "cognito" ] }, "tenantId": { "type": "string", "format": "uuid" }, "role": { "oneOf": [ { "$ref": "#/components/schemas/WorkspaceRole" }, { "type": "null" } ] }, "credentialId": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/components/schemas/CreditsTenantScope" } }, "stepUpEligible": { "type": "boolean" }, "stepUpFresh": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "Missing, invalid, expired, or revoked management credential" } } } }, "/credits/balance": { "get": { "tags": [ "Tenants" ], "operationId": "getCreditsBalance", "summary": "Read the platform or end-user balance", "description": "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.", "security": [ { "secretKey": [] } ], "parameters": [ { "name": "X-Locus-End-User", "in": "header", "required": false, "description": "Stable external user ID. Omit to read the platform pool.", "schema": { "$ref": "#/components/schemas/ExternalUserId" } } ], "responses": { "200": { "description": "Current balance and tenant denomination", "content": { "application/json": { "schema": { "type": "object", "required": [ "usd", "credits", "denomination" ], "properties": { "usd": { "$ref": "#/components/schemas/DecimalString" }, "credits": { "$ref": "#/components/schemas/DecimalString" }, "denomination": { "type": "object", "required": [ "creditsPerDollar" ], "properties": { "creditsPerDollar": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "401": { "description": "Missing or invalid tenant secret key" }, "403": { "description": "The credential lacks tenant:read" } } } }, "/credits/agent-connections": { "post": { "tags": [ "Authentication", "MCP" ], "summary": "Create a scoped Agent Connection", "description": "Creates a short-lived, least-privilege lcac_ credential for MCP and wrapped execution. Because the returned credential can spend credits, callers must hold both credentials:manage and credits:move rather than delegating spend authority they do not hold. A secret key with both scopes may automate this route; human callers must be a workspace owner or admin with fresh MFA/passkey step-up.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "x-required-scopes": [ "credentials:manage", "credits:move" ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionCreateRequest" } } } }, "responses": { "201": { "description": "Connection created; credential is returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionEnvelope" } } } }, "400": { "description": "Invalid identity, endpoint, expiry, or exact-credit scope" }, "401": { "$ref": "#/components/responses/UnauthorizedManagement" }, "403": { "$ref": "#/components/responses/InsufficientScope" } } }, "get": { "tags": [ "Authentication", "MCP" ], "summary": "List scoped Agent Connections", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "x-required-scopes": [ "credentials:manage" ], "responses": { "200": { "description": "Connection metadata; raw credentials are never returned", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "connections" ], "properties": { "success": { "const": true }, "connections": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConnection" } }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/UnauthorizedManagement" }, "403": { "$ref": "#/components/responses/InsufficientScope" } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pass nextCursor from the previous page unchanged." }, { "name": "externalUserId", "in": "query", "schema": { "type": "string" }, "description": "Only connections bound to this customer." } ], "description": "Results are bounded to 100 records and sorted newest first. Follow nextCursor until null." } }, "/credits/agent-connections/{connectionId}": { "get": { "tags": [ "Authentication", "MCP" ], "summary": "Read one scoped Agent Connection", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "x-required-scopes": [ "credentials:manage" ], "parameters": [ { "$ref": "#/components/parameters/AgentConnectionId" } ], "responses": { "200": { "description": "Connection metadata; the raw credential is omitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionEnvelope" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedManagement" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "description": "Connection not found in this workspace" } } } }, "/credits/agent-connections/{connectionId}/rotate": { "post": { "tags": [ "Authentication", "MCP" ], "summary": "Rotate a scoped Agent Connection credential", "description": "Immediately invalidates the prior lcac_ credential and returns its spend-capable replacement once. Callers require credentials:manage and credits:move; a scoped secret key with both may automate this operation, while human callers additionally require owner/admin step-up.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "x-required-scopes": [ "credentials:manage", "credits:move" ], "parameters": [ { "$ref": "#/components/parameters/AgentConnectionId" }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "200": { "description": "Credential rotated and returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionEnvelope" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedManagement" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "description": "Connection not found in this workspace" }, "409": { "description": "Connection is no longer active" } } } }, "/credits/agent-connections/{connectionId}/revoke": { "post": { "tags": [ "Authentication", "MCP" ], "summary": "Revoke a scoped Agent Connection credential", "description": "Idempotently revokes the lcac_ credential. A scoped secret key may automate this Agent Connection operation; human callers require owner/admin step-up.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "x-required-scopes": [ "credentials:manage" ], "parameters": [ { "$ref": "#/components/parameters/AgentConnectionId" }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "200": { "description": "Connection is revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentConnectionEnvelope" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedManagement" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "description": "Connection not found in this workspace" } } } }, "/credits/tenants/me": { "get": { "tags": [ "Tenants" ], "summary": "Get tenant profile", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Tenant profile and configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } } } }, "patch": { "tags": [ "Tenants" ], "summary": "Update tenant profile", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "defaultMarkupBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "feeMode": { "type": "string", "enum": [ "pass_through", "absorb" ] }, "billingMode": { "type": "string", "enum": [ "wholesale_pool", "embedded_topups" ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Tenant profile updated" }, "400": { "description": "Invalid profile value, immutable creditsPerDollar, or one or more unknown fields", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UnknownTenantFieldsError" }, { "type": "object", "required": [ "success", "error", "message" ], "properties": { "success": { "const": false }, "error": { "const": "Bad Request" }, "message": { "type": "string" } } } ] } } } }, "403": { "description": "Caller is neither an owner/admin dashboard member nor a secret key, or lacks tenant:write" } } }, "put": { "tags": [ "Tenants" ], "summary": "Update tenant settings", "description": "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 a dashboard session from a workspace owner or admin with MFA or passkey step-up completed in the last ten minutes; every other principal receives 403. Changing marginPayoutAddress starts a 24-hour payout hold.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "webhookUrl": { "type": [ "string", "null" ], "format": "uri" }, "feeMode": { "type": "string", "enum": [ "pass_through", "absorb" ] }, "marginPayoutAddress": { "type": [ "string", "null" ], "pattern": "^0x[a-fA-F0-9]{40}$", "description": "Dashboard-session only. A change starts a 24-hour payout hold." }, "payoutMethod": { "type": "string", "enum": [ "usdc", "stripe" ], "description": "Dashboard-session only." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Settings updated; no webhook ownership challenge is pending" }, "202": { "description": "Settings updated and webhook ownership verification queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "tenant", "webhookVerification" ], "properties": { "success": { "const": true }, "tenant": { "$ref": "#/components/schemas/Tenant" }, "webhookVerification": { "$ref": "#/components/schemas/WebhookVerification" } } } } } }, "400": { "description": "Invalid setting or one or more unknown fields", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UnknownTenantFieldsError" }, { "type": "object", "required": [ "success", "error", "message" ], "properties": { "success": { "const": false }, "error": { "const": "Bad Request" }, "message": { "type": "string" } } } ] } } } }, "403": { "description": "INSUFFICIENT_SCOPE, STEP_UP_REQUIRED for a payout-setting change, a secret key attempted a dashboard-only payout change, or payouts are locked for an evaluation workspace" } } } }, "/credits/tenants/me/keys": { "get": { "tags": [ "Tenants" ], "summary": "List API-key metadata and immutable execution policies", "description": "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, monthCalls \u2014 null for keys with no attributed burns; attribution began 2026-08 with the burn initiator envelope). Secret-key callers never receive those two enrichment fields: member emails and spend rollups stay behind a human session, matching the /members boundary. Results are bounded to 100 records and sorted newest first. Follow nextCursor until null.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "{ success, keys: [...] } \u2014 lifecycle metadata only; raw keys and hashes are never returned" }, "403": { "description": "INSUFFICIENT_SCOPE (needs credentials:manage; dashboard callers must be owner or admin)." } }, "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pass nextCursor from the previous page unchanged." }, { "name": "usage", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "Set to false to omit the dashboard-session enrichment (usage and createdByEmail). Paging a large key list for a picker does not need the month's usage rollup on every page." } ] }, "post": { "tags": [ "Tenants" ], "summary": "Issue an independently scoped API key", "description": "Creates an overlapping named credential. Requires a workspace owner or admin with credentials:manage and MFA or passkey step-up completed in the last ten minutes. A human caller cannot put a scope on a secret key that is absent from their own effective membership scopes. tools.enable narrows the tenant-enabled catalog for this key; pricing applies only to end-user calls and never widens tenant enablement. kind 'sandbox' issues a scopeless test credential (lcrsb_...) whose metered calls are simulated: no credits move and no providers are called. Unknown body fields are rejected with 400.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreateRequest" } } } }, "responses": { "201": { "description": "{ success, kind, key, keyMetadata } \u2014 the raw key is returned exactly once, with the stored lifecycle metadata beside it." }, "400": { "description": "Invalid kind, name, scopes (including a secret scope the acting member does not hold), tools, pricing, expiresIn \u2014 or an unknown body field." }, "403": { "description": "STEP_UP_REQUIRED or INSUFFICIENT_SCOPE." } } } }, "/credits/tenants/me/keys/rotate": { "post": { "tags": [ "Tenants" ], "summary": "Rotate every active key of a kind (cutover)", "description": "Creates ONE replacement and supersedes ALL other active keys of that kind. Requires a workspace owner or admin with credentials:manage and MFA or passkey step-up completed in the last ten minutes. A human caller cannot delegate a secret-key scope absent from their own effective membership scopes. For rotating a single key while its siblings keep working, use POST /credits/tenants/me/keys/{keyId}/rotate.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "secret", "publishable", "sandbox" ] }, "expiresIn": { "type": [ "integer", "null" ], "description": "Lifetime of the new key in seconds. Omit for the default." }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/CreditsTenantScope" }, "description": "Scopes for the new key. Omit to keep the kind's defaults. Publishable keys accept only widget:read." }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name for the replacement key." }, "tools": { "type": "object", "additionalProperties": false, "required": [ "enable" ], "properties": { "enable": { "type": "array", "maxItems": 1000, "items": { "type": "string", "pattern": "^[^/]+/[^/]+$" }, "uniqueItems": true } }, "description": "Endpoint allowlist for the replacement; makes it a burn-only execution credential." }, "pricing": { "$ref": "#/components/schemas/CredentialPricingPolicy" }, "gracePeriodSeconds": { "type": "integer", "minimum": 0, "description": "Keep the old key valid this long for zero-downtime cutover. Omitted means the old key dies with this response." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "{ success, kind, key, keyPrefix } \u2014 the raw key is returned exactly once. Unlike create and per-key rotation, this cutover endpoint returns keyPrefix rather than a keyMetadata object. Without gracePeriodSeconds the superseded keys stop working with this response; with it they keep authenticating until the overlap ends." }, "400": { "description": "Invalid field or unknown body field \u2014 including a requested secret scope the acting member does not hold, or a bare rotation that would silently widen authority (some active key of the kind carries an endpoint allowlist, pricing, execution audience, or narrowed scopes; pass the replacement's shape explicitly)." }, "403": { "description": "STEP_UP_REQUIRED or INSUFFICIENT_SCOPE." } } } }, "/credits/tenants/me/webhook-verification": { "get": { "tags": [ "Webhooks" ], "summary": "Read the latest webhook ownership challenge", "description": "Polling this endpoint never reveals or consumes the webhook signing secret.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Latest tenant-scoped verification, or null when none was requested", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "webhookVerification" ], "properties": { "success": { "const": true }, "webhookVerification": { "oneOf": [ { "$ref": "#/components/schemas/WebhookVerification" }, { "type": "null" } ] } } } } } } } } }, "/credits/tenants/me/webhook-secret/reveal": { "post": { "tags": [ "Webhooks" ], "summary": "Reveal the first verified webhook signing secret once", "description": "Workspace owner/admin and MFA/passkey step-up protected. Status polling cannot consume this reveal. If it was already revealed, rotate the secret instead.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "200": { "description": "First signing secret", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "webhookSecret" ], "properties": { "success": { "const": true }, "webhookSecret": { "type": "string", "pattern": "^whsec_" } } } } } }, "409": { "description": "Verification is incomplete or the secret was already revealed" } } } }, "/credits/tenants/me/webhook-secret/rotate": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate the webhook signing secret", "description": "Returns the new secret once. Requires a workspace owner or admin 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.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "200": { "description": "New signing secret and old-secret expiry", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "webhook_secret", "previous_secret_valid_until" ], "properties": { "success": { "const": true }, "webhook_secret": { "type": "string", "pattern": "^whsec_" }, "previous_secret_valid_until": { "type": "string", "format": "date-time" } } } } } } } } }, "/credits/tenants/me/auto-recharge": { "post": { "tags": [ "Top-ups" ], "summary": "Configure automatic balance reload", "description": "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 ten minutes. Enterprise workspaces call it auto-recharge and require a workspace owner or admin with payouts:manage plus recent MFA or passkey step-up. Evaluation workspaces may configure auto-recharge without activating a commercial agreement. Make one successful manual top-up first so Stripe has a reusable payment method.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "thresholdUsd", "amountUsd" ], "properties": { "thresholdUsd": { "$ref": "#/components/schemas/DecimalString" }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" } }, "additionalProperties": false }, { "type": "object", "required": [ "thresholdUsd", "amountUsd" ], "properties": { "thresholdUsd": { "type": "null" }, "amountUsd": { "type": "null" } }, "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Automatic reload configuration updated; autoRecharge is null when disabled" }, "400": { "description": "Unknown field, non-positive amount, or only one of thresholdUsd and amountUsd was supplied" }, "403": { "description": "Owner/recent-authentication requirement, enterprise step-up requirement, insufficient scope, or funding unavailable" } } } }, "/credits/catalog": { "put": { "tags": [ "Catalog" ], "summary": "Set the workspace default markup", "description": "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 just that one; null restores the platform default.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "markupBps": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 10000, "description": "Percentage markup in basis points, capped by the workspace markup ceiling. null restores the default." }, "flatMarkupUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "Flat per-call markup in USD. null restores the default." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "New workspace defaults", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "scope", "tenant" ], "properties": { "success": { "const": true }, "scope": { "const": "global" }, "tenant": { "type": "object", "required": [ "defaultMarkupBps", "defaultFlatMarkupUsd", "creditsPerDollar" ], "properties": { "defaultMarkupBps": { "type": "integer" }, "defaultFlatMarkupUsd": { "$ref": "#/components/schemas/DecimalString" }, "creditsPerDollar": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Unknown field, no field supplied, or a markup above the workspace ceiling." }, "403": { "$ref": "#/components/responses/InsufficientScope" } } }, "get": { "tags": [ "Catalog" ], "summary": "List catalog with your effective prices", "description": "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 page also publishes pageCursors so the dashboard can fetch the remaining pages concurrently. view=summary returns every provider as price-free card metadata and endpoint counts in one response. Agents should stay on compact and follow nextCursor; the 2026-08-31 revision only adds the optional provider secondaryCategories field, the 2026-09-05 revision adds `overridden` and `mcpPinned` to the dashboard endpoint plus the dashboard-only `enabled=true` filter, and the 2026-09-06 revision adds optional endpoint `billingModel` metadata. Personal accounts receive the price-safe dashboard projection when view is omitted or full/compact/dashboard is requested; they may also request summary. Request view=full only for the backward-compatible full export. Cache privately for at most 60 seconds and revalidate with If-None-Match; do not poll more often than once per minute.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "view", "in": "query", "schema": { "type": "string", "enum": [ "compact", "dashboard", "summary", "full" ], "default": "compact" }, "description": "The default is compact for enterprise workspaces and dashboard for personal accounts. Personal accounts are always projected to dashboard except for summary." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 512 }, "description": "Opaque provider cursor; valid only for the paged views (compact, dashboard)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Provider page size; valid only for the paged views (compact, dashboard)." }, { "name": "enabled", "in": "query", "schema": { "type": "boolean", "const": true }, "description": "view=dashboard only (personal accounts are always served that view): page over what the workspace has on. Every provider keeps only its enabled endpoints and is omitted when none is left; page cursors are computed over that list, and the response echoes filter.enabled so a client can tell a filtered page from one served by an older task. Any other view, or any value but true, is a 400." } ], "responses": { "200": { "description": "Full export or compact provider page. Responses include ETag, X-Locus-Catalog-Version, and a private no-cache directive so enablement changes are never read from cache.", "headers": { "ETag": { "schema": { "type": "string" } }, "X-Locus-Catalog-Version": { "schema": { "type": "string", "const": "2026-09-06" } }, "Cache-Control": { "schema": { "type": "string", "const": "private, no-cache" }, "description": "The catalog is a mutable control surface: it always revalidates, so a read right after an enable/disable can never be served a stale body. The ETag keeps revalidation cheap (304, no body)." } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogResponse" }, { "$ref": "#/components/schemas/CompactCatalogResponse" }, { "$ref": "#/components/schemas/DashboardCatalogResponse" }, { "$ref": "#/components/schemas/PersonalDashboardCatalogResponse" }, { "$ref": "#/components/schemas/DashboardCatalogSummaryResponse" } ] } } } }, "304": { "description": "The tenant-scoped catalog page is unchanged." } } } }, "/credits/catalog/bulk": { "put": { "tags": [ "Catalog" ], "summary": "Enable or disable a bounded provider batch", "description": "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 larger selections into bounded batches so edge inspection cannot reject an oversized request. Batches commit independently: a failure after an earlier batch committed leaves that batch applied.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "providers", "enabled" ], "properties": { "providers": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Known provider slugs. Unknown providers reject the whole batch transaction." }, "enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Provider rows updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "scope", "enabled", "updated", "endpointOverridesCleared" ], "properties": { "success": { "const": true }, "scope": { "const": "bulk" }, "enabled": { "type": "boolean" }, "updated": { "type": "integer", "minimum": 1, "maximum": 50 }, "endpointOverridesCleared": { "type": "integer", "minimum": 0, "description": "Endpoint-level enablement overrides reset to inherit by this batch." } }, "additionalProperties": false } } } }, "400": { "description": "Empty/oversized provider list or invalid enabled value" }, "404": { "description": "At least one provider slug is unknown; no rows are updated" } } } }, "/credits/models/{provider}": { "get": { "tags": [ "Catalog" ], "summary": "Read the reviewed inference model contract", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" }, "example": "openai" }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "ETag returned by a previous model-catalog response." } ], "responses": { "200": { "description": "Versioned inference model contract", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "Private cache lifetime and stale-while-revalidate policy." }, "ETag": { "schema": { "type": "string" }, "description": "Strong validator for the complete catalog document." }, "X-Locus-Model-Schema-Version": { "schema": { "type": "string" }, "description": "Machine-readable schema version." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelCatalogResponse" } } } }, "304": { "description": "Catalog is unchanged for the supplied If-None-Match value." }, "404": { "description": "No reviewed model catalog exists for this provider." } } } }, "/credits/catalog/{slug}": { "delete": { "tags": [ "Catalog" ], "summary": "Clear a catalog override", "description": "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: false. This clears configuration only \u2014 it never disables an endpoint.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "provider or provider/endpoint (URL-encoded)." } ], "responses": { "200": { "description": "Override cleared, or already absent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "slug", "cleared" ], "properties": { "success": { "const": true }, "slug": { "type": "string" }, "cleared": { "type": "boolean", "description": "false when there was no override to remove." } }, "additionalProperties": false } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "description": "No such provider or endpoint in the Locus catalog. Clearing an override that was never set is not a 404 \u2014 that returns 200 with cleared: false." } } }, "put": { "tags": [ "Catalog" ], "summary": "Enable/disable or override markup", "description": "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. Enablement resolves endpoint override -> provider override -> platform default. Omitting enabled never changes enablement. Sending enabled on a provider slug resets that provider's endpoint-level enablement overrides to inherit while preserving markup overrides.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PersonalCatalogMutationRequest" }, { "type": "object", "title": "Enterprise catalog mutation", "minProperties": 1, "properties": { "enabled": { "type": "boolean" }, "markupBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "flatMarkupUsdc": { "$ref": "#/components/schemas/DecimalString" } }, "additionalProperties": false } ], "description": "The authenticated account tier selects the accepted branch." } } } }, "responses": { "200": { "description": "Updated configuration", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PersonalCatalogMutationResponse" }, { "type": "object", "title": "Enterprise catalog mutation response", "required": [ "success", "config" ], "properties": { "success": { "const": true }, "config": { "type": "object", "required": [ "endpointSlug", "enabled", "enabledOverride", "markupBps", "flatMarkupUsdc" ], "properties": { "endpointSlug": { "type": "string" }, "enabled": { "type": "boolean", "description": "Effective enablement after this write." }, "enabledOverride": { "type": [ "boolean", "null" ], "description": "This row's override; null means inherit." }, "markupBps": { "type": [ "integer", "null" ] }, "flatMarkupUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false } ] } } } } } }, "get": { "tags": [ "Catalog" ], "summary": "Get one full provider catalog document", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 256 }, "description": "Provider ID for this read operation." } ], "responses": { "200": { "description": "Full enterprise detail or the price-safe personal projection", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogProviderDetailResponse" }, { "$ref": "#/components/schemas/PersonalCatalogProviderDetailResponse" } ] } } } }, "304": { "description": "The tenant-scoped provider detail is unchanged." }, "404": { "description": "Unknown provider." } } } }, "/credits/analytics": { "get": { "tags": [ "Ledger" ], "summary": "Tenant usage analytics", "description": "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 partial UTC day, and is narrowed by the same filter so deltas stay like-for-like; top-ups, allocations, refunds, and open reservations are excluded. usageDrift is null when the optional detector read is temporarily unavailable.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 }, "description": "Legacy form: N whole UTC days ending with today so far. Cannot be combined with from/to. Any value outside the enum \u2014 including a repeated parameter \u2014 is a 400 rather than a silent fall back to the default." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Window start, inclusive. Strict ISO-8601 (must round-trip). Requires to. Must be on or after 2000-01-01T00:00:00.000Z." }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Window end, EXCLUSIVE. Strict ISO-8601. Requires from, must be later than it, and may not be more than 24 hours ahead of the server clock. A window ending in the future gap-fills its trailing buckets with zeros." }, { "name": "bucket", "in": "query", "schema": { "type": "string", "enum": [ "hour", "day", "week", "month" ], "default": "day" }, "description": "Series granularity, aligned to UTC calendar boundaries (weeks start Monday). A window yielding more than 400 buckets is rejected." }, { "name": "initiator", "in": "query", "schema": { "type": "string" }, "description": "Spender reference :, where type is one of oauth_member, end_user, agent_connection, credential, unattributed. The id is the identity analytics ranks by (external user id, Cognito sub, agent-connection id, or API key id); unattributed takes no id." }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider label as analytics reports it, including the literal 'Unknown service' for burns whose provider was never captured." }, { "name": "endpoint", "in": "query", "schema": { "type": "string" }, "description": "Endpoint name. Requires provider." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Row cap applied to services, providers, users, and initiators." } ], "responses": { "200": { "description": "Usage, cost, margin, service, and account rollups", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "400": { "description": "Unsupported range" } } } }, "/credits/ledger": { "get": { "tags": [ "Ledger" ], "summary": "Tenant-wide ledger", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "TOPUP", "BURN", "REFUND", "CLAWBACK", "FEE", "ADJUSTMENT", "ALLOCATION", "PROMO" ] } }, { "name": "externalUserId", "in": "query", "schema": { "$ref": "#/components/schemas/ExternalUserId" } }, { "name": "initiator", "in": "query", "schema": { "type": "string" }, "description": "Spender reference :, matching the analytics initiator identity. Cannot be combined with externalUserId or account=platform; unattributed is not filterable." }, { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Matches the provider recorded on the ledger entry. Legacy entries without provider metadata are excluded from this filtered ledger view." }, { "name": "endpoint", "in": "query", "schema": { "type": "string" }, "description": "metadata.endpoint equality. Requires provider." }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower bound. Strict ISO-8601." }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive upper bound. Strict ISO-8601." }, { "name": "attribution.{key}", "in": "query", "schema": { "type": "string" }, "description": "Equality filter on metadata.attribution., one query parameter per key: attribution.entityId=acct_889. Dot form only \u2014 bracket form is not parsed." }, { "name": "sourceKey", "in": "query", "schema": { "type": "string" }, "description": "Narrow to one ledger event kind, e.g. wapi_burn or stripe_topup." }, { "name": "account", "in": "query", "schema": { "type": "string", "enum": [ "platform" ] }, "description": "Restrict to the tenant's pooled platform account. Mutually exclusive with externalUserId and with an end-user initiator." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Ledger page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantLedgerPage" } } } } } } }, "/credits/webhooks/events": { "get": { "tags": [ "Webhooks" ], "summary": "List durable webhook events", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/WebhookEventType" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Newest events first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventPage" } } } } } } }, "/credits/webhooks/events/{eventId}": { "get": { "tags": [ "Webhooks" ], "summary": "Inspect an event and every delivery attempt", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Immutable envelope and delivery history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventDetail" } } } }, "404": { "description": "Event not found in this tenant" } } } }, "/credits/webhooks/events/{eventId}/replay": { "post": { "tags": [ "Webhooks" ], "summary": "Replay a retained event", "description": "Creates one new attempt using the same stable event ID and current endpoint. Returns 409 while another attempt is pending.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Replay attempted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventDetail" } } } }, "409": { "description": "An attempt is already pending or event retention expired" }, "422": { "description": "Webhook endpoint is not configured" } } } }, "/credits/end-users": { "get": { "tags": [ "End users" ], "summary": "List end-users with balances", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 }, "description": "Case-insensitive substring match on externalUserId." }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "End-user accounts", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "endUsers", "nextCursor" ], "properties": { "success": { "const": true }, "endUsers": { "type": "array", "items": { "$ref": "#/components/schemas/EndUserAccount" } }, "nextCursor": { "type": [ "string", "null" ] } } } } } } } } }, "/credits/end-users/{externalUserId}": { "delete": { "tags": [ "End users" ], "summary": "Retire a test or integration end user without deleting financial history", "description": "Workspace owner or admin 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 the credit account, and marks the identity inactive. Ledger, funding, settlement, replay, and audit rows are retained. Repeating a completed retirement is safe.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "200": { "description": "Retirement converged", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "externalUserId", "retired", "alreadyRetired", "accountId", "revokedTokens", "revokedAgentConnections", "canceledApprovals", "policyReset" ], "properties": { "success": { "const": true }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "retired": { "type": "boolean" }, "alreadyRetired": { "type": "boolean" }, "accountId": { "type": [ "string", "null" ], "format": "uuid" }, "revokedTokens": { "type": "integer", "minimum": 0 }, "revokedAgentConnections": { "type": "integer", "minimum": 0 }, "canceledApprovals": { "type": "integer", "minimum": 0 }, "policyReset": { "type": "boolean" } } } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Workspace owner/admin role and fresh MFA/passkey step-up required" }, "409": { "description": "Balance or asynchronous money work is still open" } } } }, "/credits/end-users/{externalUserId}/token": { "post": { "tags": [ "End users" ], "summary": "Mint an end-user token", "description": "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 of clock skew. There is no refresh token; re-authenticate the user and mint a replacement. A sid-bound token requires the original value in X-Locus-Session-Id whenever used.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserTokenRequest" } } } }, "responses": { "200": { "description": "Token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserTokenResponse" } } } }, "400": { "description": "Invalid externalUserId, expiresIn, sessionId, or unknown field" } } } }, "/credits/end-users/{externalUserId}/policy": { "get": { "tags": [ "End users" ], "summary": "Read an immutable end user's execution policy", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } } ], "responses": { "200": { "description": "Current policy or null", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserPolicyEnvelope" } } } } } }, "put": { "tags": [ "End users" ], "summary": "Create or replace an end user's execution policy", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserPolicyInput" } } } }, "responses": { "200": { "description": "Policy applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserPolicyEnvelope" } } } }, "400": { "description": "Unknown field or invalid exact-credit/count contract" } } }, "delete": { "tags": [ "End users" ], "summary": "Reset an end user's execution policy to no policy", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } } ], "responses": { "200": { "description": "Policy is null", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "externalUserId", "policy", "reset", "priorPolicyId" ], "properties": { "success": { "const": true }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "policy": { "type": "null" }, "reset": { "type": "boolean" }, "priorPolicyId": { "type": [ "string", "null" ], "format": "uuid" } } } } } }, "409": { "description": "An active reservation must capture or release before reset" } } } }, "/credits/end-users/{externalUserId}/policy/events": { "get": { "tags": [ "End users" ], "summary": "List policy allow, deny, capture, release, and reset decisions", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100 } } ], "responses": { "200": { "description": "Newest policy decisions first", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "externalUserId", "events" ], "properties": { "success": { "const": true }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EndUserPolicyEvent" } } } } } } } } } }, "/credits/end-users/{externalUserId}/allocate": { "post": { "tags": [ "End users" ], "summary": "Allocate credits to an end-user", "description": "Atomic platform-pool \u2192 end-user transfer; both sides ledgered. Fails (402) if the pool cannot cover it \u2014 unfunded allocations are impossible. Amounts are exact decimal strings.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "One key per logical transfer; reuse it on retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "credits" ], "properties": { "credits": { "$ref": "#/components/schemas/DecimalString" }, "promo": { "type": "boolean", "description": "Ledger as a promo/comp grant" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Allocation applied; returns both balances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferResult" } } } }, "402": { "description": "Platform pool balance insufficient" } } } }, "/credits/end-users/{externalUserId}/deallocate": { "post": { "tags": [ "End users" ], "summary": "Reverse an allocation", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "One key per logical transfer; reuse it on retries." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "credits" ], "properties": { "credits": { "$ref": "#/components/schemas/DecimalString" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Credits returned to the platform pool", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferResult" } } } } } } }, "/credits/topups/quote": { "post": { "tags": [ "Top-ups" ], "summary": "Quote a top-up (exact-decimal gross-up)", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupQuoteRequest" } } } }, "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "quote" ], "properties": { "success": { "const": true }, "quote": { "$ref": "#/components/schemas/TopupQuote" } } } } } }, "400": { "$ref": "#/components/responses/TopupError" } } } }, "/credits/topups/config": { "get": { "tags": [ "Top-ups" ], "summary": "Get machine-readable top-up constraints", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Tenant-specific amount constraints and denomination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupConstraintsEnvelope" } } } } } } }, "/credits/topups": { "post": { "tags": [ "Top-ups" ], "summary": "Create a hosted checkout session", "description": "Canonical v2 contract. externalUserId present \u2192 end-user top-up. Absent \u2192 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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Reuse for retries of the same checkout creation." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupRequest" } } } }, "responses": { "201": { "description": "Checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupSessionResponse" } } } }, "400": { "description": "Validation or minimum-amount failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupErrorResponse" } } } } } } }, "/credits/topups/{sessionId}": { "get": { "tags": [ "Top-ups" ], "summary": "Get authoritative checkout state", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cs_" } } ], "responses": { "200": { "description": "Checkout state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupStatus" } } } }, "400": { "$ref": "#/components/responses/TopupError" } } } }, "/credits/earnings": { "get": { "tags": [ "Ledger" ], "summary": "Margin earnings", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Accrued / matured / paid-out margin (USD decimal strings)", "content": { "application/json": { "schema": { "type": "object", "properties": { "accrued": { "type": "string" }, "matured": { "type": "string" }, "paidOut": { "type": "string" } } } } } } } } }, "/credits/me/balance": { "get": { "tags": [ "Widget" ], "summary": "Own balance (end-user)", "security": [ { "endUserToken": [] }, { "endUserToken": [], "publishableKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "responses": { "200": { "description": "Balance in the tenant's credit denomination", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "balance" ], "properties": { "success": { "const": true }, "balance": { "type": "object", "required": [ "externalUserId", "balanceUsdc", "balanceCredits", "status" ], "properties": { "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "balanceUsdc": { "$ref": "#/components/schemas/DecimalString" }, "balanceCredits": { "$ref": "#/components/schemas/DecimalString" }, "status": { "type": "string", "enum": [ "active", "frozen" ] } }, "additionalProperties": false } }, "additionalProperties": false } } } } } } }, "/credits/me/catalog": { "get": { "tags": [ "Widget", "Catalog" ], "summary": "Discover APIs available to the authenticated end user", "description": "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 customer-visible effective price. Results sort by stable endpoint ID. Cursors are opaque, filters are exact/case-insensitive, and responses are private/non-cacheable so policy changes are visible on the next request. The end-user token authenticates this read on its own; when a publishable key is sent it must belong to the token's tenant.", "security": [ { "endUserToken": [] }, { "endUserToken": [], "publishableKey": [] } ], "parameters": [ { "name": "provider", "in": "query", "schema": { "type": "string", "maxLength": 128 }, "description": "Exact stable provider ID (case-insensitive)" }, { "name": "category", "in": "query", "schema": { "type": "string", "maxLength": 128 }, "description": "Exact provider category (case-insensitive)" }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 512 }, "description": "Opaque cursor returned by the previous page" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Privacy-safe, policy-filtered provider catalog", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndUserCatalogResponse" } } } } } } }, "/credits/me/ledger": { "get": { "tags": [ "Widget" ], "summary": "Own ledger (end-user)", "description": "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, and internal pricing configuration.", "security": [ { "endUserToken": [] }, { "endUserToken": [], "publishableKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "cursor", "in": "query", "description": "Opaque nextCursor from the previous page.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of transaction-history entries to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "End-user transaction history with internal pricing fields redacted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerPage" } } } } } } }, "/credits/me/topups": { "post": { "tags": [ "Widget" ], "summary": "Open a top-up for self (end-user)", "description": "Identity is derived only from the end-user token. externalUserId is rejected.", "security": [ { "endUserToken": [] }, { "endUserToken": [], "publishableKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupSelfRequest" } } } }, "responses": { "201": { "description": "Checkout session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupSessionResponse" } } } }, "400": { "description": "Validation or minimum-amount failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupErrorResponse" } } } } } } }, "/credits/me/topups/config": { "get": { "tags": [ "Widget" ], "summary": "Get machine-readable top-up constraints", "security": [ { "endUserToken": [] }, { "endUserToken": [], "publishableKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "responses": { "200": { "description": "Amount constraints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupConstraintsEnvelope" } } } } } } }, "/credits/me/topups/{sessionId}": { "get": { "tags": [ "Widget" ], "summary": "Get authoritative state for this user's checkout", "security": [ { "endUserToken": [] }, { "endUserToken": [], "publishableKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cs_" } } ], "responses": { "200": { "description": "Checkout state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupStatus" } } } }, "400": { "$ref": "#/components/responses/TopupError" } } } }, "/credits/md": { "get": { "tags": [ "Burn" ], "summary": "Per-tenant generated docs (markdown)", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Provider detail page" } ], "responses": { "200": { "description": "Markdown", "content": { "text/markdown": {} } }, "403": { "description": "Enterprise tier or tenant:read scope required" }, "404": { "description": "Unknown or disabled provider" } } } }, "/credits/mcp": { "post": { "tags": [ "MCP" ], "summary": "Hosted MCP server (stateless Streamable HTTP)", "description": "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 agent connections remain compatibility credentials. This transport is stateless: it issues no MCP-Session-Id, retains no resumable SSE stream, and recomputes the authenticated tenant catalog on every request. For tools/call, inspect result.isError even when HTTP and JSON-RPC both succeeded.", "security": [ { "mcpOAuth": [ "mcp:read" ] }, { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "MCP-Protocol-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2025-06-18" }, "description": "Negotiated MCP version on requests after initialize. The server also accepts 2025-03-26 clients." }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json, text/event-stream" }, "description": "Streamable HTTP clients advertise both media types. This stateless server returns application/json." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcRequest" }, "examples": { "listTools": { "value": { "jsonrpc": "2.0", "id": "list-1", "method": "tools/list", "params": {} } }, "callTool": { "value": { "jsonrpc": "2.0", "id": "call-1", "method": "tools/call", "params": { "name": "execute", "arguments": { "slug": "tavily/search", "args": { "query": "agent payment infrastructure" }, "idempotency_key": "job-42-search", "approval_token": "" } } } } } } } }, "responses": { "200": { "description": "JSON-RPC success or protocol error. A tools/call application failure is a success envelope whose result.isError is true.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/McpJsonRpcSuccess" }, { "$ref": "#/components/schemas/McpJsonRpcError" } ] } } } }, "202": { "description": "Accepted MCP notification; no JSON-RPC response body." }, "400": { "description": "Malformed JSON-RPC or unsupported Streamable HTTP request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcError" } } } }, "401": { "description": "OAuth authorization is missing or invalid, or a compatibility secret-key, end-user, or agent-connection credential is invalid. Sandbox and publishable keys are not accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcError" } } } }, "403": { "description": "The OAuth token lacks mcp:read or, for billed tools/call, mcp:execute; or an authenticated compatibility principal is denied by tenant, origin, or policy controls.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcError" } } } }, "405": { "description": "POST is the only supported method; stateless sessions cannot be fetched or deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcError" } } } }, "413": { "description": "Encoded JSON request exceeds the 4 MiB Locus Pro execution limit", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code", "limitBytes" ], "properties": { "success": { "const": false }, "error": { "const": "Payload too large" }, "code": { "const": "REQUEST_BODY_TOO_LARGE" }, "limitBytes": { "const": 4194304 } }, "additionalProperties": false } } } }, "500": { "description": "Request-scoped MCP transport failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpJsonRpcError" } } } } } }, "get": { "tags": [ "MCP" ], "summary": "Unsupported in stateless mode", "security": [ { "mcpOAuth": [ "mcp:read" ] }, { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "responses": { "401": { "description": "Missing or invalid OAuth or compatibility credential" }, "403": { "description": "OAuth scope, origin, tenant, or policy denied the request" }, "405": { "description": "No resumable session or SSE stream exists" } } }, "delete": { "tags": [ "MCP" ], "summary": "Unsupported in stateless mode", "security": [ { "mcpOAuth": [ "mcp:read" ] }, { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "responses": { "401": { "description": "Missing or invalid OAuth or compatibility credential" }, "403": { "description": "OAuth scope, origin, tenant, or policy denied the request" }, "405": { "description": "No server-side session exists to delete" } } } }, "/wrapped/credits/v1/chat/completions": { "post": { "tags": [ "Burn" ], "summary": "OpenAI-compatible metered chat completions", "description": "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.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One key per model request body; reuse it on an identical retry." }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" } }, { "name": "X-Locus-Agent-Loop-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Required when this user's policy sets maxCallsPerLoop." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAIChatCompletionRequest" } } } }, "responses": { "200": { "description": "OpenAI JSON response, or unbuffered OpenAI SSE when stream=true", "headers": { "X-Locus-Api-Call-Id": { "schema": { "type": "string", "format": "uuid" } }, "X-Locus-Credits-Charged": { "schema": { "$ref": "#/components/schemas/DecimalString" } }, "X-Locus-Credits-Balance": { "schema": { "$ref": "#/components/schemas/DecimalString" } }, "X-Locus-Stream-Billing": { "schema": { "const": "captured-before-delivery" } }, "X-Locus-Stream-Status-Url": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } }, "text/event-stream": { "schema": { "type": "string", "description": "OpenAI data: JSON chunks followed by data: [DONE]. Text and tool_calls deltas are passed through byte-for-byte." } } } }, "400": { "description": "Local request validation or provider validation error before stream delivery" }, "402": { "description": "Insufficient credits; no provider dispatch" }, "403": { "description": "Endpoint or native end-user policy denied execution" }, "409": { "description": "Idempotency conflict or stream_not_replayable status response" }, "413": { "description": "Encoded JSON request exceeds the 4 MiB Locus Pro chat limit", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code", "limitBytes" ], "properties": { "success": { "const": false }, "error": { "const": "Payload too large" }, "code": { "const": "REQUEST_BODY_TOO_LARGE" }, "limitBytes": { "const": 4194304 } }, "additionalProperties": false } } } }, "429": { "description": "Tenant or provider rate limit before stream delivery" }, "502": { "description": "Provider/transport failure before stream delivery; reservation released" }, "503": { "description": "Provider configuration or stream settlement pending" }, "504": { "description": "Provider timeout before stream delivery; reservation released" } } } }, "/wrapped/credits/calls/{callId}": { "get": { "tags": [ "Burn" ], "summary": "Read authoritative stream state and final billing", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" }, "description": "Secret-key callers must repeat the original end user." } ], "responses": { "200": { "description": "Call ownership verified; state and final credit values returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsCallStatus" } } } }, "404": { "description": "Call not found for this credit account" } } } }, "/wrapped/credits/{provider}/{endpoint}": { "post": { "tags": [ "Burn" ], "summary": "Metered pay-per-use call", "description": "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 or end-user-bound Agent Connection) charges that user's account at your effective price; a secret-key call without it or a platform-mode Agent Connection charges your platform account at base price with zero markup.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "provider", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "endpoint", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Required. Missing \u2192 400. Same key + different body \u2192 409. Retries replay the stored outcome." }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Upstream-shaped request body (see the per-endpoint docs at /credits/md)" } } } }, "responses": { "200": { "description": "Raw upstream response", "headers": { "X-Locus-Credits-Charged": { "schema": { "type": "string" }, "description": "Charged amount in the tenant's credit denomination" }, "X-Locus-Credits-Balance": { "schema": { "type": "string" }, "description": "Remaining balance in credits" }, "X-Locus-Cost-Usd": { "schema": { "type": "string" }, "description": "Base cost in USD \u2014 tenant secret/sandbox credentials and platform-mode Agent Connections only" }, "X-Locus-Model": { "schema": { "type": "string" }, "description": "Inference model reported by the provider, when available" }, "X-Locus-Finish-Reason": { "schema": { "type": "string" }, "description": "Normalized provider finish or stop reason, when available" }, "X-Locus-Input-Tokens": { "schema": { "type": "integer", "minimum": 0 }, "description": "Provider-reported input tokens" }, "X-Locus-Visible-Output-Tokens": { "schema": { "type": "integer", "minimum": 0 }, "description": "Output tokens excluding provider-reported reasoning tokens" }, "X-Locus-Reasoning-Tokens": { "schema": { "type": "integer", "minimum": 0 }, "description": "Provider-reported hidden reasoning or thinking tokens" }, "X-Locus-Billed-Tokens": { "schema": { "type": "integer", "minimum": 0 }, "description": "Provider-reported total billed tokens" } } }, "400": { "description": "Missing Idempotency-Key, locally invalid request, or caller-correctable upstream validation error", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UpstreamWrapperError" }, { "type": "object", "additionalProperties": true } ] } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "message", "requiredCredits", "availableCredits", "docsUrl" ], "properties": { "error": { "const": "Insufficient credits" }, "message": { "type": "string" }, "requiredCredits": { "$ref": "#/components/schemas/DecimalString" }, "availableCredits": { "$ref": "#/components/schemas/DecimalString" }, "docsUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false } } } }, "403": { "description": "The call was refused before dispatch and no credits moved. Either the endpoint is disabled for this tenant or outside the credential's scope, or the workspace has reached its monthly spend limit \u2014 the latter carries code TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED and is terminal until resetsAt.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WorkspaceSpendLimitDenial" }, { "type": "object", "additionalProperties": true, "description": "Endpoint disabled, out of credential scope, or denied by the end user's execution policy." } ] } } } }, "409": { "description": "Idempotency-Key reused with a different body" }, "422": { "description": "Caller-correctable upstream validation error; credits are released", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpstreamWrapperError" } } } } } } }, "/credits/.well-known/end-user-jwks.json": { "get": { "tags": [ "End users" ], "summary": "Public JWKS for end-user tokens", "description": "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.", "security": [], "responses": { "200": { "description": "JWK Set", "headers": { "Cache-Control": { "schema": { "const": "public, max-age=300, must-revalidate" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "type": "object", "required": [ "kty", "n", "e", "alg", "use", "kid" ], "properties": { "kty": { "const": "RSA" }, "n": { "type": "string" }, "e": { "type": "string" }, "alg": { "const": "RS256" }, "use": { "const": "sig" }, "kid": { "type": "string" } } } } } } } } } } } }, "/credits/tenants/me/spend-controls": { "get": { "tags": [ "Tenants" ], "summary": "Read account spend and balance controls", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Current controls and window position", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "controls" ], "properties": { "success": { "const": true }, "controls": { "$ref": "#/components/schemas/WorkspaceSpendControls" } }, "additionalProperties": false } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } }, "put": { "tags": [ "Tenants" ], "summary": "Set or clear account spend and balance controls", "description": "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 exceed monthlyLimitUsd. Once committed spend reaches the ceiling, burns are denied with TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED until the window resets \u2014 the limit bounds new spend and never cancels in-flight calls. Personal changes require the account owner on a session authenticated within the last ten minutes; enterprise changes require a workspace owner or admin with MFA or passkey step-up in that window.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "monthlyLimitUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "Hard monthly ceiling, or null to remove it." }, "alertThresholdUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "Monthly spend email trigger, or null to remove it. Lowering it below current spend triggers the alert immediately." }, "lowBalanceAlertUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "Remaining prepaid-balance threshold for a one-time email, or null to remove it. The alert re-arms after the balance recovers above the threshold." } }, "additionalProperties": false }, "examples": { "setBoth": { "summary": "Cap at $5,000 and alert at $4,000", "value": { "monthlyLimitUsd": "5000.00", "alertThresholdUsd": "4000.00" } }, "clearLimit": { "summary": "Remove the hard cap, keep the alerts", "value": { "monthlyLimitUsd": null } }, "setLowBalanceAlert": { "summary": "Email when the remaining balance reaches $10", "value": { "lowBalanceAlertUsd": "10.00" } } } } } }, "responses": { "200": { "description": "Updated controls", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "controls" ], "properties": { "success": { "const": true }, "controls": { "$ref": "#/components/schemas/WorkspaceSpendControls" } }, "additionalProperties": false } } } }, "400": { "description": "Unknown field, no field supplied, a non-positive or over-precise amount, or an alert threshold above the limit." }, "403": { "description": "RECENT_AUTHENTICATION_REQUIRED or OWNER_REQUIRED for a Personal account; STEP_UP_REQUIRED for an enterprise owner/admin without recent MFA/passkey step-up or for a non-workspace-administrator principal; or INSUFFICIENT_SCOPE." } } } }, "/credits/tenants/me/keys/{keyId}": { "delete": { "tags": [ "Tenants" ], "summary": "Revoke an API key", "description": "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 a workspace owner or admin with MFA step-up completed in the last ten minutes.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Key record id from GET /credits/tenants/me/keys." }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Recorded on the credential audit event." } }, "additionalProperties": false } } } }, "responses": { "204": { "description": "Revoked. The key is dead as of this response. Idempotent: revoking an already-revoked key returns 204 again without a second audit event." }, "400": { "description": "Invalid reason (over 200 characters, control characters, or not a string), or an unknown body field." }, "403": { "description": "STEP_UP_REQUIRED or INSUFFICIENT_SCOPE." }, "404": { "description": "No such key in this workspace (malformed ids included)." } } }, "patch": { "tags": [ "Tenants" ], "summary": "Rename an API key", "description": "Metadata-only: the credential itself never changes. Appends a RENAMED credential audit event carrying the previous name. Requires a workspace owner or admin with MFA step-up completed in the last ten minutes.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Key record id from GET /credits/tenants/me/keys." }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Updated key metadata under keyMetadata." }, "400": { "description": "Invalid name (empty, over 100 characters, or control characters), an unknown body field, or the key is revoked." }, "403": { "description": "STEP_UP_REQUIRED or INSUFFICIENT_SCOPE." }, "404": { "description": "No such key in this workspace (malformed ids included)." } } } }, "/credits/tenants/me/credentials/audit": { "get": { "tags": [ "Tenants" ], "summary": "Credential lifecycle audit", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "Clamped to 1-200." } ], "responses": { "200": { "description": "Credential audit events", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "events" ], "properties": { "success": { "const": true }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CredentialAuditEvent" } } }, "additionalProperties": false } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/credits/tenants/me/security/audit": { "get": { "tags": [ "Tenants" ], "summary": "Sensitive-mutation security audit", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 100 }, "description": "Clamped to 1-200." } ], "responses": { "200": { "description": "Security audit events", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "events" ], "properties": { "success": { "const": true }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityAuditEvent" } } }, "additionalProperties": false } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/credits/pricing/explain": { "get": { "tags": [ "Catalog" ], "summary": "Explain one endpoint's price", "description": "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 base.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "provider", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Provider id, for example tavily." }, { "name": "endpoint", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Endpoint name within that provider, for example search." }, { "name": "args", "in": "query", "schema": { "type": "string" }, "description": "JSON-encoded call arguments, used to price metered endpoints. Malformed JSON returns 400; any other JSON value parses and is passed through to the cost function, which ignores what it cannot use." } ], "responses": { "200": { "description": "Price breakdown", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "explain" ], "properties": { "success": { "const": true }, "explain": { "$ref": "#/components/schemas/PricingExplain" } }, "additionalProperties": false } } } }, "400": { "description": "provider or endpoint missing, or args is not a JSON-encoded object." }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "description": "Unknown provider or endpoint." } } } }, "/credits/end-users/{externalUserId}/tokens": { "get": { "tags": [ "End users" ], "summary": "List an end user's minted tokens", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } } ], "responses": { "200": { "description": "Token metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "tokens" ], "properties": { "success": { "const": true }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/EndUserTokenRecord" } } }, "additionalProperties": false } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/credits/end-users/{externalUserId}/tokens/{tokenId}": { "delete": { "tags": [ "End users" ], "summary": "Revoke an end-user token", "description": "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 \u2014 bearer tokens are otherwise replayable until they expire.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "externalUserId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ExternalUserId" } }, { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Token record id from GET /credits/end-users/{externalUserId}/tokens." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Recorded on the credential audit event." } }, "additionalProperties": false } } } }, "responses": { "204": { "description": "Revoked." }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "description": "No such token for this end user." } } } }, "/credits/stripe/operations": { "get": { "tags": [ "Top-ups" ], "summary": "Top-up and Stripe ingress health", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Inbox and activity status", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "operations" ], "properties": { "success": { "const": true }, "operations": { "type": "object", "required": [ "inbox", "activity" ], "properties": { "inbox": { "type": "object", "additionalProperties": true, "description": "Signed Stripe webhook inbox state, including unprocessed and dead-lettered counts." }, "activity": { "type": "object", "additionalProperties": true, "description": "Recent top-up session and settlement activity for this workspace." } } } }, "additionalProperties": false } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/credits/billing/commercial": { "get": { "tags": [ "Ledger" ], "summary": "Commercial agreement and invoice history", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Commercial billing summary", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "commercial" ], "properties": { "success": { "const": true }, "commercial": { "type": "object", "additionalProperties": true, "description": "Agreement terms, current-period estimate, and invoice history." } }, "additionalProperties": false } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/credits/connect/stripe/status": { "get": { "tags": [ "Ledger" ], "summary": "Stripe Connect status for payouts", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Connect status", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "status" ], "properties": { "success": { "const": true }, "status": { "$ref": "#/components/schemas/StripeConnectStatus" } }, "additionalProperties": false } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/credits/connect/stripe/authorize": { "get": { "tags": [ "Ledger" ], "summary": "Begin Stripe Connect onboarding", "description": "Returns the Stripe consent URL to send a workspace owner or admin to. Dashboard-only: a tenant secret key cannot start this flow, and evaluation workspaces are refused until a commercial agreement is active. Requires an owner or admin with MFA step-up completed in the last ten minutes.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "returnTo", "in": "query", "schema": { "type": "string" }, "description": "Absolute dashboard URL to return to after consent. Defaults to the billing page." }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "200": { "description": "Consent URL", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "url" ], "properties": { "success": { "const": true }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": false } } } }, "403": { "description": "STEP_UP_REQUIRED, a non-Cognito principal, INSUFFICIENT_SCOPE, or payouts locked for an evaluation workspace." } } } }, "/credits/connect/stripe/callback": { "get": { "tags": [ "Ledger" ], "summary": "Stripe Connect OAuth redirect target", "description": "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 \u2014 do not call it yourself. It always answers with a 302 back to the dashboard, carrying connected=1 on success or connect_error= on failure or cancellation.", "security": [], "parameters": [ { "name": "code", "in": "query", "schema": { "type": "string" }, "description": "Stripe authorization code." }, { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Signed state minted by the authorize step." }, { "name": "error", "in": "query", "schema": { "type": "string" }, "description": "Present when the workspace administrator cancelled consent." } ], "responses": { "302": { "description": "Redirect to the dashboard with connected=1 or connect_error=." } } } }, "/credits/connect/stripe/disconnect": { "post": { "tags": [ "Ledger" ], "summary": "Disconnect Stripe and revert to USDC payouts", "description": "Unlinks the Stripe account and returns the workspace to USDC margin payouts. Dashboard-only, and requires a workspace owner or admin with MFA step-up completed in the last ten minutes.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "responses": { "200": { "description": "Disconnected", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } }, "additionalProperties": false } } } }, "403": { "description": "STEP_UP_REQUIRED, a non-Cognito principal, or INSUFFICIENT_SCOPE." } } } }, "/credits/mcp/docs": { "get": { "tags": [ "MCP" ], "summary": "Machine-readable MCP connection guide", "description": "Public connection guide with the MCP URL, OAuth discovery metadata, plugin installation commands, and client configuration. Plugin installation uses these published commands; it does not require a separate plugin-management API.", "security": [], "responses": { "200": { "description": "Connection guide", "headers": { "Cache-Control": { "schema": { "const": "public, max-age=300" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "required": [ "name", "server_url", "resource_metadata", "authorization_server_metadata" ], "properties": { "name": { "const": "Locus Pro MCP" }, "server_url": { "type": "string", "format": "uri" }, "resource_metadata": { "type": "string", "format": "uri", "description": "RFC 9728 protected-resource metadata URL." }, "authorization_server_metadata": { "type": "string", "format": "uri", "description": "RFC 8414 authorization-server metadata URL." }, "client_configurations": { "type": "object", "additionalProperties": true }, "scopes": { "type": "object", "additionalProperties": true }, "oauth_lifecycle": { "type": "object", "additionalProperties": true }, "plugin": { "type": "object", "additionalProperties": true, "description": "Marketplace and supported client installation commands." } } } } } } } } }, "/credits/tenants/me/keys/{keyId}/rotate": { "post": { "tags": [ "Tenants" ], "summary": "Rotate ONE key; sibling keys of the same kind keep working", "description": "The replacement inherits the target's name, scopes, endpoint allowlist, pricing, audience (legacy policy-bearing rows are normalized to the execution audience), and \u2014 unless expiresIn is passed \u2014 its expiry deadline. A human caller cannot rotate a secret key whose inherited scopes include authority absent from their own effective membership scopes. Only the target is superseded: with gracePeriodSeconds > 0 it keeps authenticating until the overlap ends (capped at the target's own expiry), otherwise it is revoked with this response. Rotating a key that is already rotating out is rejected (rotate its replacement instead), as is rotating an expired key without a fresh expiresIn. This is the rotation the dashboard uses; the kind-level /keys/rotate remains the rotate-everything cutover. Requires a workspace owner or admin with MFA or passkey step-up completed in the last ten minutes.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "keyId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Key record id from GET /credits/tenants/me/keys." }, { "$ref": "#/components/parameters/WorkspaceStepUpHeader" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "gracePeriodSeconds": { "type": "integer", "minimum": 0, "maximum": 86400, "description": "Overlap during which the old key still works. Omitted or 0 means it dies with this response." }, "expiresIn": { "type": "integer", "minimum": 60, "maximum": 31536000, "description": "Lifetime of the replacement in seconds. Omit to inherit the target's deadline." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "New raw key (returned exactly once) with keyMetadata." }, "400": { "description": "Target is revoked, already rotating out, expired without a fresh expiresIn, carries a secret scope the acting member does not hold \u2014 or an unknown body field." }, "403": { "description": "STEP_UP_REQUIRED or INSUFFICIENT_SCOPE." }, "404": { "description": "No such key in this workspace (malformed ids included)." } } } }, "/credits/agent/onboarding": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Read the agent-native onboarding contract", "description": "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.", "security": [], "responses": { "200": { "description": "Current onboarding steps, URLs, and security boundaries" } } } }, "/credits/agent/register": { "post": { "tags": [ "Agent-native onboarding" ], "summary": "Begin or complete verified agent-owned signup", "description": "A first request creates only a 30-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/subject pair is the durable one-account boundary. No free or bonus credits are issued.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentNativeRegistrationRequest" } } } }, "responses": { "200": { "description": "Existing verified account replayed, renewed, or recovered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOwnedAccountEnvelope" } } } }, "201": { "description": "Verified agent-owned account created at a zero balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOwnedAccountEnvelope" } } } }, "202": { "description": "Only a short-lived pending signup exists; AgentID verification is required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSignupPendingEnvelope" } } } }, "409": { "description": "The token is bound to different account details" }, "429": { "description": "Registration rate limit exceeded" } } } }, "/credits/agent/account": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Read the agent-owned account", "description": "Returns only the authenticated self-registered account, its usable pooled balance, expiry, links, and next action. Tenant-managed agent connections are rejected.", "security": [ { "agentConnection": [] } ], "responses": { "200": { "description": "Agent-owned account state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOwnedAccountEnvelope" } } } }, "403": { "description": "The credential belongs to a tenant-managed connection" } } } }, "/credits/agent/credential/rotate": { "post": { "tags": [ "Agent-native onboarding" ], "summary": "Rotate the agent-owned credential", "description": "Atomically replaces the account recovery digest and bearer credential from a newly generated 24-byte base64url token, then extends expiry by 365 days.", "security": [ { "agentConnection": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "registrationToken" ], "properties": { "registrationToken": { "$ref": "#/components/schemas/AgentRegistrationToken" } } } } } }, "responses": { "200": { "description": "Credential rotated and returned once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentOwnedAccountEnvelope" } } } }, "403": { "description": "Not the self-registered account credential" }, "409": { "description": "Credential expired, changed concurrently, or replacement token already exists" } } } }, "/credits/agent/catalog/search": { "post": { "tags": [ "Agent-native onboarding" ], "summary": "Search capabilities for an agent-owned account", "description": "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.", "security": [ { "agentConnection": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 256 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "Ranked price-free capability metadata with current enablement" }, "403": { "description": "Not the self-registered account credential" } } } }, "/credits/agent/catalog": { "put": { "tags": [ "Agent-native onboarding" ], "summary": "Enable or disable one agent-owned capability", "description": "Changes only the enabled flag for one exact catalog slug on the self-registered account. It cannot change pricing or any other tenant setting.", "security": [ { "agentConnection": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "slug", "enabled" ], "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 512 }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Effective capability enablement" }, "403": { "description": "Not the self-registered account credential" }, "404": { "description": "Unknown catalog slug" } } } }, "/credits/agent/funding/config": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Read agent funding constraints", "description": "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.", "security": [ { "agentConnection": [] } ], "responses": { "200": { "description": "Funding constraints and Checkout properties" }, "403": { "description": "Not the self-registered account credential" } } } }, "/credits/agent/funding-sessions": { "post": { "tags": [ "Agent-native onboarding" ], "summary": "Create a human funding handoff", "description": "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.", "security": [ { "agentConnection": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFundingAmount" } } } }, "responses": { "201": { "description": "Stripe funding handoff created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFundingSession" } } } }, "400": { "description": "Invalid amount or missing Idempotency-Key" }, "403": { "description": "Not the self-registered account credential or funding is disabled" }, "429": { "description": "Funding-link rate limit exceeded" } } } }, "/credits/agent/funding-sessions/{sessionId}": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Poll an agent funding handoff", "description": "Returns ready only after the signed Stripe webhook has been durably consumed and the credit ledger balance is usable.", "security": [ { "agentConnection": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cs_" } } ], "responses": { "200": { "description": "Current authenticated funding state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFundingStatus" } } } }, "404": { "description": "Session does not belong to this agent account" } } } }, "/credits/agent/funding-sessions/public/{sessionId}": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Read the payer-safe funding result", "description": "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.", "security": [], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^cs_" } } ], "responses": { "200": { "description": "Payer-safe funding state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFundingPublicStatus" } } } }, "404": { "description": "Unknown funding session" }, "429": { "description": "Public polling rate limit exceeded" } } } }, "/credits/auth/signup": { "post": { "tags": [ "Authentication" ], "summary": "Start a self-serve Locus Pro account", "description": "Creates an unconfirmed Cognito identity and sends a 6-digit email code. It does not provision a workspace or grant credits. Passwords require 8\u2013256 characters with uppercase, lowercase, and numeric characters.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 256 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Verification code sent", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "required": [ "email", "userConfirmed" ], "properties": { "email": { "type": "string", "format": "email" }, "userConfirmed": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid email, name, or password" }, "409": { "description": "The account already exists; sign in or reset its password" }, "429": { "description": "Signup rate limit exceeded" } } } }, "/credits/auth/signup/confirm": { "post": { "tags": [ "Authentication" ], "summary": "Verify email and create the self-serve workspace", "description": "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.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "code", "password", "workspaceName" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "code": { "type": "string", "pattern": "^[0-9]{6}$" }, "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 256 }, "workspaceName": { "type": "string", "minLength": 1, "maxLength": 160 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Replay returned the already-provisioned workspace" }, "201": { "description": "Workspace created; returns dashboard tokens or an MFA challenge, plus tenantId" }, "400": { "description": "Invalid or expired verification code or invalid fields" }, "401": { "description": "The password does not match the confirmed identity" }, "403": { "description": "Email is not verified" }, "429": { "description": "Verification rate limit exceeded" } } } }, "/credits/auth/signup/resend": { "post": { "tags": [ "Authentication" ], "summary": "Resend a signup verification code", "description": "Always returns the same success shape for a syntactically valid email, whether or not an unconfirmed identity exists.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Generic resend acknowledgement" }, "400": { "description": "Invalid email" }, "429": { "description": "Signup rate limit exceeded" } } } }, "/credits/tenants/self-serve": { "post": { "tags": [ "Tenants" ], "summary": "Resume interrupted self-serve workspace provisioning", "description": "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.", "security": [ { "dashboardSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workspaceName" ], "properties": { "workspaceName": { "type": "string", "minLength": 1, "maxLength": 160 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Existing workspace returned with alreadyProvisioned=true" }, "201": { "description": "Workspace created" }, "401": { "description": "Authentication required" }, "403": { "description": "Token subject mismatch or email is not verified" } } } }, "/credits/router/settings": { "get": { "tags": [ "Recipes" ], "summary": "Read Recipe defaults and eligible providers", "description": "Enterprise-only management read; requires tenant:read.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "Saved settings and provider availability", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Enterprise tier and tenant:read scope required" } } }, "put": { "tags": [ "Recipes" ], "summary": "Update Recipe defaults", "description": "Enterprise-only management update. Legacy strategy is translated when mode is absent; legacy rails is accepted and ignored.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "webSearch" ], "properties": { "webSearch": { "type": "object", "additionalProperties": false, "properties": { "mode": { "type": "string", "enum": [ "fast", "balanced", "comprehensive" ] }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 20 }, "maxProviders": { "type": "integer", "minimum": 1, "maximum": 13 }, "strategy": { "type": "string", "enum": [ "balanced", "cost", "quality", "speed" ], "deprecated": true, "description": "Legacy v1 selector. When mode is omitted, quality maps to comprehensive, cost/speed map to fast, and balanced maps to balanced." }, "topic": { "type": "string", "enum": [ "general", "news" ] }, "includeImages": { "type": "boolean" }, "providers": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "null allows every registered provider; an array is a hard allowlist." }, "rails": { "type": "array", "items": { "type": "string", "enum": [ "api-key", "x402", "mpp" ] }, "deprecated": true, "description": "Legacy v1 payment-path allowlist. Accepted but ignored because Locus chooses each provider payment path internally." } } } } } } } }, "responses": { "200": { "description": "Updated settings and provider availability", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Enterprise tier and catalog:write scope required" } } } }, "/credits/router/providers/{providerId}/enable": { "post": { "tags": [ "Recipes" ], "summary": "Enable a provider for Recipes", "description": "Enterprise-only management update; requires catalog:write.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated settings and provider availability", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Enterprise tier and catalog:write scope required" } } } }, "/credits/router/preview": { "post": { "tags": [ "Recipes" ], "summary": "Preview the saved multi-provider web-search plan", "description": "Enterprise-only free preview; requires tenant:read.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebSearchRequest" } } } }, "responses": { "200": { "description": "Free routing plan and current estimate", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "Enterprise tier and tenant:read scope required" } } } }, "/wrapped/credits/router/web-search": { "post": { "tags": [ "Recipes" ], "summary": "Run Web Search", "description": "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.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Reuse the same value only when retrying the same logical request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebSearchRequest" } } } }, "responses": { "200": { "description": "Result, sources, and billing receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebSearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Capability, provider, policy, or spend limit denied the request" }, "409": { "description": "The aggregate tenant-aware estimate exceeds maxCredits" } } } }, "/wrapped/credits/router/web-search/preview": { "post": { "tags": [ "Recipes" ], "summary": "Preview Web Search", "description": "Plans eligible providers and returns the current tenant-aware estimate without calling a provider or burning credits.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebSearchRequest" } } } }, "responses": { "200": { "description": "Free routing plan and current estimate", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Capability, provider, policy, or spend limit denied the request" }, "409": { "description": "The aggregate tenant-aware estimate exceeds maxCredits" } } } }, "/wrapped/credits/router/web-research": { "post": { "tags": [ "Recipes" ], "summary": "Run Web Research", "description": "With effort set, returns a grounded answer with citations. Without effort, uses the legacy structured-source or multi-provider evidence contract.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Reuse the same value only when retrying the same logical request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebResearchRequest" } } } }, "responses": { "200": { "description": "Result, sources, and billing receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebResearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Capability, provider, policy, or spend limit denied the request" }, "409": { "description": "The aggregate tenant-aware estimate exceeds maxCredits" } } } }, "/wrapped/credits/router/web-research/preview": { "post": { "tags": [ "Recipes" ], "summary": "Preview Web Research", "description": "Plans eligible providers and returns the current tenant-aware estimate without calling a provider or burning credits.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebResearchRequest" } } } }, "responses": { "200": { "description": "Free routing plan and current estimate", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Capability, provider, policy, or spend limit denied the request" }, "409": { "description": "The aggregate tenant-aware estimate exceeds maxCredits" } } } }, "/credits/agent/identity/agentid": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Read the Locus AgentID client descriptor", "security": [], "responses": { "200": { "description": "OpenID client, callback, and canonical skill URLs" } } } }, "/credits/agent/identity/agentid/callback": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Complete AgentID authorization-code verification", "description": "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.", "security": [], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "iss", "in": "query", "required": true, "schema": { "type": "string", "const": "https://auth.agentid.com" }, "description": "Required RFC 9207 authorization-response issuer; it must match the trusted AgentID issuer." } ], "responses": { "200": { "description": "Static success page; replay registration to activate" }, "400": { "description": "Invalid, denied, expired, or unverifiable AgentID callback" }, "503": { "description": "AgentID or signup configuration is temporarily unavailable" } } } }, "/credits/ledger/summary": { "get": { "tags": [ "Ledger" ], "summary": "Ledger row counts for a filter", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "TOPUP", "BURN", "REFUND", "CLAWBACK", "FEE", "ADJUSTMENT", "ALLOCATION", "PROMO" ] } }, { "name": "externalUserId", "in": "query", "schema": { "$ref": "#/components/schemas/ExternalUserId" } }, { "name": "initiator", "in": "query", "schema": { "type": "string" }, "description": "Spender reference :, matching the analytics initiator identity." }, { "name": "provider", "in": "query", "schema": { "type": "string" } }, { "name": "endpoint", "in": "query", "schema": { "type": "string" }, "description": "Requires provider." }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "attribution.{key}", "in": "query", "schema": { "type": "string" }, "description": "Equality filter on metadata.attribution., one parameter per key. Dot form only." }, { "name": "sourceKey", "in": "query", "schema": { "type": "string" } }, { "name": "account", "in": "query", "schema": { "type": "string", "enum": [ "platform" ] } } ], "responses": { "200": { "description": "Total row count, plus per-category counts and amounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantLedgerSummary" } } } } } } }, "/wrapped/credits/router/capabilities": { "get": { "tags": [ "Recipes" ], "summary": "Read Recipes and provider availability", "description": "Returns the system-managed routing capabilities, saved settings, and current provider availability for the authenticated caller.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "responses": { "200": { "description": "Routing capabilities, settings, and provider availability", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid execution credential" }, "403": { "description": "Credential or account policy denied discovery" } } } }, "/credits/tools/search": { "post": { "tags": [ "Catalog" ], "summary": "Search executable and requestable tools", "description": "REST counterpart to MCP search_apis. Returns compact ranked summaries and routes a selected result through /credits/tools/describe. Workspace and agent principals see enabled and requestable disabled tools by default; end-user-bound callers see enabled tools only, and an account setting may choose enabled-only discovery. Results honor key endpoint allowlists, agent-connection scopes, and end-user policies. Secret keys require tenant:read rather than credits:move. This operation does not call a provider or burn credits.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" }, "description": "Optional end-user identity for a tenant secret key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trimmed natural-language capability, provider, or tool query. Optional with category or pack." }, "category": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Live canonical category ID or unambiguous alias." }, "pack": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Live curated-pack ID or unambiguous alias." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 500 }, "include_facets": { "type": "boolean", "default": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Ranked compact tool summaries", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolSearchResponse" } } } }, "400": { "description": "Invalid search scope, group, or scoped cursor" }, "401": { "description": "Missing or invalid execution credential" }, "500": { "description": "Tool search failed" } } } }, "/credits/mcp/.well-known/oauth-protected-resource": { "get": { "tags": [ "MCP" ], "summary": "Discover the MCP protected resource (compatibility alias)", "description": "API-prefixed compatibility alias for the canonical RFC 9728 metadata path.", "security": [], "responses": { "200": { "description": "Protected-resource metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpProtectedResourceMetadata" } } } } } } }, "/credits/mcp/oauth/.well-known/oauth-authorization-server": { "get": { "tags": [ "MCP" ], "summary": "Discover the MCP authorization server (compatibility alias)", "description": "API-prefixed compatibility alias for the canonical RFC 8414 metadata path.", "security": [], "responses": { "200": { "description": "Authorization-server metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAuthorizationServerMetadata" } } } } } } }, "/credits/mcp/oauth/authorize": { "get": { "tags": [ "MCP" ], "summary": "Start MCP OAuth authorization", "description": "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.", "security": [], "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "type": "string", "const": "code" } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 2048 } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri", "maxLength": 2048 } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "type": "string", "const": "S256" } }, { "name": "resource", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Exact Locus Pro MCP resource URL." }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 512, "example": "mcp:read mcp:execute offline_access" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048 } } ], "responses": { "302": { "description": "Redirect to consent, or to the registered redirect URI with an OAuth error" }, "400": { "description": "Invalid client or request before a safe redirect URI can be established", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } } } } }, "/credits/mcp/oauth/token": { "post": { "tags": [ "MCP" ], "summary": "Exchange or refresh an MCP OAuth token", "description": "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 rotate on every successful use.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/McpOAuthTokenRequest" } } } }, "responses": { "200": { "description": "Resource-bound bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthTokenResponse" } } } }, "400": { "description": "Invalid request, grant, target, or grant type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "401": { "description": "Unknown client or unsupported client authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "415": { "description": "Content type must be application/x-www-form-urlencoded" } } } }, "/credits/mcp/oauth/register": { "post": { "tags": [ "MCP" ], "summary": "Dynamically register an MCP OAuth client", "description": "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.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthClientMetadata" } } } }, "responses": { "201": { "description": "Registered client and one-time registration access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthClientRegistration" } } } }, "400": { "description": "Invalid client metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "415": { "description": "Content type must be application/json" } } } }, "/credits/mcp/oauth/register/{clientId}": { "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "tags": [ "MCP" ], "summary": "Read a dynamic MCP client registration", "security": [ { "mcpRegistrationToken": [] } ], "responses": { "200": { "description": "Current registration metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthClientRegistration" } } } }, "401": { "description": "Missing or invalid registration access token" } } }, "put": { "tags": [ "MCP" ], "summary": "Replace a dynamic MCP client registration", "security": [ { "mcpRegistrationToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthClientMetadataUpdate" } } } }, "responses": { "200": { "description": "Updated registration metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthClientRegistration" } } } }, "400": { "description": "Invalid client metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "401": { "description": "Missing or invalid registration access token" } } }, "delete": { "tags": [ "MCP" ], "summary": "Delete a dynamic MCP client registration", "description": "Deletes the registration and revokes its active authorization and token families.", "security": [ { "mcpRegistrationToken": [] } ], "responses": { "204": { "description": "Registration deleted" }, "401": { "description": "Missing or invalid registration access token" } } } }, "/credits/mcp/oauth/revoke": { "post": { "tags": [ "MCP" ], "summary": "Revoke an MCP OAuth token family", "description": "RFC 7009-style public-client revocation. Revoking an access or refresh token revokes its token family; unknown tokens still return success.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token", "client_id" ], "properties": { "token": { "type": "string" }, "client_id": { "type": "string" } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "Revocation processed" }, "400": { "description": "token and client_id are required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "415": { "description": "Content type must be application/x-www-form-urlencoded" } } } }, "/.well-known/oauth-protected-resource/api/credits/mcp": { "get": { "tags": [ "MCP" ], "summary": "Discover the MCP protected resource", "description": "Canonical RFC 9728 path derived from the MCP resource identifier.", "servers": [ { "url": "https://api.paywithlocus.com", "description": "Production origin" }, { "url": "https://api.stage.paywithlocus.com", "description": "Stage origin" } ], "security": [], "responses": { "200": { "description": "Protected-resource metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpProtectedResourceMetadata" } } } } } } }, "/.well-known/oauth-authorization-server/api/credits/mcp/oauth": { "get": { "tags": [ "MCP" ], "summary": "Discover the MCP authorization server", "description": "Canonical RFC 8414 path derived from the MCP OAuth issuer.", "servers": [ { "url": "https://api.paywithlocus.com", "description": "Production origin" }, { "url": "https://api.stage.paywithlocus.com", "description": "Stage origin" } ], "security": [], "responses": { "200": { "description": "Authorization-server metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAuthorizationServerMetadata" } } } } } } }, "/credits/mcp/oauth/authorize/public-context": { "get": { "tags": [ "MCP" ], "summary": "Read safe signed-out context for an MCP authorization", "description": "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.", "security": [], "parameters": [ { "name": "request", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^lmo_req_[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Safe context for a live pending authorization", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "data" ], "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "clientName", "clientId", "scopes", "resource", "expiresAt", "agentIdAuthorizationUrl" ], "properties": { "clientName": { "type": "string" }, "clientId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "resource": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "agentIdAuthorizationUrl": { "type": "string", "format": "uri" } } } } } } } }, "400": { "description": "Authorization request is malformed, expired, or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } } } } }, "/credits/mcp/oauth/authorize/agentid": { "get": { "tags": [ "MCP" ], "summary": "Continue a pending MCP authorization with AgentID", "description": "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.", "security": [], "parameters": [ { "name": "request", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^lmo_req_[A-Za-z0-9_-]{43}$" } } ], "responses": { "302": { "description": "Redirect to AgentID" }, "400": { "description": "Authorization request is malformed, expired, or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "503": { "description": "AgentID sign-in is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } } } } }, "/credits/mcp/oauth/agentid/client": { "get": { "tags": [ "MCP" ], "summary": "Read the Locus MCP AgentID client descriptor", "security": [], "responses": { "200": { "description": "OpenID client and callback metadata for the MCP AgentID login" } } } }, "/credits/mcp/oauth/agentid/callback": { "get": { "tags": [ "MCP" ], "summary": "Complete AgentID login for a pending MCP authorization", "description": "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.", "security": [], "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 4096 } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^lmo_req_[A-Za-z0-9_-]{43}$" } }, { "name": "error", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "iss", "in": "query", "required": false, "schema": { "type": "string" }, "description": "AgentID authorization-response issuer. The exchanged identity token is still verified against the trusted issuer." } ], "responses": { "302": { "description": "Redirect to the registered MCP callback with an authorization code or OAuth error" }, "400": { "description": "AgentID callback state is malformed, expired, or already used", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } } } } }, "/credits/okibi/cli-credential": { "get": { "tags": [ "Okibi Identity" ], "summary": "Read Okibi CLI credential bootstrap status", "description": "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. The account block names the linked Locus user and whether that user still has to choose a password. Requires both mcp:read and mcp:execute from Okibi Identity.", "security": [ { "okibiIdentity": [] } ], "responses": { "200": { "description": "Verified installation and current native credential state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "success", "identityProvider", "installationId", "account", "credentialConfigured", "connection", "bootstrap" ], "properties": { "success": { "const": true }, "identityProvider": { "const": "okibi" }, "installationId": { "type": "string" }, "account": { "$ref": "#/components/schemas/OkibiLinkedAccount" }, "credentialConfigured": { "type": "boolean" }, "connection": { "oneOf": [ { "$ref": "#/components/schemas/OkibiCliConnectionMetadata" }, { "type": "null" } ] }, "bootstrap": { "type": "object", "additionalProperties": false, "required": [ "method", "registrationToken", "tools" ], "properties": { "method": { "const": "POST" }, "registrationToken": { "type": "string" }, "tools": { "type": "string" } } } } } } } }, "401": { "description": "Missing, invalid, expired, or inactive Okibi capability" }, "403": { "description": "Missing mcp:read/mcp:execute or inactive Locus membership" } } }, "post": { "tags": [ "Okibi Identity" ], "summary": "Bootstrap a scoped Locus CLI credential from Okibi Identity", "description": "Exchanges a verified Okibi identity grant for one Locus lcac_ execution credential bound to the Okibi identity, CLI installation, and selected workspace. The credential expires 7 days after its last use and never later than 30 days after issue; every bootstrap issues it fresh for 7 days. Generate registrationToken locally from exactly 24 random bytes encoded as unpadded base64url. Replaying the token renews the installation's credential unchanged; a new token rotates that credential in place (same connection, new secret and prefix). A revoked credential is never renewed or rotated. When tools is present the server enables exactly those catalog slugs and restricts the credential to them; when it is omitted the credential may use every endpoint the workspace has enabled, and a fresh bootstrap may replace or lift an existing allowlist. The token is never stored; Locus stores only the derived credential hash.", "security": [ { "okibiIdentity": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "registrationToken" ], "properties": { "registrationToken": { "$ref": "#/components/schemas/AgentRegistrationToken" }, "tools": { "type": "object", "additionalProperties": false, "required": [ "enable" ], "description": "Optional endpoint allowlist. Omit it to leave the credential unrestricted within the workspace's enabled endpoints.", "properties": { "enable": { "type": "array", "minItems": 1, "maxItems": 200, "uniqueItems": true, "items": { "type": "string", "pattern": "^[^/\\s]+/[^/\\s]+$", "description": "Exact provider/endpoint catalog slug, for example apollo/people-search." } } } } } } } } }, "responses": { "200": { "description": "Existing credential renewed (same token) or rotated in place (new token); rotated tells which", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkibiCliCredentialEnvelope" } } } }, "201": { "description": "New native credential created for this installation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OkibiCliCredentialEnvelope" } } } }, "400": { "description": "Invalid registration token, empty endpoint allowlist, or unknown field" }, "401": { "description": "Missing, invalid, expired, or inactive Okibi capability" }, "403": { "description": "Missing mcp:read/mcp:execute or inactive Locus membership" }, "404": { "description": "Unknown provider/endpoint catalog slug" }, "409": { "description": "The installation's native credential was revoked in the dashboard, or the registration token already belongs to another installation" } } } }, "/credits/tenants/me/topups": { "get": { "tags": [ "Top-ups" ], "summary": "List the account's payment history", "description": "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.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 25 }, "description": "Maximum entries to return." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque nextCursor from the previous page." } ], "responses": { "200": { "description": "Top-up history page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerPage" } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/credits/custom-endpoints": { "get": { "tags": [ "Custom APIs" ], "summary": "List custom API providers and actions", "description": "Feature-gated 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 authorized caller receives null for those upstream configuration fields.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "x-required-scopes": [ "catalog:write" ], "responses": { "200": { "description": "Custom providers, effective workspace markup cap, and schema-backed actions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomProviderListResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedManagement" }, "403": { "description": "Custom APIs are not enabled for this enterprise workspace or the credential lacks catalog:write" } } }, "post": { "tags": [ "Custom APIs" ], "summary": "Create a custom API provider", "description": "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 controls, encrypts the credential, validates every JSON Schema and example, and never returns the raw credential.", "security": [ { "dashboardSession": [] } ], "x-required-scopes": [ "credentials:manage", "catalog:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomProviderCreateRequest" } } } }, "responses": { "201": { "description": "Provider and any supplied actions created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomProviderResponse" } } } }, "400": { "description": "Invalid URL, authentication, traffic policy, schema, example, route, or pricing" }, "403": { "description": "Feature, enterprise plan, owner, scope, or recent step-up requirement not met" }, "409": { "description": "That provider slug is already in use in this workspace" } } } }, "/credits/custom-endpoints/{providerId}": { "patch": { "tags": [ "Custom APIs" ], "summary": "Update a custom API provider", "description": "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.", "security": [ { "dashboardSession": [] } ], "x-required-scopes": [ "credentials:manage", "catalog:write" ], "parameters": [ { "$ref": "#/components/parameters/CustomProviderId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomProviderUpdateRequest" } } } }, "responses": { "200": { "description": "Provider updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomProviderResponse" } } } }, "400": { "description": "No changes or invalid configuration" }, "403": { "description": "Feature, enterprise plan, owner, scope, or recent step-up requirement not met" }, "404": { "description": "Custom provider not found in this workspace" } } }, "delete": { "tags": [ "Custom APIs" ], "summary": "Delete a custom API provider", "description": "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.", "security": [ { "dashboardSession": [] } ], "x-required-scopes": [ "credentials:manage", "catalog:write" ], "parameters": [ { "$ref": "#/components/parameters/CustomProviderId" } ], "responses": { "204": { "description": "Provider and actions deleted" }, "403": { "description": "Feature, enterprise plan, owner, scope, or recent step-up requirement not met" }, "404": { "description": "Custom provider not found in this workspace" } } } }, "/credits/custom-endpoints/{providerId}/endpoints": { "post": { "tags": [ "Custom APIs" ], "summary": "Create an action for a custom provider", "description": "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. Publishing an enabled action requires a positive end-user price.", "security": [ { "dashboardSession": [] } ], "x-required-scopes": [ "credentials:manage", "catalog:write" ], "parameters": [ { "$ref": "#/components/parameters/CustomProviderId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEndpointCreateRequest" } } } }, "responses": { "201": { "description": "Action created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEndpointResponse" } } } }, "400": { "description": "Invalid schema, example, path, pricing, or action configuration" }, "403": { "description": "Feature, enterprise plan, owner, scope, or recent step-up requirement not met" }, "404": { "description": "Custom provider not found in this workspace" }, "409": { "description": "That action slug is already in use for this provider" } } } }, "/credits/custom-endpoints/{providerId}/endpoints/{endpointId}": { "patch": { "tags": [ "Custom APIs" ], "summary": "Update a custom API action", "description": "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.", "security": [ { "dashboardSession": [] } ], "x-required-scopes": [ "credentials:manage", "catalog:write" ], "parameters": [ { "$ref": "#/components/parameters/CustomProviderId" }, { "$ref": "#/components/parameters/CustomEndpointId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEndpointUpdateRequest" } } } }, "responses": { "200": { "description": "Action updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomEndpointResponse" } } } }, "400": { "description": "No changes or invalid schema, example, path, pricing, or action configuration" }, "403": { "description": "Feature, enterprise plan, owner, scope, or recent step-up requirement not met" }, "404": { "description": "Custom provider or action not found in this workspace" } } }, "delete": { "tags": [ "Custom APIs" ], "summary": "Delete a custom API action", "description": "Permanently removes one custom action. Requires the enterprise owner with credentials:manage, catalog:write, and recent step-up.", "security": [ { "dashboardSession": [] } ], "x-required-scopes": [ "credentials:manage", "catalog:write" ], "parameters": [ { "$ref": "#/components/parameters/CustomProviderId" }, { "$ref": "#/components/parameters/CustomEndpointId" } ], "responses": { "204": { "description": "Action deleted" }, "403": { "description": "Feature, enterprise plan, owner, scope, or recent step-up requirement not met" }, "404": { "description": "Custom provider or action not found in this workspace" } } } }, "/credits/catalog/search": { "post": { "tags": [ "Catalog" ], "summary": "Search the management catalog", "description": "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 enablement, and current platform availability so a dashboard can help a person choose tools before enabling them. Always-on system routes are omitted; a tenant-toggleable Locus Travel route is included when available. This operation does not call a provider or burn credits.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Trimmed natural-language capability, provider, or endpoint query." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 30 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Ranked management results", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManagementCatalogSearchResponse" } } } }, "400": { "description": "Body must contain only a valid query and optional limit" }, "401": { "description": "Missing or invalid management credential" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "500": { "description": "Catalog search failed" } } } }, "/credits/mcp/oauth/device_authorization": { "post": { "tags": [ "MCP" ], "summary": "Start MCP device authorization", "description": "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.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/McpOAuthDeviceAuthorizationRequest" } } } }, "responses": { "200": { "description": "Pending device authorization", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthDeviceAuthorizationResponse" } } } }, "400": { "description": "Invalid client, resource, scope, or grant registration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "401": { "description": "Unknown client or an Authorization header was supplied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "415": { "description": "Content type must be application/x-www-form-urlencoded" } } } }, "/credits/mcp/oauth/device/public-context": { "get": { "tags": [ "MCP" ], "summary": "Read signed-out device authorization context", "description": "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.", "security": [], "parameters": [ { "$ref": "#/components/parameters/McpDeviceUserCodeQuery" } ], "responses": { "200": { "description": "Safe public context", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthDevicePublicContextResponse" } } } }, "400": { "description": "User code is invalid, expired, or no longer pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthError" } } } }, "429": { "description": "Too many verification attempts" } } } }, "/credits/mcp/oauth/device/tenants": { "get": { "tags": [ "MCP" ], "summary": "List memberships available to a device authorization", "description": "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.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/McpDeviceUserCodeQuery" }, { "$ref": "#/components/parameters/LocusTenantSelectionHeader" } ], "responses": { "200": { "description": "Available memberships and current selection", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthDeviceTenantListResponse" } } } }, "400": { "description": "Invalid/expired user code or missing signed-in user" }, "401": { "description": "Dashboard session required" }, "403": { "description": "No active Locus Pro membership is available" }, "429": { "description": "Too many verification attempts" } } } }, "/credits/mcp/oauth/device/context": { "get": { "tags": [ "MCP" ], "summary": "Read signed-in device consent context", "description": "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.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/McpDeviceUserCodeQuery" }, { "$ref": "#/components/parameters/LocusTenantSelectionHeader" } ], "responses": { "200": { "description": "Device consent context", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthDeviceContextResponse" } } } }, "400": { "description": "Invalid/expired user code, invalid account selection, or missing signed-in user" }, "401": { "description": "Dashboard session required" }, "403": { "description": "Selected membership is unavailable" }, "429": { "description": "Too many verification attempts" } } } }, "/credits/mcp/oauth/device/decision": { "post": { "tags": [ "MCP" ], "summary": "Approve or deny an MCP device authorization", "description": "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.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "$ref": "#/components/parameters/LocusTenantSelectionHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "userCode", "allow" ], "properties": { "userCode": { "$ref": "#/components/schemas/McpOAuthDeviceUserCodeInput" }, "allow": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "Request approved or denied", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpOAuthDeviceDecisionResponse" } } } }, "400": { "description": "Invalid/expired user code, invalid account selection, or missing signed-in user" }, "401": { "description": "Dashboard session required" }, "403": { "description": "Selected membership is unavailable" }, "409": { "description": "The request was already resolved or the account has no connection capacity" }, "429": { "description": "Too many verification attempts" } } } }, "/wrapped/credits/locus-travel/flight-search/preview": { "post": { "tags": [ "Recipes" ], "summary": "Plan a multi-provider flight search without dispatching", "description": "Feature-gated 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 when at least one selected provider has a live or otherwise variable price.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" }, "description": "Optional end-user identity for a tenant secret or sandbox key. It must agree with body externalUserId when both are present." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelFlightSearchRequest" } } } }, "responses": { "200": { "description": "No-dispatch provider plan and aggregate estimate", "headers": { "Cache-Control": { "schema": { "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelFlightSearchPreview" } } } }, "400": { "description": "Invalid flight search" }, "401": { "description": "Missing or invalid execution credential" }, "403": { "description": "Account, end-user, Agent Connection, or endpoint policy denied access" }, "409": { "description": "The planned provider calls exceed maxCredits or another credential-level charge ceiling" } } } }, "/wrapped/credits/locus-travel/flight-search": { "post": { "tags": [ "Recipes" ], "summary": "Search flights across selected providers", "description": "Feature-gated 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 maxCredits or credential-level ceiling prevents dispatch when the aggregate estimate is too high. Retries must reuse the same Idempotency-Key and identical logical request; a 202 response means one or more child providers are still processing, so retry with the same key.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "One key per logical travel search. Reuse it with an identical request to replay or finish the run." }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" }, "description": "Optional end-user identity for a tenant secret or sandbox key. It must agree with body externalUserId when both are present." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelFlightSearchRequest" } } } }, "responses": { "200": { "description": "Normalized, ranked flight search with provider outcomes and aggregate billing", "headers": { "X-Locus-Router-Run-Id": { "schema": { "type": "string", "format": "uuid" } }, "X-Locus-Router-Capability": { "schema": { "const": "travel.flight_search" } }, "X-Locus-Router-Dispatches": { "schema": { "type": "integer", "minimum": 0 } }, "X-Locus-Credits-Charged": { "schema": { "$ref": "#/components/schemas/DecimalString" } }, "X-Locus-Credits-Balance": { "schema": { "$ref": "#/components/schemas/DecimalString" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelFlightSearchResponse" } } } }, "202": { "description": "The durable run is still processing; retry with the same Idempotency-Key", "headers": { "Retry-After": { "schema": { "type": "integer", "const": 2 } }, "X-Locus-Router-Run-Id": { "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelFlightSearchPending" } } } }, "400": { "description": "Invalid search, missing/invalid Idempotency-Key, or caller-correctable request error" }, "401": { "description": "Missing or invalid execution credential" }, "403": { "description": "Account, end-user, Agent Connection, catalog, or endpoint policy denied execution" }, "409": { "description": "Idempotency-Key belongs to a different request or the planned aggregate charge exceeds a ceiling" }, "502": { "description": "All selected travel providers failed; per-provider outcomes and any incurred child billing are returned" } } } }, "/wrapped/credits/locus-travel/flight-search/{runId}/feedback": { "post": { "tags": [ "Recipes" ], "summary": "Submit feedback for a completed flight search", "description": "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.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" }, "description": "Secret or sandbox keys must repeat the run's end-user identity, when any." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelFlightSearchFeedbackRequest" } } } }, "responses": { "200": { "description": "Feedback saved", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelFlightSearchFeedbackResponse" } } } }, "400": { "description": "Invalid run ID, feedback, or itinerary ID" }, "401": { "description": "Missing or invalid execution credential" }, "403": { "description": "The credential is not allowed to access Locus Travel feedback" }, "404": { "description": "No matching run is visible to this account" }, "409": { "description": "The travel search has not completed" } } } }, "/credits/catalog/batch": { "put": { "tags": [ "Catalog" ], "summary": "Enable or disable a bounded set of slugs", "description": "Enables or disables up to 50 slugs (provider ids or provider/endpoint) in one transaction, each with the row semantics of the single write: a provider entry converges its endpoint-level enablement overrides to inherit (and clears their MCP pins when it turns off); an endpoint entry writes its own row (and drops its own pin when it turns off). Markup overrides are preserved. Everything is validated before anything is written; entries apply in the order given; the response reports the effective enablement per entry. Open to personal accounts. Registered ahead of the provider routes, so batch is never read as a provider id.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "slug", "enabled" ], "properties": { "slug": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A provider id or provider/endpoint. Slugs must be unique within a request." }, "enabled": { "type": "boolean" } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Every entry written; enabled is what the burn and discovery paths now resolve per slug", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "scope", "updated", "results" ], "properties": { "success": { "const": true }, "scope": { "const": "batch" }, "updated": { "type": "integer", "minimum": 1, "maximum": 50 }, "results": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "slug", "enabled", "scope" ], "properties": { "slug": { "type": "string" }, "enabled": { "type": "boolean" }, "scope": { "type": "string", "enum": [ "provider", "endpoint" ] } }, "additionalProperties": false } } }, "additionalProperties": false } } } }, "400": { "description": "Empty or oversized entry list, a duplicate slug, or an unexpected body key" }, "404": { "description": "At least one slug is unknown, named in the message; no rows are written" } } } }, "/credits/catalog/changes": { "get": { "tags": [ "Catalog" ], "summary": "Recent enablement changes with who made them", "description": "The newest catalog enablement changes first: which tool or provider moved, from what to what, who did it (a member by email, an API key by name, an agent connection by name) and through which surface. Rows are written inside the transaction that moved the enablement and only when the state actually changed; the journal is append-only.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Newest rows to return; anything outside 1-200 is a 400." } ], "responses": { "200": { "description": "Recent changes, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "changes" ], "properties": { "success": { "const": true }, "changes": { "type": "array", "maxItems": 200, "items": { "$ref": "#/components/schemas/CatalogChange" } } }, "additionalProperties": false } } } }, "400": { "description": "limit outside 1-200" }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/credits/tools/describe": { "post": { "tags": [ "Catalog" ], "summary": "Describe one selected tool", "description": "Returns the full input schema, example, response contract, pricing, and next action for one principal-visible search result. Secret keys require tenant:read. This operation does not call a provider or burn credits.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" }, "description": "Optional end-user identity for a tenant secret key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$" }, "operation_query": { "type": "string", "maxLength": 256, "description": "Original search intent used to select the most relevant operation from a directory endpoint." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Full selected tool contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolDescribeResponse" } } } }, "400": { "description": "Invalid slug" }, "401": { "description": "Missing or invalid discovery credential" }, "404": { "description": "Tool is not visible to this principal" }, "500": { "description": "Tool description failed" } } } }, "/credits/tools/estimate": { "post": { "tags": [ "Catalog" ], "summary": "Quote one described tool", "description": "Prices the intended request without dispatching it or burning credits. Variable-price and live external-rail tools may return an executable approval token or request a hard maximum before execution.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" }, "description": "Optional end-user identity for a tenant secret key." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*$" }, "body": { "type": "object", "additionalProperties": true }, "max_charge_credits": { "$ref": "#/components/schemas/DecimalString" }, "preflight_external_quote": { "type": "boolean" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "expires_in_seconds": { "type": "integer", "minimum": 30, "maximum": 600 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "No-dispatch price estimate or executable quote", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "estimate" ], "properties": { "success": { "const": true }, "estimate": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "400": { "description": "Invalid endpoint arguments or quote controls" }, "401": { "description": "Missing or invalid discovery credential" }, "403": { "description": "Tool is disabled or denied for this principal" }, "404": { "description": "Tool is not visible to this principal" }, "500": { "description": "Tool estimate failed" } } } }, "/credits/tools/groups": { "get": { "tags": [ "Catalog" ], "summary": "List live executable categories and curated packs", "description": "Returns principal-scoped group metadata and executable counts. Discovery does not enable tools or widen permissions.", "security": [ { "secretKey": [] }, { "sandboxKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "all", "category", "pack" ], "default": "all" } }, { "name": "query", "in": "query", "schema": { "type": "string", "maxLength": 120 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 500 } } ], "responses": { "200": { "description": "Live group page", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid scoped cursor" }, "401": { "description": "Missing or invalid execution credential" } } } }, "/credits/workflows/artifacts": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Upload a tenant-owned source or input artifact", "description": "Accepts authenticated JSON content up to the configured artifact ceiling. It never fetches caller-supplied URLs.", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind", "content" ], "properties": { "kind": { "type": "string", "enum": [ "source", "input" ] }, "content": {} }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Tenant-scoped artifact metadata" }, "400": { "description": "Invalid or oversized artifact" }, "403": { "description": "Hosted Workflows unavailable or unauthorized" } } } }, "/credits/workflows/artifacts/{artifactId}": { "get": { "tags": [ "Hosted Workflows" ], "summary": "Read a bounded tenant-owned artifact page", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "name": "artifactId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 500 } }, { "name": "max_characters", "in": "query", "schema": { "type": "integer", "minimum": 1024, "maximum": 20000, "default": 20000 } } ], "responses": { "200": { "description": "Artifact metadata and content page" }, "404": { "description": "Artifact is not owned by this account" } } } }, "/credits/workflows": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Create a tenant-private Workflow draft", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowCreateRequest" } } } }, "responses": { "201": { "$ref": "#/components/responses/WorkflowObject" }, "400": { "description": "Invalid source bundle" }, "403": { "description": "Hosted Workflows unavailable or unauthorized" } } }, "get": { "tags": [ "Hosted Workflows" ], "summary": "List saved Workflow definitions", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor returned by the preceding page." }, { "name": "query", "in": "query", "schema": { "type": "string", "maxLength": 160 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "archived", "all" ], "default": "active" } } ], "responses": { "200": { "description": "Workflow summaries and next_cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid filter or cursor" } } } }, "/credits/workflows/{workflowId}": { "get": { "tags": [ "Hosted Workflows" ], "summary": "Get a Workflow draft and its recent validation/version history", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowId" } ], "responses": { "200": { "$ref": "#/components/responses/WorkflowObject" }, "404": { "description": "Workflow not found for this account" } } }, "put": { "tags": [ "Hosted Workflows" ], "summary": "Update a Workflow draft with optimistic concurrency", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_revision", "source" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 }, "source": { "$ref": "#/components/schemas/WorkflowSource" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Reuse for retries of the same draft update." } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/WorkflowObject" }, "409": { "description": "Draft revision conflict" } } } }, "/credits/workflows/{workflowId}/validate": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Structurally check or fixture-test an exact draft revision", "description": "check does not evaluate user code. fixtures runs in the fixed sandbox without live gateway authority or egress.", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision", "mode" ], "properties": { "revision": { "type": "integer", "minimum": 1 }, "mode": { "type": "string", "enum": [ "check", "fixtures" ] }, "fixture_set": { "type": "string", "maxLength": 120 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Durable validation evidence" }, "409": { "description": "Draft revision changed" } } } }, "/credits/workflows/{workflowId}/versions": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Save an immutable checked Workflow version", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "revision" ], "properties": { "revision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Immutable version identity and validation evidence" }, "409": { "description": "Successful exact-revision check required" } } } }, "/credits/workflows/{workflowId}/runs": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Queue a bounded pilot or production run", "description": "Complete successful fixture tests for the exact source before starting a live pilot. A production run also requires a successful pilot of the same saved version. The run inherits and is bounded by the current connection.", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowRunRequest" } } } }, "responses": { "200": { "description": "Idempotent replay of the original run" }, "202": { "$ref": "#/components/responses/WorkflowRunObject" }, "409": { "description": "Idempotency conflict, archived Workflow, or missing successful fixture tests or pilot" } } } }, "/credits/workflow-runs": { "get": { "tags": [ "Hosted Workflows" ], "summary": "List tenant-owned Workflow runs", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bounded run summaries and continuation cursor" } } } }, "/credits/workflow-runs/{runId}": { "get": { "tags": [ "Hosted Workflows" ], "summary": "Inspect durable run state, metering, receipts, and artifact references", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowRunId" } ], "responses": { "200": { "$ref": "#/components/responses/WorkflowRunObject" }, "404": { "description": "Run not found for this account" } } } }, "/credits/workflow-runs/{runId}/cancel": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Stop new dispatch and request sandbox termination", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowRunId" } ], "responses": { "200": { "$ref": "#/components/responses/WorkflowRunObject" } } } }, "/credits/workflow-runs/{runId}/resume": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Resume eligible unfinished work with current authorization", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowRunId" } ], "responses": { "202": { "$ref": "#/components/responses/WorkflowRunObject" }, "409": { "description": "Run is not resumable" } } } }, "/agent/guides/manifest.json": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Get the immutable public Locus guide release manifest", "security": [], "responses": { "200": { "description": "Versioned guide IDs, resources, media types, digests, and URLs" } } } }, "/agent/compatibility.json": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Get independently versioned platform compatibility", "security": [], "responses": { "200": { "description": "API, taxonomy, guide bundle, plugin, runtime, SDK, and Workflow availability" } } } }, "/agent/guides/{bundleVersion}/{guideId}.md": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Read one public guide resource as Markdown or text", "security": [], "parameters": [ { "$ref": "#/components/parameters/GuideBundleVersion" }, { "$ref": "#/components/parameters/GuideId" } ], "responses": { "200": { "description": "Digest-addressed guide bytes" }, "404": { "description": "Unknown guide or bundle version" } } } }, "/agent/guides/{bundleVersion}/{guideId}.json": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Read one public guide resource as a JSON envelope", "security": [], "parameters": [ { "$ref": "#/components/parameters/GuideBundleVersion" }, { "$ref": "#/components/parameters/GuideId" } ], "responses": { "200": { "description": "Guide metadata, content, resources, and digest" }, "404": { "description": "Unknown guide or bundle version" } } } }, "/agent/guides/{bundleVersion}/{guideId}/content": { "get": { "tags": [ "Agent-native onboarding" ], "summary": "Read one public guide resource using its declared media type", "security": [], "parameters": [ { "$ref": "#/components/parameters/GuideBundleVersion" }, { "$ref": "#/components/parameters/GuideId" } ], "responses": { "200": { "description": "Digest-addressed guide or template bytes" }, "404": { "description": "Unknown guide or bundle version" } } } }, "/wrapped/credits/router/web-extract": { "post": { "tags": [ "Recipes" ], "summary": "Run Web Extract", "description": "Reads the exact supplied URLs and returns their content and provider sources. Failed resources can use an extraction fallback.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Reuse the same value only when retrying the same logical request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebExtractRequest" } } } }, "responses": { "200": { "description": "Result, sources, and billing receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebExtractResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Capability, provider, policy, or spend limit denied the request" }, "409": { "description": "The aggregate tenant-aware estimate exceeds maxCredits" } } } }, "/wrapped/credits/router/web-extract/preview": { "post": { "tags": [ "Recipes" ], "summary": "Preview Web Extract", "description": "Plans eligible providers and returns the current tenant-aware estimate without calling a provider or burning credits.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusWebExtractRequest" } } } }, "responses": { "200": { "description": "Free routing plan and current estimate", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Capability, provider, policy, or spend limit denied the request" }, "409": { "description": "The aggregate tenant-aware estimate exceeds maxCredits" } } } }, "/wrapped/credits/locus-gtm/enrich": { "post": { "tags": [ "Recipes" ], "summary": "Run GTM Enrichment", "description": "Enriches a person or company record, verifies discovered contact data by default, and returns field sources and exact charges.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "Reuse the same value only when retrying the same logical request." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusGtmEnrichmentRequest" } } } }, "responses": { "200": { "description": "Enriched record, sources, and charges", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Still running; retry the same request with the same idempotency key." }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Recipe, provider, or account access denied" }, "409": { "description": "Idempotency conflict or credit ceiling exceeded" } } } }, "/wrapped/credits/locus-gtm/enrich/preview": { "post": { "tags": [ "Recipes" ], "summary": "Preview GTM Enrichment", "description": "Plans enrichment and verification without calling providers or spending credits.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/SessionBindingHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocusGtmEnrichmentRequest" } } } }, "responses": { "200": { "description": "Enrichment plan and estimate", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "402": { "description": "Insufficient credits" }, "403": { "description": "Recipe, provider, or account access denied" }, "409": { "description": "Idempotency conflict or credit ceiling exceeded" } } } }, "/credits/workflows/{workflowId}/clone": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Clone a Workflow draft", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } } } }, "responses": { "201": { "$ref": "#/components/responses/WorkflowObject" }, "404": { "description": "Workflow not found for this account" }, "409": { "description": "Revision or idempotency conflict" } } } }, "/credits/workflows/{workflowId}/archive": { "post": { "tags": [ "Hosted Workflows" ], "summary": "Archive a Workflow definition", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "parameters": [ { "$ref": "#/components/parameters/WorkflowId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "expected_revision" ], "properties": { "expected_revision": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } } } }, "responses": { "200": { "$ref": "#/components/responses/WorkflowObject" }, "404": { "description": "Workflow not found for this account" }, "409": { "description": "Revision or idempotency conflict" } } } }, "/credits/tools/access-requests": { "post": { "tags": [ "Catalog" ], "summary": "Request access to a disabled tool", "description": "Return approval_url to a human workspace member. Creating a request does not enable the tool. MCP clients use request_tool_access instead.", "security": [ { "secretKey": [] }, { "agentConnection": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug" ], "additionalProperties": false, "properties": { "slug": { "type": "string", "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._/-]*$" } } } } } }, "responses": { "200": { "description": "Already enabled: status, slug, and next_step for a fresh tool search", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Pending human approval; the link expires after 30 minutes", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "status", "slug", "approval_url", "expires_at", "message" ], "properties": { "success": { "const": true }, "status": { "const": "pending_human_approval" }, "slug": { "type": "string" }, "approval_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" }, "message": { "type": "string" } } } } } }, "400": { "description": "Invalid tool slug" }, "401": { "description": "Missing or invalid execution credential" }, "403": { "description": "Credential cannot request tool access" }, "404": { "description": "Tool unavailable to this account" }, "409": { "description": "An unexpired request already exists for this credential and tool" }, "429": { "description": "Access-request rate limit reached" } } } }, "/credits/tool-access-requests/context": { "post": { "tags": [ "Catalog" ], "summary": "Read a tool access approval request", "description": "Requires a signed-in member of the requested workspace. The request token selects the workspace, independently of the dashboard workspace selection.", "security": [ { "dashboardSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "request" ], "additionalProperties": false, "properties": { "request": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Request token from the approval URL." } } } } } }, "responses": { "200": { "description": "success and data containing agentName, toolTitle, slug, providerName, tenantName, status, enabled, canDecide, and expiresAt", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace membership or decision permission missing" }, "404": { "description": "Request not found" } } } }, "/credits/tool-access-requests/decision": { "post": { "tags": [ "Catalog" ], "summary": "Approve or deny tool access", "description": "Requires a signed-in member of the requested workspace with catalog:write. Approval enables the tool for that workspace; denial leaves its current setting unchanged.", "security": [ { "dashboardSession": [] } ], "x-required-scopes": [ "catalog:write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "request", "allow" ], "additionalProperties": false, "properties": { "request": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Request token from the approval URL." }, "allow": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "success and data containing status (approved or denied), slug, and enabled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request body" }, "401": { "description": "Sign-in required" }, "403": { "description": "Workspace membership or decision permission missing" }, "404": { "description": "Request not found" }, "409": { "description": "Request is no longer pending" }, "410": { "description": "Request expired" } } } }, "/credits/plans": { "get": { "tags": [ "Tenant" ], "summary": "Read monthly plan and Enterprise trial status", "operationId": "getCreditsPlanStatus", "description": "Requires a human workspace session with tenant:read. Trial expiry pauses Enterprise features without erasing prepaid balances or changing the assigned usage rate. Complete paid Enterprise checkout to restore those features; a top-up does not extend the trial.", "security": [ { "dashboardSession": [] } ], "parameters": [ { "name": "refresh", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Reconcile the current Stripe subscription before returning the plan." } ], "responses": { "200": { "description": "Current subscription, trial deadline and checkout availability", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "enterpriseTrial": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "status", "startedAt", "endsAt" ], "properties": { "status": { "enum": [ "active", "expired" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" } }, "description": "A stored 14-day Enterprise trial. Paid conversion clears the visible trial, preserves its audit dates and keeps the assigned usage-pricing profile." } ] }, "enabled": { "type": "boolean" }, "currentPlan": { "enum": [ "free", "plus", "enterprise", "enterprise_plus" ] }, "legacy": { "type": "boolean" }, "checkoutConfigured": { "type": "boolean" }, "includedBalanceUsd": { "type": "string" }, "includedExpiresAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "403": { "description": "Human workspace membership is required" } } } }, "/credits/tools/execute": { "post": { "tags": [ "Tool discovery" ], "summary": "Execute a tool with an optional approved quote", "operationId": "executeCreditsTool", "description": "Uses the same approval, spending limits, idempotency and billing result as MCP execute. Reuse the estimate approval_token and idempotency_key with the identical slug, customer and args. HTTP 200 means the execution envelope was delivered; inspect result.isError and its billing metadata before treating the call as successful. Sandbox credentials are not supported.", "security": [ { "secretKey": [] }, { "agentConnection": [] }, { "endUserToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "slug", "idempotency_key" ], "additionalProperties": false, "properties": { "slug": { "type": "string" }, "args": { "type": "object", "additionalProperties": true }, "approval_token": { "type": "string", "maxLength": 4096 }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200 }, "loop_id": { "type": "string", "maxLength": 200 }, "attribution": { "type": "object", "additionalProperties": { "type": "string" } } } } } } }, "responses": { "200": { "description": "MCP-compatible tool result, including success or failure and charge metadata", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "result" ], "properties": { "success": { "const": true }, "result": { "type": "object", "properties": { "isError": { "type": "boolean" }, "content": { "type": "array", "items": { "type": "object" } }, "structuredContent": { "type": "object" }, "_meta": { "type": "object", "additionalProperties": true } } } } } } } }, "400": { "description": "Invalid execution request" }, "401": { "description": "Invalid credentials" }, "403": { "description": "Execution is not permitted" } }, "parameters": [ { "name": "X-Locus-End-User", "in": "header", "schema": { "type": "string" }, "description": "For a trusted workspace credential, select the same customer used for the estimate. A customer-bound credential cannot select another account." } ] } }, "/credits/catalog/changes/{requestId}/revert": { "post": { "tags": [ "Catalog" ], "summary": "Put a journaled write back", "description": "Restores the rows one whole-catalog write moved, each to exactly what it held before (an explicit on or off, or inherit), and only where the write is still the last word on it: the row must read as the write left it (a turn-on left explicit on rows; a turn-off left provider rows off and the tool rows it converged at inherit) and no later write may have journaled the slug. Anything else was decided since and is skipped and counted, never clobbered. Rows are never deleted, so putting an earlier write back afterwards still finds them. A tool pinned now stays on and counts as skipped: putting a turn-on back never takes a pin away. Any other tool put back off drops its MCP pin; a tool put back on does not get its pin back, but pass the unpinned slugs the write answered with as repin and the answer names those that came back on. Only the id a whole-catalog write answered with (all-on:\u2026 or all-off:\u2026) is accepted: other writers converge exceptions their journals do not record, so their state cannot be rebuilt exactly. The revert is journaled like any other write, under this request's id.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "parameters": [ { "name": "requestId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "The requestId a whole-catalog write answered with (all-on::\u2026 or all-off::\u2026)." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "repin": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Tool slugs whose pins the write cleared (its unpinned answer)." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Rows restored where they still held; skipped counts rows decided since; repin names the asked-about tools now back on", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "reverted", "skipped", "skippedSlugs", "repin", "requestId" ], "properties": { "success": { "const": true }, "reverted": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 }, "skippedSlugs": { "type": "array", "maxItems": 200, "items": { "type": "string" }, "description": "The first 200 slugs left alone because they were decided since; skipped is the full count." }, "repin": { "type": "array", "items": { "type": "string" }, "description": "Of the slugs asked about, those whose tool this revert put back on." }, "requestId": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "requestId empty, longer than 200 characters, or not one a whole-catalog write answered with; or a body that is not { repin?: string[] }" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "description": "No catalog changes are journaled for that request" } } } }, "/credits/catalog/all": { "put": { "tags": [ "Catalog" ], "summary": "Turn every mutable tool on or off", "description": "Moves every tool the workspace can switch in one transaction. enabled: true writes tool rows only: provider-level rows never move, so a tool added to a provider later still starts off. enabled: false writes every provider with a tool on at provider scope, resetting its endpoint-level enablement overrides to inherit and clearing their MCP pins, exactly as a provider entry of the batch route does. Markup overrides are preserved; always-on tools and custom endpoints are untouched. Every mutable provider is locked first, in one statement. The write is journaled under a fresh request id of its own, never the caller's x-request-id, and the response returns it so POST /credits/catalog/changes/{requestId}/revert can put exactly this write back. Open to personal accounts. Registered ahead of the provider routes, so all is never read as a provider id.", "security": [ { "dashboardSession": [] }, { "secretKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Every tool not already there has moved; updated counts tools whose effective enablement changed, providers counts the providers touched", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "scope", "enabled", "updated", "providers", "unpinned", "requestId" ], "properties": { "success": { "const": true }, "scope": { "const": "all" }, "enabled": { "type": "boolean" }, "updated": { "type": "integer", "minimum": 0 }, "providers": { "type": "integer", "minimum": 0 }, "unpinned": { "type": "array", "items": { "type": "string" }, "description": "Tools whose MCP pins a turn-off cleared (empty for a turn-on). A revert restores enablement, not pins: the caller may pin these again." }, "requestId": { "type": "string", "pattern": "^all-(on|off):[0-9]+:", "description": "The journal id of this write, naming its direction and its enablement revision, for the revert route." } }, "additionalProperties": false } } } }, "400": { "description": "enabled missing, not a boolean, or an unexpected body key" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "503": { "description": "Curation could not be read, even after reading it again; nothing was changed" } } } }, "/wrapped/credits/calls/{callId}/result": { "post": { "tags": [ "Burn" ], "summary": "Read async job result", "description": "Read the provider result of an async job, such as clado/bulk-contacts. Pass the apiCallId returned by the submit call. Locus reads the job id from that call's receipt. Reads are free and never create a new charge, so polling the same call again is safe. Access follows the submit endpoint's scope. Set waitSeconds to wait on the server for up to 45 seconds. When state is pending, call again after pollAfterMs. When nextPage is present, call again with its skip and limit to read the next page.", "security": [ { "secretKey": [] }, { "endUserToken": [] }, { "agentConnection": [] } ], "parameters": [ { "name": "callId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The apiCallId of the submit call." }, { "$ref": "#/components/parameters/SessionBindingHeader" }, { "name": "X-Locus-End-User", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ExternalUserId" }, "description": "Secret-key callers must repeat the original end user." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "waitSeconds": { "type": "integer", "minimum": 0, "maximum": 45, "default": 0, "description": "Seconds to wait on the server for the job to finish. 0 reads the current state once." }, "skip": { "type": "integer", "minimum": 0, "description": "Result offset for paged results. Copy it from nextPage." }, "limit": { "type": "integer", "minimum": 1, "description": "Results per page for paged results. Copy it from nextPage." } } } } } }, "responses": { "200": { "description": "Job state and provider result. No credits charged.", "content": { "application/json": { "schema": { "type": "object", "required": [ "apiCallId", "provider", "endpoint", "statusEndpoint", "jobId", "state", "result", "billing" ], "properties": { "apiCallId": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "endpoint": { "type": "string", "description": "The submit endpoint." }, "statusEndpoint": { "type": "string", "description": "The provider status endpoint Locus read." }, "jobId": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "pollAfterMs": { "type": "integer", "description": "Present when state is pending." }, "nextPage": { "type": "object", "required": [ "skip" ], "properties": { "skip": { "type": "integer" }, "limit": { "type": "integer" } }, "description": "Present when more result pages remain. Pass these values as skip and limit." }, "result": { "description": "The provider status body. When state is completed it holds the final result." }, "billing": { "type": "object", "required": [ "chargedCredits" ], "properties": { "chargedCredits": { "type": "string" } } } } } } } }, "400": { "description": "Invalid waitSeconds, skip, or limit (invalid_request), or skip or limit sent for a result that is not paged (pagination_unsupported)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "403": { "description": "Credential cannot call the submit endpoint (credential_endpoint_denied)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "404": { "description": "No job for this call id is visible to this credential, or the provider no longer has it (job_not_found)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "409": { "description": "The call did not start an async job (not_async_job)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "424": { "description": "The provider status read failed. Retry; reads are free (upstream_error)", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code", "message" ], "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "429": { "description": "Tenant rate limit exceeded" } } } } }, "components": { "securitySchemes": { "secretKey": { "type": "http", "scheme": "bearer", "description": "Tenant secret key (lcr_\u2026). Server-side only." }, "sandboxKey": { "type": "http", "scheme": "bearer", "description": "Sandbox key (lcrsb_\u2026). Metered calls are simulated: no credits move, no providers are called. No management access. Simulation is served from fixtures for the hosted provider catalog; external-rail providers are not registered with the sandbox interceptor and answer 404." }, "endUserToken": { "type": "http", "scheme": "bearer", "description": "60-3600 second end-user JWT minted via /credits/end-users/{id}/token. If the JWT has sid, send the original session value in X-Locus-Session-Id; sid contains only its SHA-256 fingerprint. Bearer tokens are replayable until expiry; use short TTLs, optional session binding, and Idempotency-Key on operations." }, "publishableKey": { "type": "apiKey", "in": "header", "name": "X-Locus-Publishable-Key", "description": "Widget calls: rides alongside the end-user token." }, "dashboardSession": { "type": "http", "scheme": "bearer", "description": "Locus Pro dashboard session (Cognito). High-risk workspace administration requires an owner or admin role and fresh MFA/passkey step-up." }, "agentConnection": { "type": "http", "scheme": "bearer", "description": "Scoped lcac_ credential. Tenant-managed Agent Connections authorize only their bound MCP and wrapped execution surfaces. A bootstrap connection for a self-registered agent additionally authorizes the explicit /credits/agent/* self-service routes for its own account; neither form authorizes general tenant management." }, "mcpOAuth": { "type": "oauth2", "description": "Primary authentication for the hosted MCP resource. Public clients use Authorization Code with PKCE S256. mcp:read covers discovery and resource reads; billed tools/call additionally requires mcp:execute; offline_access requests a rotating refresh token.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.paywithlocus.com/api/credits/mcp/oauth/authorize", "tokenUrl": "https://api.paywithlocus.com/api/credits/mcp/oauth/token", "refreshUrl": "https://api.paywithlocus.com/api/credits/mcp/oauth/token", "scopes": { "mcp:read": "Discover and read the authenticated MCP catalog and resources.", "mcp:execute": "Execute billed MCP tools.", "offline_access": "Issue and rotate a persistent refresh token." } } } }, "mcpRegistrationToken": { "type": "http", "scheme": "bearer", "description": "Dynamic-client registration access token returned once when the MCP OAuth client is created. It remains valid only for that client's registration management URI." }, "okibiIdentity": { "type": "http", "scheme": "bearer", "bearerFormat": "Okibi capability", "description": "Short-lived capability injected only by an Identity-eligible signed Okibi CLI release. It is verified by @okibi/partner-kit for issuer, audience, installation, grant activity, and required route scopes. Never persist or copy it into native Locus configuration." } }, "parameters": { "AgentConnectionId": { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "SessionBindingHeader": { "name": "X-Locus-Session-Id", "in": "header", "required": false, "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$" }, "description": "Required only when the end-user JWT carries sid. Send the original high-entropy session value; sid is its SHA-256 fingerprint. Ignored for secret-key authentication." }, "CustomProviderId": { "name": "providerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace-owned custom provider ID. This is distinct from its public custom-{slug} catalog name." }, "CustomEndpointId": { "name": "endpointId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Workspace-owned custom action ID." }, "McpDeviceUserCodeQuery": { "name": "user_code", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/McpOAuthDeviceUserCodeInput" }, "description": "Six-character device user code. Input is case-insensitive; non-alphanumeric punctuation is ignored and the value is normalized to XXX-XXX." }, "LocusTenantSelectionHeader": { "name": "X-Locus-Tenant-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Explicit account selection for a signed-in identity with multiple active memberships." }, "WorkspaceStepUpHeader": { "name": "X-Locus-Step-Up", "in": "header", "required": false, "schema": { "type": "string", "format": "password" }, "description": "Short-lived raw MFA/passkey step-up token bound to the authenticated Cognito subject. Send it alongside the dashboard Bearer token for workspace-administrator mutations when the base session does not itself prove MFA within the last ten minutes. Never send it with a tenant secret key." }, "WorkflowId": { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "WorkflowRunId": { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "GuideBundleVersion": { "name": "bundleVersion", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 40 } }, "GuideId": { "name": "guideId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 80 } } }, "responses": { "UnauthorizedManagement": { "description": "Missing, invalid, expired, or revoked management credential" }, "InsufficientScope": { "description": "The authenticated management credential lacks one or more required scopes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientScopeError" } } } }, "EvaluationPayoutLocked": { "description": "Evaluation payouts and Stripe Connect are disabled until a commercial agreement is active", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "error", "code", "message" ], "properties": { "success": { "const": false }, "error": { "const": "Evaluation payouts locked" }, "code": { "const": "evaluation_payout_locked" }, "message": { "type": "string" } } } } } }, "TopupError": { "description": "Stable top-up validation, velocity, or ownership error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopupError" } } } }, "BadRequest": { "description": "The request is malformed or fails local validation before any provider or payment action." }, "WorkflowObject": { "description": "Tenant-scoped Workflow definition envelope", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "workflow" ], "properties": { "success": { "const": true }, "workflow": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } }, "WorkflowRunObject": { "description": "Tenant-scoped durable Workflow run envelope", "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "run" ], "properties": { "success": { "const": true }, "replay": { "type": "boolean" }, "run": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } } } }, "schemas": { "LocusWebSearchRequest": { "type": "object", "properties": { "query": { "type": "string", "pattern": "^\\s*(?:\\S|\\S[\\s\\S]{0,398}\\S)\\s*$", "description": "Search or research request." }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "mode": { "type": "string", "enum": [ "fast", "balanced", "comprehensive" ], "default": "balanced" }, "maxProviders": { "type": "integer", "minimum": 1, "maximum": 13, "default": 4 }, "strategy": { "type": "string", "enum": [ "balanced", "cost", "quality", "speed" ], "description": "Legacy mode selector retained for compatible clients." }, "topic": { "type": "string", "enum": [ "general", "news" ], "default": "general" }, "recencyDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "includeDomains": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "excludeDomains": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "includeImages": { "type": "boolean", "default": false }, "providers": { "type": "array", "maxItems": 13, "items": { "type": "string", "pattern": "^\\s*(?:[aA][gG][eE][nN][tT]402|[aA][gG][eE][nN][tT][sS][tT][oO][oO][lL][sS]|[aA][nN][dD][iI]|[bB][rR][aA][vV][eE]|[dD][aA][tT][aA][fF][oO][rR][sS][eE][oO]|[eE][xX][aA]|[fF][iI][rR][eE][cC][rR][aA][wW][lL]|[lL][iI][nN][kK][uU][pP]|[pP][aA][rR][aA][lL][lL][eE][lL]|[pP][eE][rR][pP][lL][eE][xX][iI][tT][yY]|[sS][eE][lL][tT][zZ]|[sS][eE][rR][pP][eE][rR]|[tT][aA][vV][iI][lL][yY])\\s*$", "description": "Provider ID. Available values: agent402, agentstools, andi, brave, dataforseo, exa, firecrawl, linkup, parallel, perplexity, seltz, serper, tavily. Matching ignores case and surrounding whitespace." } }, "maxCredits": { "oneOf": [ { "type": "string", "pattern": "^\\s*(?=[0-9.]{1,100}\\s*$)0*(?:(?:[1-9]\\d{0,11})(?:\\.\\d{1,6})?|1000000000000(?:\\.0{1,6})?|0\\.(?=\\d{0,5}[1-9])\\d{1,6})\\s*$" }, { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000 } ], "description": "Aggregate hard charge ceiling in workspace credits. Decimal strings support up to six fractional digits; numeric values are rounded down to six digits." }, "rails": { "type": "array", "items": { "type": "string", "enum": [ "api-key", "mpp", "x402" ] }, "description": "Legacy access-path field retained for compatible clients." }, "externalUserId": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Optional end-user billing attribution for a tenant secret key." }, "attribution": { "type": "object", "additionalProperties": true, "description": "Optional JSON ledger metadata such as a task or customer identifier." } }, "required": [ "query" ], "additionalProperties": false }, "LocusWebResearchRequest": { "type": "object", "properties": { "query": { "type": "string", "pattern": "^\\s*(?:\\S|\\S[\\s\\S]{0,398}\\S)\\s*$", "description": "Search or research request." }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 }, "mode": { "type": "string", "enum": [ "fast", "balanced", "comprehensive" ], "default": "balanced" }, "maxProviders": { "type": "integer", "minimum": 1, "maximum": 13, "default": 4 }, "strategy": { "type": "string", "enum": [ "balanced", "cost", "quality", "speed" ], "description": "Legacy mode selector retained for compatible clients." }, "topic": { "type": "string", "enum": [ "general", "news" ], "default": "general" }, "recencyDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "includeDomains": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "excludeDomains": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "pattern": "\\S" } }, "includeImages": { "type": "boolean", "default": false }, "providers": { "type": "array", "maxItems": 13, "items": { "type": "string", "pattern": "^\\s*(?:[aA][gG][eE][nN][tT]402|[aA][gG][eE][nN][tT][sS][tT][oO][oO][lL][sS]|[aA][nN][dD][iI]|[bB][rR][aA][vV][eE]|[dD][aA][tT][aA][fF][oO][rR][sS][eE][oO]|[eE][xX][aA]|[fF][iI][rR][eE][cC][rR][aA][wW][lL]|[lL][iI][nN][kK][uU][pP]|[pP][aA][rR][aA][lL][lL][eE][lL]|[pP][eE][rR][pP][lL][eE][xX][iI][tT][yY]|[sS][eE][lL][tT][zZ]|[sS][eE][rR][pP][eE][rR]|[tT][aA][vV][iI][lL][yY])\\s*$", "description": "Provider ID. Available values: agent402, agentstools, andi, brave, dataforseo, exa, firecrawl, linkup, parallel, perplexity, seltz, serper, tavily. Matching ignores case and surrounding whitespace." } }, "maxCredits": { "oneOf": [ { "type": "string", "pattern": "^\\s*(?=[0-9.]{1,100}\\s*$)0*(?:(?:[1-9]\\d{0,11})(?:\\.\\d{1,6})?|1000000000000(?:\\.0{1,6})?|0\\.(?=\\d{0,5}[1-9])\\d{1,6})\\s*$" }, { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000 } ], "description": "Aggregate hard charge ceiling in workspace credits. Decimal strings support up to six fractional digits; numeric values are rounded down to six digits." }, "rails": { "type": "array", "items": { "type": "string", "enum": [ "api-key", "mpp", "x402" ] }, "description": "Legacy access-path field retained for compatible clients." }, "externalUserId": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Optional end-user billing attribution for a tenant secret key." }, "attribution": { "type": "object", "additionalProperties": true, "description": "Optional JSON ledger metadata such as a task or customer identifier." }, "effort": { "type": "string", "enum": [ "light", "medium", "heavy" ], "description": "Explicitly request a grounded answer. Omit only for the legacy evidence-only contract." }, "outputSchema": { "type": "object", "description": "Optional bounded JSON object schema for the answer. Requires effort and preserves the same grounded-reference envelope.", "properties": { "type": { "const": "object" }, "properties": { "type": "object", "maxProperties": 100, "additionalProperties": true }, "required": { "type": "array", "maxItems": 100, "uniqueItems": true, "items": { "type": "string", "minLength": 1 }, "description": "Declared properties omitted here are optional." }, "additionalProperties": { "const": false }, "description": { "type": "string", "maxLength": 2000 } }, "required": [ "type", "properties", "required", "additionalProperties" ], "additionalProperties": false } }, "required": [ "query" ], "additionalProperties": false, "dependentRequired": { "outputSchema": [ "effort" ] } }, "LocusWebExtractRequest": { "type": "object", "properties": { "urls": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "format": "uri", "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://", "maxLength": 2048 }, "description": "Exact public HTTP(S) resources to read. The router never substitutes another URL." }, "objective": { "type": "string", "minLength": 1, "maxLength": 400, "description": "Optional focus within each supplied resource; it does not authorize discovery." }, "maxCharactersPerUrl": { "type": "integer", "minimum": 1000, "maximum": 100000, "default": 50000 }, "maxAgeSeconds": { "type": "integer", "minimum": 600, "maximum": 2592000, "description": "Maximum accepted cache age. Omit to use each extractor default." }, "maxCredits": { "oneOf": [ { "type": "string", "pattern": "^\\s*(?=[0-9.]{1,100}\\s*$)0*(?:(?:[1-9]\\d{0,11})(?:\\.\\d{1,6})?|1000000000000(?:\\.0{1,6})?|0\\.(?=\\d{0,5}[1-9])\\d{1,6})\\s*$" }, { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000 } ], "description": "Aggregate hard charge ceiling in workspace credits. Decimal strings support up to six fractional digits; numeric values are rounded down to six digits." }, "externalUserId": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "Optional end-user billing attribution for a tenant secret key." }, "attribution": { "type": "object", "additionalProperties": true, "description": "Optional JSON ledger metadata such as a task or customer identifier." } }, "required": [ "urls" ], "additionalProperties": false }, "LocusWebSearchResponse": { "type": "object", "properties": { "object": { "const": "locus.web_search" }, "capability": { "const": "web.search" }, "routerVersion": { "const": "2026-09-14.v28" }, "query": { "type": "string" }, "mode": { "type": "string", "enum": [ "fast", "balanced", "comprehensive" ] }, "partial": { "type": "boolean" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" }, "estimatedCostUsd": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "succeeded", "failed", "pending" ] }, "latencyMs": { "type": "integer", "minimum": 0 }, "resultCount": { "type": "integer", "minimum": 0 }, "imageCount": { "type": "integer", "minimum": 0 }, "chargedCredits": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "errorCode": { "type": "string" }, "dispatchedQuery": { "type": "string" }, "surfacedResultCount": { "type": "integer", "minimum": 0 }, "uniqueSurfacedResultCount": { "type": "integer", "minimum": 0 }, "marginalResultCount": { "type": "integer", "minimum": 0 }, "tailLatencyContributionMs": { "type": "integer", "minimum": 0 } }, "required": [ "providerId", "providerName", "status", "latencyMs", "resultCount", "imageCount", "surfacedResultCount", "uniqueSurfacedResultCount", "marginalResultCount", "tailLatencyContributionMs" ], "additionalProperties": false } }, "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "snippet": { "type": "string" }, "publishedAt": { "type": "string" }, "engine": { "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "sources": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" }, "rank": { "type": "integer", "minimum": 1 } }, "required": [ "providerId", "providerName", "rank" ], "additionalProperties": false } }, "sourceCount": { "type": "integer", "minimum": 1 } }, "required": [ "title", "url", "sources", "sourceCount" ], "additionalProperties": false } }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" }, "sources": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" } }, "required": [ "providerId", "providerName" ], "additionalProperties": false } } }, "required": [ "url", "sources" ], "additionalProperties": false } }, "resultCount": { "type": "integer", "minimum": 0 }, "imageCount": { "type": "integer", "minimum": 0 }, "billing": { "type": "object", "properties": { "chargedCredits": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "successfulProviders": { "type": "integer", "minimum": 0 }, "attemptedProviders": { "type": "integer", "minimum": 0 } }, "required": [ "chargedCredits", "successfulProviders", "attemptedProviders" ], "additionalProperties": false }, "routingPolicy": { "type": "object", "properties": { "requestedMode": { "type": "string", "enum": [ "shadow", "canary", "enforce" ] }, "effectiveMode": { "type": "string", "enum": [ "static", "shadow", "canary", "enforce" ] }, "policyId": { "type": "string" }, "predictedRouteId": { "type": "string" }, "predictedDecision": { "type": "string", "enum": [ "single", "multi" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "accepted": { "type": "boolean" }, "applied": { "type": "boolean" }, "fallbackReason": { "type": "string", "enum": [ "policy_unavailable", "artifact_not_eligible", "unsupported_request", "low_confidence", "shadow_only", "canary_holdout", "route_unavailable" ] } }, "required": [ "requestedMode", "effectiveMode", "accepted", "applied" ], "additionalProperties": false } }, "required": [ "object", "capability", "routerVersion", "query", "mode", "partial", "providers", "results", "images", "resultCount", "imageCount", "billing" ], "additionalProperties": false }, "LocusWebResearchResponse": { "type": "object", "properties": { "object": { "const": "locus.web_research" }, "capability": { "const": "web.research" }, "routerVersion": { "const": "2026-09-14.v28" }, "query": { "type": "string" }, "objective": { "type": "string", "enum": [ "find_sources", "structured_answer", "resolved_answer" ] }, "partial": { "type": "boolean" }, "answer": { "type": "string" }, "references": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "startIndex": { "type": "integer", "minimum": 0 }, "endIndex": { "type": "integer", "minimum": 0 } }, "required": [ "id", "url" ], "additionalProperties": false } }, "completionStatus": { "type": "string", "enum": [ "complete", "partial" ] }, "stopReason": { "type": "string", "enum": [ "completed", "provider_incomplete" ] }, "effort": { "type": "string", "enum": [ "light", "medium", "heavy" ] }, "output": { "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": true } ], "description": "Exact JSON value returned by the selected structured endpoint." }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "structured_data", "web_page" ] }, "title": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "excerpt": { "type": "string" }, "publishedAt": { "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "sourceCount": { "type": "integer", "minimum": 1 } }, "required": [ "kind", "title", "url", "sourceCount" ], "additionalProperties": false } }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "sourceUrl": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false } }, "structuredData": { "type": "object", "properties": { "format": { "const": "json" }, "source": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "required": [ "name", "url" ], "additionalProperties": false }, "value": { "oneOf": [ { "type": "null" }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": true } ], "description": "Exact JSON value returned by the selected structured endpoint." } }, "required": [ "format", "source", "value" ], "additionalProperties": false }, "route": { "oneOf": [ { "type": "object", "properties": { "strategy": { "const": "web_search" }, "successfulProviders": { "type": "integer", "minimum": 0 }, "attemptedProviders": { "type": "integer", "minimum": 0 } }, "required": [ "strategy", "successfulProviders", "attemptedProviders" ], "additionalProperties": false }, { "type": "object", "properties": { "strategy": { "const": "structured_source" }, "provider": { "type": "string" }, "endpoint": { "type": "string" }, "reason": { "type": "string" }, "successfulProviders": { "type": "integer", "minimum": 0 }, "attemptedProviders": { "type": "integer", "minimum": 0 }, "fallbackUsed": { "const": false } }, "required": [ "strategy", "provider", "endpoint", "reason", "successfulProviders", "attemptedProviders", "fallbackUsed" ], "additionalProperties": false }, { "type": "object", "properties": { "strategy": { "const": "structured_source_fallback" }, "provider": { "type": "string" }, "endpoint": { "type": "string" }, "reason": { "type": "string" }, "successfulProviders": { "type": "integer", "minimum": 0 }, "attemptedProviders": { "type": "integer", "minimum": 0 }, "fallbackUsed": { "const": true }, "fallbackReason": { "type": "string" } }, "required": [ "strategy", "provider", "endpoint", "reason", "successfulProviders", "attemptedProviders", "fallbackUsed", "fallbackReason" ], "additionalProperties": false }, { "type": "object", "properties": { "strategy": { "const": "grounded_answer" }, "provider": { "const": "Parallel" }, "endpoint": { "const": "responses" }, "successfulProviders": { "type": "integer", "minimum": 0 }, "attemptedProviders": { "type": "integer", "minimum": 1 }, "modelTurns": { "type": "integer", "minimum": 1 }, "searches": { "type": "integer", "minimum": 0 }, "fetches": { "type": "integer", "minimum": 0 } }, "required": [ "strategy", "provider", "endpoint", "successfulProviders", "attemptedProviders", "modelTurns", "searches", "fetches" ], "additionalProperties": false } ] }, "billing": { "type": "object", "properties": { "chargedCredits": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "successfulProviders": { "type": "integer", "minimum": 0 }, "attemptedProviders": { "type": "integer", "minimum": 0 } }, "required": [ "chargedCredits", "successfulProviders", "attemptedProviders" ], "additionalProperties": false }, "routingPolicy": { "type": "object", "properties": { "requestedMode": { "type": "string", "enum": [ "shadow", "canary", "enforce" ] }, "effectiveMode": { "type": "string", "enum": [ "static", "shadow", "canary", "enforce" ] }, "policyId": { "type": "string" }, "predictedRouteId": { "type": "string" }, "predictedDecision": { "type": "string", "enum": [ "single", "multi" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "accepted": { "type": "boolean" }, "applied": { "type": "boolean" }, "fallbackReason": { "type": "string", "enum": [ "policy_unavailable", "artifact_not_eligible", "unsupported_request", "low_confidence", "shadow_only", "canary_holdout", "route_unavailable" ] } }, "required": [ "requestedMode", "effectiveMode", "accepted", "applied" ], "additionalProperties": false } }, "required": [ "object", "capability", "routerVersion", "query", "objective", "partial", "evidence", "images", "route", "billing" ], "oneOf": [ { "properties": { "objective": { "const": "structured_answer" }, "route": { "properties": { "strategy": { "const": "structured_source" } }, "required": [ "strategy" ] } }, "required": [ "structuredData" ] }, { "properties": { "objective": { "const": "find_sources" }, "route": { "properties": { "strategy": { "enum": [ "web_search", "structured_source_fallback" ] } }, "required": [ "strategy" ] } }, "not": { "required": [ "structuredData" ] } }, { "properties": { "objective": { "const": "resolved_answer" }, "route": { "properties": { "strategy": { "const": "grounded_answer" } }, "required": [ "strategy" ] } }, "required": [ "answer", "references", "completionStatus", "stopReason", "effort" ], "not": { "required": [ "structuredData" ] } } ], "additionalProperties": false }, "LocusWebExtractResponse": { "type": "object", "properties": { "object": { "const": "locus.web_extract" }, "capability": { "const": "web.extract" }, "routerVersion": { "const": "2026-09-14.v28" }, "partial": { "type": "boolean" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "requestedUrl": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "title": { "type": "string" }, "content": { "type": "string" }, "contentType": { "const": "text/markdown" }, "publishedAt": { "type": "string" }, "retrievedAt": { "type": "string", "format": "date-time" }, "truncated": { "type": "boolean" }, "coverage": { "type": "string", "enum": [ "full_content", "excerpt", "none" ] }, "source": { "type": "object", "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" } }, "required": [ "providerId", "providerName" ], "additionalProperties": false }, "errorCode": { "type": "string" } }, "required": [ "requestedUrl", "url", "status", "retrievedAt", "truncated", "coverage", "source" ], "additionalProperties": false } }, "route": { "type": "object", "properties": { "strategy": { "const": "exact_resource_fallback" }, "primary": { "const": "parallel/extract" }, "fallback": { "const": "firecrawl/scrape" }, "fallbackUsed": { "type": "boolean" } }, "required": [ "strategy", "primary", "fallback", "fallbackUsed" ], "additionalProperties": false }, "billing": { "type": "object", "properties": { "chargedCredits": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "successfulResources": { "type": "integer", "minimum": 0 }, "attemptedResources": { "type": "integer", "minimum": 1 }, "providerCalls": { "type": "integer", "minimum": 1 } }, "required": [ "chargedCredits", "successfulResources", "attemptedResources", "providerCalls" ], "additionalProperties": false } }, "required": [ "object", "capability", "routerVersion", "partial", "resources", "route", "billing" ], "additionalProperties": false }, "LocusGtmEnrichmentRequest": { "type": "object", "properties": { "entity": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "person", "company" ] }, "identifiers": { "type": "object", "description": "Person records require email, LinkedIn URL, provider ID, or a name plus company identifier. A phone may accompany another seed but is not supported alone. Company records require a domain, name, LinkedIn URL, or provider ID.", "properties": { "fullName": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" }, "lastName": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" }, "email": { "type": "string", "format": "email", "minLength": 1, "maxLength": 320 }, "phone": { "type": "string", "minLength": 7, "maxLength": 40, "pattern": "\\S", "description": "Optional contact value. It may accompany another supported person seed but cannot be the sole enrichment identifier." }, "linkedinUrl": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2000 }, "companyName": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" }, "companyDomain": { "type": "string", "minLength": 3, "maxLength": 253, "pattern": "\\S" }, "companyLinkedinUrl": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2000 }, "companyId": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" }, "personId": { "type": "string", "minLength": 1, "maxLength": 500, "pattern": "\\S" }, "ipAddress": { "type": "string", "minLength": 3, "maxLength": 64, "pattern": "\\S" } }, "additionalProperties": false } }, "required": [ "kind", "identifiers" ], "additionalProperties": false, "oneOf": [ { "properties": { "kind": { "const": "person" }, "identifiers": { "anyOf": [ { "required": [ "email" ] }, { "required": [ "linkedinUrl" ] }, { "required": [ "personId" ] }, { "allOf": [ { "anyOf": [ { "required": [ "fullName" ] }, { "required": [ "firstName", "lastName" ] } ] }, { "anyOf": [ { "required": [ "companyDomain" ] }, { "required": [ "companyName" ] }, { "required": [ "companyLinkedinUrl" ] } ] } ] } ] } } }, { "properties": { "kind": { "const": "company" }, "identifiers": { "anyOf": [ { "required": [ "companyDomain" ] }, { "required": [ "companyName" ] }, { "required": [ "companyLinkedinUrl" ] }, { "required": [ "companyId" ] } ] } } } ] }, "requestedFields": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "person.fullName", "person.firstName", "person.lastName", "person.jobTitle", "person.location", "person.linkedinUrl", "person.workEmail", "person.personalEmail", "person.mobilePhone", "company.name", "company.domain", "company.website", "company.linkedinUrl", "company.description", "company.industry", "company.employeeCount", "company.employeeRange", "company.revenueRange", "company.headquarters", "company.phone", "company.technologies", "company.funding", "company.hiring" ] } }, "profile": { "type": "string", "enum": [ "person_core", "person_contact", "company_core", "company_intelligence", "full" ] }, "objective": { "type": "string", "enum": [ "highest_coverage" ], "default": "highest_coverage" }, "providers": { "type": "array", "uniqueItems": true, "items": { "type": "string" } }, "maxCredits": { "oneOf": [ { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$" }, { "type": "number", "exclusiveMinimum": 0 } ], "description": "Aggregate provider-and-verification ceiling in workspace credits. Required for direct and hosted Workflow execution; set it equal to the Workflow call maxChargeCredits unless the Workflow call intentionally allows a tighter cap." }, "contactVerification": { "type": "string", "enum": [ "required", "none" ], "default": "required", "description": "Require deliverability checks for discovered emails and validity, reachability, and available ownership evidence for discovered phones." }, "externalUserId": { "type": "string" }, "attribution": { "type": "object", "additionalProperties": true } }, "required": [ "entity", "maxCredits" ], "additionalProperties": false }, "InsufficientScopeError": { "type": "object", "additionalProperties": false, "required": [ "success", "error", "code", "message", "requiredScopes", "presentScopes" ], "properties": { "success": { "const": false }, "error": { "const": "Forbidden" }, "code": { "const": "INSUFFICIENT_SCOPE" }, "message": { "type": "string" }, "requiredScopes": { "type": "array", "items": { "$ref": "#/components/schemas/CreditsTenantScope" }, "minItems": 1, "uniqueItems": true }, "presentScopes": { "type": "array", "items": { "$ref": "#/components/schemas/CreditsTenantScope" }, "uniqueItems": true } } }, "CredentialPriceOverride": { "type": "object", "additionalProperties": false, "properties": { "markupBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "flatMarkupUsdc": { "$ref": "#/components/schemas/DecimalString" } }, "minProperties": 1 }, "CredentialPricingPolicy": { "type": "object", "additionalProperties": false, "properties": { "markupBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "flatMarkupUsdc": { "$ref": "#/components/schemas/DecimalString" }, "endpoints": { "type": "object", "maxProperties": 1000, "additionalProperties": { "$ref": "#/components/schemas/CredentialPriceOverride" } } }, "minProperties": 1 }, "ApiKeyCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "type": "string", "enum": [ "secret", "publishable", "sandbox" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/CreditsTenantScope" }, "uniqueItems": true }, "tools": { "type": "object", "additionalProperties": false, "required": [ "enable" ], "properties": { "enable": { "type": "array", "maxItems": 1000, "items": { "type": "string", "pattern": "^[^/]+/[^/]+$" }, "uniqueItems": true } } }, "pricing": { "$ref": "#/components/schemas/CredentialPricingPolicy" }, "expiresIn": { "type": "integer", "minimum": 60, "maximum": 31536000 } } }, "AgentConnectionCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "mode" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "mode": { "type": "string", "enum": [ "platform", "end_user" ] }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "tools": { "type": "object", "additionalProperties": false, "properties": { "enable": { "type": "array", "maxItems": 1000, "items": { "type": "string", "pattern": "^[^/]+/[^/]+$" }, "uniqueItems": true } } }, "pricing": { "$ref": "#/components/schemas/CredentialPricingPolicy" }, "maxCreditsPerCall": { "$ref": "#/components/schemas/DecimalString" }, "maxCreditsPerLoop": { "$ref": "#/components/schemas/DecimalString" }, "expiresInSeconds": { "type": "integer", "minimum": 300, "maximum": 31536000 } } }, "AgentConnection": { "type": "object", "required": [ "id", "name", "status", "mode", "keyPrefix", "expiresAt", "createdAt", "updatedAt", "mcp" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "mode": { "type": "string", "enum": [ "platform", "end_user" ] }, "externalUserId": { "oneOf": [ { "$ref": "#/components/schemas/ExternalUserId" }, { "type": "null" } ] }, "tools": { "type": "object", "properties": { "enable": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "pricing": { "oneOf": [ { "$ref": "#/components/schemas/CredentialPricingPolicy" }, { "type": "null" } ] }, "maxCreditsPerCall": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "maxCreditsPerLoop": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "keyPrefix": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "rotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "mcp": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } } }, "credential": { "type": "string", "description": "Present only in create/rotate responses and shown once" } } }, "AgentConnectionEnvelope": { "type": "object", "additionalProperties": false, "required": [ "success", "connection" ], "properties": { "success": { "const": true }, "connection": { "$ref": "#/components/schemas/AgentConnection" } } }, "UnknownTenantFieldsError": { "type": "object", "additionalProperties": false, "required": [ "success", "error", "code", "fields", "message" ], "properties": { "success": { "const": false }, "error": { "const": "Bad Request" }, "code": { "const": "unknown_fields" }, "fields": { "type": "array", "items": { "type": "string" }, "minItems": 1, "uniqueItems": true }, "message": { "type": "string" } } }, "CreditsTenantScope": { "type": "string", "enum": [ "tenant:read", "tenant:write", "catalog:write", "credits:move", "credentials:manage", "tokens:manage", "payouts:manage", "members:manage", "widget:read" ] }, "WorkspaceRole": { "type": "string", "description": "Owner and admin are workspace-administrator roles. The original owner membership cannot be reassigned or removed.", "enum": [ "owner", "admin", "developer", "billing", "viewer" ] }, "InvitableWorkspaceRole": { "type": "string", "enum": [ "admin", "developer", "billing", "viewer" ] }, "WorkspaceMembership": { "type": "object", "additionalProperties": false, "required": [ "tenantId", "tenantName", "tenantStatus", "role" ], "properties": { "tenantId": { "type": "string", "format": "uuid" }, "tenantName": { "type": "string" }, "tenantStatus": { "type": "string", "enum": [ "active", "suspended" ] }, "role": { "$ref": "#/components/schemas/WorkspaceRole" } } }, "WorkspaceMember": { "type": "object", "additionalProperties": false, "required": [ "id", "email", "role", "cognitoSub", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/WorkspaceRole" }, "cognitoSub": { "type": "string", "description": "Cognito subject usage is attributed to; the identity analytics keys member spend by." }, "createdAt": { "type": "string", "format": "date-time" } } }, "WorkspaceInvitation": { "type": "object", "additionalProperties": false, "required": [ "id", "email", "role", "status", "deliveryStatus", "expiresAt", "deliveryAttempts", "lastDeliveryError", "lastSentAt", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "$ref": "#/components/schemas/InvitableWorkspaceRole" }, "status": { "type": "string", "enum": [ "PENDING", "PROVISIONING" ] }, "deliveryStatus": { "type": "string", "enum": [ "QUEUED", "SENT", "FAILED" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "deliveryAttempts": { "type": "integer", "minimum": 0 }, "lastDeliveryError": { "type": [ "string", "null" ] }, "lastSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "WorkspaceInvitationPreview": { "type": "object", "additionalProperties": false, "required": [ "id", "emailMasked", "workspaceName", "role", "status", "expiresAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "emailMasked": { "type": "string" }, "workspaceName": { "type": "string" }, "role": { "$ref": "#/components/schemas/InvitableWorkspaceRole" }, "status": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "ExternalUserId": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,199}$", "description": "Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address." }, "EndUserTokenRequest": { "type": "object", "properties": { "expiresIn": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 3600 }, "sessionId": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{15,127}$", "description": "High-entropy binding value. The JWT stores only its SHA-256 fingerprint; send the raw value as X-Locus-Session-Id." } }, "additionalProperties": false }, "EndUserTokenResponse": { "type": "object", "required": [ "success", "token", "expiresAt", "expiresIn", "tokenId", "externalUserId" ], "properties": { "success": { "const": true }, "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "expiresIn": { "type": "integer", "minimum": 60, "maximum": 3600 }, "tokenId": { "type": "string", "format": "uuid" }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" } }, "additionalProperties": false }, "DecimalString": { "type": "string", "pattern": "^\\d+(?:\\.\\d{1,6})?$", "description": "Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply." }, "InferenceModelCapabilities": { "type": "object", "required": [ "text", "vision", "tools", "json", "streaming", "reasoning" ], "properties": { "text": { "type": "boolean" }, "vision": { "type": "boolean" }, "tools": { "type": "boolean" }, "json": { "type": "boolean" }, "streaming": { "type": "boolean", "description": "Capability of the current Locus credits route, not only the upstream model." }, "reasoning": { "type": "boolean" } }, "additionalProperties": false }, "InferenceModelMetadata": { "type": "object", "required": [ "id", "status", "deprecationDate", "contextWindowTokens", "providerMaxOutputTokens", "locusMaxOutputTokens", "recommendedMinOutputTokens", "pricing", "capabilities", "request" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "deprecated" ] }, "deprecationDate": { "type": [ "string", "null" ], "format": "date" }, "contextWindowTokens": { "type": "integer", "minimum": 1 }, "providerMaxOutputTokens": { "type": "integer", "minimum": 1 }, "locusMaxOutputTokens": { "type": "integer", "minimum": 1 }, "recommendedMinOutputTokens": { "type": "integer", "minimum": 1 }, "pricing": { "type": "object", "required": [ "unit", "input", "output" ], "properties": { "unit": { "const": "usd_per_1m_tokens" }, "input": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" }, "output": { "type": "string", "pattern": "^\\d+(?:\\.\\d+)?$" } }, "additionalProperties": false }, "capabilities": { "$ref": "#/components/schemas/InferenceModelCapabilities" }, "request": { "type": "object", "required": [ "outputTokenField", "incompatibleFields" ], "properties": { "outputTokenField": { "type": "string", "enum": [ "max_tokens", "max_completion_tokens" ] }, "incompatibleFields": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "additionalProperties": false } }, "additionalProperties": false }, "InferenceModelCatalog": { "type": "object", "required": [ "schemaVersion", "pricingVersion", "provider", "publishedAt", "freshness", "models" ], "properties": { "schemaVersion": { "const": "2026-08-01" }, "pricingVersion": { "type": "string" }, "provider": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" }, "freshness": { "type": "object", "required": [ "maxAgeSeconds", "staleAfter", "source" ], "properties": { "maxAgeSeconds": { "type": "integer", "minimum": 0 }, "staleAfter": { "type": "string", "format": "date-time" }, "source": { "const": "locus-reviewed-static" } }, "additionalProperties": false }, "models": { "type": "array", "items": { "$ref": "#/components/schemas/InferenceModelMetadata" } } }, "additionalProperties": false }, "ModelCatalogResponse": { "type": "object", "required": [ "success", "catalog" ], "properties": { "success": { "const": true }, "catalog": { "$ref": "#/components/schemas/InferenceModelCatalog" } }, "additionalProperties": false }, "SafeUpstreamValidationDetail": { "type": "object", "properties": { "type": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "maxLength": 128 }, "param": { "type": "string", "maxLength": 256 }, "message": { "type": "string", "maxLength": 1024 } }, "additionalProperties": false }, "UpstreamWrapperError": { "type": "object", "required": [ "success", "error", "code", "upstreamStatus", "apiCallId" ], "properties": { "success": { "const": false }, "error": { "const": "Upstream API call failed" }, "code": { "const": "upstream_validation_error" }, "upstreamStatus": { "type": "integer", "enum": [ 400, 422 ] }, "validation": { "$ref": "#/components/schemas/SafeUpstreamValidationDetail" }, "apiCallId": { "type": "string" } }, "additionalProperties": false }, "McpJsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "method": { "type": "string", "examples": [ "initialize", "tools/list", "tools/call", "resources/read", "prompts/get" ] }, "params": { "type": "object", "additionalProperties": true } }, "additionalProperties": false }, "McpJsonRpcSuccess": { "type": "object", "required": [ "jsonrpc", "id", "result" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/McpToolCallResult" }, { "type": "object", "additionalProperties": true } ] } }, "additionalProperties": false }, "McpJsonRpcError": { "type": "object", "required": [ "jsonrpc", "id", "error" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "JSON-RPC/MCP protocol code, not a Locus billing status." }, "message": { "type": "string" }, "data": {} }, "additionalProperties": false } }, "additionalProperties": false }, "McpToolCallResult": { "type": "object", "required": [ "content" ], "description": "Success and application-failure result for tools/call. isError=true is failure even though the JSON-RPC promise resolved.", "properties": { "content": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/McpTextContent" }, { "$ref": "#/components/schemas/McpImageContent" }, { "$ref": "#/components/schemas/McpAudioContent" }, { "$ref": "#/components/schemas/McpEmbeddedResource" } ] } }, "isError": { "type": "boolean", "default": false }, "structuredContent": { "type": "object", "additionalProperties": true, "description": "Typed success data and compact artifact/billing descriptors. Raw binary or oversized JSON is not duplicated here." }, "_meta": { "$ref": "#/components/schemas/McpLocusMeta" } }, "additionalProperties": false }, "McpTextContent": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "text" }, "text": { "type": "string", "description": "JSON for normal results. When isError=true, parse this as McpToolErrorBody." } }, "additionalProperties": true }, "McpImageContent": { "type": "object", "required": [ "type", "data", "mimeType" ], "properties": { "type": { "const": "image" }, "data": { "type": "string", "contentEncoding": "base64" }, "mimeType": { "type": "string", "pattern": "^image/" } }, "additionalProperties": true }, "McpAudioContent": { "type": "object", "required": [ "type", "data", "mimeType" ], "properties": { "type": { "const": "audio" }, "data": { "type": "string", "contentEncoding": "base64" }, "mimeType": { "type": "string", "pattern": "^audio/" } }, "additionalProperties": true }, "McpEmbeddedResource": { "type": "object", "required": [ "type", "resource" ], "properties": { "type": { "const": "resource" }, "resource": { "type": "object", "required": [ "uri" ], "properties": { "uri": { "type": "string" }, "mimeType": { "type": "string" }, "text": { "type": "string" }, "blob": { "type": "string", "contentEncoding": "base64" } }, "additionalProperties": true } }, "additionalProperties": true }, "McpLocusMeta": { "type": "object", "properties": { "locus/status": { "type": "integer", "minimum": 100, "maximum": 599 }, "locus/creditsCharged": { "$ref": "#/components/schemas/DecimalString" }, "locus/creditsBalance": { "$ref": "#/components/schemas/DecimalString" }, "locus/costUsd": { "$ref": "#/components/schemas/DecimalString", "description": "Base USD cost; secret-key principals only." }, "locus/idempotencyKey": { "type": "string" }, "locus/approvalId": { "type": "string", "format": "uuid" }, "locus/maxChargeCredits": { "$ref": "#/components/schemas/DecimalString" }, "locus/reapprovalRequired": { "type": "boolean" }, "locus/artifact": { "$ref": "#/components/schemas/McpArtifact" }, "locus/presentation": { "$ref": "#/components/schemas/McpPresentation" } }, "additionalProperties": true }, "McpToolErrorBody": { "type": "object", "required": [ "failureClass", "retryable", "safeToRetry", "idempotencyStatus", "hint" ], "properties": { "error": { "type": "string" }, "code": { "type": "string", "examples": [ "charge_ceiling_exceeded", "approval_expired" ] }, "message": { "type": "string" }, "failureClass": { "type": "string", "enum": [ "validation", "insufficient_credits", "authorization", "discovery", "approval_or_idempotency", "rate_limit", "upstream_or_transport", "request" ] }, "retryable": { "type": "boolean" }, "safeToRetry": { "type": "boolean", "description": "True only when retrying with the same idempotency key is safe and useful." }, "retryAfter": { "type": "integer", "minimum": 1, "description": "Whole seconds to wait before retrying a rate-limited call." }, "idempotencyStatus": { "const": "protected" }, "refunded": { "type": "boolean", "description": "Present for upstream/transport failures; the caller was not charged or its reservation was released." }, "hint": { "type": "string" }, "requiredCredits": { "$ref": "#/components/schemas/DecimalString" }, "availableCredits": { "$ref": "#/components/schemas/DecimalString" }, "maxChargeCredits": { "$ref": "#/components/schemas/DecimalString" }, "currentChargeCredits": { "$ref": "#/components/schemas/DecimalString" }, "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/McpAlternative" } } }, "additionalProperties": true }, "McpAlternative": { "type": "object", "required": [ "slug", "capabilityMatch", "expectedCredits", "requiresReapproval" ], "properties": { "slug": { "type": "string" }, "capabilityMatch": { "type": "string" }, "expectedCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "const": "variable" } ] }, "requiresReapproval": { "const": true } }, "additionalProperties": false }, "McpArtifact": { "type": "object", "required": [ "uri", "mime_type", "byte_size", "sha256", "filename", "disposition", "expires_at" ], "properties": { "uri": { "type": "string", "pattern": "^urn:locus:artifact:sha256:" }, "mime_type": { "type": "string" }, "byte_size": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "filename": { "type": "string" }, "disposition": { "const": "inline" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "McpPresentation": { "type": "object", "required": [ "providerName", "actionName", "category", "description", "logoUrl", "fallback", "assetVersion", "cacheControl", "presentationOnly" ], "properties": { "providerName": { "type": "string" }, "actionName": { "type": "string" }, "category": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ], "format": "uri" }, "fallback": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "monogram" }, "text": { "type": "string", "minLength": 1 } }, "additionalProperties": false, "description": "Stable monogram used when logoUrl is absent or fails." }, "assetVersion": { "const": "1", "description": "Version token used in Locus-hosted logo URLs for cache invalidation." }, "cacheControl": { "const": "public, max-age=86400" }, "presentationOnly": { "const": true } }, "additionalProperties": false }, "TopupAmount": { "oneOf": [ { "type": "object", "required": [ "usd" ], "not": { "required": [ "credits" ] }, "properties": { "usd": { "$ref": "#/components/schemas/DecimalString" } } }, { "type": "object", "required": [ "credits" ], "not": { "required": [ "usd" ] }, "properties": { "credits": { "$ref": "#/components/schemas/DecimalString" } } } ] }, "TopupMetadata": { "type": "object", "maxProperties": 16, "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,39}$" }, "additionalProperties": { "type": "string", "maxLength": 256 }, "description": "Serialized object is limited to 500 characters." }, "TopupSelfRequest": { "allOf": [ { "$ref": "#/components/schemas/TopupAmount" }, { "type": "object", "required": [ "successUrl", "cancelUrl" ], "properties": { "usd": { "$ref": "#/components/schemas/DecimalString" }, "credits": { "$ref": "#/components/schemas/DecimalString" }, "successUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "cancelUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "metadata": { "$ref": "#/components/schemas/TopupMetadata" } }, "unevaluatedProperties": false } ] }, "TopupRequest": { "allOf": [ { "$ref": "#/components/schemas/TopupAmount" }, { "type": "object", "required": [ "successUrl", "cancelUrl" ], "properties": { "usd": { "$ref": "#/components/schemas/DecimalString" }, "credits": { "$ref": "#/components/schemas/DecimalString" }, "successUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "cancelUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "metadata": { "$ref": "#/components/schemas/TopupMetadata" } }, "unevaluatedProperties": false } ] }, "TopupQuote": { "type": "object", "required": [ "feeMode", "creditsUsd", "credits", "feeUsd", "totalUsd" ], "properties": { "feeMode": { "type": "string", "enum": [ "pass_through", "absorb" ] }, "creditsUsd": { "type": "string" }, "credits": { "type": "string" }, "feeUsd": { "type": "string" }, "totalUsd": { "type": "string" }, "bonus": { "type": [ "object", "null" ], "description": "Volume bonus this amount earns (POST /topups/quote only; tenant pool top-ups). Null when no tier is reached; end-user purchases never earn one.", "required": [ "bonusUsd", "bonusCredits", "bonusBps" ], "properties": { "bonusUsd": { "type": "string", "description": "USD value of the bonus credits, 6dp decimal string." }, "bonusCredits": { "type": "string", "description": "bonusUsd in the tenant's display denomination." }, "bonusBps": { "type": "integer", "description": "Applied bonus rate in basis points." } } }, "nextBonusTier": { "type": [ "object", "null" ], "description": "Cheapest volume-bonus tier this amount has NOT reached \u2014 the add-more upsell hint. Null at or above the top tier. POST /topups/quote only.", "required": [ "minUsd", "bonusBps" ], "properties": { "minUsd": { "type": "string" }, "bonusBps": { "type": "integer" } } } } }, "TopupSession": { "type": "object", "required": [ "success", "sessionId", "url", "externalUserId", "quote" ], "properties": { "success": { "const": true }, "sessionId": { "type": "string", "pattern": "^cs_" }, "url": { "type": "string", "format": "uri" }, "externalUserId": { "type": [ "string", "null" ] }, "quote": { "$ref": "#/components/schemas/TopupQuote" } } }, "TopupSessionResponse": { "type": "object", "required": [ "success", "sessionId", "url", "externalUserId", "quote" ], "properties": { "success": { "type": "boolean", "const": true }, "sessionId": { "type": "string", "pattern": "^cs_" }, "url": { "type": "string", "format": "uri" }, "externalUserId": { "type": [ "string", "null" ] }, "quote": { "$ref": "#/components/schemas/TopupQuote" }, "bonus": { "type": "object", "description": "Present only when this checkout session will mint a volume bonus on completion (tenant pool top-up reaching a tier).", "required": [ "bonusUsd", "bonusCredits", "bonusBps" ], "properties": { "bonusUsd": { "type": "string" }, "bonusCredits": { "type": "string" }, "bonusBps": { "type": "integer" } } } }, "additionalProperties": false }, "TopupConstraints": { "type": "object", "required": [ "currency", "minUsd", "maxUsd", "incrementUsd", "maxAmountDecimalPlaces", "amountEncoding", "creditsPerDollar", "purchasingEnabled", "disabledReason" ], "properties": { "currency": { "const": "USD" }, "minUsd": { "type": "string", "example": "5.00" }, "maxUsd": { "type": [ "string", "null" ], "const": null, "description": "No fixed platform maximum; commercial and processor controls remain risk-based." }, "incrementUsd": { "const": "0.01" }, "maxAmountDecimalPlaces": { "const": 6 }, "amountEncoding": { "const": "decimal_string" }, "creditsPerDollar": { "type": "string" }, "purchasingEnabled": { "type": "boolean", "description": "False when this tenant cannot currently create checkout sessions or buy credits." }, "disabledReason": { "type": [ "string", "null" ], "enum": [ "funding_unavailable", null ] }, "bonusTiers": { "type": "array", "description": "Volume-bonus cliff tiers over creditsUsd \u2014 the highest reached tier applies to the whole purchase. Management surface only; omitted from the end-user /me config because end-user top-ups never earn a bonus.", "items": { "type": "object", "required": [ "minUsd", "bonusBps" ], "properties": { "minUsd": { "type": "string" }, "bonusBps": { "type": "integer" } } } } } }, "TopupConstraintsEnvelope": { "type": "object", "required": [ "success", "constraints" ], "properties": { "success": { "const": true }, "constraints": { "$ref": "#/components/schemas/TopupConstraints" } } }, "TopupStatus": { "type": "object", "required": [ "success", "sessionId", "state", "paymentStatus" ], "properties": { "success": { "const": true }, "sessionId": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "completed", "expired" ] }, "paymentStatus": { "type": "string" } } }, "TopupError": { "type": "object", "required": [ "success", "error", "code", "message" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "below_minimum", "not_whole_cents", "invalid_amount", "invalid_amount_choice", "invalid_request", "invalid_url", "invalid_external_user_id", "invalid_metadata", "identity_not_allowed", "unknown_field", "invalid_session_id", "tenant_unavailable", "missing_stripe_customer" ] }, "message": { "type": "string" } } }, "TopupErrorResponse": { "type": "object", "required": [ "success", "error", "code", "message" ], "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "code": { "type": "string", "enum": [ "below_minimum", "not_whole_cents", "invalid_amount", "invalid_amount_choice", "invalid_request", "invalid_url", "invalid_external_user_id", "invalid_metadata", "identity_not_allowed", "unknown_field", "invalid_session_id", "tenant_unavailable", "missing_stripe_customer" ] }, "message": { "type": "string" } }, "additionalProperties": false }, "Tenant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended" ] }, "secretKeyPrefix": { "type": "string", "example": "lcr_live_ab12" }, "publishableKeyPrefix": { "type": "string", "example": "lcrpk_live_cd34" }, "defaultMarkupBps": { "type": "integer" }, "feeMode": { "type": "string", "enum": [ "pass_through", "absorb" ] }, "provisioningSource": { "type": "string", "enum": [ "operator", "self_serve", "system" ] }, "creditsPerDollar": { "type": "integer" } } }, "TenantCreated": { "type": "object", "required": [ "success", "tenant", "keys" ], "properties": { "success": { "const": true }, "tenant": { "$ref": "#/components/schemas/Tenant" }, "keys": { "type": "object", "required": [ "secretKey", "publishableKey", "webhookSecret" ], "properties": { "secretKey": { "type": "string", "description": "Shown exactly once" }, "publishableKey": { "type": "string", "description": "Shown exactly once" }, "webhookSecret": { "type": [ "string", "null" ], "pattern": "^whsec_", "description": "Always null during initial account creation. Configure and verify a destination after onboarding, then explicitly reveal the secret once." } }, "additionalProperties": false } }, "additionalProperties": false }, "TransferResult": { "type": "object", "required": [ "success", "externalUserId", "usd", "credits", "poolBalanceUsd", "endUserBalanceUsd" ], "properties": { "success": { "const": true }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "usd": { "$ref": "#/components/schemas/DecimalString" }, "credits": { "$ref": "#/components/schemas/DecimalString" }, "poolBalanceUsd": { "$ref": "#/components/schemas/DecimalString" }, "endUserBalanceUsd": { "$ref": "#/components/schemas/DecimalString" } }, "additionalProperties": false }, "CatalogResponse": { "type": "object", "required": [ "success", "version", "view", "tenant", "providers" ], "properties": { "success": { "const": true }, "version": { "type": "string", "const": "2026-09-06" }, "view": { "type": "string", "const": "full" }, "tenant": { "type": "object", "required": [ "defaultMarkupBps", "defaultFlatMarkupUsd", "creditsPerDollar" ], "properties": { "defaultMarkupBps": { "type": "integer" }, "defaultFlatMarkupUsd": { "$ref": "#/components/schemas/DecimalString" }, "creditsPerDollar": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProvider" } } }, "additionalProperties": false }, "CompactCatalogResponse": { "type": "object", "required": [ "success", "version", "view", "tenant", "providers", "nextCursor" ], "properties": { "success": { "const": true }, "version": { "type": "string", "const": "2026-09-06" }, "view": { "type": "string", "const": "compact" }, "tenant": { "type": "object", "required": [ "defaultMarkupBps", "defaultFlatMarkupUsd", "creditsPerDollar" ], "properties": { "defaultMarkupBps": { "type": "integer" }, "defaultFlatMarkupUsd": { "$ref": "#/components/schemas/DecimalString" }, "creditsPerDollar": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "providers": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/CompactCatalogProvider" } }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "CatalogProviderDetailResponse": { "type": "object", "required": [ "success", "version", "view", "tenant", "provider" ], "properties": { "success": { "const": true }, "version": { "type": "string", "const": "2026-09-06" }, "view": { "type": "string", "const": "detail" }, "tenant": { "type": "object", "required": [ "defaultMarkupBps", "defaultFlatMarkupUsd", "creditsPerDollar" ], "properties": { "defaultMarkupBps": { "type": "integer" }, "defaultFlatMarkupUsd": { "$ref": "#/components/schemas/DecimalString" }, "creditsPerDollar": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "provider": { "$ref": "#/components/schemas/CatalogProvider" } }, "additionalProperties": false }, "CatalogProvider": { "type": "object", "required": [ "provider", "iconFallback", "serviceUrl", "endpoints" ], "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "secondaryCategories": { "type": "array", "items": { "type": "string" }, "description": "Additional marketplace categories beyond the primary (Parse), so catalogs can file a provider under every category its marketplace lists it in." }, "verified": { "type": "boolean" }, "logoUrl": { "type": "string", "format": "uri" }, "iconFallback": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "monogram" }, "text": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "serviceUrl": { "type": "string", "format": "uri" }, "websiteUrl": { "type": "string", "format": "uri" }, "docsUrl": { "type": "string", "format": "uri" }, "catalogPriority": { "type": "integer" }, "catalogIdentity": { "type": "string" }, "attribution": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "logoUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "marketplaceRank": { "type": "integer" }, "marketplaceFeatured": { "type": "boolean" }, "externalRail": { "type": "string", "enum": [ "mpp", "x402" ] }, "availability": { "type": "string", "enum": [ "available", "temporarily_unavailable", "unknown" ], "description": "Current platform readiness. Omitted from compact agent projections." }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "delivery_breaker", "platform_pause", null ] }, "modelCatalog": { "$ref": "#/components/schemas/InferenceModelCatalog" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogEndpoint" } } }, "additionalProperties": false }, "CompactCatalogProvider": { "type": "object", "required": [ "provider", "iconFallback", "serviceUrl", "endpoints" ], "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "secondaryCategories": { "type": "array", "items": { "type": "string" }, "description": "Additional marketplace categories beyond the primary (Parse), so catalogs can file a provider under every category its marketplace lists it in." }, "verified": { "type": "boolean" }, "logoUrl": { "type": "string", "format": "uri" }, "iconFallback": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "const": "monogram" }, "text": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "serviceUrl": { "type": "string", "format": "uri" }, "websiteUrl": { "type": "string", "format": "uri" }, "docsUrl": { "type": "string", "format": "uri" }, "catalogPriority": { "type": "integer" }, "catalogIdentity": { "type": "string" }, "attribution": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "logoUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "marketplaceRank": { "type": "integer" }, "marketplaceFeatured": { "type": "boolean" }, "externalRail": { "type": "string", "enum": [ "mpp", "x402" ] }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/CompactCatalogEndpoint" } } }, "additionalProperties": false }, "CatalogEndpoint": { "type": "object", "required": [ "slug", "method", "inputSchema", "inputExample", "dynamic", "enabled", "markupBps", "overridden", "markupSource", "flatSource", "flatMarkupUsdc", "flatMarkupUsd", "baseUsdc", "chargedUsdc", "effectiveUsd", "marginUsdc", "baseCredits", "effectiveCredits", "marginCredits" ], "properties": { "slug": { "type": "string" }, "method": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "estimatedCost": { "type": "string" }, "billingModel": { "type": "string", "enum": [ "usage", "prepaid_runtime" ], "description": "Variable charge collection model; omitted for ordinary fixed-price actions." }, "inputSchema": { "type": "object", "description": "The same usable JSON Schema published by MCP tools/list for this endpoint." }, "inputExample": { "type": "object", "description": "Canonical example arguments accepted by inputSchema." }, "dynamic": { "type": "boolean" }, "enabled": { "type": "boolean" }, "availability": { "type": "string", "enum": [ "available", "temporarily_unavailable", "unknown" ], "description": "Current platform readiness. This is separate from tenant enablement." }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "delivery_breaker", "platform_pause", null ] }, "systemManaged": { "const": true, "description": "Present for virtual capability-router endpoints that ordinary catalog controls cannot disable." }, "route": { "type": "string", "description": "Exact execution route for a system-managed capability." }, "previewRoute": { "type": "string", "description": "No-dispatch estimate route for a system-managed capability." }, "markupBps": { "type": "integer" }, "overridden": { "type": "boolean" }, "markupSource": { "type": "string", "enum": [ "endpoint", "provider", "global" ] }, "flatSource": { "type": "string", "enum": [ "endpoint", "provider", "global" ] }, "flatMarkupUsdc": { "$ref": "#/components/schemas/DecimalString" }, "flatMarkupUsd": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "chargedUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "effectiveUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "marginUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "baseCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "effectiveCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "marginCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] } }, "additionalProperties": false }, "CompactCatalogEndpoint": { "type": "object", "required": [ "slug", "method", "dynamic", "enabled", "markupBps", "overridden", "markupSource", "flatSource", "flatMarkupUsdc", "flatMarkupUsd", "baseUsdc", "chargedUsdc", "effectiveUsd", "marginUsdc", "baseCredits", "effectiveCredits", "marginCredits" ], "properties": { "slug": { "type": "string" }, "method": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "estimatedCost": { "type": "string" }, "billingModel": { "type": "string", "enum": [ "usage", "prepaid_runtime" ], "description": "Variable charge collection model; omitted for ordinary fixed-price actions." }, "dynamic": { "type": "boolean" }, "enabled": { "type": "boolean" }, "systemManaged": { "const": true, "description": "Present for virtual capability-router endpoints that ordinary catalog controls cannot disable." }, "route": { "type": "string", "description": "Exact execution route for a system-managed capability." }, "previewRoute": { "type": "string", "description": "No-dispatch estimate route for a system-managed capability." }, "markupBps": { "type": "integer" }, "overridden": { "type": "boolean" }, "markupSource": { "type": "string", "enum": [ "endpoint", "provider", "global" ] }, "flatSource": { "type": "string", "enum": [ "endpoint", "provider", "global" ] }, "flatMarkupUsdc": { "$ref": "#/components/schemas/DecimalString" }, "flatMarkupUsd": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "chargedUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "effectiveUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "marginUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "baseCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "effectiveCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "marginCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] } }, "additionalProperties": false }, "SignedDecimalString": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d{1,6})?$", "description": "Exact signed USD decimal string with at most six fractional digits." }, "WebhookVerification": { "type": "object", "required": [ "id", "destinationUrl", "status", "attempts", "scheduledAt", "verifiedAt", "error" ], "properties": { "id": { "type": "string", "format": "uuid" }, "destinationUrl": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "pending", "verifying", "verified", "failed", "superseded" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 5 }, "scheduledAt": { "type": "string", "format": "date-time" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "WebhookEventType": { "type": "string", "enum": [ "credits.topup.completed", "credits.topup.failed", "credits.burn.completed", "credits.burn.failed", "credits.refund.issued", "credits.dispute.opened", "credits.dispute.closed", "credits.balance.changed", "credits.balance.low", "credits.account.frozen", "credits.usage_drift.detected", "credits.usage_drift.resolved" ] }, "WebhookTopupCompletedData": { "type": "object", "required": [ "externalUserId", "amountUsd", "balanceUsd", "reference", "source", "metadata" ], "properties": { "externalUserId": { "type": [ "string", "null" ] }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" }, "balanceUsd": { "$ref": "#/components/schemas/DecimalString" }, "reference": { "type": "string" }, "source": { "type": "string", "enum": [ "checkout_session", "auto_recharge" ] }, "bonusUsd": { "$ref": "#/components/schemas/DecimalString", "description": "Volume bonus minted alongside this top-up (pool purchases only). Present only when a bonus was actually granted; balanceUsd then reflects the post-bonus balance." }, "metadata": { "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] } }, "additionalProperties": false }, "WebhookTopupFailedData": { "type": "object", "required": [ "externalUserId", "reason", "reference" ], "properties": { "externalUserId": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "reference": { "type": "string" }, "paymentIntentId": { "type": "string" } }, "additionalProperties": false }, "WebhookBurnCompletedData": { "type": "object", "required": [ "apiCallId", "provider", "endpoint", "amountUsd", "balanceUsd", "mode", "externalUserId" ], "properties": { "apiCallId": { "type": "string" }, "provider": { "type": "string" }, "endpoint": { "type": "string" }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" }, "balanceUsd": { "$ref": "#/components/schemas/DecimalString" }, "mode": { "type": "string", "enum": [ "platform", "end_user" ] }, "externalUserId": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "WebhookBurnFailedData": { "type": "object", "required": [ "apiCallId", "provider", "endpoint", "amountUsd", "mode", "externalUserId", "reason" ], "properties": { "apiCallId": { "type": "string" }, "provider": { "type": "string" }, "endpoint": { "type": "string" }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" }, "mode": { "type": "string", "enum": [ "platform", "end_user" ] }, "externalUserId": { "type": [ "string", "null" ] }, "reason": { "type": "string" } }, "additionalProperties": false }, "WebhookRefundIssuedData": { "oneOf": [ { "type": "object", "required": [ "apiCallId", "reference", "provider", "endpoint", "amountUsd", "mode", "externalUserId", "reason" ], "properties": { "apiCallId": { "type": "string" }, "reference": { "type": "string" }, "provider": { "type": "string" }, "endpoint": { "type": "string" }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" }, "mode": { "type": "string", "enum": [ "platform", "end_user" ] }, "externalUserId": { "type": [ "string", "null" ] }, "reason": { "const": "upstream_failure" } }, "additionalProperties": false }, { "type": "object", "required": [ "externalUserId", "amountUsd", "reason", "reference" ], "properties": { "externalUserId": { "type": [ "string", "null" ] }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" }, "reason": { "const": "account_frozen" }, "reference": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "accountId", "chargeId", "amountUsd", "marginClawbackUsd", "cumulativeRefundedCents", "reason", "reference" ], "properties": { "accountId": { "type": "string" }, "chargeId": { "type": "string" }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" }, "marginClawbackUsd": { "$ref": "#/components/schemas/DecimalString" }, "bonusClawbackUsd": { "$ref": "#/components/schemas/DecimalString", "description": "Volume-bonus credits clawed back alongside the principal. Present only when the refunded top-up had earned a bonus." }, "cumulativeRefundedCents": { "type": "integer", "minimum": 0 }, "reason": { "const": "stripe_refund" }, "reference": { "type": "string" } }, "additionalProperties": false }, { "type": "object", "required": [ "externalUserId", "amountUsd", "reason", "reference" ], "properties": { "externalUserId": { "type": [ "string", "null" ] }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" }, "reason": { "const": "funding_unavailable" }, "reference": { "type": "string" } }, "additionalProperties": false } ] }, "WebhookDisputeOpenedData": { "type": "object", "required": [ "accountId", "disputeId", "amountUsd", "clawbackUsd", "marginClawbackUsd", "status" ], "properties": { "accountId": { "type": "string" }, "disputeId": { "type": "string" }, "amountUsd": { "$ref": "#/components/schemas/DecimalString" }, "clawbackUsd": { "$ref": "#/components/schemas/DecimalString" }, "marginClawbackUsd": { "$ref": "#/components/schemas/DecimalString" }, "bonusClawbackUsd": { "$ref": "#/components/schemas/DecimalString", "description": "Volume-bonus credits clawed alongside the principal. Present only when the disputed top-up had earned a bonus." }, "status": { "type": "string" } }, "additionalProperties": false }, "WebhookDisputeClosedData": { "type": "object", "required": [ "accountId", "disputeId", "outcome" ], "properties": { "accountId": { "type": [ "string", "null" ] }, "disputeId": { "type": "string" }, "outcome": { "type": "string" } }, "additionalProperties": false }, "WebhookBalanceChangedData": { "type": "object", "required": [ "reference", "externalUserId", "deltaUsd", "balanceUsd", "reason" ], "properties": { "apiCallId": { "type": "string" }, "reference": { "type": "string" }, "externalUserId": { "type": [ "string", "null" ] }, "deltaUsd": { "$ref": "#/components/schemas/SignedDecimalString" }, "balanceUsd": { "$ref": "#/components/schemas/DecimalString" }, "reason": { "type": "string", "enum": [ "topup", "burn", "refund", "dispute_reversal", "allocate", "deallocate" ] } }, "additionalProperties": false }, "WebhookBalanceLowData": { "type": "object", "required": [ "reason" ], "properties": { "balanceUsd": { "$ref": "#/components/schemas/DecimalString" }, "thresholdUsd": { "$ref": "#/components/schemas/DecimalString" }, "reason": { "type": "string" }, "paymentIntentId": { "type": "string" } }, "additionalProperties": false }, "WebhookAccountFrozenData": { "type": "object", "required": [ "accountId", "disputeId", "reason" ], "properties": { "accountId": { "type": "string" }, "disputeId": { "type": "string" }, "reason": { "const": "dispute_opened" } }, "additionalProperties": false }, "WebhookEventEnvelope": { "type": "object", "required": [ "id", "type", "api_version", "created_at", "sequence", "tenant_id", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "api_version": { "const": "2026-08-13" }, "created_at": { "type": "string", "format": "date-time" }, "sequence": { "type": "string", "pattern": "^\\d+$" }, "tenant_id": { "type": "string", "format": "uuid" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/WebhookTopupCompletedData" }, { "$ref": "#/components/schemas/WebhookTopupFailedData" }, { "$ref": "#/components/schemas/WebhookBurnCompletedData" }, { "$ref": "#/components/schemas/WebhookBurnFailedData" }, { "$ref": "#/components/schemas/WebhookRefundIssuedData" }, { "$ref": "#/components/schemas/WebhookDisputeOpenedData" }, { "$ref": "#/components/schemas/WebhookDisputeClosedData" }, { "$ref": "#/components/schemas/WebhookBalanceChangedData" }, { "$ref": "#/components/schemas/WebhookBalanceLowData" }, { "$ref": "#/components/schemas/WebhookAccountFrozenData" } ] } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "attempt", "destination_url", "status", "manual_replay", "scheduled_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "attempt": { "type": "integer", "minimum": 1 }, "destination_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "pending", "delivering", "delivered", "failed" ] }, "manual_replay": { "type": "boolean" }, "scheduled_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "http_status": { "type": [ "integer", "null" ] }, "response_body": { "type": [ "string", "null" ], "maxLength": 1024 }, "error": { "type": [ "string", "null" ] } } }, "WebhookEventPage": { "type": "object", "required": [ "success", "data", "next_cursor" ], "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "required": [ "retained_until", "delivery" ], "properties": { "retained_until": { "type": "string", "format": "date-time" }, "delivery": { "oneOf": [ { "$ref": "#/components/schemas/WebhookDelivery" }, { "type": "null" } ] } } } ] } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } } }, "WebhookEventDetail": { "type": "object", "required": [ "success", "event" ], "properties": { "success": { "const": true }, "event": { "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "required": [ "retained_until", "deliveries" ], "properties": { "retained_until": { "type": "string", "format": "date-time" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } } } ] } } }, "AnalyticsSummary": { "type": "object", "required": [ "usageUsdc", "baseUsdc", "marginUsdc", "calls", "activeUsers" ], "properties": { "usageUsdc": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "$ref": "#/components/schemas/DecimalString" }, "marginUsdc": { "$ref": "#/components/schemas/DecimalString" }, "calls": { "type": "integer", "minimum": 0 }, "activeUsers": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "AnalyticsDay": { "type": "object", "additionalProperties": false, "required": [ "date", "usageUsdc", "baseUsdc", "marginUsdc", "calls", "activeUsers" ], "properties": { "date": { "type": "string", "format": "date" }, "usageUsdc": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "$ref": "#/components/schemas/DecimalString" }, "marginUsdc": { "$ref": "#/components/schemas/DecimalString" }, "calls": { "type": "integer", "minimum": 0 }, "activeUsers": { "type": "integer", "minimum": 0 } } }, "AnalyticsService": { "type": "object", "additionalProperties": false, "required": [ "provider", "endpoint", "usageUsdc", "baseUsdc", "marginUsdc", "calls", "activeUsers", "spenders" ], "properties": { "provider": { "type": "string" }, "endpoint": { "type": [ "string", "null" ] }, "usageUsdc": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "$ref": "#/components/schemas/DecimalString" }, "marginUsdc": { "$ref": "#/components/schemas/DecimalString" }, "calls": { "type": "integer", "minimum": 0 }, "activeUsers": { "type": "integer", "minimum": 0, "description": "Distinct END USERS. Pooled agents, API keys and members have no end user, so an endpoint driven only by those reports zero here." }, "spenders": { "type": "integer", "minimum": 0, "description": "Distinct spenders, the same population AnalyticsProvider.spenders counts." } } }, "AnalyticsUser": { "type": "object", "required": [ "externalUserId", "usageUsdc", "marginUsdc", "calls" ], "properties": { "externalUserId": { "oneOf": [ { "$ref": "#/components/schemas/ExternalUserId" }, { "type": "null" } ] }, "usageUsdc": { "$ref": "#/components/schemas/DecimalString" }, "marginUsdc": { "$ref": "#/components/schemas/DecimalString" }, "calls": { "type": "integer", "minimum": 0 } }, "additionalProperties": false }, "AnalyticsResponse": { "type": "object", "required": [ "success", "analytics" ], "properties": { "success": { "const": true }, "analytics": { "type": "object", "required": [ "days", "bucket", "filter", "timezone", "periodStart", "periodEndExclusive", "priorPeriodStart", "priorPeriodEndExclusive", "summary", "priorSummary", "series", "daily", "services", "providers", "users", "initiators", "usageDrift" ], "properties": { "days": { "type": [ "integer", "null" ], "enum": [ 7, 30, 90, null ], "description": "Echo of the legacy form; null when the request used from/to." }, "bucket": { "type": "string", "enum": [ "hour", "day", "week", "month" ] }, "filter": { "$ref": "#/components/schemas/AnalyticsFilter" }, "timezone": { "const": "UTC" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEndExclusive": { "type": "string", "format": "date-time" }, "priorPeriodStart": { "type": "string", "format": "date-time" }, "priorPeriodEndExclusive": { "type": "string", "format": "date-time" }, "summary": { "$ref": "#/components/schemas/AnalyticsSummary" }, "priorSummary": { "$ref": "#/components/schemas/AnalyticsSummary" }, "series": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsBucket" } }, "daily": { "type": "array", "description": "series relabelled by the UTC day of each bucket start; identical to series when bucket is day.", "items": { "$ref": "#/components/schemas/AnalyticsDay" } }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsService" } }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsProvider" } }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsUser" } }, "initiators": { "type": "array", "items": { "$ref": "#/components/schemas/AnalyticsInitiator" } }, "usageDrift": { "oneOf": [ { "$ref": "#/components/schemas/UsageDriftAnalytics" }, { "type": "null" } ] } }, "additionalProperties": false } }, "additionalProperties": false }, "EndUserCatalogEndpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "displayName", "description", "enabled", "price" ], "properties": { "id": { "type": "string", "description": "Stable public endpoint ID" }, "slug": { "type": "string", "example": "tavily/search" }, "displayName": { "type": "string", "example": "Search" }, "description": { "type": "string", "description": "Price- and policy-neutral endpoint description" }, "enabled": { "type": "boolean", "const": true }, "price": { "$ref": "#/components/schemas/EndUserCatalogPrice" } } }, "EndUserCatalogPrice": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "state", "credits", "usd" ], "properties": { "state": { "type": "string", "const": "exact" }, "credits": { "type": "string" }, "usd": { "type": "string", "description": "Final customer-visible effective USD price; never base cost" } } }, { "type": "object", "additionalProperties": false, "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "dynamic", "unavailable" ] } } } ] }, "EndUserCatalogProvider": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "displayName", "category", "description", "logoUrl", "enabled", "endpoints" ], "properties": { "id": { "type": "string", "description": "Stable public provider ID" }, "slug": { "type": "string" }, "displayName": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "logoUrl": { "type": "string", "format": "uri", "description": "Absolute stable brand-asset URL" }, "enabled": { "type": "boolean", "const": true }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/EndUserCatalogEndpoint" } } } }, "EndUserCatalogResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "version", "providers", "nextCursor" ], "properties": { "success": { "type": "boolean", "const": true }, "version": { "type": "string", "const": "2026-08-14" }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/EndUserCatalogProvider" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "LedgerEntry": { "type": "object", "additionalProperties": false, "required": [ "id", "direction", "category", "amountUsdc", "amountCredits", "balanceAfterUsdc", "baseUsdc", "marginUsdc", "markupBps", "sourceKey", "externalReference", "externalUserId", "metadata", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "direction": { "type": "string", "enum": [ "DEBIT", "CREDIT" ] }, "category": { "type": "string" }, "amountUsdc": { "$ref": "#/components/schemas/DecimalString" }, "amountCredits": { "$ref": "#/components/schemas/DecimalString" }, "balanceAfterUsdc": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "marginUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "markupBps": { "type": [ "integer", "null" ] }, "sourceKey": { "type": "string" }, "externalReference": { "type": [ "string", "null" ] }, "externalUserId": { "type": [ "string", "null" ] }, "metadata": {}, "createdAt": { "type": "string", "format": "date-time" } } }, "EndUserPolicyInput": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "type": "string", "enum": [ "ask", "bounded", "unlimited" ] }, "budgetPeriod": { "type": [ "string", "null" ], "enum": [ "hour", "day", "week", "month", null ] }, "budgetCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "maxChargeCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "allowProviders": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 200 }, "denyProviders": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 200 }, "allowEndpoints": { "type": [ "array", "null" ], "items": { "type": "string", "description": "provider/endpoint" }, "maxItems": 200 }, "denyEndpoints": { "type": [ "array", "null" ], "items": { "type": "string", "description": "provider/endpoint" }, "maxItems": 200 }, "allowModels": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 200 }, "denyModels": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 200 }, "maxConcurrentReservations": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000 }, "maxCallsPerPeriod": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000 }, "maxCallsPerLoop": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000 } }, "additionalProperties": false }, "EndUserPolicy": { "allOf": [ { "$ref": "#/components/schemas/EndUserPolicyInput" }, { "type": "object", "required": [ "id", "activeReservations", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "activeReservations": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } } ] }, "EndUserPolicyEnvelope": { "type": "object", "required": [ "success", "externalUserId", "policy" ], "properties": { "success": { "const": true }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "policy": { "oneOf": [ { "$ref": "#/components/schemas/EndUserPolicy" }, { "type": "null" } ] } } }, "EndUserPolicyEvent": { "type": "object", "required": [ "id", "policyId", "accountId", "action", "reasonCode", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "policyId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "reservationId": { "type": [ "string", "null" ], "format": "uuid" }, "action": { "type": "string", "enum": [ "ALLOW", "DENY", "CAPTURE", "RELEASE" ] }, "reasonCode": { "type": "string", "description": "Stable POLICY_* denial code or lifecycle reason." }, "amountUsdc": { "type": [ "string", "null" ] }, "amountCredits": { "type": [ "string", "null" ] }, "idempotencyKey": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "OpenAIChatCompletionRequest": { "type": "object", "required": [ "model", "messages" ], "properties": { "model": { "type": "string" }, "messages": { "type": "array", "minItems": 1, "items": { "type": "object", "additionalProperties": true } }, "stream": { "type": "boolean", "default": false }, "stream_options": { "type": "object", "additionalProperties": true }, "max_tokens": { "type": "integer", "minimum": 1 }, "max_completion_tokens": { "type": "integer", "minimum": 1, "description": "For reviewed reasoning models, an explicit value must be at least that model's recommendedMinOutputTokens (currently 4000); smaller budgets are rejected before dispatch or billing because hidden reasoning can exhaust the budget before visible output." }, "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "tool_choice": {} }, "additionalProperties": true }, "CreditsCallStatus": { "type": "object", "required": [ "apiCallId", "status", "provider", "endpoint", "stream", "billing", "createdAt" ], "properties": { "apiCallId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "provider": { "type": "string" }, "endpoint": { "type": "string" }, "stream": { "oneOf": [ { "type": "null" }, { "type": "object", "required": [ "state", "contentType" ], "properties": { "state": { "type": "string", "enum": [ "streaming", "completed", "client_disconnected", "upstream_error", "settlement_pending" ] }, "contentType": { "type": "string" }, "error": { "type": "string" } } } ] }, "billing": { "type": "object", "required": [ "chargedCredits", "balanceCredits", "settlement" ], "properties": { "chargedCredits": { "$ref": "#/components/schemas/DecimalString" }, "balanceCredits": { "$ref": "#/components/schemas/DecimalString" }, "settlement": { "type": "string", "enum": [ "captured-before-delivery", "standard" ] } } }, "error": { "type": [ "string", "null" ] }, "errorStage": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "EndUserAccount": { "type": "object", "required": [ "externalUserId", "accountId", "balanceUsdc", "balanceCredits", "status", "createdAt" ], "properties": { "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "accountId": { "type": "string", "format": "uuid" }, "balanceUsdc": { "$ref": "#/components/schemas/DecimalString" }, "balanceCredits": { "$ref": "#/components/schemas/DecimalString" }, "status": { "type": "string", "enum": [ "active", "frozen" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "WorkspaceSpendLimitDenial": { "type": "object", "description": "Terminal denial returned when a burn would push the workspace past its monthly spend ceiling. Do not retry before resetsAt: the ceiling is a workspace setting, not a transient condition, and the call was never dispatched so no credits moved.", "additionalProperties": false, "required": [ "error", "code", "message", "limitUsd", "committedUsd", "requestedUsd", "resetsAt", "apiCallId" ], "properties": { "success": { "const": false, "description": "Present on external-rail denials and absent on hosted-provider denials. Match on `code`, not on this field." }, "error": { "const": "Workspace monthly spend limit reached" }, "code": { "const": "TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED" }, "message": { "type": "string" }, "limitUsd": { "$ref": "#/components/schemas/DecimalString" }, "committedUsd": { "$ref": "#/components/schemas/DecimalString", "description": "Captured plus in-flight spend already counted against the ceiling." }, "requestedUsd": { "$ref": "#/components/schemas/DecimalString", "description": "What this call would have added." }, "resetsAt": { "type": "string", "format": "date-time", "description": "When the window rolls over and burns resume. Raising monthlyLimitUsd also clears the denial immediately." }, "apiCallId": { "type": "string", "format": "uuid" } } }, "WorkspaceSpendControls": { "type": "object", "description": "Account-wide monthly spend controls and low-balance notification state, plus the live position in the current UTC month window. Available to Personal and enterprise accounts. Amounts are exact USD decimal strings.", "additionalProperties": false, "required": [ "periodStart", "periodEnd", "spentUsd", "pendingUsd", "committedUsd", "remainingUsd", "monthlyLimitUsd", "alertThresholdUsd", "lowBalanceAlertUsd", "lowBalanceAlertSentAt", "hardLimitReached", "alert" ], "properties": { "periodStart": { "type": "string", "format": "date-time", "description": "Start of the current UTC calendar-month window." }, "periodEnd": { "type": "string", "format": "date-time", "description": "When the window resets." }, "spentUsd": { "allOf": [ { "$ref": "#/components/schemas/DecimalString" } ], "description": "Captured spend in this window." }, "pendingUsd": { "allOf": [ { "$ref": "#/components/schemas/DecimalString" } ], "description": "Held but not yet captured (in-flight calls)." }, "committedUsd": { "allOf": [ { "$ref": "#/components/schemas/DecimalString" } ], "description": "spentUsd plus pendingUsd \u2014 the figure checked against the limit." }, "remainingUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "null when no monthly limit is set." }, "monthlyLimitUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "Hard ceiling. null means unlimited." }, "alertThresholdUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "Monthly spend email trigger. null means no alert." }, "lowBalanceAlertUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "Remaining prepaid-balance email trigger. null means no alert." }, "lowBalanceAlertSentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the current low-balance crossing was emailed. null while armed; it returns to null after the balance recovers above the threshold." }, "hardLimitReached": { "type": "boolean", "description": "true once committedUsd reaches monthlyLimitUsd. Further burns are denied with TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED until the window resets." }, "alert": { "type": "object", "additionalProperties": false, "required": [ "status", "triggeredAt", "sentAt", "lastError" ], "properties": { "status": { "type": [ "string", "null" ], "enum": [ "pending", "sent", "failed", null ] }, "triggeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] } } } } }, "PricingExplain": { "type": "object", "description": "The base-cost to effective-price translation for one endpoint, including which configuration level supplied each markup. Money fields are exact decimal strings, and are null for endpoints priced live per call.", "additionalProperties": false, "required": [ "provider", "endpoint", "slug", "method", "dynamic", "estimated", "enabled", "creditsPerDollar", "markupBps", "markupSource", "flatSource", "overridden", "baseUsd", "baseCredits", "markupUsd", "flatMarkupUsd", "marginUsd", "marginCredits", "effectiveUsd", "effectiveCredits", "humanSummary" ], "properties": { "provider": { "type": "string" }, "endpoint": { "type": "string" }, "slug": { "type": "string", "description": "provider/endpoint" }, "method": { "type": "string", "description": "Upstream HTTP method." }, "dynamic": { "type": "boolean", "description": "true when the endpoint is metered and priced per call." }, "estimated": { "type": "boolean", "description": "true when baseUsd is an estimate rather than a fixed price." }, "enabled": { "type": "boolean" }, "creditsPerDollar": { "type": "integer" }, "markupBps": { "type": "integer" }, "markupSource": { "type": "string", "enum": [ "endpoint", "provider", "global" ] }, "flatSource": { "type": "string", "enum": [ "endpoint", "provider", "global" ] }, "overridden": { "type": "boolean", "description": "true when either markup comes from a provider or endpoint override rather than the tenant default." }, "baseUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "baseCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "markupUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ], "description": "Percentage portion: base times bps/10000, ceiling at 6dp." }, "flatMarkupUsd": { "allOf": [ { "$ref": "#/components/schemas/DecimalString" } ] }, "marginUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "marginCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "effectiveUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "effectiveCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "humanSummary": { "type": "string", "description": "One-sentence plain-language explanation of the price." } } }, "CredentialAuditEvent": { "type": "object", "description": "One credential-lifecycle event. Raw credentials and key hashes are never included.", "additionalProperties": false, "required": [ "id", "credentialType", "credentialId", "action", "actorType", "actorId", "metadata", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "credentialType": { "type": "string", "description": "Which credential family the event describes, for example api_key, agent_connection, end_user_token, or webhook_secret." }, "credentialId": { "type": [ "string", "null" ] }, "action": { "type": "string", "description": "issued, rotated, or revoked." }, "actorType": { "type": "string", "description": "Whether a signed-in member, a secret key, or the system performed it." }, "actorId": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "SecurityAuditEvent": { "type": "object", "description": "One sensitive-mutation audit row, written before the success response and fail-closed if the audit write fails. Submitted credentials are redacted inside beforeState and afterState.", "additionalProperties": false, "required": [ "id", "action", "resourceType", "actorType", "authMethod", "requestId", "outcome", "httpStatus", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "tenantId": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "resourceType": { "type": "string" }, "resourceId": { "type": [ "string", "null" ] }, "actorType": { "type": "string" }, "actorId": { "type": [ "string", "null" ] }, "authMethod": { "type": "string" }, "requestId": { "type": "string" }, "sourceIp": { "type": [ "string", "null" ] }, "outcome": { "type": "string" }, "httpStatus": { "type": "integer" }, "beforeState": { "type": [ "object", "null" ], "additionalProperties": true }, "afterState": { "type": [ "object", "null" ], "additionalProperties": true }, "errorCode": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "EndUserTokenRecord": { "type": "object", "description": "Metadata for one minted end-user token. The token itself is returned only at mint time and is never recoverable.", "additionalProperties": false, "required": [ "id", "signingKeyId", "status", "expiresAt", "revokedAt", "revokedReason", "lastUsedAt", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "signingKeyId": { "type": "string", "description": "kid of the RS256 key that signed it, resolvable through the public JWKS." }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ], "description": "Reported as expired as soon as expiresAt has passed, without waiting for a sweep." }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revokedReason": { "type": [ "string", "null" ] }, "lastUsedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "StripeConnectStatus": { "type": "object", "description": "Stripe Connect linkage for margin payouts.", "additionalProperties": false, "required": [ "configured", "connected", "accountId", "payoutMethod", "payoutsEnabled" ], "properties": { "configured": { "type": "boolean", "description": "false when this deployment has no Connect application configured." }, "connected": { "type": "boolean" }, "accountId": { "type": [ "string", "null" ], "description": "The tenant's own Stripe account id." }, "payoutMethod": { "type": "string", "enum": [ "usdc", "stripe" ] }, "payoutsEnabled": { "type": [ "boolean", "null" ], "description": "Live capability read from Stripe. null when the account is unreachable or not linked." } } }, "AgentRegistrationToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{32}$", "description": "Canonical base64url encoding of 24 bytes generated by a cryptographically secure random-number generator." }, "AgentNativeRegistrationRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "registrationToken" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Control and bidirectional-formatting characters are rejected." }, "registrationToken": { "$ref": "#/components/schemas/AgentRegistrationToken" }, "agentEmail": { "type": "string", "format": "email", "maxLength": 320, "description": "Optional AgentID inbox sent as login_hint. The verified token claim is authoritative." } } }, "AgentOwnedBalance": { "type": "object", "additionalProperties": false, "required": [ "usd", "credits", "creditsPerDollar" ], "properties": { "usd": { "$ref": "#/components/schemas/DecimalString" }, "credits": { "$ref": "#/components/schemas/DecimalString" }, "creditsPerDollar": { "type": "string", "pattern": "^\\d+$" } } }, "AgentOwnedAccount": { "type": "object", "required": [ "id", "name", "status", "onboardingState", "balance", "connection", "identity", "mcp", "links", "nextAction", "activated" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "onboardingState": { "type": "string", "enum": [ "funding_required", "ready" ] }, "balance": { "$ref": "#/components/schemas/AgentOwnedBalance" }, "connection": { "type": "object", "additionalProperties": false, "required": [ "id", "keyPrefix", "expiresAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "keyPrefix": { "type": "string", "pattern": "^lcac_" }, "expiresAt": { "type": "string", "format": "date-time" }, "credential": { "type": "string", "pattern": "^lcac_", "description": "Returned on registration replay and rotation. Store immediately." } } }, "identity": { "type": "object", "additionalProperties": false, "required": [ "provider", "email" ], "properties": { "provider": { "const": "agentid" }, "email": { "type": "string", "format": "email" } } }, "mcp": { "type": "object", "additionalProperties": true }, "links": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "nextAction": { "type": "object", "additionalProperties": true }, "created": { "type": "boolean" }, "credentialRenewed": { "type": "boolean" }, "credentialRecovered": { "type": "boolean" }, "activated": { "const": true } } }, "AgentOwnedAccountEnvelope": { "type": "object", "additionalProperties": false, "required": [ "success", "account" ], "properties": { "success": { "const": true }, "account": { "$ref": "#/components/schemas/AgentOwnedAccount" } } }, "AgentFundingState": { "type": "string", "enum": [ "awaiting_payment", "processing", "ready", "expired", "failed" ] }, "AgentFundingQuote": { "type": "object", "additionalProperties": false, "required": [ "feeMode", "creditsUsd", "credits", "feeUsd", "totalUsd" ], "properties": { "feeMode": { "type": "string", "enum": [ "pass_through", "absorb" ] }, "creditsUsd": { "$ref": "#/components/schemas/DecimalString" }, "credits": { "$ref": "#/components/schemas/DecimalString" }, "feeUsd": { "$ref": "#/components/schemas/DecimalString" }, "totalUsd": { "$ref": "#/components/schemas/DecimalString" } } }, "AgentFundingSession": { "type": "object", "additionalProperties": false, "required": [ "success", "fundingSessionId", "checkoutUrl", "statusUrl", "expiresAt", "quote", "humanHandoff", "pollAfterMs" ], "properties": { "success": { "const": true }, "fundingSessionId": { "type": "string", "pattern": "^cs_" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "Share only this Stripe-hosted URL with the human payer." }, "statusUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "quote": { "$ref": "#/components/schemas/AgentFundingQuote" }, "humanHandoff": { "type": "object", "additionalProperties": false, "required": [ "message", "instruction" ], "properties": { "message": { "type": "string" }, "instruction": { "type": "string" } } }, "pollAfterMs": { "type": "integer", "minimum": 1000 } } }, "AgentFundingStatus": { "type": "object", "additionalProperties": false, "required": [ "success", "fundingSessionId", "state", "paymentStatus", "balance", "nextAction" ], "properties": { "success": { "const": true }, "fundingSessionId": { "type": "string", "pattern": "^cs_" }, "state": { "$ref": "#/components/schemas/AgentFundingState" }, "paymentStatus": { "type": "string" }, "balance": { "$ref": "#/components/schemas/AgentOwnedBalance" }, "nextAction": { "type": "object", "additionalProperties": true } } }, "AgentFundingPublicStatus": { "type": "object", "additionalProperties": false, "required": [ "success", "funding" ], "properties": { "success": { "const": true }, "funding": { "type": "object", "additionalProperties": false, "required": [ "state", "agentName", "creditsUsd", "credits" ], "properties": { "state": { "$ref": "#/components/schemas/AgentFundingState" }, "agentName": { "type": "string" }, "creditsUsd": { "$ref": "#/components/schemas/DecimalString" }, "credits": { "$ref": "#/components/schemas/DecimalString" } } } } }, "TopupQuoteRequest": { "description": "Quote pricing for a hypothetical top-up. Declare externalUserId when the eventual create targets an end user, so the quote's bonus fields match what the create will actually grant (end-user top-ups never earn a volume bonus).", "allOf": [ { "$ref": "#/components/schemas/TopupAmount" }, { "type": "object", "properties": { "usd": { "$ref": "#/components/schemas/DecimalString" }, "credits": { "$ref": "#/components/schemas/DecimalString" }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" } }, "unevaluatedProperties": false } ] }, "DashboardCatalogResponse": { "type": "object", "description": "view=dashboard: the compact paging projected to the fields the Locus Pro dashboard renders. Same ETag/cache semantics as CompactCatalogResponse.", "required": [ "success", "version", "view", "tenant", "providers", "nextCursor" ], "properties": { "success": { "const": true }, "version": { "type": "string", "const": "2026-09-06" }, "view": { "type": "string", "const": "dashboard" }, "tenant": { "type": "object", "required": [ "defaultMarkupBps", "defaultFlatMarkupUsd", "creditsPerDollar" ], "properties": { "defaultMarkupBps": { "type": "integer" }, "defaultFlatMarkupUsd": { "$ref": "#/components/schemas/DecimalString" }, "creditsPerDollar": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "providers": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/DashboardCatalogProvider" } }, "nextCursor": { "type": [ "string", "null" ] }, "filter": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "const": true } }, "additionalProperties": false, "description": "Present when the page was narrowed by enabled=true." }, "pageCursors": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 512 }, "description": "First page only: the cursor of every following page, so the rest of the walk can be fetched concurrently. Omitted when the walk has more than 100 further pages. A page whose own nextCursor differs from the next published cursor signals a registry change; restart with nextCursor." } }, "additionalProperties": false }, "DashboardCatalogProvider": { "type": "object", "required": [ "provider", "logoUrl", "serviceUrl", "endpoints" ], "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "secondaryCategories": { "type": "array", "items": { "type": "string" }, "description": "Additional marketplace categories beyond the primary (Parse), so catalogs can file a provider under every category its marketplace lists it in." }, "verified": { "type": "boolean" }, "logoUrl": { "type": "string", "format": "uri" }, "serviceUrl": { "type": "string", "format": "uri" }, "websiteUrl": { "type": "string", "format": "uri" }, "docsUrl": { "type": "string", "format": "uri" }, "catalogIdentity": { "type": "string" }, "attribution": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "logoUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "marketplaceRank": { "type": "integer" }, "marketplaceFeatured": { "type": "boolean" }, "catalogPriority": { "type": "integer" }, "externalRail": { "type": "string", "enum": [ "mpp", "x402" ] }, "availability": { "type": "string", "enum": [ "available", "temporarily_unavailable", "unknown" ], "description": "Current platform readiness. This is separate from tenant enablement." }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "delivery_breaker", "platform_pause", null ] }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardCatalogEndpoint" } } }, "additionalProperties": false }, "DashboardCatalogEndpoint": { "type": "object", "required": [ "slug", "method", "dynamic", "enabled", "mcpPinned", "overridden", "markupBps", "flatMarkupUsdc", "baseUsdc", "chargedUsdc", "marginUsdc" ], "properties": { "slug": { "type": "string" }, "method": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "estimatedCost": { "type": "string", "description": "Display-only estimate present for dynamic-price endpoints." }, "billingModel": { "type": "string", "enum": [ "usage", "prepaid_runtime" ], "description": "Variable charge collection model; omitted for ordinary fixed-price actions." }, "dynamic": { "type": "boolean" }, "enabled": { "type": "boolean" }, "mcpPinned": { "type": "boolean" }, "overridden": { "type": "boolean", "description": "Markup or flat fee come from a row of this endpoint's own or its provider's, not the workspace default." }, "availability": { "type": "string", "enum": [ "available", "temporarily_unavailable", "unknown" ], "description": "Current platform readiness. This is separate from tenant enablement." }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "delivery_breaker", "platform_pause", null ] }, "systemManaged": { "const": true }, "route": { "type": "string" }, "previewRoute": { "type": "string" }, "markupBps": { "type": "integer" }, "flatMarkupUsdc": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "chargedUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "marginUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] } }, "additionalProperties": false }, "UsageDriftDetection": { "type": "object", "required": [ "id", "feature", "appVersion", "status", "severity", "mode", "coverageRatio", "baselineSamples", "currentSamples", "requiredSamples", "baseline", "current", "percentageChange", "adjustedPValue", "contributors", "lastEvaluatedAt", "ledgerFilterPath", "informational" ], "properties": { "id": { "type": "string", "format": "uuid" }, "feature": { "type": "string" }, "appVersion": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "SHADOW", "ACTIVE", "RESOLVED" ] }, "severity": { "type": "string", "enum": [ "INFO", "WARNING", "CRITICAL" ] }, "mode": { "type": "string", "enum": [ "shadow", "enabled" ] }, "coverageRatio": { "$ref": "#/components/schemas/DecimalString" }, "baselineSamples": { "type": "integer", "minimum": 0 }, "currentSamples": { "type": "integer", "minimum": 0 }, "requiredSamples": { "type": "integer", "minimum": 0 }, "baseline": { "type": "object" }, "current": { "type": "object" }, "percentageChange": { "type": [ "string", "null" ] }, "adjustedPValue": { "type": [ "string", "null" ] }, "contributors": { "type": "object" }, "firstSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "detectedAt": { "type": [ "string", "null" ], "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastEvaluatedAt": { "type": "string", "format": "date-time" }, "ledgerFilterPath": { "type": "string" }, "informational": { "const": true } } }, "UsageDriftAnalytics": { "type": "object", "required": [ "mode", "attributionCoverageRequired", "currentWindowDays", "baselineWindowDays", "collecting", "active", "recentResolved" ], "properties": { "mode": { "type": "string", "enum": [ "shadow", "enabled" ] }, "attributionCoverageRequired": { "$ref": "#/components/schemas/DecimalString" }, "currentWindowDays": { "type": "integer" }, "baselineWindowDays": { "type": "integer" }, "collecting": { "type": "integer", "minimum": 0 }, "active": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDriftDetection" } }, "recentResolved": { "type": "array", "items": { "$ref": "#/components/schemas/UsageDriftDetection" } } }, "additionalProperties": false }, "AgentSignupPending": { "type": "object", "additionalProperties": false, "required": [ "onboardingState", "registration", "nextAction", "activated" ], "properties": { "onboardingState": { "const": "identity_required" }, "registration": { "type": "object", "additionalProperties": false, "required": [ "id", "provider", "status", "authorizationUrl", "expiresAt", "pollAfterMs" ], "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "const": "agentid" }, "status": { "type": "string", "enum": [ "pending", "verified" ] }, "authorizationUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" }, "pollAfterMs": { "type": "integer", "minimum": 1000 } } }, "nextAction": { "type": "object", "additionalProperties": true }, "activated": { "const": false } } }, "AgentSignupPendingEnvelope": { "type": "object", "additionalProperties": false, "required": [ "success", "account" ], "properties": { "success": { "const": true }, "account": { "$ref": "#/components/schemas/AgentSignupPending" } } }, "AnalyticsBucket": { "type": "object", "description": "One gap-filled series bucket.", "additionalProperties": false, "required": [ "start", "usageUsdc", "baseUsdc", "marginUsdc", "calls", "activeUsers" ], "properties": { "start": { "type": "string", "format": "date-time", "description": "First instant of the bucket (UTC)." }, "usageUsdc": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "$ref": "#/components/schemas/DecimalString" }, "marginUsdc": { "$ref": "#/components/schemas/DecimalString" }, "calls": { "type": "integer", "minimum": 0 }, "activeUsers": { "type": "integer", "minimum": 0 } } }, "AnalyticsProvider": { "type": "object", "description": "Provider-level rollup: every endpoint of one provider folded together.", "additionalProperties": false, "required": [ "provider", "spenders", "endpoints", "usageUsdc", "baseUsdc", "marginUsdc", "calls", "activeUsers" ], "properties": { "provider": { "type": "string" }, "spenders": { "type": "integer", "description": "Distinct spenders who used the provider." }, "endpoints": { "type": "integer", "description": "Distinct endpoints used; a provider-level burn with no endpoint counts as one." }, "usageUsdc": { "$ref": "#/components/schemas/DecimalString" }, "baseUsdc": { "$ref": "#/components/schemas/DecimalString" }, "marginUsdc": { "$ref": "#/components/schemas/DecimalString" }, "calls": { "type": "integer", "minimum": 0 }, "activeUsers": { "type": "integer", "minimum": 0 } } }, "AnalyticsInitiator": { "type": "object", "additionalProperties": false, "required": [ "type", "initiatorId", "label", "authMethod", "clients", "usageUsdc", "marginUsdc", "calls", "providers" ], "properties": { "type": { "type": "string", "enum": [ "oauth_member", "end_user", "agent_connection", "credential", "unattributed" ] }, "initiatorId": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "authMethod": { "type": [ "string", "null" ] }, "clients": { "type": "array", "items": { "type": "string" } }, "usageUsdc": { "type": "string" }, "marginUsdc": { "type": "string" }, "calls": { "type": "integer" }, "providers": { "type": "integer", "description": "Distinct providers this spender used in the current window." } } }, "AnalyticsFilter": { "type": "object", "additionalProperties": false, "description": "The filter the response was computed under, echoed back.", "required": [ "initiator", "provider", "endpoint" ], "properties": { "initiator": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "oauth_member", "end_user", "agent_connection", "credential", "unattributed" ] }, "id": { "type": [ "string", "null" ] } } }, { "type": "null" } ] }, "provider": { "type": [ "string", "null" ] }, "endpoint": { "type": [ "string", "null" ] } } }, "LedgerPage": { "type": "object", "additionalProperties": false, "required": [ "success", "entries", "nextCursor" ], "properties": { "success": { "type": "boolean", "const": true }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "AppliedLedgerFilters": { "type": "array", "description": "Names of the narrowing query filters this server applied. An empty array means the request did not include a narrowing filter.", "items": { "type": "string", "enum": [ "account", "attribution", "category", "createdAfter", "createdBefore", "endpoint", "externalUserId", "initiator", "provider", "sourceKey" ] }, "uniqueItems": true }, "TenantLedgerPage": { "type": "object", "additionalProperties": false, "required": [ "success", "entries", "nextCursor", "appliedFilters" ], "properties": { "success": { "type": "boolean", "const": true }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerEntry" } }, "nextCursor": { "type": [ "string", "null" ] }, "appliedFilters": { "$ref": "#/components/schemas/AppliedLedgerFilters" } } }, "TenantLedgerSummary": { "type": "object", "additionalProperties": false, "required": [ "success", "total", "byCategory", "amountUsdcByCategory", "appliedFilters" ], "properties": { "success": { "type": "boolean", "const": true }, "total": { "type": "integer" }, "byCategory": { "type": "object", "description": "Counts keyed by ledger category; categories with no rows are absent.", "additionalProperties": { "type": "integer" } }, "amountUsdcByCategory": { "type": "object", "description": "Unsigned USDC magnitude keyed by ledger category, over the same rows (direction carries the sign). Analytics covers BURN rows only, so a refund total for the same filters comes from here.", "additionalProperties": { "$ref": "#/components/schemas/DecimalString" } }, "appliedFilters": { "$ref": "#/components/schemas/AppliedLedgerFilters" } } }, "McpOAuthError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "OAuth protocol error code." }, "error_description": { "type": "string" } }, "additionalProperties": false }, "McpProtectedResourceMetadata": { "type": "object", "required": [ "resource", "authorization_servers", "bearer_methods_supported", "scopes_supported", "resource_name", "resource_documentation" ], "properties": { "resource": { "type": "string", "format": "uri" }, "authorization_servers": { "type": "array", "minItems": 1, "items": { "type": "string", "format": "uri" } }, "bearer_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "header" ] }, "scopes_supported": { "type": "array", "items": { "type": "string", "enum": [ "mcp:read", "mcp:execute", "offline_access" ] } }, "resource_name": { "type": "string", "const": "Locus Pro MCP" }, "resource_documentation": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "McpAuthorizationServerMetadata": { "type": "object", "required": [ "issuer", "authorization_endpoint", "device_authorization_endpoint", "token_endpoint", "registration_endpoint", "revocation_endpoint", "response_types_supported", "response_modes_supported", "grant_types_supported", "token_endpoint_auth_methods_supported", "revocation_endpoint_auth_methods_supported", "code_challenge_methods_supported", "scopes_supported", "authorization_response_iss_parameter_supported", "resource_parameter_supported", "client_id_metadata_document_supported" ], "properties": { "issuer": { "type": "string", "format": "uri" }, "authorization_endpoint": { "type": "string", "format": "uri" }, "device_authorization_endpoint": { "type": "string", "format": "uri" }, "token_endpoint": { "type": "string", "format": "uri" }, "registration_endpoint": { "type": "string", "format": "uri" }, "revocation_endpoint": { "type": "string", "format": "uri" }, "response_types_supported": { "type": "array", "items": { "type": "string" }, "example": [ "code" ] }, "response_modes_supported": { "type": "array", "items": { "type": "string" }, "example": [ "query" ] }, "grant_types_supported": { "type": "array", "items": { "type": "string", "enum": [ "authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code" ] } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "none" ] }, "revocation_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "none" ] }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" }, "example": [ "S256" ] }, "scopes_supported": { "type": "array", "items": { "type": "string", "enum": [ "mcp:read", "mcp:execute", "offline_access" ] } }, "authorization_response_iss_parameter_supported": { "type": "boolean", "const": true }, "resource_parameter_supported": { "type": "boolean", "const": true }, "client_id_metadata_document_supported": { "type": "boolean", "const": true } }, "additionalProperties": false }, "McpOAuthTokenRequest": { "oneOf": [ { "type": "object", "title": "Authorization code exchange", "required": [ "grant_type", "client_id", "resource", "code", "redirect_uri", "code_verifier" ], "properties": { "grant_type": { "const": "authorization_code" }, "client_id": { "type": "string" }, "resource": { "type": "string", "format": "uri" }, "code": { "type": "string" }, "redirect_uri": { "type": "string", "format": "uri" }, "code_verifier": { "type": "string" } }, "additionalProperties": true }, { "type": "object", "title": "Device-code exchange", "required": [ "grant_type", "client_id", "resource", "device_code" ], "properties": { "grant_type": { "const": "urn:ietf:params:oauth:grant-type:device_code" }, "client_id": { "type": "string" }, "resource": { "type": "string", "format": "uri" }, "device_code": { "type": "string", "pattern": "^lmo_dc_[A-Za-z0-9_-]{43}$" } }, "additionalProperties": true }, { "type": "object", "title": "Refresh token exchange", "required": [ "grant_type", "client_id", "resource", "refresh_token" ], "properties": { "grant_type": { "const": "refresh_token" }, "client_id": { "type": "string" }, "resource": { "type": "string", "format": "uri" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } }, "additionalProperties": true } ] }, "McpOAuthTokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope", "resource" ], "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "minimum": 1 }, "refresh_token": { "type": "string", "description": "Present when offline_access was granted; rotated on every refresh." }, "scope": { "type": "string" }, "resource": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "McpOAuthClientMetadata": { "type": "object", "allOf": [ { "anyOf": [ { "not": { "required": [ "grant_types" ] } }, { "required": [ "grant_types" ], "properties": { "grant_types": { "contains": { "const": "authorization_code" } } } }, { "required": [ "grant_types" ], "properties": { "grant_types": { "contains": { "const": "urn:ietf:params:oauth:grant-type:device_code" } } } } ] }, { "if": { "anyOf": [ { "not": { "required": [ "grant_types" ] } }, { "required": [ "grant_types" ], "properties": { "grant_types": { "contains": { "const": "authorization_code" } } } } ] }, "then": { "required": [ "redirect_uris" ], "properties": { "redirect_uris": { "minItems": 1 }, "response_types": { "minItems": 1, "maxItems": 1 } } }, "else": { "properties": { "response_types": { "maxItems": 0 } } } } ], "properties": { "client_name": { "type": "string", "maxLength": 120 }, "application_type": { "type": "string", "enum": [ "native", "web" ] }, "redirect_uris": { "type": "array", "minItems": 0, "maxItems": 10, "uniqueItems": true, "items": { "type": "string", "format": "uri" }, "description": "Required and non-empty when grant_types contains authorization_code; may be empty for a device-only client." }, "grant_types": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code" ] }, "default": [ "authorization_code" ], "description": "Must contain authorization_code or the device-code grant. refresh_token may accompany either." }, "response_types": { "type": "array", "minItems": 0, "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "const": "code" }, "description": "Exactly [\"code\"] for authorization_code clients and [] for device-only clients." }, "token_endpoint_auth_method": { "type": "string", "const": "none" }, "client_uri": { "type": "string", "format": "uri" }, "logo_uri": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "McpOAuthClientRegistration": { "allOf": [ { "$ref": "#/components/schemas/McpOAuthClientMetadata" }, { "type": "object", "required": [ "client_id", "client_id_issued_at", "client_name", "application_type", "redirect_uris", "grant_types", "response_types", "token_endpoint_auth_method", "registration_client_uri" ], "properties": { "client_id": { "type": "string" }, "client_id_issued_at": { "type": "integer" }, "registration_client_uri": { "type": "string", "format": "uri" }, "registration_access_token": { "type": "string", "description": "Returned only when the client is created; show and store it once." } } } ] }, "PersonalCatalogTenant": { "type": "object", "required": [ "creditsPerDollar" ], "properties": { "creditsPerDollar": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "PersonalCatalogEndpoint": { "type": "object", "required": [ "slug", "method", "dynamic", "enabled", "mcpPinned", "chargedUsdc", "effectiveUsd", "effectiveCredits" ], "properties": { "slug": { "type": "string" }, "method": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "dynamic": { "type": "boolean" }, "estimatedCost": { "type": "string", "description": "Display-only quoted range for variable-price actions." }, "billingModel": { "type": "string", "enum": [ "usage", "prepaid_runtime" ], "description": "Variable charge collection model; omitted for ordinary fixed-price actions." }, "enabled": { "type": "boolean" }, "mcpPinned": { "type": "boolean" }, "availability": { "type": "string", "enum": [ "available", "temporarily_unavailable", "unknown" ], "description": "Current platform readiness. This is separate from tenant enablement." }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "delivery_breaker", "platform_pause", null ] }, "systemManaged": { "const": true }, "chargedUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "effectiveUsd": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "effectiveCredits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] } }, "additionalProperties": false }, "PersonalCatalogProvider": { "type": "object", "required": [ "provider", "logoUrl", "serviceUrl", "endpoints" ], "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "secondaryCategories": { "type": "array", "items": { "type": "string" }, "description": "Additional marketplace categories beyond the primary (Parse), so catalogs can file a provider under every category its marketplace lists it in." }, "verified": { "type": "boolean", "description": "Whether the provider listing has been explicitly verified by its source catalog." }, "logoUrl": { "type": "string", "format": "uri" }, "serviceUrl": { "type": "string", "format": "uri" }, "websiteUrl": { "type": "string", "format": "uri" }, "docsUrl": { "type": "string", "format": "uri" }, "marketplaceRank": { "type": "integer" }, "marketplaceFeatured": { "type": "boolean" }, "externalRail": { "type": "string", "enum": [ "mpp", "x402" ] }, "availability": { "type": "string", "enum": [ "available", "temporarily_unavailable", "unknown" ], "description": "Current platform readiness. This is separate from tenant enablement." }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "delivery_breaker", "platform_pause", null ] }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/PersonalCatalogEndpoint" } } }, "additionalProperties": false }, "PersonalDashboardCatalogResponse": { "type": "object", "description": "Personal-account catalog projection. Upstream cost, margin, markup policy, and pricing provenance are removed at the API boundary.", "required": [ "success", "version", "view", "tenant", "providers", "nextCursor" ], "properties": { "success": { "const": true }, "version": { "type": "string", "const": "2026-09-06" }, "view": { "type": "string", "const": "dashboard" }, "tenant": { "$ref": "#/components/schemas/PersonalCatalogTenant" }, "providers": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PersonalCatalogProvider" } }, "nextCursor": { "type": [ "string", "null" ] }, "filter": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "const": true } }, "additionalProperties": false, "description": "Present when the page was narrowed by enabled=true." }, "pageCursors": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 512 } } }, "additionalProperties": false }, "PersonalCatalogProviderDetailResponse": { "type": "object", "required": [ "success", "version", "view", "tenant", "provider" ], "properties": { "success": { "const": true }, "version": { "type": "string", "const": "2026-09-06" }, "view": { "type": "string", "const": "detail" }, "tenant": { "$ref": "#/components/schemas/PersonalCatalogTenant" }, "provider": { "$ref": "#/components/schemas/PersonalCatalogProvider" } }, "additionalProperties": false }, "PersonalCatalogMutationRequest": { "type": "object", "title": "Personal catalog mutation", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false }, "PersonalCatalogMutationResponse": { "type": "object", "required": [ "success", "config" ], "properties": { "success": { "const": true }, "config": { "type": "object", "required": [ "endpointSlug", "enabled" ], "properties": { "endpointSlug": { "type": "string" }, "enabled": { "type": "boolean", "description": "Effective enablement after this write." } }, "additionalProperties": false } }, "additionalProperties": false }, "DashboardCatalogSummaryProvider": { "type": "object", "required": [ "provider", "logoUrl", "serviceUrl", "endpointCount", "enabledEndpointCount", "mutableEndpointCount", "enabledMutableEndpointCount" ], "properties": { "provider": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "secondaryCategories": { "type": "array", "items": { "type": "string" }, "description": "Additional marketplace categories beyond the primary (Parse), so catalogs can file a provider under every category its marketplace lists it in." }, "verified": { "type": "boolean", "description": "Whether the provider listing has been explicitly verified by its source catalog." }, "logoUrl": { "type": "string", "format": "uri" }, "serviceUrl": { "type": "string", "format": "uri" }, "websiteUrl": { "type": "string", "format": "uri" }, "docsUrl": { "type": "string", "format": "uri" }, "catalogIdentity": { "type": "string" }, "attribution": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "websiteUrl": { "type": "string", "format": "uri" }, "logoUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "marketplaceRank": { "type": "integer" }, "marketplaceFeatured": { "type": "boolean" }, "catalogPriority": { "type": "integer", "description": "Cross-surface browse priority for deliberately featured providers." }, "externalRail": { "type": "string", "enum": [ "mpp", "x402" ] }, "availability": { "type": "string", "enum": [ "available", "temporarily_unavailable", "unknown" ], "description": "Current platform readiness. This is separate from tenant enablement." }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "delivery_breaker", "platform_pause", null ] }, "endpointCount": { "type": "integer", "minimum": 0 }, "enabledEndpointCount": { "type": "integer", "minimum": 0 }, "mutableEndpointCount": { "type": "integer", "minimum": 0 }, "enabledMutableEndpointCount": { "type": "integer", "minimum": 0 }, "callableEndpointCount": { "type": "integer", "minimum": 0, "description": "Enabled endpoints that are currently callable. Present for external rails." } }, "additionalProperties": false }, "DashboardCatalogSummaryResponse": { "type": "object", "required": [ "success", "version", "view", "tenant", "providers" ], "properties": { "success": { "const": true }, "version": { "type": "string", "const": "2026-09-06" }, "view": { "type": "string", "const": "summary" }, "tenant": { "oneOf": [ { "$ref": "#/components/schemas/PersonalCatalogTenant" }, { "type": "object", "required": [ "defaultMarkupBps", "defaultFlatMarkupUsd", "creditsPerDollar" ], "properties": { "defaultMarkupBps": { "type": "integer" }, "defaultFlatMarkupUsd": { "$ref": "#/components/schemas/DecimalString" }, "creditsPerDollar": { "type": "integer", "minimum": 1 } }, "additionalProperties": false } ] }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardCatalogSummaryProvider" } } }, "additionalProperties": false }, "ToolSearchMatch": { "type": "object", "required": [ "slug", "tool", "provider", "endpoint", "title", "enabled", "description", "category_ids", "pack_ids", "pricing", "next_step" ], "properties": { "slug": { "type": "string" }, "tool": { "type": "string" }, "provider": { "type": "string" }, "endpoint": { "type": "string" }, "title": { "type": "string" }, "enabled": { "type": "boolean" }, "description": { "type": "string" }, "category": { "type": "string" }, "category_ids": { "type": "array", "items": { "type": "string" } }, "pack_ids": { "type": "array", "items": { "type": "string" } }, "credits": { "$ref": "#/components/schemas/DecimalString" }, "variableCost": { "const": true }, "pricing": { "type": "object", "required": [ "type", "credits", "estimation_required" ], "properties": { "type": { "type": "string", "enum": [ "fixed", "variable", "quote_required" ] }, "credits": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "null" } ] }, "estimation_required": { "type": "boolean" } }, "additionalProperties": false }, "next_step": { "type": "object", "required": [ "method", "path", "body" ], "properties": { "method": { "const": "POST" }, "path": { "type": "string", "enum": [ "/api/credits/tools/describe", "/api/credits/tools/access-requests" ] }, "body": { "type": "object", "required": [ "slug" ], "properties": { "slug": { "type": "string" }, "operation_query": { "type": "string", "maxLength": 256 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "ToolSearchResponse": { "type": "object", "required": [ "success", "query", "taxonomy_revision", "count", "results" ], "properties": { "success": { "const": true }, "query": { "type": "string" }, "taxonomy_revision": { "type": "string" }, "appliedFilters": { "type": "object", "additionalProperties": { "type": "string" } }, "count": { "type": "integer", "minimum": 0, "maximum": 50 }, "next_cursor": { "type": "string" }, "facets": { "type": "array", "maxItems": 50, "items": { "type": "object", "additionalProperties": true } }, "results": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/ToolSearchMatch" } }, "note": { "type": "string", "description": "Present when no enabled tool matched." } }, "additionalProperties": false }, "AgentFundingAmount": { "oneOf": [ { "type": "object", "required": [ "usd" ], "not": { "required": [ "credits" ] }, "properties": { "usd": { "$ref": "#/components/schemas/DecimalString" } }, "additionalProperties": false }, { "type": "object", "required": [ "credits" ], "not": { "required": [ "usd" ] }, "properties": { "credits": { "$ref": "#/components/schemas/DecimalString" } }, "additionalProperties": false } ] }, "OkibiCliConnectionMetadata": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "keyPrefix", "tools", "expiresAt", "lastUsedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "keyPrefix": { "type": "string", "description": "Non-secret display prefix." }, "tools": { "$ref": "#/components/schemas/OkibiCliConnectionTools" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Moves forward on each authenticated use, to 7 days after that use and never past 30 days after issue." }, "lastUsedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "OkibiCliCredentialEnvelope": { "type": "object", "additionalProperties": false, "required": [ "success", "created", "rotated", "account", "connection", "storage" ], "properties": { "success": { "const": true }, "created": { "type": "boolean", "description": "True when this bootstrap created the installation's credential (HTTP 201)." }, "rotated": { "type": "boolean", "description": "True when a new registration token replaced the existing credential's secret in place (HTTP 200)." }, "account": { "$ref": "#/components/schemas/OkibiLinkedAccount" }, "connection": { "type": "object", "additionalProperties": false, "required": [ "id", "status", "keyPrefix", "tools", "expiresAt", "lastUsedAt", "credential" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] }, "keyPrefix": { "type": "string", "description": "Non-secret display prefix." }, "tools": { "$ref": "#/components/schemas/OkibiCliConnectionTools" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Moves forward on each authenticated use, to 7 days after that use and never past 30 days after issue." }, "lastUsedAt": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "credential": { "type": "string", "pattern": "^lcac_", "readOnly": true, "description": "Raw scoped Locus credential. Capture once and never log it." } } }, "storage": { "type": "object", "additionalProperties": false, "required": [ "environmentVariable", "instruction" ], "properties": { "environmentVariable": { "const": "LOCUS_SECRET_KEY" }, "instruction": { "type": "string" } } } } }, "McpOAuthDeviceUserCode": { "type": "string", "pattern": "^[A-HJ-NP-Z2-9]{3}-[A-HJ-NP-Z2-9]{3}$", "description": "Human-readable code that omits ambiguous characters. Display it exactly as returned." }, "McpOAuthDeviceUserCodeInput": { "type": "string", "pattern": "^[^A-Za-z0-9]*[A-HJ-NP-Za-hj-np-z2-9](?:[^A-Za-z0-9]*[A-HJ-NP-Za-hj-np-z2-9]){5}[^A-Za-z0-9]*$", "description": "Case-insensitive device-code input. Locus ignores non-alphanumeric punctuation, rejects ambiguous characters, and normalizes the six significant characters to XXX-XXX." }, "McpOAuthDeviceAuthorizationRequest": { "type": "object", "additionalProperties": true, "required": [ "client_id", "resource" ], "properties": { "client_id": { "type": "string", "minLength": 1, "maxLength": 2048 }, "resource": { "type": "string", "format": "uri", "description": "Exact Locus Pro MCP resource URL." }, "scope": { "type": "string", "maxLength": 512, "example": "mcp:read mcp:execute offline_access" } } }, "McpOAuthDeviceAuthorizationResponse": { "type": "object", "additionalProperties": false, "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ], "properties": { "device_code": { "type": "string", "pattern": "^lmo_dc_[A-Za-z0-9_-]{43}$", "description": "Secret device grant credential. Keep it only in the client that initiated the device flow and do not log it." }, "user_code": { "$ref": "#/components/schemas/McpOAuthDeviceUserCode" }, "verification_uri": { "type": "string", "format": "uri" }, "verification_uri_complete": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer", "const": 900 }, "interval": { "type": "integer", "const": 5, "description": "Initial minimum token-poll interval in seconds. A slow_down response increases it by five seconds, up to 60 seconds." } } }, "McpConnectionCapacity": { "type": "object", "additionalProperties": false, "required": [ "plan", "limit", "active", "reserved", "remaining" ], "properties": { "plan": { "type": "string", "enum": [ "free", "plus", "unlimited" ] }, "limit": { "type": [ "integer", "null" ], "minimum": 1, "description": "Null for an unlimited plan or enterprise workspace." }, "active": { "type": "integer", "minimum": 0 }, "reserved": { "type": "integer", "minimum": 0, "description": "Approved browser and device grants that have not yet been exchanged and have not expired." }, "remaining": { "type": [ "integer", "null" ], "minimum": 0 } } }, "McpOAuthDevicePublicContextResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "userCode", "clientName", "clientId", "scopes", "resource", "expiresAt" ], "properties": { "userCode": { "$ref": "#/components/schemas/McpOAuthDeviceUserCode" }, "clientName": { "type": "string" }, "clientId": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mcp:read", "mcp:execute", "offline_access" ] } }, "resource": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } } } } }, "McpOAuthDeviceTenantListResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "tenants", "selectedTenantId" ], "properties": { "tenants": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "role" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "role": { "$ref": "#/components/schemas/WorkspaceRole" } } } }, "selectedTenantId": { "type": [ "string", "null" ], "format": "uuid" } } } } }, "McpOAuthDeviceContextResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "userCode", "clientName", "clientId", "tenantName", "scopes", "scopeReduced", "connectionCapacity", "resource", "expiresAt" ], "properties": { "userCode": { "$ref": "#/components/schemas/McpOAuthDeviceUserCode" }, "clientName": { "type": "string" }, "clientId": { "type": "string" }, "tenantName": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "mcp:read", "mcp:execute", "offline_access" ] } }, "scopeReduced": { "type": "boolean" }, "connectionCapacity": { "$ref": "#/components/schemas/McpConnectionCapacity" }, "resource": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } } } } }, "McpOAuthDeviceDecisionResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "approved", "denied" ] } } } } }, "McpOAuthClientMetadataUpdate": { "allOf": [ { "$ref": "#/components/schemas/McpOAuthClientMetadata" }, { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string", "description": "Must exactly match the clientId path parameter." } } } ] }, "ManagementCatalogSearchMatch": { "type": "object", "additionalProperties": false, "required": [ "slug", "provider", "providerName", "endpoint", "title", "description", "enabled", "availability", "unavailableReason" ], "properties": { "slug": { "type": "string", "pattern": "^[^/]+/[^/]+$" }, "provider": { "type": "string" }, "providerName": { "type": "string" }, "endpoint": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "enabled": { "type": "boolean", "description": "The account's desired enablement. This is separate from current platform availability." }, "availability": { "type": "string", "enum": [ "available", "temporarily_unavailable", "unknown" ] }, "unavailableReason": { "type": [ "string", "null" ], "enum": [ "delivery_breaker", "platform_pause", null ] } } }, "ManagementCatalogSearchResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "query", "count", "results" ], "properties": { "success": { "const": true }, "query": { "type": "string" }, "count": { "type": "integer", "minimum": 0, "maximum": 50 }, "results": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/ManagementCatalogSearchMatch" } }, "note": { "type": "string", "description": "Present when no catalog endpoint matched." } } }, "CustomAuthInput": { "type": "object", "additionalProperties": false, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "bearer", "header", "query", "none" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Required for header and query authentication; must be a valid HTTP field name." }, "prefix": { "type": "string", "maxLength": 80, "description": "Optional value prefix for header or query authentication. Bearer authentication always uses 'Bearer '." }, "credential": { "type": "string", "minLength": 1, "maxLength": 4096, "writeOnly": true, "description": "Required when creating a bearer, header, or query provider. Omit during an update to retain the encrypted credential. Never returned." } }, "description": "For type=none, omit credential. For type=header or type=query, supply name." }, "CustomAuthView": { "type": "object", "additionalProperties": false, "required": [ "type", "name", "prefix", "configured", "hint", "version", "updatedAt" ], "properties": { "type": { "type": [ "string", "null" ], "enum": [ "bearer", "header", "query", "none", null ], "description": "Null when upstream configuration is redacted for this caller." }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": [ "string", "null" ] }, "configured": { "type": "boolean" }, "hint": { "type": [ "string", "null" ], "description": "Non-secret credential hint for an authorized owner; never the credential itself." }, "version": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "CustomCircuitBreakerPolicy": { "type": "object", "additionalProperties": false, "required": [ "failureThreshold", "windowSeconds", "cooldownSeconds" ], "properties": { "failureThreshold": { "type": "integer", "minimum": 2, "maximum": 100 }, "windowSeconds": { "type": "integer", "minimum": 1, "maximum": 600 }, "cooldownSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 } } }, "CustomTrafficPolicy": { "type": "object", "additionalProperties": false, "required": [ "requestsPerMinute", "maxConcurrency", "timeoutSeconds", "circuitBreaker" ], "properties": { "requestsPerMinute": { "type": "integer", "minimum": 1, "maximum": 60000, "description": "Must not exceed the platform-wide 60,000 request-per-minute ceiling." }, "maxConcurrency": { "type": "integer", "minimum": 1, "maximum": 1000 }, "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 120 }, "circuitBreaker": { "$ref": "#/components/schemas/CustomCircuitBreakerPolicy" } } }, "CustomTrafficPolicyUpdate": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "requestsPerMinute": { "type": "integer", "minimum": 1, "maximum": 60000 }, "maxConcurrency": { "type": "integer", "minimum": 1, "maximum": 1000 }, "timeoutSeconds": { "type": "integer", "minimum": 1, "maximum": 120 }, "circuitBreaker": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "failureThreshold": { "type": "integer", "minimum": 2, "maximum": 100 }, "windowSeconds": { "type": "integer", "minimum": 1, "maximum": 600 }, "cooldownSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 } } } } }, "CustomEndpointCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "slug", "name", "description", "method", "path", "inputSchema", "inputExample", "providerCostUsdc", "markupBps", "flatMarkupUsdc" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$", "description": "Stable 3\u201364 character action name." }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "path": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "Upstream path. Placeholders must reference required scalar properties from inputSchema." }, "inputSchema": { "type": "object", "additionalProperties": true, "description": "Compilable JSON Schema, at most 64 KiB and 32 levels deep, whose root type is object. Top-level transport-control names are reserved." }, "inputExample": { "type": "object", "additionalProperties": true, "description": "Executable example that must satisfy inputSchema." }, "outputSchema": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ], "description": "Optional JSON Schema, at most 64 KiB and 32 levels deep." }, "outputExample": { "description": "Optional example that must satisfy outputSchema when both are provided." }, "providerCostUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "number", "minimum": 0 } ], "description": "Upstream provider cost in USD, rounded up to six decimal places." }, "markupBps": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Percentage markup, also limited by the workspace's effective cap." }, "flatMarkupUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "number", "minimum": 0 } ], "description": "Flat USD markup, also limited by the workspace's effective cap." }, "enabled": { "type": "boolean", "default": false, "description": "Enabled actions must have a positive end-user price." } } }, "CustomEndpointUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "path": { "type": "string", "minLength": 1, "maxLength": 1024 }, "inputSchema": { "type": "object", "additionalProperties": true }, "inputExample": { "type": "object", "additionalProperties": true }, "outputSchema": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "outputExample": {}, "providerCostUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "number", "minimum": 0 } ] }, "markupBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "flatMarkupUsdc": { "oneOf": [ { "$ref": "#/components/schemas/DecimalString" }, { "type": "number", "minimum": 0 } ] }, "enabled": { "type": "boolean" } }, "description": "Any non-empty subset of the create fields except slug. Unspecified fields remain unchanged; all affected contracts and prices are revalidated." }, "CustomEndpoint": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "publicSlug", "name", "description", "method", "path", "inputSchema", "inputExample", "outputSchema", "outputExample", "providerCostUsdc", "markupBps", "flatMarkupUsdc", "endUserPriceUsdc", "enabled", "pricingRevision", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "publicSlug": { "type": "string", "pattern": "^custom-[^/]+/[^/]+$", "description": "Catalog and execution identity." }, "name": { "type": "string" }, "description": { "type": "string" }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "path": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true }, "inputExample": { "type": "object", "additionalProperties": true }, "outputSchema": { "oneOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "outputExample": {}, "providerCostUsdc": { "$ref": "#/components/schemas/DecimalString" }, "markupBps": { "type": "integer", "minimum": 0 }, "flatMarkupUsdc": { "$ref": "#/components/schemas/DecimalString" }, "endUserPriceUsdc": { "$ref": "#/components/schemas/DecimalString" }, "enabled": { "type": "boolean" }, "pricingRevision": { "type": "integer", "minimum": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CustomProviderCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "slug", "name", "baseUrl", "auth" ], "properties": { "slug": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$", "description": "Stable provider name. The public catalog name is custom-{slug}." }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 500 }, "baseUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS upstream origin validated against SSRF and private-network controls." }, "auth": { "$ref": "#/components/schemas/CustomAuthInput" }, "traffic": { "$ref": "#/components/schemas/CustomTrafficPolicy" }, "endpoint": { "$ref": "#/components/schemas/CustomEndpointCreateRequest" }, "endpoints": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/CustomEndpointCreateRequest" }, "description": "Use endpoint or endpoints, never both. Slugs must be unique within the request." } } }, "CustomProviderUpdateRequest": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "baseUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "auth": { "$ref": "#/components/schemas/CustomAuthInput" }, "traffic": { "$ref": "#/components/schemas/CustomTrafficPolicyUpdate" } } }, "CustomProvider": { "type": "object", "additionalProperties": false, "required": [ "id", "slug", "publicProvider", "name", "description", "baseUrl", "auth", "traffic", "endpoints", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "publicProvider": { "type": "string", "pattern": "^custom-", "description": "Provider name used in catalog discovery and /wrapped/credits/{provider}/{endpoint}." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "baseUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Null when upstream configuration is redacted for this caller." }, "auth": { "$ref": "#/components/schemas/CustomAuthView" }, "traffic": { "$ref": "#/components/schemas/CustomTrafficPolicy" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/CustomEndpoint" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CustomProviderListResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "markupCapBps", "providers" ], "properties": { "success": { "const": true }, "markupCapBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomProvider" } } } }, "CustomProviderResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "provider" ], "properties": { "success": { "const": true }, "provider": { "$ref": "#/components/schemas/CustomProvider" } } }, "CustomEndpointResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "endpoint" ], "properties": { "success": { "const": true }, "endpoint": { "$ref": "#/components/schemas/CustomEndpoint" } } }, "TravelFlightSearchRequest": { "type": "object", "additionalProperties": false, "required": [ "origin", "destination", "departureDate" ], "properties": { "origin": { "type": "string", "minLength": 2, "maxLength": 120, "description": "IATA code or place name. Three-letter codes are normalized to uppercase." }, "destination": { "type": "string", "minLength": 2, "maxLength": 120, "description": "Must differ from origin." }, "departureDate": { "type": "string", "format": "date", "description": "Real calendar date in YYYY-MM-DD form." }, "returnDate": { "type": "string", "format": "date", "description": "Optional return date on or after departureDate." }, "adults": { "type": "integer", "minimum": 1, "maximum": 9, "default": 1 }, "children": { "type": "integer", "minimum": 0, "maximum": 8, "default": 0 }, "infants": { "type": "integer", "minimum": 0, "maximum": 4, "default": 0, "description": "Cannot exceed adults. Total travelers cannot exceed nine." }, "cabinClass": { "type": "string", "enum": [ "economy", "premium_economy", "business", "first" ], "default": "economy" }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$", "default": "USD" }, "optimize": { "type": "array", "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "cost", "quality", "context" ] }, "description": "Cost favors fewer inexpensive sources, quality increases depth, and context favors compact agent-readable output." }, "preferredAirlines": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "excludedAirlines": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "preferredAirports": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "excludedAirports": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "maxStops": { "type": "integer", "minimum": 0, "maximum": 3 }, "minLayoverMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "maxLayoverMinutes": { "type": "integer", "minimum": 0, "maximum": 2880 }, "maxDurationMinutes": { "type": "integer", "minimum": 30, "maximum": 10080 }, "maxPrice": { "type": "number", "exclusiveMinimum": 0, "maximum": 10000000, "description": "Maximum itinerary price in currency." }, "departAfter": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "departBefore": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "arriveAfter": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "arriveBefore": { "type": "string", "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$" }, "maxResults": { "type": "integer", "minimum": 1, "maximum": 50 }, "maxProviders": { "type": "integer", "minimum": 1, "maximum": 11 }, "providers": { "type": "array", "maxItems": 11, "uniqueItems": true, "items": { "type": "string", "enum": [ "aircanada", "duffel", "stabletravel", "almosafer", "flightconnections", "justfly", "kayak_hk", "skyscanner", "skiplagged", "trip", "united" ] }, "description": "Optional explicit provider selection, still narrowed by credential, catalog, availability, and request compatibility." }, "maxCredits": { "oneOf": [ { "type": "string", "pattern": "^(?:0*[1-9]\\d*)(?:\\.\\d{1,6})?$|^0*\\.0*[1-9]\\d{0,5}$" }, { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000 } ], "description": "Aggregate no-dispatch ceiling for all selected child calls, in account credits." }, "externalUserId": { "$ref": "#/components/schemas/ExternalUserId" }, "attribution": { "type": "object", "additionalProperties": true, "description": "Optional JSON attribution copied to child calls." } }, "description": "Preferred and excluded values cannot overlap. minLayoverMinutes cannot exceed maxLayoverMinutes. Defaults are selected from optimize when optional depth controls are absent." }, "TravelFlightSearchPreview": { "type": "object", "additionalProperties": false, "required": [ "object", "capability", "request", "providers", "eligibleProviders", "ineligibleProviders", "estimatedCostCredits", "estimateExact" ], "properties": { "object": { "const": "locus.travel_flight_search.preview" }, "capability": { "const": "travel.flight_search" }, "request": { "$ref": "#/components/schemas/TravelFlightSearchRequest" }, "providers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "providerId", "providerName", "estimatedCostCredits", "priceExact" ], "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" }, "estimatedCostCredits": { "$ref": "#/components/schemas/DecimalString" }, "priceExact": { "type": "boolean" }, "estimatedCostUsd": { "type": "number", "minimum": 0, "description": "Shown only to secret-key and dashboard principals." } } } }, "eligibleProviders": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "providerId", "providerName" ], "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" } } } }, "ineligibleProviders": { "type": "array", "items": { "$ref": "#/components/schemas/TravelIneligibleProvider" } }, "estimatedCostCredits": { "$ref": "#/components/schemas/DecimalString" }, "estimateExact": { "type": "boolean" }, "estimatedCostUsd": { "type": "number", "minimum": 0, "description": "Shown only to secret-key and dashboard principals." } } }, "TravelIneligibleProvider": { "type": "object", "additionalProperties": false, "required": [ "providerId", "providerName", "reason" ], "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" }, "reason": { "type": "string", "enum": [ "credential_scope", "provider_disabled", "provider_filtered", "provider_unavailable", "request_unsupported" ] }, "detail": { "type": "string" } } }, "TravelPlace": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "city": { "type": "string" } } }, "TravelSegment": { "type": "object", "additionalProperties": false, "required": [ "origin", "destination", "departure", "arrival" ], "properties": { "origin": { "$ref": "#/components/schemas/TravelPlace" }, "destination": { "$ref": "#/components/schemas/TravelPlace" }, "departure": { "type": "string", "description": "Provider-normalized departure timestamp." }, "arrival": { "type": "string", "description": "Provider-normalized arrival timestamp." }, "durationMinutes": { "type": "integer", "minimum": 0 }, "flightNumber": { "type": "string" }, "marketingCarrier": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "operatingCarrier": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "name": { "type": "string" } } }, "aircraft": { "type": "string" } } }, "TravelLeg": { "type": "object", "additionalProperties": false, "required": [ "origin", "destination", "departure", "arrival", "stopCount", "segments" ], "properties": { "origin": { "$ref": "#/components/schemas/TravelPlace" }, "destination": { "$ref": "#/components/schemas/TravelPlace" }, "departure": { "type": "string" }, "arrival": { "type": "string" }, "durationMinutes": { "type": "integer", "minimum": 0 }, "stopCount": { "type": "integer", "minimum": 0 }, "segments": { "type": "array", "items": { "$ref": "#/components/schemas/TravelSegment" } }, "intermediateAirports": { "type": "array", "items": { "$ref": "#/components/schemas/TravelPlace" } }, "layoverDurationsMinutes": { "type": "array", "items": { "type": "integer", "minimum": 0 } } } }, "TravelOffer": { "type": "object", "additionalProperties": false, "required": [ "amount", "currency", "providerId", "providerName" ], "properties": { "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string" }, "formatted": { "type": "string" }, "bookingUrl": { "type": "string", "format": "uri" }, "linkType": { "type": "string", "enum": [ "booking", "search_handoff" ] }, "seller": { "type": "string" }, "cabinClass": { "type": "string", "enum": [ "economy", "premium_economy", "business", "first" ] }, "refundable": { "type": "boolean" }, "providerId": { "type": "string" }, "providerName": { "type": "string" } } }, "TravelItinerary": { "type": "object", "additionalProperties": false, "required": [ "id", "score", "legs", "offers", "tags", "confidence", "sources", "sourceCount", "bookability" ], "properties": { "id": { "type": "string" }, "score": { "type": "number" }, "providerItineraryId": { "type": "string", "description": "Provider-native itinerary ID when one canonical source supplies it." }, "legs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelLeg" } }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/TravelOffer" } }, "tags": { "type": "array", "items": { "type": "string" } }, "selfTransfer": { "type": "boolean" }, "baggage": { "type": "string" }, "seatsRemaining": { "type": "integer", "minimum": 0 }, "confidence": { "type": "object", "additionalProperties": false, "required": [ "score", "sourceCount", "scheduleAgreement" ], "properties": { "score": { "type": "number" }, "sourceCount": { "type": "integer", "minimum": 1 }, "scheduleAgreement": { "type": "string", "enum": [ "single_source", "corroborated" ] }, "priceSpreadPercent": { "type": "number", "minimum": 0 } } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "providerId", "providerName", "rank" ], "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" }, "rank": { "type": "integer", "minimum": 0 }, "providerItineraryId": { "type": "string" } } } }, "sourceCount": { "type": "integer", "minimum": 1 }, "bookability": { "type": "object", "additionalProperties": false, "required": [ "status", "offerCount", "bookingLinkOfferCount", "searchHandoffOfferCount", "currency" ], "properties": { "status": { "type": "string", "enum": [ "booking_link_available", "search_handoff_available", "price_only" ] }, "offerCount": { "type": "integer", "minimum": 0 }, "bookingLinkOfferCount": { "type": "integer", "minimum": 0 }, "searchHandoffOfferCount": { "type": "integer", "minimum": 0 }, "cheapestBookableAmount": { "type": "number", "minimum": 0 }, "currency": { "type": "string" } } } } }, "TravelProviderOutcome": { "type": "object", "additionalProperties": false, "required": [ "providerId", "providerName", "status", "latencyMs", "itineraryCount", "surfacedItineraryCount", "uniqueSurfacedItineraryCount", "tailLatencyContributionMs" ], "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "pending" ] }, "latencyMs": { "type": "number", "minimum": 0 }, "itineraryCount": { "type": "integer", "minimum": 0 }, "surfacedItineraryCount": { "type": "integer", "minimum": 0 }, "uniqueSurfacedItineraryCount": { "type": "integer", "minimum": 0 }, "tailLatencyContributionMs": { "type": "number", "minimum": 0 }, "chargedCredits": { "$ref": "#/components/schemas/DecimalString" }, "errorCode": { "type": "string" }, "estimatedCostUsd": { "type": "number", "minimum": 0 } } }, "TravelFlightSearchResponse": { "type": "object", "additionalProperties": false, "required": [ "object", "capability", "routerVersion", "runId", "search", "appliedOptimizations", "partial", "warnings", "providers", "itineraries", "itineraryCount", "bookability", "feedback", "billing" ], "properties": { "object": { "const": "locus.travel_flight_search" }, "capability": { "const": "travel.flight_search" }, "routerVersion": { "type": "string" }, "runId": { "type": "string", "format": "uuid" }, "search": { "$ref": "#/components/schemas/TravelFlightSearchRequest" }, "appliedOptimizations": { "type": "array", "items": { "type": "string", "enum": [ "cost", "quality", "context" ] } }, "partial": { "type": "boolean", "description": "True when at least one selected provider did not produce a complete successful result." }, "warnings": { "type": "array", "items": { "type": "string" } }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/TravelProviderOutcome" } }, "itineraries": { "type": "array", "items": { "$ref": "#/components/schemas/TravelItinerary" } }, "itineraryCount": { "type": "integer", "minimum": 0 }, "bookability": { "type": "object", "additionalProperties": false, "required": [ "bookableItineraryCount", "searchHandoffItineraryCount", "bookingLinkOfferCount", "searchHandoffOfferCount", "offerCount" ], "properties": { "bookableItineraryCount": { "type": "integer", "minimum": 0 }, "searchHandoffItineraryCount": { "type": "integer", "minimum": 0 }, "bookingLinkOfferCount": { "type": "integer", "minimum": 0 }, "searchHandoffOfferCount": { "type": "integer", "minimum": 0 }, "offerCount": { "type": "integer", "minimum": 0 } } }, "feedback": { "type": "object", "additionalProperties": false, "required": [ "method", "route", "runId" ], "properties": { "method": { "const": "POST" }, "route": { "type": "string" }, "runId": { "type": "string", "format": "uuid" } } }, "billing": { "type": "object", "additionalProperties": false, "required": [ "chargedCredits", "successfulProviders", "attemptedProviders" ], "properties": { "chargedCredits": { "$ref": "#/components/schemas/DecimalString" }, "successfulProviders": { "type": "integer", "minimum": 0 }, "attemptedProviders": { "type": "integer", "minimum": 0 } } } } }, "TravelFlightSearchPending": { "type": "object", "additionalProperties": false, "required": [ "object", "capability", "runId", "status", "message" ], "properties": { "object": { "const": "locus.travel_flight_search.pending" }, "capability": { "const": "travel.flight_search" }, "runId": { "type": "string", "format": "uuid" }, "status": { "const": "processing" }, "providers": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "providerId", "providerName", "status", "latencyMs" ], "properties": { "providerId": { "type": "string" }, "providerName": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "pending" ] }, "latencyMs": { "type": "number", "minimum": 0 } } } }, "billing": { "type": "object", "additionalProperties": false, "required": [ "chargedCredits" ], "properties": { "chargedCredits": { "$ref": "#/components/schemas/DecimalString" } } }, "message": { "type": "string" } } }, "TravelFlightSearchFeedbackRequest": { "type": "object", "additionalProperties": false, "required": [ "helpful" ], "properties": { "helpful": { "type": "boolean" }, "selectedItineraryId": { "type": "string", "minLength": 1, "maxLength": 64 }, "reason": { "type": "string", "enum": [ "price", "schedule", "missing_option", "provider_quality", "other" ] }, "note": { "type": "string", "minLength": 1, "maxLength": 2000 } } }, "TravelFlightSearchFeedbackResponse": { "type": "object", "additionalProperties": false, "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "additionalProperties": false, "required": [ "runId", "helpful", "selectedItineraryId", "reason", "updatedAt" ], "properties": { "runId": { "type": "string", "format": "uuid" }, "helpful": { "type": "boolean" }, "selectedItineraryId": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "price", "schedule", "missing_option", "provider_quality", "other", null ] }, "updatedAt": { "type": "string", "format": "date-time" } } } } }, "WorkflowFile": { "type": "object", "required": [ "path", "content" ], "properties": { "path": { "type": "string", "minLength": 1 }, "content": { "type": "string" } }, "additionalProperties": false }, "WorkflowSource": { "oneOf": [ { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "minItems": 1, "maxItems": 64, "items": { "$ref": "#/components/schemas/WorkflowFile" } } }, "additionalProperties": false }, { "type": "object", "required": [ "artifact_id" ], "properties": { "artifact_id": { "type": "string", "format": "uuid" } }, "additionalProperties": false } ] }, "WorkflowCreateRequest": { "type": "object", "required": [ "source" ], "properties": { "source": { "$ref": "#/components/schemas/WorkflowSource" }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "WorkflowRunRequest": { "type": "object", "required": [ "version", "mode", "max_charge_credits", "idempotency_key" ], "properties": { "version": { "type": "integer", "minimum": 1 }, "input": { "description": "Inline JSON input, up to 256 KiB. Omitted or null input becomes an empty object. Cannot be combined with input_artifact_id." }, "input_artifact_id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "pilot", "run" ] }, "max_charge_credits": { "$ref": "#/components/schemas/DecimalString", "description": "Positive total credit ceiling for the run." }, "max_rows": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Defaults to 10 for a pilot or 10,000 for a production run. Pilots accept at most 10 rows." }, "idempotency_key": { "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false, "not": { "required": [ "input", "input_artifact_id" ] }, "allOf": [ { "if": { "properties": { "mode": { "const": "pilot" } }, "required": [ "mode" ] }, "then": { "properties": { "max_rows": { "maximum": 10 } } } } ] }, "CatalogChange": { "type": "object", "description": "One catalog enablement change. Endpoint rows carry the effective state before and after; provider rows carry the provider row's own override (null before means no override existed).", "additionalProperties": false, "required": [ "id", "slug", "scope", "enabledBefore", "enabledAfter", "actor", "via", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string", "description": "A provider id or provider/endpoint." }, "scope": { "type": "string", "enum": [ "provider", "endpoint" ] }, "enabledBefore": { "type": [ "boolean", "null" ] }, "enabledAfter": { "type": "boolean" }, "actor": { "type": "object", "required": [ "type", "id", "label" ], "properties": { "type": { "type": "string", "enum": [ "member", "credential", "agent", "system" ] }, "id": { "type": [ "string", "null" ], "description": "The member's subject, the key's id, or the agent connection's id." }, "label": { "type": "string", "description": "What to show: a member's email, a key's name, an agent connection's name, or a fixed name when nothing better is known." } }, "additionalProperties": false }, "via": { "type": "string", "enum": [ "dashboard", "onboarding", "api", "agent", "credential", "cli", "router", "batch", "system" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "ToolDescribeResponse": { "type": "object", "required": [ "success", "tool" ], "properties": { "success": { "const": true }, "tool": { "type": "object", "required": [ "slug", "tool", "provider", "endpoint", "title", "enabled", "description", "contract_revision", "contract_digest", "pricing", "method", "path", "inputSchema", "exampleArguments", "annotations", "next_step" ], "additionalProperties": true } }, "additionalProperties": false }, "OkibiLinkedAccount": { "type": "object", "additionalProperties": false, "required": [ "email", "passwordSetupPending" ], "description": "The Locus user behind the Okibi identity link. Locus provisions an account for an Okibi-verified email that has none; that account keeps a managed password until the person sets one through the emailed link or the dashboard's first screen.", "properties": { "email": { "type": "string", "format": "email" }, "passwordSetupPending": { "type": "boolean", "description": "True while the provisioned account still has to choose a password. Tell the user to check their email for the Locus set-password link." } } }, "OkibiCliConnectionTools": { "type": "object", "additionalProperties": false, "required": [ "enable" ], "properties": { "enable": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Provider/endpoint slugs this credential may call. null means every endpoint the workspace has enabled." } } } } } }