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

# Change a pitch

> Act on a pitch as the app's pitch controls do. `action` is one of: `reactivate` brings back a paused or expired pitch (with days left it resumes its remaining time; with none it uses the pitch's one 7-day extension, and a pitch with no days left whose extension is used cannot be reactivated, so convert it); `extend` adds 7 days to an active pitch, using its one extension, only in its last 48 hours; `refresh` runs a new visibility report for an active pitch, using one of its 5 manual refreshes (while a report is already running for it, its first report or one an earlier refresh or an unfiltered Run report started, the refresh joins that report and uses none); `convert` turns the pitch into a client project with every feature unlocked, its prompts moving onto the plan's prompt allowance, and cannot be undone; `decline` pauses an active pitch, keeping its data, while its expiry keeps running; `hide` and `unhide` take a paused or expired pitch out of the project picker, or put it back. The API has no confirm step: the request is the decision, so every action acts at once, including a `reactivate` that uses the extension, an `extend`, a `refresh` and a `convert`. `dryRun: true` is the way to look first: it runs every check the action runs and answers the preview with 200, changing nothing. The roles follow the app's pitch routes: extending and refreshing need write access to the pitch; converting, declining, hiding and unhiding need manage access to it; reactivating needs the right to create projects in its workspace (403 `forbidden` otherwise). Requires a connection minted with the `project:manage` capability (not the bare `write` scope); a project-bound key reaches only its own pitch. Supports `Idempotency-Key` replay, scoped to the pitch: a replayed `refresh` uses one refresh, a reused key with a different body returns 409 `idempotency_conflict` (a `dryRun` answer is stored too, so acting after a preview takes a new key), and the same key on another pitch is a new request. Refusals: 403 `plan_upgrade_required` (with `requiresUpgrade: true`) when the workspace's plan has no pitches, 403 `pitch_allowance_used` when a reactivated pitch's prompts no longer fit the pitch allowance, 403 `quota_exceeded` (with `quotaConflict`) for a convert the plan's prompt allowance cannot take, a `dryRun` included, 409 `cannot_reactivate`, `already_extended`, `extend_not_available_yet` (with `opensAt`), `no_refreshes_left`, `pitch_not_active`, `pitch_still_active`, `already_converted` and `not_a_pitch`, 409 `duplicate_domain` for a reactivation while another project or pitch holds the domain (it names no holder), and 503 `refresh_failed` when the report could not start, in which case no refresh is used. 403 `security_policy_denied` when the pitch's workspace has API access disabled or its IP allowlist refuses the request (a caller who is no member of that workspace gets 404 `not_found` instead).



## OpenAPI

