> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an API

> Start an agent job. Returns job_id for polling.

By default returns `{job_id, status:"queued"}` immediately and the caller
polls `GET /jobs/{id}` then `GET /jobs/{id}/results`.

**Synchronous mode (`?wait=true`)**, opt-in: the request is held open while
the job is polled server-side (backoff), then:
  • completed → `{job_id, agent, status:"completed", row_count, returned,
    truncated, data}` with up to `API_WAIT_INLINE_ROW_CAP` (100) rows inline.
    If `truncated`, fetch the rest via `GET /jobs/{id}/results` (streamed) or
    `/jobs/{id}/download`.
  • failed / cancelled → `{job_id, agent, status, error}` inline.
  • timeout (default 60s, hard-capped; override lower with `wait_timeout`) →
    falls back to `{job_id, status:"running", created_at}`; poll as above.
MCP-sourced runs ignore `wait` (the MCP server self-polls).

A withdrawn id that still has live callers is rewritten to its replacement
BEFORE anything else, so validation, the wallet hold, the run row and the
invoice all name the surviving API (see `agent_registry.DEPRECATED_ALIASES`).

**Bad params 422 before anything is booked.** Which rule set decides is
`PARAM_VALIDATION_MODE` (api/core/config.py): `legacy` is the hand-rolled
gates alone, `shadow` (the default) runs them and logs what the shared
validator WOULD have done, `enforce` hands the decision to the shared
validator, the same `mindcase_core.param_validation` the MCP server and the
playground run, so a request this door accepts is one the data plane
accepts. A rejection carries per-field `errors[]` (`api/core/errors.py`), so
a UI can bind each one to the input that caused it. Every mode rejects
before `create_job`, before the wallet hold and before dispatch.



## OpenAPI

````yaml POST /v1/data/{group}/{slug}/run
openapi: 3.1.0
info:
  title: Mindcase API
  version: '1.0'
  description: Structured web data APIs for AI agents.
servers:
  - url: https://api.mindcase.co
security:
  - bearerAuth: []
paths:
  /v1/data/{group}/{slug}/run:
    post:
      tags:
        - Developer API
      summary: Run Agent
      description: >-
        Start an agent job. Returns job_id for polling.


        By default returns `{job_id, status:"queued"}` immediately and the
        caller

        polls `GET /jobs/{id}` then `GET /jobs/{id}/results`.


        **Synchronous mode (`?wait=true`)**, opt-in: the request is held open
        while

        the job is polled server-side (backoff), then:
          • completed → `{job_id, agent, status:"completed", row_count, returned,
            truncated, data}` with up to `API_WAIT_INLINE_ROW_CAP` (100) rows inline.
            If `truncated`, fetch the rest via `GET /jobs/{id}/results` (streamed) or
            `/jobs/{id}/download`.
          • failed / cancelled → `{job_id, agent, status, error}` inline.
          • timeout (default 60s, hard-capped; override lower with `wait_timeout`) →
            falls back to `{job_id, status:"running", created_at}`; poll as above.
        MCP-sourced runs ignore `wait` (the MCP server self-polls).


        A withdrawn id that still has live callers is rewritten to its
        replacement

        BEFORE anything else, so validation, the wallet hold, the run row and
        the

        invoice all name the surviving API (see
        `agent_registry.DEPRECATED_ALIASES`).


        **Bad params 422 before anything is booked.** Which rule set decides is

        `PARAM_VALIDATION_MODE` (api/core/config.py): `legacy` is the
        hand-rolled

        gates alone, `shadow` (the default) runs them and logs what the shared

        validator WOULD have done, `enforce` hands the decision to the shared

        validator, the same `mindcase_core.param_validation` the MCP server and
        the

        playground run, so a request this door accepts is one the data plane

        accepts. A rejection carries per-field `errors[]`
        (`api/core/errors.py`), so

        a UI can bind each one to the input that caused it. Every mode rejects

        before `create_job`, before the wallet hold and before dispatch.
      operationId: run_agent_v1_data__group___slug__run_post
      parameters:
        - name: group
          in: path
          required: true
          schema:
            type: string
            title: Group
        - name: slug
          in: path
          required: true
          schema:
            type: string
            title: Slug
        - name: wait
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Opt-in synchronous mode: hold the request open until the run
              completes (or the wait times out) and return rows inline. Ignored
              for MCP-sourced runs.
            default: false
            title: Wait
          description: >-
            Opt-in synchronous mode: hold the request open until the run
            completes (or the wait times out) and return rows inline. Ignored
            for MCP-sourced runs.
        - name: wait_timeout
          in: query
          required: false
          schema:
            anyOf:
              - type: number
              - type: 'null'
            description: >-
              Seconds to wait when wait=true (clamped to the server ceiling,
              default 60). On timeout you get {job_id, status:'running'} and
              poll /jobs/{id} + /jobs/{id}/results as usual.
            title: Wait Timeout
          description: >-
            Seconds to wait when wait=true (clamped to the server ceiling,
            default 60). On timeout you get {job_id, status:'running'} and poll
            /jobs/{id} + /jobs/{id}/results as usual.
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 8
            maxLength: 255
          description: >-
            Optional, recommended. A unique string per run (e.g. a UUID).
            Retrying with the same key within 24h returns the original job
            instead of starting and charging a second one; the response carries
            `X-Idempotent-Replay: true`. The same key with a different agent or
            params returns 422 `idempotency_key_reused`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunAgentRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        default:
          description: Any error. See `error.code`.
          headers:
            X-Request-ID:
              description: >-
                The id of this call, also in `error.request_id`. Quote it when
                contacting support.
              schema:
                type: string
            Retry-After:
              description: Seconds to wait before retrying, on retryable errors.
              schema:
                type: integer
            RateLimit-Limit:
              description: Requests allowed per minute in this bucket.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests left in the window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until a slot frees.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey: []
