openapi: 3.1.0
info:
  title: Retriever Public API
  version: "1.0.0"
  description: |
    Retriever public API: start the prospecting agent (runs), read and export
    tables, import data, sync exclusion lists, run structured research (Go),
    and call atomic services.

    **Model Context Protocol (MCP)**: the same account and credits are available
    through the hosted MCP server (`POST /mcp`, Streamable HTTP). See the MCP
    guide in this documentation (Model Context Protocol navigation). Primary
    tools: `service_discover`, `service_execute`, `service_batch_execute` and
    `service_batch_get` (the slow services), `retriever_build_list_*`,
    `retriever_research_*`, `workspace_list`, `table_*`, `exclusion_*`,
    `credits`, `sequence_*`, `sender_*`, `inbox_*`.

    **Authentication**: `Authorization: Bearer ret_live_…`. Create the key in the
    app: Settings → **API keys** → **Create API key**. The key grants access to
    resources in the key owner's organization.

    **Errors**: every HTTP error has the shape
    `{ "error": { "code": "…", "message": "…", "details": … } }`.
    Branch your code on `error.code` (stable), never on `message`.

    **Rate limits**: key-authenticated responses include
    `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` (seconds).
    A `429` response also includes `Retry-After` (seconds).
    Any key-authenticated operation can also answer `503` with code
    `key_check_busy` (see `components.responses.KeyCheckBusy`): the key could
    not be checked right now, often a key created a moment ago during a flood
    of unknown keys. Retry after `Retry-After` seconds.

    **Request size**: a request body can be at most 10 MiB (10,485,760
    bytes), and 25 MiB (26,214,400 bytes) on a table import. A larger body
    gets `413 body_too_large`.

    API error messages are in English.
  contact:
    name: Retriever
servers:
  - url: https://api.retriever.run
    description: "Production"
  - url: http://localhost:4320
    description: "Local app-server"

security:
  - bearerAuth: []

tags:
  - name: Runs
    description: "Prospecting agent « prompt in, table out ». Asynchronous."
  - name: Tables
    description: "Read live tables in a workspace."
  - name: Workspaces
    description: "Create workspaces and import tables."
  - name: Exclusions
    description: "Company and people lists to never source."
  - name: Scheduled runs
    description: "Repeat a list-building mission on a cadence."
  - name: Plays
    description: "Find, qualify and contact leads on a cadence, and sort them."
  - name: Go
    description: "One question, one structured answer: the Go agent searches the web and can call every Retriever service."
  - name: Services
    description: "Atomic services (search, scraping, email…)."
  - name: Credits
    description: "Credit balance."