````yaml /api-reference/openapi.json post /api/mcp/pitches/{pitchId}/lifecycle
openapi: 3.1.0
info:
  title: Searchable REST API
  version: 1.0.0
  summary: >-
    Query AI visibility, sources, sentiment, traffic, and content data, and
    trigger audits/reports/sitemap syncs.
  description: >-
    The Searchable REST API (`/api/mcp/*` and
    `/api/v1/projects/{projectId}/audits`) exposes the same data and actions
    available in the Searchable dashboard and MCP server, over plain HTTP with a
    bearer API key. It is a **read-mostly** surface — 75 of its 91 operations
    are GET. The mutating ones are capability-gated (a bare `write` scope does
    not satisfy a capability such as `prompt:draft`), and those listed under
    [Idempotency](/api-reference/introduction#idempotency) support
    `Idempotency-Key` replay.


    See **[Getting started](/api-reference/introduction)** for auth, rate
    limits, idempotency, and pagination conventions, and the **[error
    reference](/api/errors)** for every error `code` this API returns.


    `/api/mcp/*` is a frozen v1 contract — see the [changelog](/changelog) for
    the deprecation policy.
  contact:
    name: Searchable Support
    email: support@searchable.com
    url: https://docs.searchable.com/api-reference/introduction
servers:
  - url: https://app.searchable.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: List and inspect the projects an API key can reach.
  - name: Visibility
    description: >-
      AI visibility score, platform/topic/prompt/location breakdowns, and
      historical trend.
  - name: Share of Voice
    description: Brand vs. competitor mention-share ranking and its daily trend.
  - name: Competitors
    description: >-
      The project's tracked competitor roster — share of voice, sentiment, and
      mention/citation counts.
  - name: Sources
    description: >-
      Domains and URLs cited by AI answers — citation share, trend, and cached
      page content.
  - name: Sentiment
    description: Brand sentiment summary, trend, and head-to-head competitor comparison.
  - name: Query Fanout
    description: The sub-queries AI models generate when answering tracked prompts.
  - name: Traffic
    description: >-
      First-party AI-crawler and AI-referral traffic sourced from the
      tracker/CDN pipeline.
  - name: Shopping
    description: AI shopping/product-carousel visibility.
  - name: Ads
    description: >-
      Sponsored ads surfaced in AI answers — advertisers, individual creatives,
      ad-heavy prompts, and the frequency trend.
  - name: Answers
    description: Raw, per-response AI-answer data for a single prompt.
  - name: GSC
    description: Live Google Search Console performance data for the project's linked site.
  - name: GA4
    description: Live Google Analytics 4 traffic and AI-referral data.
  - name: Audits & Issues
    description: >-
      Page audits (technical + AEO), site issues, monitored pages, and sitemap
      sync.
  - name: Reports
    description: Generate and list shareable visibility/sentiment reports.
  - name: Articles
    description: Content pieces (articles) created in Searchable.
  - name: Opportunities
    description: >-
      Actionable, prioritized suggestions Searchable has surfaced for the
      project.
  - name: Brand
    description: Brand profile (knowledge base + AI-observed facts) and domain authority.
  - name: Prompts
    description: >-
      The project's prompt catalog (tracked, untracked, and AI-suggested
      prompts).
paths:
  /api/mcp/pitches/{pitchId}/lifecycle:
    post:
      tags:
        - Projects
      summary: Change a pitch
      description: >-
        Act on a pitch as the app's pitch controls do. `action` is one of:
        `reactivate` brings back a paused or expired pitch (with days left it
        resumes its remaining time; with none it uses the pitch's one 7-day
        extension, and a pitch with no days left whose extension is used cannot
        be reactivated, so convert it); `extend` adds 7 days to an active pitch,
        using its one extension, only in its last 48 hours; `refresh` runs a new
        visibility report for an active pitch, using one of its 5 manual
        refreshes (while a report is already running for it, its first report or
        one an earlier refresh or an unfiltered Run report started, the refresh
        joins that report and uses none); `convert` turns the pitch into a
        client project with every feature unlocked, its prompts moving onto the
        plan's prompt allowance, and cannot be undone; `decline` pauses an
        active pitch, keeping its data, while its expiry keeps running; `hide`
        and `unhide` take a paused or expired pitch out of the project picker,
        or put it back. The API has no confirm step: the request is the
        decision, so every action acts at once, including a `reactivate` that
        uses the extension, an `extend`, a `refresh` and a `convert`. `dryRun:
        true` is the way to look first: it runs every check the action runs and
        answers the preview with 200, changing nothing. The roles follow the
        app's pitch routes: extending and refreshing need write access to the
        pitch; converting, declining, hiding and unhiding need manage access to
        it; reactivating needs the right to create projects in its workspace
        (403 `forbidden` otherwise). Requires a connection minted with the
        `project:manage` capability (not the bare `write` scope); a
        project-bound key reaches only its own pitch. Supports `Idempotency-Key`
        replay, scoped to the pitch: a replayed `refresh` uses one refresh, a
        reused key with a different body returns 409 `idempotency_conflict` (a
        `dryRun` answer is stored too, so acting after a preview takes a new
        key), and the same key on another pitch is a new request. Refusals: 403
        `plan_upgrade_required` (with `requiresUpgrade: true`) when the
        workspace's plan has no pitches, 403 `pitch_allowance_used` when a
        reactivated pitch's prompts no longer fit the pitch allowance, 403
        `quota_exceeded` (with `quotaConflict`) for a convert the plan's prompt
        allowance cannot take, a `dryRun` included, 409 `cannot_reactivate`,
        `already_extended`, `extend_not_available_yet` (with `opensAt`),
        `no_refreshes_left`, `pitch_not_active`, `pitch_still_active`,
        `already_converted` and `not_a_pitch`, 409 `duplicate_domain` for a
        reactivation while another project or pitch holds the domain (it names
        no holder), and 503 `refresh_failed` when the report could not start, in
        which case no refresh is used. 403 `security_policy_denied` when the
        pitch's workspace has API access disabled or its IP allowlist refuses
        the request (a caller who is no member of that workspace gets 404
        `not_found` instead).
      operationId: changePitch
      parameters:
        - $ref: '#/components/parameters/pitchId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PitchLifecycleRequest'
      responses:
        '200':
          description: >-
            The action was carried out, or, with `dryRun: true`, the preview of
            it.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
            X-Idempotent-Replay:
              $ref: '#/components/headers/XIdempotentReplay'
            X-Idempotent-Skipped:
              $ref: '#/components/headers/XIdempotentSkipped'
          content:
            application/json:
              schema:
                description: >-
                  The pitch after the action, or, with `dryRun: true`, the
                  preview of it.
                oneOf:
                  - $ref: '#/components/schemas/PitchLifecycleResponse'
                  - $ref: '#/components/schemas/PitchPreviewResponse'
        '400':
          $ref: '#/components/responses/defaultError'
        '401':
          $ref: '#/components/responses/defaultError'
        '403':
          $ref: '#/components/responses/defaultError'
        '404':
          $ref: '#/components/responses/defaultError'
        '409':
          description: >-
            The pitch's state refuses the action (`cannot_reactivate`,
            `already_extended`, `extend_not_available_yet`, `no_refreshes_left`,
            `pitch_not_active`, `pitch_still_active`, `already_converted`,
            `not_a_pitch`), or `duplicate_domain`: another project or pitch
            holds the pitch's domain, so it can't be reactivated; no holder is
            named. `idempotency_conflict`: the `Idempotency-Key` was reused with
            a different body. `idempotency_in_flight`: a request with the same
            key is still executing; `Retry-After` (5 seconds) is present, so
            retry with the SAME key.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          $ref: '#/components/responses/rateLimited'
        '500':
          $ref: '#/components/responses/defaultError'
        '503':
          $ref: '#/components/responses/defaultError'
