> ## Documentation Index > Fetch the complete documentation index at: https://monid.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start an endpoint run > Start an execution of an endpoint. For a sync COMPLETED run the HTTP status FAITHFULLY MIRRORS the provider's own status (2xx → 2xx, provider 4xx/5xx → 4xx/5xx, request-timeout → 504); the body always carries the full run. A control gate returns a 200 BLOCKED run, and a run that exceeds its time budget returns 408 (TIMED_OUT). Async endpoints return a 202 acceptance ack — poll GET /v1/runs/{runId} for the result. Scopes: `runs:create`, plus `resources:create` / `resources:update` / `resources:delete` when the endpoint provisions / updates / releases a resource. ## OpenAPI ````yaml https://monid.ai/openapi.json post /v1/run openapi: 3.1.0 info: title: Monid API version: 0.1.0 description: >- Agentic payment platform for data — agents discover and buy data on demand. Authenticated `/v1/*` routes accept a Monid API key or Clerk JWT as a Bearer token. All errors return `{ code, message }`. List endpoints use cursor pagination; consult each operation schema for its last-page cursor encoding. servers: - url: https://api.monid.ai description: Production - url: https://monid.ai description: Public registry alias (public/v1 only) security: [] paths: /v1/run: post: tags: - Runs summary: Start an endpoint run description: >- Start an execution of an endpoint. For a sync COMPLETED run the HTTP status FAITHFULLY MIRRORS the provider's own status (2xx → 2xx, provider 4xx/5xx → 4xx/5xx, request-timeout → 504); the body always carries the full run. A control gate returns a 200 BLOCKED run, and a run that exceeds its time budget returns 408 (TIMED_OUT). Async endpoints return a 202 acceptance ack — poll GET /v1/runs/{runId} for the result. Scopes: `runs:create`, plus `resources:create` / `resources:update` / `resources:delete` when the endpoint provisions / updates / releases a resource. parameters: - $ref: '#/components/parameters/AgentModelHeader' - $ref: '#/components/parameters/AgentHarnessHeader' - $ref: '#/components/parameters/AgentSessionIdHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunRequest' responses: '200': description: >- Terminal run — COMPLETED (sync execution, when the provider responded 2xx) or BLOCKED (a workspace control gate rejected the run). A COMPLETED run with a non-2xx provider status is returned with that same HTTP status and this body shape — EXCEPT a provider 402 (the upstream vendor's payment/quota failure, not your wallet), which is returned as 502. content: application/json: schema: anyOf: - $ref: '#/components/schemas/RunCompleted' - $ref: '#/components/schemas/RunBlocked' '202': description: Async run accepted — poll GET /v1/runs/{runId} for results content: application/json: schema: $ref: '#/components/schemas/RunAccepted' '400': description: Bad request — input failed validation content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: >- Payment required — workspace wallet balance insufficient. (A 402 from this API is ALWAYS about your wallet; an upstream provider's own 402 surfaces as 502.) content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — caller has no workspace or no access content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Endpoint not found for provider content: application/json: schema: $ref: '#/components/schemas/Error' '408': description: >- TIMED_OUT — the run exceeded its time budget (run deadline or provider request timeout). Terminal, zero-billed; the body is the full run with status TIMED_OUT. content: application/json: schema: $ref: '#/components/schemas/RunCompleted' '429': description: >- Rate limited (errorCode `RATE_LIMITED`, message `Rate limited. Retry after Ns.`) — the `Retry-After` header carries whole seconds until the caller may retry; `RateLimit-Limit/-Remaining/-Reset` describe the binding limit as numbers only (also sent on allowed responses that matched a rule; responses that matched no rule, or an `unlimited` exemption, carry none of them). Applies to every authenticated `/v1` route (per API key / user / workspace); POST /v1/run additionally enforces per-provider/endpoint run limits. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: >- Upstream provider payment/quota failure — the provider returned 402 (its account problem, not your wallet). The body is the full COMPLETED run with the provider's error in providerResponse.error; the run is not charged. content: application/json: schema: $ref: '#/components/schemas/RunCompleted' security: - Bearer: - runs:create components: parameters: AgentModelHeader: name: X-Monid-Agent-Model in: header required: false description: >- Model driving the calling agent. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: claude-opus-5-5 AgentHarnessHeader: name: X-Monid-Agent-Harness in: header required: false description: >- Agent harness or client making the call (e.g. a coding agent, an agent framework). Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: claude-code AgentSessionIdHeader: name: X-Monid-Agent-Session-Id in: header required: false description: >- Caller-side session identifier, so the calls of one agent session (discover → inspect → run → polling) can be correlated. Optional; a value that is empty, longer than 256 characters or not printable ASCII is ignored (never an error). schema: type: string maxLength: 256 example: 01JABCDEF0123456789XYZ schemas: RunRequest: type: object properties: provider: type: string minLength: 1 description: Provider slug. example: exa endpoint: type: string minLength: 1 description: Endpoint path within the provider. example: search input: type: object properties: body: type: object additionalProperties: {} description: Request body fields. queryParams: type: object additionalProperties: {} description: URL query string parameters. pathParams: type: object additionalProperties: {} description: URL path placeholder substitutions (e.g. {id} in `/users/{id}`). additionalProperties: false description: >- Composite endpoint input — body + URL query + URL path. All sub-fields optional. required: - provider - endpoint additionalProperties: false RunCompleted: type: object properties: runId: type: string provider: type: string endpoint: type: string status: type: string enum: - READY - RUNNING - STOPPING - COMPLETED - FAILED - BLOCKED - STOPPED - TIMED_OUT description: >- Run lifecycle status. Always one of the UPPERCASE enum values (e.g. COMPLETED, never completed) — compare case-sensitively. COMPLETED means the provider responded (any HTTP status); FAILED means an infrastructure failure. output: description: >- Provider output data (terminal runs only; may be null). Endpoints that generate FILES (e.g. audio) surface each file INSIDE output as an artifact object under a stable key: { download_link (fresh signed URL, valid until link_expires_at — re-fetch the run for a new one), content_type, link_expires_at, file_expires_at? }. After the file's retention lapses the object becomes { expired: true, file_expired_at, message }. providerResponse: $ref: '#/components/schemas/ProviderResponse' price: $ref: '#/components/schemas/Price' billing: $ref: '#/components/schemas/RunBilling' resultCount: type: number minimum: 0 billedUnits: type: number minimum: 0 resources: type: array items: type: object properties: action: type: string enum: - PROVISIONED - PROVISION_FAILED - RELEASED - RELEASE_FAILED resourceId: type: string minLength: 1 resourceType: type: string enum: - phone_number - file_system - asset_library - machine - email_account - email_inbox - email_domain - browser_session - browser_profile - voice identifier: type: string minLength: 1 required: - action - resourceId - resourceType - identifier stopRequestedAt: type: string format: date-time createdAt: type: string format: date-time completedAt: type: string format: date-time hints: type: object additionalProperties: anyOf: - type: string - type: object properties: kind: type: string enum: - command - discover - inspect - run - getRun - stop - releaseResource - topup command: type: string query: type: string provider: type: string endpoint: type: string runId: type: string resourceId: type: string stripe: type: string dashboard: type: string docs: type: string comment: type: string required: - kind required: - runId - provider - endpoint - status - providerResponse - price - createdAt RunBlocked: type: object properties: runId: type: string status: type: string enum: - BLOCKED description: >- Always the literal BLOCKED (UPPERCASE, case-sensitive) — a workspace control gate rejected the run; see `reason`. provider: type: string endpoint: type: string reason: type: string price: $ref: '#/components/schemas/Price' controls: type: array items: type: object properties: controlId: type: string controlType: type: string requiredAmount: type: number description: The gate's pre-flight cost hold/estimate (dollars). snapshot: type: object additionalProperties: {} description: >- Dollarized control state snapshot at gate time (same shape as /v1/runs/{runId}/controls). required: - controlId - controlType - snapshot createdAt: type: string format: date-time completedAt: type: string format: date-time hints: type: object additionalProperties: anyOf: - type: string - type: object properties: kind: type: string enum: - command - discover - inspect - run - getRun - stop - releaseResource - topup command: type: string query: type: string provider: type: string endpoint: type: string runId: type: string resourceId: type: string stripe: type: string dashboard: type: string docs: type: string comment: type: string required: - kind required: - runId - status - provider - endpoint - reason - price - controls - createdAt - completedAt RunAccepted: type: object properties: runId: type: string provider: type: string endpoint: type: string status: type: string enum: - READY - RUNNING - STOPPING - COMPLETED - FAILED - BLOCKED - STOPPED - TIMED_OUT description: >- Run lifecycle status. Always one of the UPPERCASE enum values (e.g. COMPLETED, never completed) — compare case-sensitively. COMPLETED means the provider responded (any HTTP status); FAILED means an infrastructure failure. price: $ref: '#/components/schemas/Price' createdAt: type: string format: date-time hints: type: object additionalProperties: anyOf: - type: string - type: object properties: kind: type: string enum: - command - discover - inspect - run - getRun - stop - releaseResource - topup command: type: string query: type: string provider: type: string endpoint: type: string runId: type: string resourceId: type: string stripe: type: string dashboard: type: string docs: type: string comment: type: string required: - kind required: - runId - provider - endpoint - status - price - createdAt Error: type: object properties: code: type: integer description: HTTP status code, duplicated in the body. example: 400 message: type: string description: Human-readable error description. example: Bad Request hints: type: object additionalProperties: anyOf: - type: string - type: object properties: kind: type: string enum: - command - discover - inspect - run - getRun - stop - releaseResource - topup command: type: string query: type: string provider: type: string endpoint: type: string runId: type: string resourceId: type: string stripe: type: string dashboard: type: string docs: type: string comment: type: string required: - kind description: >- Optional next actions, rendered for the calling client like run-response hints (e.g. the paid TinyFish version on a free-quota 429 — spending permission required). errorCode: type: string enum: - RATE_LIMITED - X402_WORKSPACE_RESOURCES - X402_WORKSPACE_ONLY - X402_ACCRUING_COST - X402_EXCEEDS_SETTLEMENT_WINDOW - X402_VALIDITY_WINDOW_TOO_SHORT - X402_UNBOUNDED_PRICE - X402_PROMOTION - INSUFFICIENT_SCOPE - WALLET_INSUFFICIENT_FUNDS - IDENTITY_PROVIDER_UNKNOWN - IDENTITY_LINK_REQUIRES_SESSION - IDENTITY_LINK_STATE_INVALID - IDENTITY_VERIFICATION_FAILED - IDENTITY_PROVIDER_UNAVAILABLE - IDENTITY_ALREADY_LINKED - IDENTITY_USER_ALREADY_LINKED - IDENTITY_LINK_RATE_LIMITED - IDENTITY_REQUIRED - PROMO_IDENTITY_REDEEMED - PROMO_REDEEM_REQUIRES_SESSION - PROMO_CODE_REDEEMED_BY_WORKSPACE - PROMO_CODE_REDEEMED_BY_USER description: >- OPTIONAL machine-readable discriminant from the documented `ApiErrorCode` registry. Absent on legacy errors; clients MUST treat unknown values as absent. required: - code - message ProviderResponse: type: object properties: httpStatus: type: integer description: HTTP status from the provider (e.g. 200, 400, 404, 429, 500). example: 200 error: description: Provider error body, passed through faithfully on failure. Price: type: object properties: type: type: string amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency flatFee: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency period: type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count per: anyOf: - type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count - type: number unit: type: string enum: - token - character - second - image - credit - result - gb-month - step - byte - url - page default: anyOf: - type: object properties: type: type: string enum: - PER_CALL amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - PER_RESULT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency flatFee: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - METERED amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count required: - type - amount - per - type: object properties: type: type: string enum: - PER_UNIT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: number unit: type: string enum: - token - character - second - image - credit - result - gb-month - step - byte - url - page required: - type - amount - per - unit selectors: type: array items: type: object properties: label: type: string key: type: string in: type: string enum: - body - queryParam - pathParam - output offset: type: integer minimum: 0 required: - label - key - in variants: type: array items: type: object properties: when: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean price: anyOf: - type: object properties: type: type: string enum: - PER_CALL amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - PER_RESULT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency flatFee: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - METERED amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count required: - type - amount - per - type: object properties: type: type: string enum: - PER_UNIT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: number unit: type: string enum: - token - character - second - image - credit - result - gb-month - step - byte - url - page required: - type - amount - per - unit label: type: string required: - when - price tiers: type: array items: type: object properties: label: type: string when: type: object additionalProperties: anyOf: - type: string - type: number - type: boolean selector: type: object properties: label: type: string key: type: string in: type: string enum: - body - queryParam - pathParam - output offset: type: integer minimum: 0 required: - label - key - in price: anyOf: - type: object properties: type: type: string enum: - PER_CALL amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - PER_RESULT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency flatFee: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency required: - type - amount - type: object properties: type: type: string enum: - METERED amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: object properties: unit: type: string enum: - MINUTE - DAY - MONTH count: type: integer exclusiveMinimum: 0 required: - unit - count required: - type - amount - per - type: object properties: type: type: string enum: - PER_UNIT amount: type: object properties: value: type: number currency: type: string enum: - USD required: - value - currency per: type: number unit: type: string enum: - token - character - second - image - credit - result - gb-month - step - byte - url - page required: - type - amount - per - unit required: - label - price notes: type: array items: type: string required: - type - amount description: User-facing price (markup applied). RunBilling: type: object properties: reportedCost: type: object properties: currency: type: string enum: - USD value: type: integer minimum: 0 unit: type: string enum: - MICRO_DOLLAR - CENT - DOLLAR required: - currency - value - unit description: What the user pays for this run. required: - reportedCost securitySchemes: Bearer: type: http scheme: bearer description: >- Monid API key (`Authorization: Bearer mk_...`) or Clerk-issued JWT. Each operation lists the ONE scope an API key needs. `{resource}:*` grants every action on that resource; `*` grants everything; Clerk sessions hold `*`. Operations with an empty list need no scope. Scope catalog: `GET /v1/api-keys/scopes`. x-aep-authentication-method: api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.