paths:
  /v1/runs:
    post:
      tags: [Runs]
      operationId: createRun
      x-mint:
        href: /api-reference/runs/create-run
      summary: Start a run
      description: |
        Registers the run and responds immediately with `202`. Poll it with
        `GET /v1/runs/{id}`. Without `workspace_id` or `conversation_id`,
        Retriever creates a workspace and a conversation. To refine or extend
        a result, send the `conversation_id` of the run that produced it: the
        agent keeps its history and tables, and can add to the same table.
        Open a new conversation for an unrelated request, or to run requests
        at the same time.

        Send an `Idempotency-Key` to safely retry the request without creating a
        duplicate: same key + same body = same run; same key + different body =
        `409 idempotency_conflict`.

        An organization executes at most 5 runs at the same time by default. A
        new run is never refused because of this limit. While all its slots
        are taken, by runs
        `running` or `recovering` or by older queued runs, it stays `queued`,
        with a `queue` field saying why, then starts on its own, oldest first.
        MCP runs share the same slots; Go jobs do not. A queued run already
        holds its conversation (`409 conversation_busy` for a follow-up). Do not
        create a queued run again: a second run is billed as a second run.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateRunRequest" }
            examples:
              simple:
                summary: Prompt only
                value: { prompt: "Find 30 French fintechs with 50 to 200 employees and their CEO." }
              frozenTable:
                summary: Frozen tabular output
                value:
                  prompt: "Find the CEO and their LinkedIn for each company in table tbl_001."
                  workspace_id: ws_001
                  output:
                    type: tables
                    tables: [{ key: contacts }]
      responses:
        "202":
          description: "Run accepted."
          headers:
            Location: { schema: { type: string }, description: "Run path, e.g. /v1/runs/run_001." }
            Retry-After: { schema: { type: integer }, description: "Suggested delay before the first poll (5 s)." }
            RateLimit-Limit: { $ref: "#/components/headers/RateLimit-Limit" }
            RateLimit-Remaining: { $ref: "#/components/headers/RateLimit-Remaining" }
            RateLimit-Reset: { $ref: "#/components/headers/RateLimit-Reset" }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Run" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404":
          description: "`workspace_not_found` or `conversation_not_found`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "409":
          description: "`idempotency_conflict` (same key, different body) or `conversation_busy` (a run is already active in this conversation)."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
              example: { error: { code: conversation_busy, message: "This conversation already has an active run." } }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "503":
          description: "`runs_unavailable`: run storage unavailable. Try again later."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    get:
      tags: [Runs]
      operationId: listRuns
      x-mint:
        href: /api-reference/runs/list-runs
      summary: List runs
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - { name: workspace_id, in: query, schema: { type: string }, description: "Filter by workspace." }
        - { name: conversation_id, in: query, schema: { type: string }, description: "Filter by conversation." }
      responses:
        "200":
          description: "Page of runs, newest to oldest."
          content:
            application/json:
              schema:
                type: object
                required: [items, next_offset]
                properties:
                  items: { type: array, items: { $ref: "#/components/schemas/Run" } }
                  next_offset: { type: [integer, "null"], description: "`null` at end of list." }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/runs/{id}:
    get:
      tags: [Runs]
      operationId: getRun
      x-mint:
        href: /api-reference/runs/get-run
      summary: Get run status
      description: |
        Poll until a terminal status (`completed`, `failed`, `cancelled`).
        Honor `Retry-After` (15 s for an active run). Send `If-None-Match` with
        the `ETag` from a prior read to get `304` when nothing changed.

        Only this read returns `credits.charged`, the credits the run was
        charged so far. The list, create and cancel responses leave it out.
      parameters:
        - $ref: "#/components/parameters/RunId"
        - { name: If-None-Match, in: header, schema: { type: string }, description: "ETag from a previous read." }
      responses:
        "200":
          description: "Current state."
          headers:
            ETag: { schema: { type: string } }
            Retry-After: { schema: { type: integer }, description: "Present only while the run is active." }
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Run" }
              example:
                id: run_001
                workspace_id: ws_001
                conversation_id: conv_001
                status: completed
                message: "I created the Fintechs FR table with 30 companies."
                artifacts:
                  - { type: table, id: tbl_001, name: Fintechs FR, effect: created, links: { self: /v1/tables/tbl_001, rows: /v1/tables/tbl_001/rows } }
                output: null
                error: null
                credits: { charged: 42.5 }
                cancellation_requested: false
                links: { self: /v1/runs/run_001, app: "https://app.retriever.run/app/workspaces/ws_001/conversations/conv_001" }
        "304": { description: "Unchanged since the provided ETag." }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/RunNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/runs/{id}/cancel:
    post:
      tags: [Runs]
      operationId: cancelRun
      x-mint:
        href: /api-reference/runs/cancel-run
      summary: Request cancellation
      description: |
        Sets `cancellation_requested: true`. The worker stops at the next
        heartbeat. Changes already made to tables are kept.
      parameters: [{ $ref: "#/components/parameters/RunId" }]
      responses:
        "200": { description: "Run updated.", content: { application/json: { schema: { $ref: "#/components/schemas/Run" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/RunNotFound" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/runs/{id}/output:
    get:
      tags: [Runs]
      operationId: getRunOutput
      x-mint:
        href: /api-reference/runs/get-run-output
      summary: Get published output
      description: "Available only if the run was created with `output` and has finished."
      parameters: [{ $ref: "#/components/parameters/RunId" }]
      responses:
        "200":
          description: "Frozen output."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RunOutput" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404":
          description: "`output_not_found`: no `output` contract, or run not finished yet."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/runs/{id}/output/tables/{key}:
    get:
      tags: [Runs]
      operationId: getRunOutputTable
      x-mint:
        href: /api-reference/runs/get-output-table
      summary: Frozen table metadata
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/OutputTableKey"
      responses:
        "200":
          description: "Frozen table."
          content:
            application/json:
              schema:
                type: object
                properties:
                  key: { type: string }
                  source_table_id: { type: string }
                  columns: { type: array, items: { type: object } }
                  row_count: { type: integer }
                  links: { type: object, properties: { rows: { type: string } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404": { $ref: "#/components/responses/TableNotFound" }

  /v1/runs/{id}/output/tables/{key}/rows:
    get:
      tags: [Runs]
      operationId: listRunOutputTableRows
      x-mint:
        href: /api-reference/runs/list-output-table-rows
      summary: Frozen table rows
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/OutputTableKey"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
      responses:
        "200":
          description: "Page of rows."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RowPage" }
        "400":
          description: "`invalid_cursor` (cursor from another run/table) or `invalid_request`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404": { $ref: "#/components/responses/TableNotFound" }

  /v1/runs/{id}/exports:
    post:
      tags: [Runs]
      operationId: createRunExport
      x-mint:
        href: /api-reference/runs/create-export
      summary: Create a CSV or JSON export of a frozen table
      description: |
        The export is generated during the request: a `201` response means it is
        ready to download. It contains business values only, without cell
        metadata. In CSV, experience and education lists are flattened to text.
      parameters: [{ $ref: "#/components/parameters/RunId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [table_key, format]
              properties:
                table_key: { type: string, minLength: 1 }
                format: { type: string, enum: [csv, json] }
            example: { table_key: contacts, format: csv }
      responses:
        "201":
          description: "Export ready."
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  byte_length: { type: integer }
                  links: { type: object, properties: { self: { type: string } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404": { $ref: "#/components/responses/TableNotFound" }

  /v1/runs/{id}/exports/{exportId}:
    get:
      tags: [Runs]
      operationId: downloadRunExport
      x-mint:
        href: /api-reference/runs/download-export
      summary: Download an export
      parameters:
        - $ref: "#/components/parameters/RunId"
        - { name: exportId, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: "File with Content-Disposition attachment header; filename output.csv or output.json."
          content:
            text/csv: { schema: { type: string } }
            application/json: { schema: { type: array, items: { type: object } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404":
          description: "`export_not_found`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }

  /v1/tables/{id}:
    get:
      tags: [Tables]
      operationId: getTable
      x-mint:
        href: /api-reference/tables/get-table
      summary: Live table metadata
      parameters:
        - $ref: "#/components/parameters/TableId"
        - $ref: "#/components/parameters/IncludeHidden"
      responses:
        "200": { description: "Table.", content: { application/json: { schema: { $ref: "#/components/schemas/Table" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/TableNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/tables/{id}/rows:
    get:
      tags: [Tables]
      operationId: listTableRows
      x-mint:
        href: /api-reference/tables/list-table-rows
      summary: Live table rows
      description: |
        Cursor pagination. Order is stable (position then id). The table may
        change while you read (run in progress).
      parameters:
        - $ref: "#/components/parameters/TableId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/IncludeHidden"
      responses:
        "200": { description: "Page.", content: { application/json: { schema: { $ref: "#/components/schemas/RowPage" } } } }
        "400":
          description: "`invalid_cursor`: cursor belongs to another table. Restart without `cursor`. `invalid_request`: `limit` or `include_hidden` out of range."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/TableNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/workspaces:
    get:
      tags: [Workspaces]
      operationId: listWorkspaces
      x-mint:
        href: /api-reference/workspaces/list-workspaces
      summary: List workspaces
      description: "Workspaces of the key owner's organization, oldest first by default. `order=desc` lists the most recently created first."
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: order
          in: query
          required: false
          schema: { type: string, enum: [asc, desc], default: asc }
          description: "`asc` (default): oldest first. `desc`: most recently created first. Any other value returns `400 invalid_request`."
      responses:
        "200":
          description: "Page of workspaces."
          content:
            application/json:
              schema:
                type: object
                properties:
                  items: { type: array, items: { $ref: "#/components/schemas/Workspace" } }
                  next_offset: { type: [integer, "null"] }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
    post:
      tags: [Workspaces]
      operationId: createWorkspace
      x-mint:
        href: /api-reference/workspaces/create-workspace
      summary: Create a workspace
      description: "No idempotency: each call creates a new workspace."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name]
              properties: { name: { type: string, minLength: 1 } }
            example: { name: Prospects CRM }
      responses:
        "201": { description: "Created.", content: { application/json: { schema: { $ref: "#/components/schemas/Workspace" } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }

  /v1/workspaces/{id}/tables:
    get:
      tags: [Workspaces]
      operationId: listWorkspaceTables
      x-mint:
        href: /api-reference/workspaces/list-workspace-tables
      summary: List non-archived tables
      parameters:
        - $ref: "#/components/parameters/WorkspaceId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/IncludeHidden"
      responses:
        "200":
          description: "Page of tables."
          content:
            application/json:
              schema:
                type: object
                properties:
                  items: { type: array, items: { $ref: "#/components/schemas/Table" } }
                  next_offset: { type: [integer, "null"] }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404": { $ref: "#/components/responses/WorkspaceNotFound" }
    post:
      tags: [Workspaces]
      operationId: createWorkspaceTable
      x-mint:
        href: /api-reference/workspaces/import-table
      summary: Import a table (columns + JSON rows)
      description: |
        Single transaction: one error rolls back the entire import. Every row
        property must match a declared column. There is no endpoint to append
        rows to an existing table.

        At most 200 columns and 10,000 rows, refused with `400` before anything
        is written. The body can be at most 25 MiB, 26,214,400 bytes
        (`413 body_too_large`).
      parameters: [{ $ref: "#/components/parameters/WorkspaceId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateTableRequest" }
            example:
              name: Companies
              columns: [{ key: company, name: Company }, { key: domain, name: Domain }]
              rows: [{ company: Acme, domain: acme.example }, { company: Beta, domain: null }]
      responses:
        "201":
          description: "Table created."
          headers: { Location: { schema: { type: string } } }
          content: { application/json: { schema: { $ref: "#/components/schemas/Table" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404": { $ref: "#/components/responses/WorkspaceNotFound" }
        "413": { $ref: "#/components/responses/ImportPayloadTooLarge" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }

  /v1/exclusions/{kind}:
    get:
      tags: [Exclusions]
      operationId: listExclusions
      x-mint:
        href: /api-reference/exclusions/list-exclusions
      summary: List an exclusion list
      description: |
        For `people`, only entries with a LinkedIn handle are returned. People
        added in the app by name and company are not listed. `linkedin_url` is
        the URL stored for that person, not a normalized form: the first one sent
        through the API, the one a CRM integration stored, or the one from a later
        CSV import in the app. When the stored value is not a `linkedin.com` URL,
        it is rebuilt as `https://www.linkedin.com/in/<handle>`. Compare people
        by handle.
      parameters:
        - $ref: "#/components/parameters/ExclusionKind"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: "Page of entries."
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        domain: { type: string, description: "For `companies`. Normalized, for example `stripe.com`." }
                        linkedin_url: { type: string, description: "For `people`. The stored URL, not normalized." }
                        created_at: { type: string, format: date-time }
                        updated_at: { type: string, format: date-time }
                  next_offset: { type: [integer, "null"] }
        "400":
          description: "`invalid_request`: unknown query parameter, `limit` not an integer from 1 to 1,000, or `offset` not an integer of 0 or more."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ExclusionKindNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
    post:
      tags: [Exclusions]
      operationId: upsertExclusions
      x-mint:
        href: /api-reference/exclusions/add-exclusions
      summary: Add values (upsert)
      description: |
        1 to 1,000 values per call. Sending an existing value again adds
        nothing and is counted in `existing`. A value that came from a CRM
        integration of the app (HubSpot, Attio) becomes owned by the API, and
        that integration no longer removes it.

        An empty string, `null`, a value that is not a string, or an unknown
        body field fails the whole request with `400 invalid_request`. Any
        other string that is not a domain (`companies`) or a `linkedin.com/in/…`
        URL (`people`) is listed in `invalid`, and the rest is applied. A
        LinkedIn handle may contain only letters `a`-`z` (any case), `0`-`9`, `_`, `%`, `.` and
        `-`, starting with a letter or a digit: `/in/andré-dupont` and
        `/in/o'brien` are invalid.

        Idempotent by value: a replay leaves the same list. `Idempotency-Key`
        is ignored.
      parameters: [{ $ref: "#/components/parameters/ExclusionKind" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ExclusionValues" }
            examples:
              companies: { value: { domains: [stripe.com, "https://www.salesforce.com"] } }
              people: { value: { linkedin_urls: ["https://www.linkedin.com/in/johndoe"] } }
      responses:
        "200":
          description: "Summary."
          content:
            application/json:
              schema:
                type: object
                required: [inserted, existing, invalid]
                properties:
                  inserted: { type: integer }
                  existing: { type: integer }
                  invalid: { type: array, items: { $ref: "#/components/schemas/InvalidExclusionValue" } }
              example: { inserted: 1, existing: 1, invalid: [{ value: "not a domain", reason: company_domain_required }] }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ExclusionKindNotFound" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/exclusions/{kind}/remove:
    post:
      tags: [Exclusions]
      operationId: removeExclusions
      x-mint:
        href: /api-reference/exclusions/remove-exclusions
      summary: Remove values
      description: |
        Removes each value from the organization's list, whoever added it: by
        hand, by CSV, through the API or by a CRM integration of the app. A
        value that a CRM integration still lists comes back on its next sync.

        Same body rules as the upsert: an empty string, `null` or a value that
        is not a string fails the whole request with `400`; any other string
        that cannot be read is listed in `invalid`. For `people`, send a
        `linkedin.com/in/…` URL: a bare handle is invalid.

        Idempotent by value: removing a value that is not on the list counts
        nothing. `Idempotency-Key` is ignored.
      parameters: [{ $ref: "#/components/parameters/ExclusionKind" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/ExclusionValues" }
      responses:
        "200":
          description: "Removal summary."
          content:
            application/json:
              schema:
                type: object
                required: [removed, invalid]
                properties:
                  removed: { type: integer }
                  invalid: { type: array, items: { $ref: "#/components/schemas/InvalidExclusionValue" } }
              example: { removed: 2, invalid: [] }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ExclusionKindNotFound" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/scheduled-runs:
    get:
      tags: [Scheduled runs]
      operationId: listScheduledRuns
      x-mint:
        href: /api-reference/scheduled-runs/list-scheduled-runs
      summary: List scheduled runs
      description: "Scheduled runs of the organization, deleted ones left out. Not paginated."
      parameters:
        - name: workspace_id
          in: query
          required: false
          schema: { type: string }
          description: "Keep only the scheduled runs of this workspace."
      responses:
        "200":
          description: "The scheduled runs."
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items: { type: array, items: { $ref: "#/components/schemas/ScheduledRunWithLatest" } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
    post:
      tags: [Scheduled runs]
      operationId: createScheduledRun
      x-mint:
        href: /api-reference/scheduled-runs/create-scheduled-run
      summary: Create a scheduled run
      description: "Creates a draft. It does not run until `POST /v1/scheduled-runs/{id}/activate`."
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CreateScheduledRunRequest" }
      responses:
        "201":
          description: "The draft."
          content: { application/json: { schema: { $ref: "#/components/schemas/ScheduledRun" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ScheduledRunNotFound" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/scheduled-runs/{id}:
    get:
      tags: [Scheduled runs]
      operationId: getScheduledRun
      x-mint:
        href: /api-reference/scheduled-runs/get-scheduled-run
      summary: Read a scheduled run
      parameters: [{ $ref: "#/components/parameters/ScheduleId" }]
      responses:
        "200":
          description: "The scheduled run."
          content: { application/json: { schema: { $ref: "#/components/schemas/ScheduledRunWithLatest" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ScheduledRunNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
    patch:
      tags: [Scheduled runs]
      operationId: updateScheduledRun
      x-mint:
        href: /api-reference/scheduled-runs/update-scheduled-run
      summary: Change a scheduled run
      description: "Keeps the status. On an active scheduled run, `next_run_at` is computed again. A scheduled run that belongs to a play cannot be changed here: `409 scheduled_run_belongs_to_play`; change it on the play, in the app."
      parameters: [{ $ref: "#/components/parameters/ScheduleId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/UpdateScheduledRunRequest" }
      responses:
        "200":
          description: "The scheduled run."
          content: { application/json: { schema: { $ref: "#/components/schemas/ScheduledRun" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ScheduledRunNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "409": { $ref: "#/components/responses/ScheduledRunConflict" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
    delete:
      tags: [Scheduled runs]
      operationId: deleteScheduledRun
      x-mint:
        href: /api-reference/scheduled-runs/delete-scheduled-run
      summary: Delete a scheduled run
      description: "Final. Cancels an execution already queued. The workspace and tables stay."
      parameters: [{ $ref: "#/components/parameters/ScheduleId" }]
      responses:
        "200":
          description: "The scheduled run, `archived`."
          content: { application/json: { schema: { $ref: "#/components/schemas/ScheduledRun" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ScheduledRunNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "409": { $ref: "#/components/responses/ScheduledRunConflict" }
  /v1/scheduled-runs/{id}/activate:
    post:
      tags: [Scheduled runs]
      operationId: activateScheduledRun
      x-mint:
        href: /api-reference/scheduled-runs/activate-scheduled-run
      summary: Start the cadence
      description: "Executions start on the cadence. Each one spends credits. No body. On a scheduled run that belongs to a play, its sequences restart too and can refuse with `400` and a sender or sequence code, for example `no_sender_available`."
      parameters: [{ $ref: "#/components/parameters/ScheduleId" }]
      responses:
        "200":
          description: "The scheduled run, `active`."
          content: { application/json: { schema: { $ref: "#/components/schemas/ScheduledRun" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ScheduledRunNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "409": { $ref: "#/components/responses/ScheduledRunConflict" }
  /v1/scheduled-runs/{id}/pause:
    post:
      tags: [Scheduled runs]
      operationId: pauseScheduledRun
      x-mint:
        href: /api-reference/scheduled-runs/pause-scheduled-run
      summary: Stop the cadence
      description: "An execution the cadence already queued is cancelled. No body."
      parameters: [{ $ref: "#/components/parameters/ScheduleId" }]
      responses:
        "200":
          description: "The scheduled run, `paused`."
          content: { application/json: { schema: { $ref: "#/components/schemas/ScheduledRun" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ScheduledRunNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "409": { $ref: "#/components/responses/ScheduledRunConflict" }
  /v1/scheduled-runs/{id}/run:
    post:
      tags: [Scheduled runs]
      operationId: runScheduledRun
      x-mint:
        href: /api-reference/scheduled-runs/run-scheduled-run
      summary: Start an execution now
      description: "A scheduled run that is not a play's starts even when draft or paused. Each call starts another billed execution. A play's scheduled run starts through its play, as `POST /v1/plays/{id}/run`: `409` with `play_paused`, `play_archived` or `play_run_busy` when the play cannot run now. No body."
      parameters: [{ $ref: "#/components/parameters/ScheduleId" }]
      responses:
        "202":
          description: "The new execution."
          content: { application/json: { schema: { $ref: "#/components/schemas/ScheduledRunExecution" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ScheduledRunNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "409": { $ref: "#/components/responses/ScheduledRunConflict" }
  /v1/scheduled-runs/{id}/runs:
    get:
      tags: [Scheduled runs]
      operationId: listScheduledRunExecutions
      x-mint:
        href: /api-reference/scheduled-runs/list-scheduled-run-executions
      summary: List executions
      description: "The 50 most recent executions, newest first. Poll it to know when an execution ends: see the Scheduled runs concept."
      parameters: [{ $ref: "#/components/parameters/ScheduleId" }]
      responses:
        "200":
          description: "The executions."
          content:
            application/json:
              schema:
                type: object
                required: [items]
                properties:
                  items:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/ScheduledRunExecution"
                        - type: object
                          required: [results]
                          properties:
                            results:
                              description: "Per delivered table, the rows created during the execution. `null` until it starts."
                              anyOf:
                                - type: array
                                  items:
                                    type: object
                                    required: [table_id, new_rows, new_qualified]
                                    properties:
                                      table_id: { type: string }
                                      new_rows: { type: integer }
                                      new_qualified: { type: [integer, "null"], description: "`null` when the table has no criteria." }
                                - type: "null"
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/ScheduledRunNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/plays:
    get:
      tags: [Plays]
      operationId: listPlays
      x-mint:
        href: /api-reference/plays/list-plays
      summary: List plays
      description: "The organization's plays, archived ones included. Not paginated."
      responses:
        "200":
          description: "The plays."
          content: { application/json: { schema: { type: object, required: [items], properties: { items: { type: array, items: { $ref: "#/components/schemas/PlaySummary" } } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
    post:
      tags: [Plays]
      operationId: createPlay
      x-mint:
        href: /api-reference/plays/create-play
      summary: Create a play
      description: "Creates a draft: it runs nothing. The body is the plays contract the app's agent uses. `defaulted` names the parts left to their default."
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PlayDraft" }
      responses:
        "201":
          description: "The draft, with `defaulted`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/news:
    get:
      tags: [Plays]
      operationId: listPlayNews
      x-mint:
        href: /api-reference/plays/list-play-news
      summary: What is new across plays
      description: "Newest first: leads waiting for review (`lead`), changes plays propose after their runs (`proposal`), finished runs (`run`). Query `play_id` keeps one play."
      parameters: [{ $ref: "#/components/parameters/PlayNewsPlayId" }]
      responses:
        "200":
          description: "The news."
          content: { application/json: { schema: { type: object, properties: { items: { type: array, items: { type: object, properties: { kind: { type: string, enum: [lead, proposal, run] }, play: { type: object, properties: { id: { type: string }, name: { type: string } } }, lead: { $ref: "#/components/schemas/PlayLead" }, proposal: { type: object, properties: { id: { type: string }, kind: { type: string }, scope: { type: string, enum: [play, brain] }, summary: { type: string }, created_at: { type: string } } }, run: { type: object } } } } } } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}:
    get:
      tags: [Plays]
      operationId: getPlay
      x-mint:
        href: /api-reference/plays/get-play
      summary: Read a play
      description: "Its blocks, limits and lead counts."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      responses:
        "200":
          description: "The play."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
    patch:
      tags: [Plays]
      operationId: updatePlay
      x-mint:
        href: /api-reference/plays/update-play
      summary: Change a play
      description: "Name, blocks (`changes`) or limits; at least one. A block given replaces the play's: `sequence` and `context` whole, `delivery` field by field. `changed` is false when nothing differed. `changes.delivery.mode: auto` turns autopilot on."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PlayEdit" }
      responses:
        "200":
          description: "The play, with `changed`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
    delete:
      tags: [Plays]
      operationId: deletePlay
      x-mint:
        href: /api-reference/plays/delete-play
      summary: Delete a play
      description: "Its runs stop and its sequences are deleted, so nothing more is sent. Its table stays in its workspace. Final."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      responses:
        "200":
          description: "Deleted."
          content: { application/json: { schema: { type: object, properties: { id: { type: string }, deleted: { type: boolean } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/versions:
    get:
      tags: [Plays]
      operationId: listPlayVersions
      x-mint:
        href: /api-reference/plays/list-play-versions
      summary: List a play's versions
      description: "Newest first. Each change to a play is a version: who made it (`made_by`: `user` by hand in the app, `agent` by an agent or the API, `feedback` a change the play proposed), when, and `changes`, each field before and after."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      responses:
        "200":
          description: "The versions."
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        version: { type: integer }
                        current: { type: boolean }
                        made_by: { type: string, enum: [user, agent, feedback] }
                        member_name: { type: [string, "null"] }
                        summary: { type: string }
                        restored_from_version: { type: [integer, "null"], description: "The version a restore brought back." }
                        changes:
                          type: array
                          items:
                            type: object
                            properties:
                              label: { type: string }
                              kind: { type: string, enum: [edit, add, del] }
                              from: { type: string }
                              to: { type: string }
                        created_at: { type: string, format: date-time }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/versions/{version}/restore:
    post:
      tags: [Plays]
      operationId: restorePlayVersion
      x-mint:
        href: /api-reference/plays/restore-play-version
      summary: Restore a play version
      description: "A new version with the content of the one chosen: its blocks and its limits, checked as a change is. The play keeps its current name. The versions in between stay in the history. `changed` is false when the play already matched it. No body."
      parameters:
        - { $ref: "#/components/parameters/PlayId" }
        - { name: version, in: path, required: true, schema: { type: integer, minimum: 1 } }
      responses:
        "200":
          description: "The play, with `changed`: false when the play already matched that version."
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: "#/components/schemas/Play" }
                  - { type: object, required: [changed], properties: { changed: { type: boolean } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "422":
          description: "`play_version_unrestorable`: that version was saved in a form plays no longer take; `message` names the fields. Change the play with `PATCH` instead."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "503": { description: "The fields of the play's AI Agent step could not be suggested just now (`agent_fields_unavailable`): try again." }
  /v1/plays/{id}/launch:
    post:
      tags: [Plays]
      operationId: launchPlay
      x-mint:
        href: /api-reference/plays/launch-play
      summary: Launch a play
      description: "Starts its scheduled run with the delivery the play has; the first run comes at the next run time, and each spends credits. Launching a launched play again sets its timezone. Body: `{ timezone }`, an IANA time zone."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, required: [timezone], additionalProperties: false, properties: { timezone: { type: string, example: Europe/Paris } } }
      responses:
        "200":
          description: "The play, `active`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/pause:
    post:
      tags: [Plays]
      operationId: pausePlay
      x-mint:
        href: /api-reference/plays/pause-play
      summary: Pause a play
      description: "No new run; its sequences stop sending. No body."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      responses:
        "200":
          description: "The play, `paused`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/run:
    post:
      tags: [Plays]
      operationId: runPlayNow
      x-mint:
        href: /api-reference/plays/run-play-now
      summary: Run a play now
      description: "A full run of a launched play starts now, without waiting for its cadence: the same search, qualification and delivery as a run on its cadence, which stays planned. Billed like any run. Refused with `409` and the reason in `message`: `play_not_launched` (a draft), `play_paused`, `play_archived`, or `play_run_busy` (one of its runs is waiting or going). No body."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      responses:
        "202":
          description: "The run, `queued`. It shows in `GET /v1/scheduled-runs/{schedule_id}/runs`; its leads come in `GET /v1/plays/{id}/leads` when it ends."
          content: { application/json: { schema: { $ref: "#/components/schemas/PlayRun" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/resume:
    post:
      tags: [Plays]
      operationId: resumePlay
      x-mint:
        href: /api-reference/plays/resume-play
      summary: Resume a play
      description: "A launched play runs again; its sequences restart and can refuse with `400` and a sender or sequence code, or `422 play_needs_account`. No body."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      responses:
        "200":
          description: "The play, `active`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "422": { $ref: "#/components/responses/PlayLeadRefused" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/archive:
    post:
      tags: [Plays]
      operationId: archivePlay
      x-mint:
        href: /api-reference/plays/archive-play
      summary: Archive a play
      description: "Stops it and takes it out of the lists. Nothing is lost. No body."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      responses:
        "200":
          description: "The play, `archived`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/restore:
    post:
      tags: [Plays]
      operationId: restorePlay
      x-mint:
        href: /api-reference/plays/restore-play
      summary: Restore a play
      description: "Back in the lists, still stopped: `paused` once launched, `draft` otherwise. No body."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      responses:
        "200":
          description: "The play."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/leads:
    get:
      tags: [Plays]
      operationId: listPlayLeads
      x-mint:
        href: /api-reference/plays/list-play-leads
      summary: List a play's leads
      description: "A page of leads, each with the person, the signal, why it fits and its first message."
      parameters: [{ $ref: "#/components/parameters/PlayId" }, { $ref: "#/components/parameters/PlayLeadReviewState" }, { $ref: "#/components/parameters/Limit" }, { $ref: "#/components/parameters/Offset" }]
      responses:
        "200":
          description: "A page of leads."
          content: { application/json: { schema: { $ref: "#/components/schemas/PlayLeadPage" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/leads/{leadId}/accept:
    post:
      tags: [Plays]
      operationId: acceptPlayLead
      x-mint:
        href: /api-reference/plays/accept-play-lead
      summary: Keep a lead
      description: "The lead enters the play's sequence, which sends its first message. On a paused play, or without an account for its channel, it waits. No body."
      parameters: [{ $ref: "#/components/parameters/PlayId" }, { $ref: "#/components/parameters/PlayLeadId" }]
      responses:
        "200":
          description: "The lead, `accepted`."
          content: { application/json: { schema: { $ref: "#/components/schemas/PlayLead" } } }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "422": { $ref: "#/components/responses/PlayLeadRefused" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/leads/{leadId}/reject:
    post:
      tags: [Plays]
      operationId: rejectPlayLead
      x-mint:
        href: /api-reference/plays/reject-play-lead
      summary: Reject a lead
      description: "With the reasons: the next runs learn from them. The person and their company are excluded for the whole organization."
      parameters: [{ $ref: "#/components/parameters/PlayId" }, { $ref: "#/components/parameters/PlayLeadId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, required: [reasons], additionalProperties: false, properties: { reasons: { type: array, maxItems: 10, items: { type: string, maxLength: 120 } }, note: { type: string, maxLength: 600 } } }
      responses:
        "200":
          description: "The lead, `rejected`."
          content: { application/json: { schema: { $ref: "#/components/schemas/PlayLead" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/leads/{leadId}/replace:
    post:
      tags: [Plays]
      operationId: replacePlayLead
      x-mint:
        href: /api-reference/plays/replace-play-lead
      summary: Find someone else
      description: "Right company, wrong person: the lead in review is set aside as a 'Wrong person' rejection (only the person is excluded) and a run of the play starts to find someone else there. Spends credits like any run. Needs a launched play that is not archived."
      parameters: [{ $ref: "#/components/parameters/PlayId" }, { $ref: "#/components/parameters/PlayLeadId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: false, properties: { instruction: { type: string, maxLength: 600 } } }
      responses:
        "200":
          description: "The lead, with `replacement`."
          content: { application/json: { schema: { $ref: "#/components/schemas/PlayLead" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/leads/{leadId}/message/rewrite:
    post:
      tags: [Plays]
      operationId: rewritePlayLeadMessage
      x-mint:
        href: /api-reference/plays/rewrite-play-lead-message
      summary: Rewrite a lead's message
      description: "A model writes the first message again, as `instructions` asks. A message edited by hand in the sequence answers `409 play_message_edited_by_hand` unless `overwrite_hand_edit` is true. `voice_rule_added`: a rule the request added to the organization's voice, or null."
      parameters: [{ $ref: "#/components/parameters/PlayId" }, { $ref: "#/components/parameters/PlayLeadId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: false, properties: { instructions: { type: string, maxLength: 600 }, overwrite_hand_edit: { type: boolean } } }
      responses:
        "200":
          description: "The lead, with `voice_rule_added`."
          content: { application/json: { schema: { $ref: "#/components/schemas/PlayLead" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/leads/{leadId}/message:
    put:
      tags: [Plays]
      operationId: savePlayLeadMessage
      x-mint:
        href: /api-reference/plays/save-play-lead-message
      summary: Save a lead's message
      description: "The first message as written, with `subject` only when the sequence's first message is an email. Once the lead is in its sequence, a message that fits that step is the one it sends; one that does not fit stays on the lead only."
      parameters: [{ $ref: "#/components/parameters/PlayId" }, { $ref: "#/components/parameters/PlayLeadId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, required: [text], additionalProperties: false, properties: { subject: { type: string, maxLength: 200 }, text: { type: string, maxLength: 4000 } } }
      responses:
        "200":
          description: "The lead."
          content: { application/json: { schema: { $ref: "#/components/schemas/PlayLead" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/steps/rewrite:
    post:
      tags: [Plays]
      operationId: rewritePlayStepInstructions
      x-mint:
        href: /api-reference/plays/rewrite-play-step-instructions
      summary: Rewrite the steps' instructions
      description: "A model rewrites the writing instructions of the sequence's steps as `request` asks, for every next message. A new version."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, required: [request], additionalProperties: false, properties: { request: { type: string, maxLength: 1000 } } }
      responses:
        "200":
          description: "The play."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/leads/move:
    post:
      tags: [Plays]
      operationId: movePlayLeads
      x-mint:
        href: /api-reference/plays/move-play-leads
      summary: Move leads to the play's channel
      description: "Leads in review found for an earlier channel go on the play's channel, each with a new first message. Without `lead_ids`, all of them."
      parameters: [{ $ref: "#/components/parameters/PlayId" }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { type: object, additionalProperties: false, properties: { lead_ids: { type: array, minItems: 1, maxItems: 200, items: { type: string } } } }
      responses:
        "200":
          description: "The play."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "415": { $ref: "#/components/responses/UnsupportedMediaType" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/proposals/{proposalId}/apply:
    post:
      tags: [Plays]
      operationId: applyPlayProposal
      x-mint:
        href: /api-reference/plays/apply-play-proposal
      summary: Apply a proposal
      description: "The play takes the change, as a new version. `409 play_update_stale`: made for blocks that changed since. `409 play_update_not_applicable`: no change to the play's blocks. No body."
      parameters: [{ $ref: "#/components/parameters/PlayId" }, { $ref: "#/components/parameters/PlayProposalId" }]
      responses:
        "200":
          description: "The play."
          content: { application/json: { schema: { $ref: "#/components/schemas/Play" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/plays/{id}/proposals/{proposalId}/dismiss:
    post:
      tags: [Plays]
      operationId: dismissPlayProposal
      x-mint:
        href: /api-reference/plays/dismiss-play-proposal
      summary: Dismiss a proposal
      description: "No body."
      parameters: [{ $ref: "#/components/parameters/PlayId" }, { $ref: "#/components/parameters/PlayProposalId" }]
      responses:
        "200":
          description: "The proposal."
          content: { application/json: { schema: { type: object, properties: { id: { type: string }, status: { type: string } } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404": { $ref: "#/components/responses/PlayNotFound" }
        "409": { $ref: "#/components/responses/PlayConflict" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
  /v1/go/run:
    post:
      tags: [Go]
      operationId: goRunSync
      x-mint:
        href: /api-reference/go/run-sync
      summary: Synchronous structured research
      description: "Waits for the result. For searches longer than ~30 s, use `POST /v1/go/runs`."
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/GoRunRequest" }
            example:
              query: "Find the founders of Alan (alan.com) with their title and LinkedIn."
              output_schema:
                type: object
                properties:
                  founders:
                    type: array
                    items: { type: object, properties: { name: { type: string }, title: { type: string }, linkedin_url: { type: string } } }
                required: [founders]
      responses:
        "200": { description: "Result.", content: { application/json: { schema: { $ref: "#/components/schemas/GoResult" } } } }
        "400": { $ref: "#/components/responses/ValidationError" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "502": { $ref: "#/components/responses/Upstream" }

  /v1/go/runs:
    post:
      tags: [Go]
      operationId: goRunAsync
      x-mint:
        href: /api-reference/go/create-go-run
      summary: Asynchronous structured research
      description: |
        At most 5 jobs can be running at once for a user. A sixth returns
        `429` with the code `too_many_runs` and `Retry-After: 30` (not the
        request budget of `rate_limited`). A job cut off by an unplanned stop
        keeps counting until it ends `interrupted`, a few minutes after the
        server is back. A job is stopped after 3 hours and ends `failed` with
        the code `timeout` (or, if it does not stop, `interrupted` within the
        next 15 minutes).
        A job asked for from a server that is restarting returns
        `503 server_restarting`: start it again after `Retry-After`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/GoRunRequest" }
      responses:
        "202":
          description: "Job started."
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  run_id: { type: string, example: go_run_9a8b7c1d2e3f4a5b }
                  status: { type: string, enum: [running], description: "Always `running` when created." }
                  poll_url: { type: string }
                  created_at: { type: string, format: date-time }
        "400": { $ref: "#/components/responses/ValidationError" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429":
          description: "`too_many_runs`: 5 jobs are already running, wait `Retry-After` (30 s). Or `rate_limited`: the request budget of your key, see Rate limits."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "503":
          description: "`server_restarting`: the server is restarting. Nothing was started. Send it again after `Retry-After`."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }

  /v1/go/runs/{id}:
    get:
      tags: [Go]
      operationId: getGoRun
      x-mint:
        href: /api-reference/go/get-go-run
      summary: Go job status
      description: |
        Always `200` if the job exists. A `failed` or `cancelled` job has
        `ok: false` and an `error` object. `Retry-After: 3` while it is running.
        A job cut off by a server restart ends `failed` with the error code
        `interrupted`: start it again. Rarely, its answer was already on its
        way and the job reads `completed` later: the answer is then there, and
        billed (a job started again meanwhile is billed too).
        After an unplanned stop of the server,
        the job keeps reading `running` until a few minutes after the server
        is back, then ends `interrupted`.
        A job that ends `failed` or `cancelled` stays billed for the services
        it already called: starting it again bills them again.
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { description: "Status.", content: { application/json: { schema: { $ref: "#/components/schemas/GoJob" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404": { $ref: "#/components/responses/RunNotFound" }

  /v1/go/runs/{id}/cancel:
    post:
      tags: [Go]
      operationId: cancelGoRun
      x-mint:
        href: /api-reference/go/cancel-go-run
      summary: Cancel a Go job
      description: "No effect on an already finished job, or on one whose outcome is being saved: returns its status. Services called before the cancel stay billed. If the answer arrives more than a few seconds after the cancel, the job stays `cancelled`: that answer is billed and not returned."
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        "200":
          description: "Status after cancellation."
          content: { application/json: { schema: { type: object, properties: { ok: { type: boolean }, run_id: { type: string }, status: { type: string } } } } }
        "500":
          description: "`internal_error`: the job is stopped but the cancel could not be saved. Send the cancel again."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404": { $ref: "#/components/responses/RunNotFound" }

  /services:
    get:
      tags: [Services]
      operationId: listServices
      x-mint:
        href: /api-reference/services/list-services
      summary: Discover services
      parameters:
        - { name: q, in: query, schema: { type: string }, description: "Full-text search." }
        - { name: category, in: query, schema: { type: string }, description: "Service category." }
        - { name: limit, in: query, schema: { type: integer } }
        - { name: offset, in: query, schema: { type: integer } }
      description: |
        Each result has `service`, `category`, `summary` and `credits`, and
        `listOnly: true` for a slow service: send it on
        `POST /v1/services/jobs/batch`, never on `POST /services/{serviceName}`.
      responses:
        "200": { description: "Catalog.", content: { application/json: { schema: { type: object } } } }
        "400": { $ref: "#/components/responses/ValidationError" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /services/{serviceName}:
    get:
      tags: [Services]
      operationId: getService
      x-mint:
        href: /api-reference/services/get-service
      summary: Describe a service (input schema, cost)
      description: "`listOnly: true` marks a slow service, sent only as a list on `POST /v1/services/jobs/batch`."
      parameters: [{ $ref: "#/components/parameters/ServiceName" }]
      responses:
        "200": { description: "Definition.", content: { application/json: { schema: { type: object } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "404":
          description: "`not_found` with `details.reason: unknown_service`: unknown or non-public service. List with `GET /services`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    post:
      tags: [Services]
      operationId: executeService
      x-mint:
        href: /api-reference/services/execute-service
      summary: Execute a service
      description: |
        Read the input schema first with `GET /services/{serviceName}`. Most
        services answer in seconds with `200`.

        The slow services (`getEmail`, `getPhoneNumber`, `webResearch`) are refused here
        with `410 list_only`: send them on `POST /v1/services/jobs/batch`, even
        for one person. They often outlive the edge's 100 second cut.
      parameters:
        - { $ref: "#/components/parameters/ServiceName" }
      requestBody:
        required: true
        description: "Input matching the schema returned by `GET /services/{serviceName}`."
        content: { application/json: { schema: { type: object } } }
      responses:
        "200":
          description: "Result and credits consumed."
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  service: { type: string }
                  output: {}
                  credits: { type: object, properties: { charged: { type: number }, remaining: { type: number } } }
        "400": { $ref: "#/components/responses/ValidationError" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402": { $ref: "#/components/responses/InsufficientCredits" }
        "404":
          description: "`not_found`: unknown or non-public service (`details.reason: unknown_service`), or, without `details`, what the input names does not exist (a post, a company page). Not retryable."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/TooManyRequests" }
        "422":
          description: "`provider_rejected`: the provider refused the input itself, or a contact lookup's input gives too little to search (give a LinkedIn profile, or a first and last name with the company). Fix the input; the same request gets the same refusal."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "502": { $ref: "#/components/responses/Upstream" }
        "503":
          description: "`capacity` (the provider had no room) or `provider_unavailable` (no provider account could be used: none enabled, key refused, credits out at the provider). Nothing was charged: send the same request again a few minutes later."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "504":
          description: "`timeout`: the provider did not answer in time. It costs nothing, unless the provider's answer lands just after the cut: the call is then billed as usual. The error carries no `credits`: such a charge shows only in the balance (see \"Reconciling with GET /credits\" in the Runs page). Send the same request again a few minutes later."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "410":
          description: "`list_only`: a slow service. Send it on `POST /v1/services/jobs/batch` (`details.batch_url`), even for one person."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }

  /v1/services/jobs:
    post:
      tags: [Services]
      operationId: createServiceJob
      deprecated: true
      summary: Removed, send a list
      description: |
        A service sent alone is refused with `410 list_only`. Send it on
        `POST /v1/services/jobs/batch`: a list of one is fine.
      responses:
        "400":
          description: "`invalid_request`: no `service` in the body."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "404":
          description: "`not_found` with `details.reason: unknown_service`: unknown or non-public service."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "410":
          description: "`list_only`: use `POST /v1/services/jobs/batch` (`details.batch_url`). Each answer is then in `jobs[i].result`, with the same fields as the direct call's output, and a failure in `jobs[i].error`."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
    get:
      tags: [Services]
      operationId: listServiceJobs
      summary: List your service jobs
      parameters:
        - { name: service, in: query, schema: { type: string }, description: "Filter by service." }
        - { name: limit, in: query, schema: { type: integer } }
        - { name: offset, in: query, schema: { type: integer } }
      responses:
        "200":
          description: "Jobs, newest to oldest."
          content:
            application/json:
              schema:
                type: object
                properties:
                  items: { type: array, items: { $ref: "#/components/schemas/ServiceJobLine" } }
                  next_offset: { type: integer, nullable: true }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/services/jobs/{id}:
    get:
      tags: [Services]
      operationId: getServiceJob
      summary: Service job status and result
      description: |
        One line of a batch on its own; the batch read already carries every
        line. A `failed` job has `error` instead of `result`, with `retryable`:
        `true` when the same input can get an answer later, sent again in a
        new batch. What each code means and what to do is in the Errors page
        (batch lines). A job has 30 minutes from the real start of its provider
        call, restarts included (the wait for a free place is not counted, up
        to two hours); a contact lookup's own call stops at 15 minutes. Past
        either, the job ends with `timeout` and is not run again.
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { description: "Status.", content: { application/json: { schema: { $ref: "#/components/schemas/ServiceJob" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404":
          description: "`not_found`: unknown job."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/services/jobs/{id}/cancel:
    post:
      tags: [Services]
      operationId: cancelServiceJob
      summary: Cancel a service job
      description: |
        A job that has not started stops immediately. A running job has its
        provider call interrupted. A job that finishes before cancellation
        arrives keeps its result: cancel is a request, not a guarantee. A job
        another batch also points to (a colleague asked for the same person)
        is not cancelled: `409 job_shared`, and it keeps running for them.

        A cancelled line can be billed too: an earlier attempt that ran
        before a restart, the Deep agent's miss price when it had finished its
        search, or a call whose answer landed as the cancel arrived. Its
        `credits.charged` shows it.
      parameters: [{ name: id, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { description: "Status after cancellation.", content: { application/json: { schema: { $ref: "#/components/schemas/ServiceJob" } } } }
        "409":
          description: "`job_shared`: another batch of your organization points to this job; it is not cancelled."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404":
          description: "`not_found`: unknown job."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/services/jobs/batch:
    post:
      tags: [Services]
      operationId: createServiceJobBatch
      summary: Run a slow service (a list of 1 to 100 inputs)
      description: |
        The only way to run a slow service (`getEmail`, `getPhoneNumber`,
        `webResearch`):
        1 to 100 inputs in one call, one job per input, in the order sent. Put
        every person of a task in the same list.
        Every input is validated first; one bad input refuses the whole list
        with its index, and no job is created.

        An input the schema accepts but that names too little to search (a
        contact with no LinkedIn profile, and no first and last name with a
        company) is not refused here: its line ends `provider_rejected`.

        Each line follows the job rules. For `getEmail` and `getPhoneNumber`
        only, an answer your organization already has for that person from the
        last 7 days is reused and the line comes back with
        `reused: true` (nothing more is charged for this answer), when it covers the request
        (an answer found by a database `databases` leaves out, or a "not
        found" a chosen database has not searched, runs again). A `getPhoneNumber`
        "not found" whose waterfall holds a `skipped` database (one that could
        not answer this time) never answers a request that runs that database:
        the same person sent again searches again. `getPhoneNumber` stops at
        the first database that finds a number, a landline as well as a
        mobile: to get another number, send the person again with
        `databases` leaving out the `source` of the number found. The stored
        answer does not cover that request, and the database left out is not
        called, so it is not paid again. Other slow services never
        reuse a finished answer: they only share a search still running, like
        every service does. A failed line is never reused: the same input sent
        again gets a new job. The batch and its jobs are
        created together or not at all. `Retriever-Fresh: true` forces a
        fresh, billed execution of every line. Collect the results with
        `GET /v1/services/jobs/batch/{id}`. Requests and results are emptied
        after 30 days.

        Each line reserves its worst-case price before its search. When the
        balance cannot reserve even the cheapest line that needs a new search,
        the whole list is refused with `402 insufficient_credits` and no job
        is created. Otherwise the list is accepted, and a line that finds no
        balance left ends `failed` with `usage_limit`: top up, then send the
        failed inputs again. Each line says what it cost in
        `credits.charged`, and the batch gives the total of its lines. A job
        that two lines or two batches share counts once, on the line that
        created it. `GET /v1/services/jobs/{id}` shows that job's full charge:
        when you add up jobs across batches, count each `job_id` once. A
        line's amount can still grow after it ends when a charge is recorded
        late, most often for a call cut by a timeout whose answer landed just
        after the cut. Late charges usually land within seconds, but this is
        not guaranteed: read it again a few minutes after the end. To compare with your balance, read
        "Reconciling with GET /credits" in the Runs page.

        `getPhoneNumber` returns every number its sources found in `phones`
        (number, country, line type, line status, `do_not_call` when the source
        flags the number, source), best first; `phone_number` is the first
        entry. Its price depends on the database that finds the number, up to
        the listed price.
      parameters:
        - { name: Retriever-Fresh, in: header, required: false, schema: { type: string, enum: ["true"] }, description: "`true`: a new, billed search for every line, even when your organization has a recent answer." }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [service, inputs]
              properties:
                service: { type: string, example: getPhoneNumber }
                inputs:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items: { type: object, description: "One direct input object, as `POST /services/{serviceName}` takes it." }
      responses:
        "202":
          description: "Batch accepted; at least one job is still running."
          headers:
            Location: { schema: { type: string } }
            Retry-After: { schema: { type: integer } }
          content: { application/json: { schema: { $ref: "#/components/schemas/ServiceJobBatch" } } }
        "200":
          description: "Every input already had an answer: the batch is complete."
          content: { application/json: { schema: { $ref: "#/components/schemas/ServiceJobBatch" } } }
        "400":
          description: "`invalid_request`: the body or an input is invalid (the message names the field, and an input's index)."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "404":
          description: "`not_found` with `details.reason: unknown_service`: no public service has this name (`GET /services` lists them)."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "402":
          description: "`insufficient_credits`: the balance cannot reserve the cheapest line that needs a new search. No job is created. Top up (`GET /credits` for the balance), then send the list again."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "413": { $ref: "#/components/responses/PayloadTooLarge" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /v1/services/jobs/batch/{id}:
    get:
      tags: [Services]
      operationId: getServiceJobBatch
      summary: Batch status and results
      description: |
        With `wait_seconds`, the request is held until no line is queued or
        running, or until the wait ends, whichever comes first: call it again
        the same way until `status` is `completed`. A restart on our side
        answers a held read at once. Without it the read
        answers at once. `status` is `completed`
        once every job has ended, whatever each one's outcome: read each
        job's `status`, `result` or `error`. `input_index` is the position in
        the list sent.
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
        - { name: wait_seconds, in: query, required: false, schema: { type: integer, minimum: 0, maximum: 60, default: 0 }, description: "Seconds to wait for every line to end before answering." }
      responses:
        "200": { description: "Batch.", content: { application/json: { schema: { $ref: "#/components/schemas/ServiceJobBatch" } } } }
        "400":
          description: "`invalid_request`: `wait_seconds` is not an integer from 0 to 60."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "404":
          description: "`not_found`: unknown batch."
          content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
        "429": { $ref: "#/components/responses/TooManyRequests" }

  /credits:
    get:
      tags: [Credits]
      operationId: getCredits
      x-mint:
        href: /api-reference/credits/get-credits
      summary: Credit balance
      responses:
        "200":
          description: "Balance."
          content: { application/json: { schema: { type: object, properties: { remainingCredits: { type: number } } }, example: { remainingCredits: 842.5 } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/TooManyRequests" }

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "API key `ret_live_…` created in Settings → API keys."

  headers:
    RateLimit-Limit: { schema: { type: integer }, description: "Window budget." }
    RateLimit-Remaining: { schema: { type: integer }, description: "Remaining requests." }
    RateLimit-Reset: { schema: { type: integer }, description: "Seconds until reset." }

  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string, minLength: 1 }
      description: "Unique client-side request id (e.g. UUID). Must not be empty."
    Limit:
      name: limit
      in: query
      schema: { type: integer, minimum: 1, maximum: 1000, default: 100 }
    Offset:
      name: offset
      in: query
      schema: { type: integer, minimum: 0, default: 0 }
    Cursor:
      name: cursor
      in: query
      schema: { type: string }
      description: "Opaque `next_cursor` value from the previous page."
    IncludeHidden:
      name: include_hidden
      in: query
      schema: { type: string, enum: ["true", "false"], default: "false" }
      description: "`true` also returns the columns hidden in the app: column lists flag them `hidden: true`, and rows include their values."
    RunId: { name: id, in: path, required: true, schema: { type: string }, example: run_001 }
    TableId: { name: id, in: path, required: true, schema: { type: string }, example: tbl_001 }
    WorkspaceId: { name: id, in: path, required: true, schema: { type: string }, example: ws_001 }
    OutputTableKey: { name: key, in: path, required: true, schema: { type: string }, example: contacts }
    ServiceName: { name: serviceName, in: path, required: true, schema: { type: string }, example: webSearch }
    ScheduleId:
      name: id
      in: path
      required: true
      schema: { type: string }
      description: "Id of the scheduled run."
    PlayId: { name: id, in: path, required: true, schema: { type: string }, description: "Id of the play." }
    PlayLeadId: { name: leadId, in: path, required: true, schema: { type: string }, description: "Id of the lead." }
    PlayLeadReviewState:
      name: review_state
      in: query
      required: false
      schema: { type: string, enum: [review, accepted, rejected] }
      description: "review: waiting for the user. Left out: all."
    PlayProposalId: { name: proposalId, in: path, required: true, schema: { type: string }, description: "Id of the proposal, from the news." }
    PlayNewsPlayId: { name: play_id, in: query, required: false, schema: { type: string }, description: "Only this play's news." }
    ExclusionKind:
      name: kind
      in: path
      required: true
      schema: { type: string, enum: [companies, people] }

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string, description: "Stable code; use in your application." }
            message: { type: string, description: "Human-readable explanation. May change." }
            details: { description: "Optional details (e.g. list of invalid fields)." }

    CreateRunRequest:
      type: object
      additionalProperties: false
      required: [prompt]
      properties:
        prompt: { type: string, minLength: 1, description: "Natural-language instruction. Must not be empty. The agent does not ask clarifying questions: put every decision here. A later run on the same conversation_id corrects a choice." }
        workspace_id: { type: string, description: "Existing workspace. Without `conversation_id`, the run opens a new conversation there; with it, it must be the conversation's workspace. Without both, a workspace is created." }
        conversation_id: { type: string, description: "Continues this conversation: the agent keeps its history and tables. Use it to refine or extend an earlier result." }
        output: { $ref: "#/components/schemas/OutputContract" }

    OutputContract:
      description: |
        Optional output contract. Without it, the run returns `message`,
        `artifacts`, and `output: null`.
      oneOf:
        - type: object
          additionalProperties: false
          required: [type, schema]
          properties:
            type: { const: json }
            schema: { description: "Standalone JSON Schema draft 7. Output is validated without coercion.", type: [object, boolean] }
        - type: object
          additionalProperties: false
          required: [type]
          properties:
            type: { const: tables }
            tables:
              type: array
              items:
                type: object
                additionalProperties: false
                required: [key]
                properties:
                  key: { type: string, minLength: 1, description: "Unique key in the contract." }
                  row_schema: { type: [object, boolean], description: "JSON Schema enforced on each row's `values`." }

    Run:
      type: object
      properties:
        id: { type: string }
        workspace_id: { type: string }
        conversation_id: { type: string }
        status: { type: string, enum: [queued, running, recovering, completed, failed, cancelled] }
        message: { type: [string, "null"], description: "Agent's final text." }
        artifacts:
          type: array
          description: "Tables created or updated by the run (live state)."
          items:
            type: object
            properties:
              type: { const: table }
              id: { type: string }
              name: { type: string }
              effect: { type: string, enum: [created, updated] }
              links: { type: object, properties: { self: { type: string }, rows: { type: string } } }
        last_heartbeat_at: { type: [string, "null"], format: date-time }
        progress: { type: object, properties: { phase: { type: [string, "null"] }, updated_at: { type: string } } }
        output:
          type: [object, "null"]
          properties:
            type: { type: string, enum: [json, tables] }
            links: { type: object, properties: { self: { type: string } } }
        error: { type: [object, "null"], properties: { code: { type: string }, message: { type: string } } }
        credits:
          type: object
          description: "Only on `GET /v1/runs/{id}`. The list, create and cancel responses do not include it. It is also missing when your credit history could not be read: read the run again."
          properties:
            charged: { type: number, description: "Credits the run was charged so far: the services and data sources it called, including the cells of the columns it launched (AI columns included), the research agent that fills a column row by row, browser sessions, and AI-written sequence messages written during the run (the first message of each lead it enrolls in an active sequence; every other AI sequence message, including those of a draft sequence the agent activates, is written when its step is due and is not charged on the run). The main agent's own model calls are not billed. It grows while the run is active, keeps growing after the run ends while cells of the columns it launched are still running, can grow after the end when a charge is recorded late (most often a call cut by a timeout, or aborted by a Stop or a cancel, whose answer landed just after the cut). A failed or cancelled run shows what it used so far: on a Stop or a cancel, running cells go back to their previous value at once, but a call they already sent can still be billed on the run. No field marks the amount as final. Read the rows of the run's tables (`artifacts`, `GET /v1/tables/{id}/rows?include_hidden=true`: hidden columns run and bill too) until no cell has `status` `running`, then read the run again later. A cell that reads `failed` may still be retried automatically, up to two times, depending on its service and on why it failed. While it waits for its retry it reads `failed`, and nothing in the API tells a failed cell that will be retried from a final one. A retried cell waits its turn in the queue, which can take more than a few minutes, and the amount grows again if the retry gets an answer. Treat the amount as provisional until it has stopped changing over a longer window. Cells started by other activity on those tables count as running too." }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        started_at: { type: [string, "null"], format: date-time, description: "Null while the run is `queued`. The maximum run duration counts from here." }
        completed_at: { type: [string, "null"], format: date-time }
        cancellation_requested: { type: boolean }
        queue:
          type: [object, "null"]
          description: "Set on every `queued` run read with `GET /v1/runs/{id}`, `null` once the run has left the queue. On the `202` of `POST /v1/runs`, `queue` can be `null` or already out of date: `GET /v1/runs/{id}` is the reference."
          required: [reason, active_runs, limit, ahead]
          properties:
            reason:
              type: string
              enum: [organization_limit, waiting_for_worker]
              description: "`organization_limit`: the organization's slots are taken, by executing runs and older queued runs; the run starts on its own as runs end. `waiting_for_worker`: a slot is free; a worker usually takes the run within seconds, longer during a deploy or when many organizations have runs waiting."
            active_runs: { type: integer, description: "Runs of the organization `running` or `recovering` now." }
            limit: { type: integer, description: "Runs one organization executes at the same time (5 by default)." }
            ahead: { type: integer, description: "Older queued runs of the organization. They start before this one." }
        links:
          type: object
          properties:
            self: { type: string }
            app: { type: string, description: "Opens the run conversation and its tables in the Retriever app (session required)." }
      example:
        id: run_001
        workspace_id: ws_001
        conversation_id: conv_001
        status: completed
        message: "I created the Fintechs FR table with 30 companies."
        artifacts:
          - { type: table, id: tbl_001, name: Fintechs FR, effect: created, links: { self: /v1/tables/tbl_001, rows: /v1/tables/tbl_001/rows } }
        output: null
        error: null
        cancellation_requested: false
        queue: null
        links: { self: /v1/runs/run_001, app: "https://app.retriever.run/app/workspaces/ws_001/conversations/conv_001" }

    RunOutput:
      oneOf:
        - type: object
          required: [type, value]
          properties: { type: { const: json }, value: {} }
        - type: object
          required: [type, tables]
          properties:
            type: { const: tables }
            tables:
              type: array
              items:
                type: object
                properties:
                  key: { type: string }
                  source_table_id: { type: string }
                  columns: { type: array, items: { type: object } }
                  row_count: { type: integer }
                  links: { type: object }

    Column:
      type: object
      properties:
        key: { type: string }
        name: { type: string }
        kind: { type: string, description: "e.g. `field`, computed column, qualification." }
        qualification: { type: object, description: "Criterion definition, if qualification column." }
        hidden: { type: boolean, description: "Only with `include_hidden=true`: the column is hidden in the app." }

    RowEntityType:
      type: string
      enum: [company, person, job, post, local_business, creator, other]
      description: "What one row of a table is. It decides what the app offers on the rows (All leads, sending to a CRM)."
    Table:
      type: object
      properties:
        id: { type: string }
        workspace_id: { type: string }
        name: { type: string }
        row_entity_type: { $ref: "#/components/schemas/RowEntityType" }
        columns: { type: array, items: { $ref: "#/components/schemas/Column" } }
        row_count: { type: integer }
        fit_counts:
          type: object
          description: "Row count per fit status. `unknown` covers rows not yet or not qualifiable."
          properties:
            qualified: { type: integer }
            disqualified: { type: integer }
            unknown: { type: integer }
        links:
          type: object
          properties:
            self: { type: string }
            rows: { type: string }
            app: { type: string, description: "Opens the table in the Retriever app (session required): its workspace, on this table. The app opens the workspace's latest conversation, or starts one." }

    Row:
      type: object
      properties:
        id: { type: string }
        values: { type: object, additionalProperties: true, description: "Business values by column key." }
        cells:
          type: object
          additionalProperties:
            type: object
            properties:
              status: { type: string, enum: [empty, running, done, failed, no_result] }
              qualification: { type: object, properties: { result: { type: string, enum: [match, no_match, unsure] }, reason: { type: string } } }
              citations: { type: array, items: { type: object } }
              stale_because: {}
              skipped: {}
              error: { type: string, description: "Only on a failed cell: why it failed. Its entry in `values` is null." }
        fit: { type: object, properties: { status: { type: string, enum: [qualified, disqualified, unknown] } } }

    RowPage:
      type: object
      required: [items, next_cursor]
      properties:
        items: { type: array, items: { $ref: "#/components/schemas/Row" } }
        next_cursor: { type: [string, "null"], description: "`null` at end of list." }

    Workspace:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        links:
          type: object
          properties:
            tables: { type: string }
            app: { type: string, description: "Opens the workspace in the Retriever app (session required): its latest conversation, or a new one when it has none." }

    CreateTableRequest:
      type: object
      additionalProperties: false
      required: [name, columns]
      properties:
        name: { type: string, minLength: 1 }
        columns:
          type: array
          minItems: 1
          maxItems: 200
          items:
            type: object
            additionalProperties: false
            required: [key, name]
            properties:
              key: { type: string, minLength: 1, description: "Unique; no surrounding spaces." }
              name: { type: string, minLength: 1 }
        rows:
          type: array
          default: []
          maxItems: 10000
          items: { type: object, additionalProperties: true, description: "Keys = column keys. Any JSON values." }
        row_entity_type:
          $ref: "#/components/schemas/RowEntityType"
          description: "What one row is. Omitted: detected from the column names and the first rows."

    InvalidExclusionValue:
      type: object
      required: [value, reason]
      properties:
        value: { type: string }
        reason: { type: string, enum: [company_domain_required, linkedin_url_required] }

    ExclusionValues:
      oneOf:
        - type: object
          additionalProperties: false
          required: [domains]
          properties: { domains: { type: array, minItems: 1, maxItems: 1000, items: { type: string, minLength: 1 } } }
        - type: object
          additionalProperties: false
          required: [linkedin_urls]
          properties: { linkedin_urls: { type: array, minItems: 1, maxItems: 1000, items: { type: string, minLength: 1, description: "URL `linkedin.com/in/…`. A handle alone is invalid." } } }

    ScheduledRunCadence:
      oneOf:
        - type: object
          required: [frequency, time]
          additionalProperties: false
          properties:
            frequency: { type: string, enum: [daily] }
            time: { type: string, description: "HH:mm in `timezone`." }
        - type: object
          required: [frequency, weekday, time]
          additionalProperties: false
          properties:
            frequency: { type: string, enum: [weekly] }
            weekday: { type: integer, minimum: 1, maximum: 7, description: "1 is Monday, 7 is Sunday." }
            time: { type: string, description: "HH:mm in `timezone`." }
        - type: object
          required: [frequency, every_days, time]
          additionalProperties: false
          properties:
            frequency: { type: string, enum: [interval] }
            every_days: { type: integer, minimum: 1, maximum: 30 }
            time: { type: string, description: "HH:mm in `timezone`." }
    CreateScheduledRunRequest:
      type: object
      required: [workspace_id, title, prompt, cadence, timezone]
      additionalProperties: false
      properties:
        workspace_id: { type: string }
        title: { type: string }
        prompt: { type: string, description: "The full mission each execution receives. Nobody answers during an execution." }
        cadence: { $ref: "#/components/schemas/ScheduledRunCadence" }
        timezone: { type: string, description: "IANA time zone, for example `Europe/Paris`." }
    UpdateScheduledRunRequest:
      type: object
      minProperties: 1
      additionalProperties: false
      properties:
        title: { type: string }
        prompt: { type: string }
        cadence: { $ref: "#/components/schemas/ScheduledRunCadence" }
        timezone: { type: string }
    PlayRun:
      type: object
      required: [id, play_id, schedule_id, scheduled_for, trigger, status, created_at]
      properties:
        id: { type: string }
        play_id: { type: string }
        schedule_id: { type: string, description: "The play's scheduled run: its executions list this run." }
        scheduled_for: { type: string, format: date-time }
        trigger: { type: string, enum: [schedule, manual] }
        status: { type: string, enum: [queued, running, succeeded, failed, cancelled] }
        created_at: { type: string, format: date-time }
    ScheduledRunExecution:
      type: object
      required: [id, schedule_id, scheduled_for, trigger, status, error, started_at, finished_at, created_at]
      properties:
        id: { type: string }
        schedule_id: { type: string }
        scheduled_for: { type: string, format: date-time }
        trigger: { type: string, enum: [schedule, manual] }
        status: { type: string, enum: [queued, running, succeeded, failed, cancelled], description: "Over at `succeeded`, `failed` or `cancelled`." }
        error: { type: [string, "null"], description: "A stable `scheduled_run_*` code when the execution failed or was cancelled." }
        started_at: { type: [string, "null"], format: date-time }
        finished_at: { type: [string, "null"], format: date-time }
        created_at: { type: string, format: date-time }
    ScheduledRun:
      type: object
      required: [id, workspace_id, title, summary, prompt, cadence, timezone, status, next_run_at, created_at, updated_at, links]
      properties:
        id: { type: string }
        workspace_id: { type: string }
        title: { type: string }
        summary: { type: [string, "null"], description: "Short description written when the app's agent created it." }
        prompt: { type: string }
        cadence: { $ref: "#/components/schemas/ScheduledRunCadence" }
        timezone: { type: string }
        status: { type: string, enum: [draft, active, paused, archived], description: "`archived` means deleted." }
        next_run_at: { type: [string, "null"], format: date-time, description: "Set only while `active`." }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        links:
          type: object
          required: [self, runs, tables, app]
          properties:
            self: { type: string }
            runs: { type: string }
            tables: { type: string, description: "The workspace's tables, where executions add rows." }
            app: { type: string, description: "Opens the workspace in Retriever." }
    ScheduledRunResult:
      type: object
      description: "A table the scheduled run delivers. Each table is counted on its own: never add up two tables."
      required: [table_id, table_name, row_entity_type, has_criteria, rows, qualified, links]
      properties:
        table_id: { type: string }
        table_name: { type: string }
        row_entity_type: { $ref: "#/components/schemas/RowEntityType" }
        has_criteria: { type: boolean, description: "The table has qualification criteria: report `qualified`, otherwise `rows`." }
        rows: { type: integer }
        qualified: { type: [integer, "null"], description: "Rows that meet the criteria. `null` when the table has no criteria." }
        links:
          type: object
          required: [rows]
          properties:
            rows: { type: string }
    ScheduledRunWithLatest:
      allOf:
        - $ref: "#/components/schemas/ScheduledRun"
        - type: object
          required: [results, latest_run]
          properties:
            results:
              type: array
              description: "Empty until an execution declares the tables it delivers (a play's table counts at once)."
              items: { $ref: "#/components/schemas/ScheduledRunResult" }
            latest_run:
              description: "The most recent execution, or `null`."
              anyOf:
                - $ref: "#/components/schemas/ScheduledRunExecution"
                - type: "null"
    PlaySummary:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        status: { type: string, enum: [draft, active, paused, archived] }
        origin: { type: string, enum: [onboarding, app] }
        launched: { type: boolean }
        version: { type: integer }
        created_at: { type: string, format: date-time }
        updated_at: { type: string, format: date-time }
        links: { type: object, properties: { self: { type: string }, leads: { type: string }, app: { type: string } } }
    Play:
      allOf:
        - $ref: "#/components/schemas/PlaySummary"
        - type: object
          properties:
            workspace_id: { type: [string, "null"] }
            schedule_id: { type: [string, "null"], description: "Its scheduled run once launched: `GET /v1/scheduled-runs/{id}/runs` lists the runs." }
            config: { type: object, description: "The blocks: signal, segment, whoToTarget, why, context, sequence, delivery. Same shape as `PlayDraft`." }
            limits: { type: object, properties: { targetQualifiedLeadsPerRun: { type: integer }, maxCreditsPerRun: { type: integer } } }
            leads: { type: object, properties: { to_review: { type: integer }, accepted: { type: integer }, rejected: { type: integer }, in_sequence: { type: integer } } }
            left_aside: { type: integer, description: "Qualified people of its table it cannot reach as it is set." }
            missing_accounts: { type: array, items: { type: string, enum: [email, linkedin] }, description: "Channels no connected account can send from: nothing leaves on them." }
    PlayDraft:
      type: object
      required: [name, signal, segment, whoToTarget]
      additionalProperties: false
      description: "The plays contract (`playDraftSchema` in app-core). Each field left out takes its default: review before sending, a run every day at 07:00, 10 leads per run, the channel's usual steps."
      properties:
        name: { type: string, maxLength: 120 }
        signal: { type: string, maxLength: 600, description: "The moment that makes an account worth contacting now." }
        segment: { type: string, maxLength: 600, description: "The accounts the play keeps." }
        whoToTarget: { type: string, maxLength: 300, description: "The person to reach at each kept account." }
        why: { type: string, maxLength: 400 }
        context: { type: array, maxItems: 8, items: { type: string, maxLength: 120 } }
        sequence:
          type: object
          required: [channel]
          properties:
            channel: { type: string, enum: [linkedin, email, both] }
            steps:
              type: array
              minItems: 1
              maxItems: 8
              items:
                type: object
                required: [kind, delayDays, label]
                properties:
                  kind: { type: string, enum: [email, linkedin_invite, linkedin_message] }
                  delayDays: { type: integer, minimum: 0, maximum: 60 }
                  label: { type: string, maxLength: 200 }
                  instructions: { type: string, maxLength: 1500 }
        delivery:
          type: object
          properties:
            mode: { type: string, enum: [review, auto] }
            cadence: { type: object, properties: { everyDays: { type: integer, minimum: 1, maximum: 30 }, time: { type: string, example: "07:00" } } }
            notify: { type: object, properties: { email: { type: boolean }, slack: { type: boolean }, crm: { type: boolean } } }
            noEmail: { type: string, enum: [linkedin, skip] }
        limits:
          type: object
          properties:
            targetQualifiedLeadsPerRun: { type: integer, minimum: 1, maximum: 100 }
            maxCreditsPerRun: { type: integer, minimum: 1, maximum: 1000 }
    PlayEdit:
      type: object
      additionalProperties: false
      description: "At least one of `name`, `changes`, `limits`. `changes` takes the blocks of `PlayDraft` (signal, segment, whoToTarget, why, context, sequence, delivery), at least one."
      properties:
        name: { type: string, maxLength: 120 }
        changes: { type: object }
        limits: { type: object, properties: { targetQualifiedLeadsPerRun: { type: integer }, maxCreditsPerRun: { type: integer } } }
    PlayLead:
      type: object
      properties:
        id: { type: string }
        review_state: { type: string, enum: [review, accepted, rejected] }
        person: { type: object, properties: { name: { type: string }, title: { type: string }, company: { type: string }, companyDomain: { type: string }, linkedinUrl: { type: string }, location: { type: string }, email: { type: string } } }
        signal: { type: [object, "null"], properties: { summary: { type: string }, source_url: { type: [string, "null"] } } }
        fit: { type: [string, "null"] }
        in_sequence: { type: boolean }
        first_message: { type: [object, "null"], properties: { subject: { type: [string, "null"] }, text: { type: string }, edited_by_user: { type: boolean } } }
        created_at: { type: string, format: date-time }
    PlayLeadPage:
      type: object
      properties:
        items: { type: array, items: { $ref: "#/components/schemas/PlayLead" } }
        total: { type: integer }
        offset: { type: integer }
        next_offset: { type: [integer, "null"] }
    GoRunRequest:
      type: object
      additionalProperties: false
      required: [query]
      properties:
        query: { type: string, minLength: 1 }
        output_schema: { type: object, description: "JSON Schema of the expected value." }
        instructions: { type: string }
        max_steps: { type: integer, minimum: 1, maximum: 100, default: 30 }
        model: { type: string, enum: [fast, smart], default: fast, deprecated: true, description: "Deprecated: every run uses the same model. `smart` is accepted and runs as `fast`." }
        stream: { type: boolean, default: false }

    GoResult:
      type: object
      properties:
        ok: { type: boolean }
        status: { type: string }
        value: { description: "Value conforming to `output_schema`." }
        usage:
          type: object
          properties:
            credits: { type: object, properties: { total: { type: number }, breakdown: { type: object } } }
            tokens: { type: object }
            model_calls: { type: integer }
            model: { type: string }
            duration_ms: { type: integer }

    GoJob:
      type: object
      properties:
        ok: { type: boolean }
        run_id: { type: string }
        status: { type: string, enum: [queued, running, completed, failed, cancelled] }
        value: {}
        usage: { type: object }
        error: { type: object, properties: { code: { type: string }, message: { type: string }, details: {} } }
        created_at: { type: string, format: date-time }
        started_at: { type: string, format: date-time }
        completed_at: { type: string, format: date-time }

    ServiceJob:
      allOf:
        - { $ref: "#/components/schemas/ServiceJobLine" }
        - type: object
          properties:
            ok: { type: boolean }
            poll_url: { type: string }
    ServiceJobLine:
      type: object
      properties:
        job_id: { type: string }
        service: { type: string }
        status: { type: string, enum: [queued, running, completed, failed, cancelled] }
        attempt: { type: integer, description: "Number of times the provider call started (the current claim included). Becomes 2 if a restart resumed a started job. A restart before the call started does not count." }
        reused: { type: boolean, description: "`true` when the answer came from one your organization already paid for (a recent answer, or a job another list started): nothing more was charged for this answer, and `credits.charged` keeps only what earlier attempts of its job paid (`0` on a batch line that points to a job it did not create). On a batch line, also `true` for a line that points to a job another line or list created." }
        credits:
          type: object
          properties:
            charged: { type: [number, "null"], description: "Credits this request paid so far, over every attempt. `0` on a batch line that points to a job it did not create. A job answered from a recent answer keeps what its earlier attempts paid. A failed line shows here what it was charged, if anything. A cancelled line can be billed too: an earlier attempt that ran before a restart, the Deep agent's miss price when it had finished its search, or a call whose answer landed as the cancel arrived. This field shows it. It can still grow after the job ends when a charge is recorded late, most often for a call cut by a timeout whose answer landed just after the cut. Late charges usually land within seconds, but this is not guaranteed: read it again a few minutes after the end. `GET /v1/services/jobs/{id}` shows the whole job's charge, even for a job you reached through reuse. `null` when the job's first call ran on a server from before this field; a job created before it but first run after shows a number. While this field was released, a job first claimed by a new server and then retried by an older one can show less than it cost." }
        result: { type: object, description: "Present only if `completed`." }
        error:
          type: object
          description: "Present only if `failed`. Never a negative answer. The failed attempt costs nothing, except the Deep agent's miss price when a contact lookup's Deep agent finished its search. A call cut by a timeout can still be billed if the provider's answer lands just after the cut. A line that ends `worker_lost` can also be billed: its call may have run, and been paid, before the worker was lost. `credits.charged` gives what the line really cost, earlier attempts included."
          properties:
            code: { type: string, description: "Retryable: `timeout`, `capacity`, `interrupted`, `provider_error`, `provider_unavailable`, `capability_error`, `service_error`, `service_execution_failed`, `worker_lost`, `usage_limit` (after a top-up). Not retryable: `provider_rejected`, `validation_error` (a value the service cannot search), `not_found` (what the input names does not exist), `invalid_output` (the service answered outside its own contract) and any other code." }
            message: { type: string }
            retryable: { type: boolean, description: "`true`: the same input can get an answer later (after a top-up for `usage_limit`), send it again in a new batch. `false`: it gets the same refusal." }
        created_at: { type: string, format: date-time }
        started_at: { type: string, format: date-time, nullable: true, description: "When the provider call first started. Null while the job waits." }
        completed_at: { type: string, format: date-time, nullable: true }
    ServiceJobBatch:
      type: object
      properties:
        ok: { type: boolean }
        batch_id: { type: string, example: svcbatch_9f2c4b1e8a7d6c5f }
        service: { type: string }
        size: { type: integer }
        status: { type: string, enum: [queued, running, completed], description: "`completed` once every job has ended, whatever each one's outcome." }
        counts:
          type: object
          properties:
            queued: { type: integer }
            running: { type: integer }
            completed: { type: integer }
            failed: { type: integer }
            cancelled: { type: integer }
        credits:
          type: object
          properties:
            charged: { type: [number, "null"], description: "The sum of the lines' `credits.charged` so far. A job shared by two lines counts once, on the line that created it. `null` when one line is `null`. It can still grow after every line has ended, when a charge is recorded late (most often a call cut by a timeout whose answer landed just after the cut)." }
        jobs:
          type: array
          description: "One entry per input, in the order sent."
          items:
            allOf:
              - { $ref: "#/components/schemas/ServiceJobLine" }
              - type: object
                properties:
                  input_index: { type: integer }
        poll_url: { type: string }

  responses:
    BadRequest:
      description: "`invalid_request`: unreadable JSON, unknown field or query parameter, wrong type, `limit` out of range, empty `Idempotency-Key`, invalid `output` contract. `message` names each invalid field; `details` lists them as `{ path, message }`. On `POST /v1/runs`, `workspace_mismatch`: the conversation does not belong to the provided workspace."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: invalid_request, message: "prompt: prompt must not be blank", details: [{ path: prompt, message: prompt must not be blank }] } }
    ValidationError:
      description: "`validation_error` (`details` = field list when the schema refused the input; when `details` is absent, `message` says what to fix) or `invalid_request` (unreadable JSON)."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example:
            error:
              code: validation_error
              message: query is required
              details: [{ path: [query], message: query is required }]
    Unauthorized:
      description: "`not_authenticated`: missing header, malformed (expected `Bearer <key>`), revoked or unknown key."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: not_authenticated, message: A valid API key is required. } }
    PayloadTooLarge:
      description: "`body_too_large`: the request body is over 10 MiB (10,485,760 bytes). Do not retry the same body: send less data per request."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: body_too_large, message: "The request body exceeds the 10 MiB limit (10485760 bytes)." } }
    ImportPayloadTooLarge:
      description: "`body_too_large`: the import body is over 25 MiB (26,214,400 bytes). Do not retry the same body: split the list into several tables."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: body_too_large, message: "The request body exceeds the 25 MiB limit (26214400 bytes)." } }
    ExclusionKindNotFound:
      description: "`not_found`: `kind` must be `companies` or `people`."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: not_found, message: Unknown exclusion list. } }
    UnsupportedMediaType:
      description: "`invalid_request`: add `Content-Type: application/json`."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: invalid_request, message: Content-Type must be application/json. } }
    KeyCheckBusy:
      description: "`key_check_busy`: the key could not be checked right now (often a key just created, during a flood of unknown keys). Retry after `Retry-After` seconds."
      headers:
        Retry-After: { schema: { type: integer } }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: key_check_busy, message: "This key cannot be checked right now. Retry in 7 s." } }
    TooManyRequests:
      description: "`rate_limited`: wait `Retry-After` seconds, then retry."
      headers:
        Retry-After: { schema: { type: integer } }
        RateLimit-Limit: { $ref: "#/components/headers/RateLimit-Limit" }
        RateLimit-Remaining: { $ref: "#/components/headers/RateLimit-Remaining" }
        RateLimit-Reset: { $ref: "#/components/headers/RateLimit-Reset" }
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: rate_limited, message: "Rate limit exceeded. Retry in 12 s." } }
    InsufficientCredits:
      description: "`insufficient_credits` or `usage_limit`: top up credits (`GET /credits` for balance)."
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    Upstream:
      description: "`provider_error` or `upstream_error` (and `agent_error` on Go, `capability_error` and `interrupted` on Services): a provider failed or the call was cut off. Retry with backoff. `invalid_output` (Services): the service answered outside its own contract, a fault on our side; do not resend, the same request fails the same way. Other unexpected categories return `500`. Changed on 2026-10-02: a refused input (an invalid cursor, an unknown country or location, a malformed post URL, an invalid `postedAfter`) is now `400 validation_error`, and a post or company that does not exist is `404 not_found`; neither is retryable."
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    ScheduledRunNotFound:
      description: "`scheduled_run_not_found`: unknown id or another organization's scheduled run. `workspace_not_found`: unknown `workspace_id` on create."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: scheduled_run_not_found, message: Scheduled run not found. } }
    ScheduledRunConflict:
      description: "`scheduled_run_archived`: the scheduled run was deleted. `scheduled_run_belongs_to_play`: the scheduled run belongs to a play; change or delete it on the play, in the app. `play_paused`, `play_archived`, `play_not_launched`, `play_run_busy`: the play this scheduled run belongs to cannot run now; `message` says why."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: scheduled_run_archived, message: This scheduled run was deleted. } }
    PlayNotFound:
      description: "`play_not_found`: unknown id or another organization's play. `play_lead_not_found`. `play_update_not_found`: unknown proposal."
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    PlayConflict:
      description: "`play_archived`: restore it first. `play_not_launched`: launch it first. `play_lead_decided`: the lead was already kept or rejected. `play_update_stale`, `play_update_decided`, `play_update_not_applicable`: about a proposal. `play_message_edited_by_hand`: the message was edited by hand in its sequence. `play_message_not_synced`: the sequence did not take the message (its step already left). `play_run_busy`: a run of the play is waiting or going. `play_paused`: resume it first. `scheduled_run_archived`: the play was archived meanwhile. `company_icp_brief_not_found`: a new channel gets its steps written from the Brain, and the organization has none. `play_version_moved`: another change was saved on the play at the same moment; read it again and retry."
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    PlayLeadRefused:
      description: "`play_lead_not_enrolled`: the sequence turned the lead down, `message` says why. `play_needs_account`: connect an account in the app to resume."
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    RunNotFound:
      description: "`run_not_found`: unknown id, or another organization's run. A Go job (`/v1/go/runs`) is also not found for another user of your organization."
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
          example: { error: { code: run_not_found, message: Run not found. } }
    TableNotFound:
      description: "`table_not_found`: unknown id/key, archived table, or other organization."
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
    WorkspaceNotFound:
      description: "`workspace_not_found`."
      content: { application/json: { schema: { $ref: "#/components/schemas/Error" } } }
