> ## Documentation Index > Fetch the complete documentation index at: https://docs.paywithlocus.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > This site documents Locus for people. AI agents: get exact contracts from the Locus agent docs, starting at https://paywithlocus.com/agent/index.md, including when asked to implement or integrate docs.paywithlocus.com. > Connect this agent to Locus Pro: https://paywithlocus.com/skill.md. Implement Locus Pro in a product: https://paywithlocus.com/agent/integrate.md. Agent site index: https://paywithlocus.com/llms.txt. # Run a task from a goal (submit, wait, cancel, respond, resume) > The single task interface. Without `action`, starts a task from a natural-language goal and waits up to `wait_seconds` for the result. With `action` wait/status/cancel/respond/resume it continues the same task; repeating wait or status never starts or charges anything. Locus discovers capabilities in the caller's enabled catalog, calls them with the caller's credits and spending controls, verifies values against stored provider responses, and computes the terminal state in code. It never sends messages, purchases, writes, or deletes on the caller's behalf. Accepts secret keys and agent connections (MCP OAuth connections use the run_task MCP tool). ## OpenAPI ````yaml /api-reference/openapi.json post /credits/tasks 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 — 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: Customers description: >- Names for the customers a tenant attributes spend to, and every customer's spend - 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: Resources description: >- Durable resources an agent bought, such as phone numbers, inboxes and sandboxes - name: Tasks description: >- Delegate a multi-step outcome to Locus with one goal string. Locus compiles an acceptance contract, discovers and calls enabled catalog capabilities with the caller's own credits and spending controls, checks every returned value against stored provider evidence, and returns structured results, files, requirement statuses, and settled cost. Enabled when the deployment sets LOCUS_TASKS_ENABLED. - 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/tasks: post: tags: - Tasks summary: Run a task from a goal (submit, wait, cancel, respond, resume) description: >- The single task interface. Without `action`, starts a task from a natural-language goal and waits up to `wait_seconds` for the result. With `action` wait/status/cancel/respond/resume it continues the same task; repeating wait or status never starts or charges anything. Locus discovers capabilities in the caller's enabled catalog, calls them with the caller's credits and spending controls, verifies values against stored provider responses, and computes the terminal state in code. It never sends messages, purchases, writes, or deletes on the caller's behalf. Accepts secret keys and agent connections (MCP OAuth connections use the run_task MCP tool). operationId: postCreditsTasks parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 200 description: Alternative to the body idempotency_key. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskRequest' examples: goal_only: value: goal: >- Find 10 Series A hardware companies based in Los Angeles, California. Verify their funding, identify the founders and their verified work emails, and return a CSV. with_inputs: value: goal: >- Read the supplied pages and compare their stated rate limits. Return a table with source links. inputs: urls: - https://docs.anthropic.com/en/api/rate-limits - https://platform.openai.com/docs/guides/rate-limits output: format: json max_credits: 800 idempotency_key: 7d0c1b9e-2f7c-4d0e-9a59-0d6a1c2b3e4f wait: value: action: wait task_id: 6be8d9cc-e44e-48f9-af6f-fae0aa5bb160 wait_seconds: 50 resume: value: action: resume task_id: 6be8d9cc-e44e-48f9-af6f-fae0aa5bb160 max_credits: 3000 responses: '200': description: Terminal or needs_input envelope (or an idempotent replay of one). content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' '202': description: Still running; call again with action wait and the task_id. content: application/json: schema: $ref: '#/components/schemas/TaskEnvelope' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/TaskError' '401': description: Missing or invalid credential. '403': description: Credential cannot delegate tasks (sandbox keys and end-user tokens). content: application/json: schema: $ref: '#/components/schemas/TaskError' '404': description: Unknown task for this tenant and account, or tasks are disabled. content: application/json: schema: $ref: '#/components/schemas/TaskError' '409': description: >- Idempotency key reused with a different request, or a respond/resume the task is not waiting for. content: application/json: schema: $ref: '#/components/schemas/TaskError' '429': description: >- The account already has 5 tasks queued or running; wait for one to finish or cancel one. content: application/json: schema: $ref: '#/components/schemas/TaskError' security: - secretKey: [] - agentConnection: [] components: schemas: TaskRequest: oneOf: - $ref: '#/components/schemas/TaskSubmitRequest' - $ref: '#/components/schemas/TaskControlRequest' TaskEnvelope: type: object required: - object - version - task_id - status - terminal - cost properties: object: type: string enum: - task version: type: string enum: - locus.task.v1 task_id: type: string format: uuid status: type: string enum: - queued - running - needs_input - completed - partial - unsupported - failed - canceled description: >- completed = every mandatory requirement met by checks; partial = useful verified subset; needs_input = answer `question` with action respond; unsupported = no enabled capability can do it; failed = nothing usable; canceled = caller canceled. terminal: type: boolean stop_reason: type: - string - 'null' enum: - completed - count_shortfall - requirements_unmet - budget_exhausted - insufficient_credits - deadline - canceled - needs_input - no_capability - no_progress - step_limit - authorization_revoked - execution_error - null goal: type: string question: type: string description: Present when status is needs_input. created_at: type: string format: date-time updated_at: type: string format: date-time completed_at: type: - string - 'null' format: date-time deadline_at: type: string format: date-time progress: type: object properties: phase: type: string turns: type: integer paid_calls: type: integer last_event: type: - object - 'null' properties: type: type: string at: type: string format: date-time result: type: - object - 'null' properties: summary: type: - string - 'null' description: >- States only what Locus's checks established (verified counts, unmet requirements, stop reason). executor_summary: type: - string - 'null' description: The executor's own account of the work; not verified. data: type: - object - 'null' properties: columns: type: array items: type: string rows: type: array items: type: object additionalProperties: true row_count: type: integer group_count: type: integer truncated: type: boolean answer: type: - string - 'null' description: >- Markdown answer for answer-type goals (every claim is cited), or, when the goal asks for a Markdown table, the delivered table as one Markdown table under the caller's column headers (first 200 rows; results.md has all). unverified_rows: type: array description: >- Table rows the executor recorded as qualified that failed verification, with their recorded values and why each was withheld (up to 25). Not part of data and not counted as delivered. items: type: object properties: values: type: object additionalProperties: true reasons: type: array items: type: string artifacts: type: array items: $ref: '#/components/schemas/TaskArtifact' requirements: type: array items: $ref: '#/components/schemas/TaskRequirement' assumptions: type: array items: type: string limitations: type: array items: type: string cost: type: object required: - unit - max_credits - charged_credits - reserved_credits - accounting_state properties: unit: type: string enum: - credits max_credits: type: string charged_credits: type: string description: Settled charges so far. reserved_credits: type: string description: >- Held for in-flight or unknown-outcome calls; released or captured on reconciliation. tool_credits: type: string model_credits: type: string paid_calls: type: integer accounting_state: type: string enum: - in_progress - settled - pending_reconciliation error: type: object description: Present when the run recorded an execution error. properties: code: type: string message: type: - string - 'null' continuation: type: - object - 'null' properties: action: type: string enum: - wait - respond - resume task_id: type: string format: uuid hint: type: string TaskError: type: object required: - success - code - message properties: success: type: boolean enum: - false code: type: string examples: - TASK_REQUEST_INVALID - TASKS_DISABLED - TASK_AUTH_UNSUPPORTED - TASK_NOT_FOUND - TASK_IDEMPOTENCY_CONFLICT - TASK_BUDGET_INVALID - TASK_INPUTS_TOO_LARGE - TASK_NOT_WAITING_FOR_INPUT - TASK_NOT_RESUMABLE - TASK_CONCURRENCY_LIMIT message: type: string TaskSubmitRequest: type: object additionalProperties: false required: - goal properties: action: type: string enum: - submit description: Optional; omitted means submit. goal: type: string minLength: 1 maxLength: 8000 description: The outcome you want, in natural language. inputs: type: object additionalProperties: true description: >- Optional caller data or references (for example urls, ids, rows). Treated as data, never as instructions. Max 256 KiB. output: type: object additionalProperties: false properties: format: type: string enum: - csv - json - markdown columns: type: array maxItems: 60 items: type: string maxLength: 80 description: Required column names, in order. instructions: type: string maxLength: 2000 max_credits: oneOf: - type: string - type: number description: >- Credit ceiling for the whole task, including model reasoning and verification. In credits, not USD. Default 5 USD worth of credits, min 0.10 USD worth, max 200 USD worth; never above the account's own spending controls. deadline_seconds: type: integer minimum: 180 maximum: 3600 description: Wall-clock limit for the task (default 900). idempotency_key: type: string maxLength: 200 description: >- Reuse to retry a submission safely; the same key with the same request returns the original task, with a different request it returns 409. The Idempotency-Key header is accepted too. Without a key every submission starts a new task, even with identical text. wait_seconds: type: integer minimum: 0 maximum: 50 description: >- Seconds to hold the request open for a result (default 45). The task keeps running after the response. TaskControlRequest: oneOf: - type: object additionalProperties: false required: - action - task_id properties: action: type: string enum: - wait task_id: type: string format: uuid wait_seconds: type: integer minimum: 0 maximum: 50 description: >- Seconds to hold the request open for a result (default 45). The task keeps running after the response. - type: object additionalProperties: false required: - action - task_id properties: action: type: string enum: - status task_id: type: string format: uuid - type: object additionalProperties: false required: - action - task_id properties: action: type: string enum: - cancel task_id: type: string format: uuid - type: object additionalProperties: false required: - action - task_id - answer properties: action: type: string enum: - respond task_id: type: string format: uuid answer: type: string maxLength: 4000 wait_seconds: type: integer minimum: 0 maximum: 50 description: >- Seconds to hold the request open for a result (default 45). The task keeps running after the response. - type: object additionalProperties: false required: - action - task_id properties: action: type: string enum: - resume task_id: type: string format: uuid max_credits: oneOf: - type: string - type: number description: >- Credit ceiling for the whole task, including model reasoning and verification. In credits, not USD. Default 5 USD worth of credits, min 0.10 USD worth, max 200 USD worth; never above the account's own spending controls. wait_seconds: type: integer minimum: 0 maximum: 50 description: >- Seconds to hold the request open for a result (default 45). The task keeps running after the response. discriminator: propertyName: action TaskArtifact: type: object required: - artifact_id - name - kind - media_type - sha256 - expires_at - download_url - link_expires_at properties: artifact_id: type: string format: uuid name: type: string examples: - results.csv - results.json - results.md - answer.md - evidence.json kind: type: string enum: - result - evidence media_type: type: string size_bytes: type: - integer - 'null' sha256: type: string expires_at: type: string format: date-time description: When the stored file is deleted (7 days). download_url: type: string format: uri description: >- Signed link bound to this tenant, account, task, and exact bytes; no Authorization header needed. link_expires_at: type: string format: date-time description: Link lifetime (1 hour); call status again for a fresh link. TaskRequirement: type: object required: - id - text - status - mandatory - detail properties: id: type: string text: type: string status: type: string enum: - met - unmet - not_checked mandatory: type: boolean detail: type: string securitySchemes: secretKey: type: http scheme: bearer description: Tenant secret key (lcr_…). Server-side only. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.