components:
  schemas:
    RunAgentRequest:
      properties:
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Agent parameters
      type: object
      title: RunAgentRequest
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
        detail:
          title: Detail
          description: Legacy field, kept for existing clients. Prefer `error`.
        errors:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Errors
          description: >-
            Legacy per-field list on parameter errors. Same as
            `error.details.errors`.
      type: object
      required:
        - error
        - detail
      title: ErrorResponse
      description: >-
        The body of every non-2xx response.


        | Situation | How you see it | `retryable` | Wait |

        |---|---|---|---|

        | Rate limited | HTTP 429 | yes | `retry_after_seconds` |

        | We couldn't read your balance | HTTP 503, or a `failed` job with
        `balance_unavailable` | yes | 5s |

        | Something failed on our side | HTTP 5xx, or a `failed` job | yes | 30s
        |

        | Bad parameters | HTTP 422 | no | Fix them first |

        | Not enough balance | HTTP 402, or `rejected_balance` | no | Add
        balance first |

        | Bad API key | HTTP 401 | no | Fix the key first |

        | Run ended short with rows | `completed` with a `stop_reason` | no |
        Run again on purpose for the rest |


        Retry only when `retryable` is true, after `retry_after_seconds`.
        Without a

        wait, back off exponentially with jitter, up to 30s and about 5
        attempts.

        Send an `Idempotency-Key` so a retry can't charge twice.
    ErrorBody:
      properties:
        code:
          type: string
          title: Code
          description: Stable machine-readable code. Branch on this.
        message:
          type: string
          title: Message
          description: Plain English. May be reworded.
        request_id:
          type: string
          title: Request Id
          description: Quote this when contacting support.
        retryable:
          type: boolean
          title: Retryable
          description: Whether the same request, unchanged, can succeed later.
        retry_after_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After Seconds
          description: >-
            When `retryable` is true, how long to wait. Matches the
            `Retry-After` header.
        fault:
          type: string
          enum:
            - input
            - mindcase
          title: Fault
          description: >-
            Whose problem this is: `input` (the request; fix it first) or
            `mindcase` (ours).
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: Extra fields, per code.
      type: object
      required:
        - code
        - message
        - request_id
        - retryable
        - fault
      title: ErrorBody
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Mindcase API key, mk_live_...
    ApiKey:
      type: http
      description: 'Your Mindcase API key: `Authorization: Bearer mk_live_...`'
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.