components:
  parameters:
    pitchId:
      name: pitchId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: >-
        The pitch's id, from `GET /api/mcp/pitches`. A pitch is a project, so
        its id works with every project endpoint too.
    idempotencyKey:
      name: Idempotency-Key
      in: header
      schema:
        type: string
      description: >-
        Optional client-generated key (e.g. a UUID). Retrying with the same key
        within 24h replays the original stored response (`X-Idempotent-Replay:
        true`) instead of repeating the side effect. See
        [Idempotency](/api-reference/introduction#idempotency).
  schemas:
    PitchLifecycleRequest:
      type: object
      properties:
        action:
          type: string
          enum:
            - reactivate
            - extend
            - refresh
            - convert
            - decline
            - hide
            - unhide
          description: >-
            What to do with the pitch: `reactivate`, `extend`, `refresh`,
            `convert`, `decline`, `hide` or `unhide`.
        dryRun:
          type: boolean
          description: >-
            Run every check the action runs and return the preview with 200,
            changing nothing. Without it, the action acts at once.
      required:
        - action
    PitchLifecycleResponse:
      type: object
      description: >-
        The action was carried out. `pitch` is the pitch afterwards, as `GET
        /api/mcp/pitches` lists it; a converted pitch is a
        `ConvertedPitchRecord`.
      properties:
        pitch:
          oneOf:
            - $ref: '#/components/schemas/PitchRecord'
            - $ref: '#/components/schemas/ConvertedPitchRecord'
        success:
          type: boolean
        message:
          type: string
          description: >-
            One sentence of what the action did, e.g. what a decline means for
            reactivating the pitch later.
        joinedExistingRun:
          type: boolean
          description: >-
            Present, and true, only on a `refresh` that joined a report already
            running for the pitch (its first report, or one an earlier refresh
            or an unfiltered Run report started): it started no new report and
            used none of the pitch's manual refreshes.
      required:
        - pitch
        - success
        - message
    PitchPreviewResponse:
      type: object
      description: >-
        A dry run: nothing was changed. `preview` holds the fields the action's
        preview has; each is present only where the action fills it in.
      properties:
        dryRun:
          type: boolean
          enum:
            - true
        preview:
          type: object
          properties:
            action:
              type: string
              enum:
                - reactivate
                - extend
                - refresh
                - convert
                - decline
                - hide
                - unhide
            needsConfirm:
              type: boolean
              description: >-
                Whether the action spends something or cannot be undone:
                `extend`, `refresh`, `convert`, and a `reactivate` that uses the
                extension. The API does not wait for a confirmation, so this is
                information for you, not a step.
            pitch:
              $ref: '#/components/schemas/PitchRecord'
              description: The pitch as it is now.
            reactivation:
              type: object
              description: '`reactivate` only: what bringing the pitch back would do.'
              properties:
                kind:
                  type: string
                  enum:
                    - resume
                    - use_extension
                  description: >-
                    `resume` keeps its remaining time; `use_extension` uses its
                    one 7-day extension.
                expiresAt:
                  type: string
                  format: date-time
                  description: 'With `resume`: when it expires.'
                newExpiresAt:
                  type: string
                  format: date-time
                  description: >-
                    With `use_extension`: when it would expire after the
                    extension.
              required:
                - kind
            newExpiresAt:
              type: string
              format: date-time
              description: '`extend` only: the expiry after the 7-day extension.'
            refreshesLeftAfter:
              type: integer
              description: '`refresh` only: the manual refreshes left afterwards.'
            wouldJoinFirstReport:
              type: boolean
              description: >-
                `refresh` only: whether the pitch's first report is still
                running, so the refresh would join it and use no refresh.
            wouldJoinRunningReport:
              type: boolean
              description: >-
                `refresh` only: whether a report an earlier refresh or an
                unfiltered Run report started is still running, so the refresh
                would join it and use no refresh.
            convert:
              type: object
              description: >-
                `convert` only: the pitch's tracked prompt-locations against the
                plan's prompt allowance. A convert the plan cannot take is
                refused with `quota_exceeded` instead.
              properties:
                pitchPromptCount:
                  type: number
                planCurrent:
                  type: number
                planLimit:
                  type:
                    - number
                    - 'null'
                  description: Null when the plan has no limit.
              required:
                - pitchPromptCount
                - planCurrent
                - planLimit
            afterDecline:
              type: object
              description: >-
                `decline` only: what reactivating the pitch later will mean, as
                its expiry keeps running.
              properties:
                expiresAt:
                  type:
                    - string
                    - 'null'
                  format: date-time
                later:
                  type: string
                  enum:
                    - resume_until_expiry
                    - uses_extension
                    - convert_only
              required:
                - expiresAt
                - later
            summary:
              type: string
              description: What the action would do, as one sentence.
          required:
            - action
            - needsConfirm
            - pitch
            - summary
      required:
        - dryRun
        - preview
    Problem:
      type: object
      description: >-
        RFC 9457 `application/problem+json` error body. `error` is retained
        verbatim as a legacy compat key equal to `message`. Some codes carry
        additional fields beyond the base shape (documented per-code in the
        [error reference](/api/errors)) — always additive, never replacing
        these.
      properties:
        type:
          type: string
          format: uri
          description: >-
            A URL identifying the error kind — the error reference page,
            anchored to `code`.
        title:
          type: string
          description: Human-readable summary of `code`.
        status:
          type: integer
          description: The HTTP status code (matches the response status).
        code:
          type: string
          description: >-
            Machine-readable, stable error code — safe to branch on. See the
            [error reference](/api/errors) for the full catalog.
          enum:
            - unauthorized
            - forbidden
            - missing_scope
            - plan_upgrade_required
            - security_policy_denied
            - not_found
            - invalid_argument
            - invalid_country
            - no_domain
            - no_workspace
            - no_pages
            - bulk_limit_exceeded
            - quota_exceeded
            - project_not_runnable
            - pitch_not_supported
            - duplicate_domain
            - conflict
            - pitch_allowance_used
            - already_extended
            - cannot_reactivate
            - pitch_not_active
            - pitch_still_active
            - no_refreshes_left
            - refresh_failed
            - already_converted
            - extend_not_available_yet
            - not_a_pitch
            - preview_stale
            - confirmation_mismatch
            - destination_not_permitted
            - cross_reseller_transfer_not_allowed
            - same_workspace
            - destination_owner_missing
            - project_state_unsupported
            - creator_domain_conflict
            - source_domain_conflict
            - access_removal_not_confirmed
            - storage_object_missing
            - quota_projects_exceeded
            - quota_prompts_exceeded
            - in_flight_agent_runs
            - lock_timeout
            - serialization_failure
            - not_active
            - role_not_permitted
            - staff_not_in_tenant
            - staff_not_eligible
            - rate_limited
            - idempotency_in_flight
            - idempotency_conflict
            - query_timeout
            - gsc_not_connected
            - gsc_site_not_linked
            - gsc_access_denied
            - ga4_not_connected
            - traffic_not_connected
            - invalid_scope
            - host_outside_domain
            - invalid_citation_type
            - missing_competitor
            - unknown_competitor
            - duplicate_scope
            - rule_limit
            - internal_error
        error:
          type: string
          description: Legacy compat key. Always equal to `message`.
        message:
          type: string
          description: Human-readable error message (identical to `error`).
        howToFix:
          type: string
          description: Present on actionable errors — a concrete next step.
        requestId:
          type: string
          format: uuid
          description: This request's id. Include it when contacting support.
        requiresUpgrade:
          type: boolean
          description: Present on `plan_upgrade_required` (403).
        retryable:
          type: boolean
          description: >-
            Present on `rate_limited`, `idempotency_in_flight`, and
            `query_timeout`.
        timeout:
          type: boolean
          description: Present on `query_timeout` (504).
        quotaExceeded:
          type: boolean
          description: Present on `quota_exceeded` (403).
        current:
          type: integer
          description: Present on `quota_exceeded` — current usage.
        limit:
          type: integer
          description: Present on `quota_exceeded` — the plan's limit.
        bulkLimitExceeded:
          type: boolean
          description: Present on `bulk_limit_exceeded` (400, `POST /audits`).
        requested:
          type: integer
          description: >-
            Present on `bulk_limit_exceeded` / `quota_exceeded` — the count
            requested.
        maxAllowed:
          type: integer
          description: Present on `bulk_limit_exceeded` — the plan's per-request cap.
        details:
          description: >-
            Present on some `invalid_argument` (400) responses — a Zod
            `.flatten()` validation breakdown.
          type: object
          properties:
            formErrors:
              type: array
              items:
                type: string
            fieldErrors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: string
        opensAt:
          type: string
          format: date-time
          description: Present on `extend_not_available_yet` (409) — when extending opens.
        existing:
          type: object
          description: >-
            Present on `duplicate_domain` (409) from `POST /api/mcp/pitches` —
            the project or pitch that already holds the domain: `projectId`,
            `name`, `domain`, `workspaceId`, `workspaceName`, `isPitch`,
            `pitchStatus`, `isActive` and `canReactivate`. Absent when the
            holder sits in a workspace the API may not reach.
          additionalProperties: true
        quotaConflict:
          type: object
          description: >-
            Present on `quota_exceeded` (403) when converting a pitch would take
            the workspace past its plan's prompt allowance: the tracked
            prompt-locations in use (`current`), those the pitch adds
            (`pitchPromptCount`), the plan's `limit`, and the `shortfall`.
          properties:
            current:
              type: number
              description: 'Can be fractional: a weekly prompt-location counts as 1/7.'
            pitchPromptCount:
              type: integer
            limit:
              type: integer
            shortfall:
              type: number
              description: Can be fractional, as `current` can.
          required:
            - current
            - pitchPromptCount
            - limit
            - shortfall
      required:
        - type
        - title
        - status
        - code
        - error
        - message
    PitchRecord:
      type: object
      description: >-
        One pitch as the Pitches tab shows it, worked out by the app's own
        rules. A converted pitch is a `ConvertedPitchRecord` instead.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        domain:
          type: string
        workspaceId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - active
            - declined
            - expired
          description: >-
            A declined pitch is paused; an expired one ran out of days. Both can
            be reactivated while `canReactivate` is true.
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        daysLeft:
          type:
            - integer
            - 'null'
          description: >-
            Whole days left, rounded up and never below zero; null without an
            expiry.
        extended:
          type: boolean
          description: Whether the pitch's one 7-day extension is used.
        refreshes:
          type: object
          description: The pitch's manual refreshes.
          properties:
            limit:
              type: integer
            used:
              type: integer
            remaining:
              type: integer
          required:
            - limit
            - used
            - remaining
        hiddenFromPicker:
          type: boolean
          description: Whether the pitch is hidden from the project picker.
        trackedPromptCount:
          type: integer
          description: Its tracked prompt-locations, as the pitch allowance counts them.
        canReactivate:
          type: boolean
          description: >-
            Whether a closed pitch can be brought back right now, as the app
            offers Reactivate.
        canExtend:
          type: boolean
          description: >-
            Whether the pitch can be extended right now: active, not yet
            extended, and in its last 48 hours.
      required:
        - id
        - name
        - domain
        - workspaceId
        - status
        - createdAt
        - expiresAt
        - daysLeft
        - extended
        - refreshes
        - hiddenFromPicker
        - trackedPromptCount
        - canReactivate
        - canExtend
    ConvertedPitchRecord:
      type: object
      description: >-
        A pitch that was converted into a client. It is a regular project now,
        so it carries no refreshes, allowance or actions; every project endpoint
        takes its id.
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        domain:
          type: string
        workspaceId:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - converted
        convertedAt:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - name
        - domain
        - workspaceId
        - status
        - convertedAt
  headers:
    XRequestId:
      description: This request's id. Include it when contacting support.
      schema:
        type: string
        format: uuid
    RateLimit:
      description: >-
        IETF draft rate-limit header:
        `"default";r=<remaining>;t=<seconds-until-reset>`. Omitted on responses
        where the limiter did not run (e.g. a pre-auth validation error, or a
        degraded limiter failing open).
      schema:
        type: string
    RateLimitPolicy:
      description: >-
        IETF draft rate-limit policy: `"default";q=<quota>;w=<window-seconds>`.
        Currently `q=600;w=60`.
      schema:
        type: string
    XRateLimitLimit:
      description: Requests allowed per window (600/minute per key).
      schema:
        type: integer
    XRateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
    XRateLimitReset:
      description: Absolute Unix-epoch second the current window resets.
      schema:
        type: integer
    XIdempotentReplay:
      description: >-
        `true` when this response is a replay of a previously stored successful
        response for the same `Idempotency-Key`.
      schema:
        type: string
        enum:
          - 'true'
    XIdempotentSkipped:
      description: >-
        `body-too-large` when a successful response exceeded the 100KB
        idempotency-store cap and was not cached (the request still ran
        normally).
      schema:
        type: string
        enum:
          - body-too-large
    RetryAfter:
      description: >-
        Seconds to wait before retrying. Set on 429s issued by Searchable's own
        rate limiter and on `409 idempotency_in_flight`; may be absent when an
        upstream provider (e.g. Google) rate-limits.
      schema:
        type: integer
  responses:
    defaultError:
      description: >-
        Error response. `code` is the machine-readable reason — see the [error
        reference](/api/errors) for the full catalog and remediation per code.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    rateLimited:
      description: >-
        Rate limited. Usually the per-API-key REST limit (600 requests/minute);
        on Google-backed endpoints it can also relay an upstream Google rate
        limit. `Retry-After` (seconds) is present when the limit was applied by
        Searchable's own rate limiter; it may be absent when an upstream
        provider rate-limits.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        X-RateLimit-Limit:
          $ref: '#/components/headers/XRateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/XRateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/XRateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sea_xxxxx
      description: >-
        A Searchable API key, created under **Manage Account → Integrations →
        API Keys**. Send as `Authorization: Bearer sea_xxxxx`. Every key carries
        one or more scopes (`read`, `write`, `admin`) and may optionally be
        bound to a single project — see [Getting
        started](/api-reference/introduction#authentication).

````

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