> ## 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.

# Move a pitch into a client workspace

> Move the pitch into a client workspace, as the app's convert dialog does for a reseller: into an existing client workspace, or into a new one created for it. The pitch becomes a client project with every feature unlocked, its prompts move onto that workspace's plan allowance, and it cannot be undone. The user's part is the app's: they type the pitch's domain (`confirmDomain`) and acknowledge each warning the preview listed (`acknowledgedWarnings`: exactly those codes, `[]` when it listed none). Send what the user gave, and never fill either in on their behalf. An existing workspace also needs the `previewSignature` of the preview of that same destination. The API has no confirm step: the request is the decision, so it moves the pitch at once. Look first with `POST /api/mcp/pitches/{pitchId}/client-move/preview`. Only a reseller's owner, or a staff-marked admin or super admin operator, can use it, and only while the reseller is in the rollout; everyone else, a pitch that is not an open pitch of the caller's reseller, and a pitch the caller cannot reach all answer 404 `not_found`, so the response never says whether the caller is a reseller. Requires a connection minted with the `project:manage` capability (not the bare `write` scope). A project-bound key is refused with 403 `forbidden`: moving a pitch into a client workspace reaches beyond one project. An existing destination's workspace API access policy is honoured as every write into a workspace honours it: a destination with API access disabled, or whose IP allowlist refuses the request, answers 403 `security_policy_denied` and nothing moves, and is left out of the options. A new client workspace has no policy yet. 403 `security_policy_denied` when the pitch's own 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). Supports `Idempotency-Key` replay, scoped to the pitch: a replayed move moves once, a reused key with a different body returns 409 `idempotency_conflict`, and the same key on another pitch is a new request. Refusals: 409 `preview_stale` when the pitch or the destination changed since the preview (or no signature was sent for an existing workspace), 409 `confirmation_mismatch` when `confirmDomain` is not the pitch's domain, 409 `destination_not_permitted` for a workspace the pitch cannot move into; other move refusals carry the move engine's own code, in lower case.



## OpenAPI

````yaml /api-reference/openapi.json post /api/mcp/pitches/{pitchId}/client-move
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}/client-move:
    post:
      tags:
        - Projects
      summary: Move a pitch into a client workspace
      description: >-
        Move the pitch into a client workspace, as the app's convert dialog does
        for a reseller: into an existing client workspace, or into a new one
        created for it. The pitch becomes a client project with every feature
        unlocked, its prompts move onto that workspace's plan allowance, and it
        cannot be undone. The user's part is the app's: they type the pitch's
        domain (`confirmDomain`) and acknowledge each warning the preview listed
        (`acknowledgedWarnings`: exactly those codes, `[]` when it listed none).
        Send what the user gave, and never fill either in on their behalf. An
        existing workspace also needs the `previewSignature` of the preview of
        that same destination. The API has no confirm step: the request is the
        decision, so it moves the pitch at once. Look first with `POST
        /api/mcp/pitches/{pitchId}/client-move/preview`. Only a reseller's
        owner, or a staff-marked admin or super admin operator, can use it, and
        only while the reseller is in the rollout; everyone else, a pitch that
        is not an open pitch of the caller's reseller, and a pitch the caller
        cannot reach all answer 404 `not_found`, so the response never says
        whether the caller is a reseller. Requires a connection minted with the
        `project:manage` capability (not the bare `write` scope). A
        project-bound key is refused with 403 `forbidden`: moving a pitch into a
        client workspace reaches beyond one project. An existing destination's
        workspace API access policy is honoured as every write into a workspace
        honours it: a destination with API access disabled, or whose IP
        allowlist refuses the request, answers 403 `security_policy_denied` and
        nothing moves, and is left out of the options. A new client workspace
        has no policy yet. 403 `security_policy_denied` when the pitch's own
        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). Supports `Idempotency-Key` replay, scoped to the
        pitch: a replayed move moves once, a reused key with a different body
        returns 409 `idempotency_conflict`, and the same key on another pitch is
        a new request. Refusals: 409 `preview_stale` when the pitch or the
        destination changed since the preview (or no signature was sent for an
        existing workspace), 409 `confirmation_mismatch` when `confirmDomain` is
        not the pitch's domain, 409 `destination_not_permitted` for a workspace
        the pitch cannot move into; other move refusals carry the move engine's
        own code, in lower case.
      operationId: movePitchToClient
      parameters:
        - $ref: '#/components/parameters/pitchId'
        - $ref: '#/components/parameters/idempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PitchClientMoveRequest'
      responses:
        '200':
          description: The pitch is a client project in the destination workspace now.
          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:
                $ref: '#/components/schemas/PitchClientMoveResponse'
        '400':
          $ref: '#/components/responses/defaultError'
        '401':
          $ref: '#/components/responses/defaultError'
        '403':
          $ref: '#/components/responses/defaultError'
        '404':
          $ref: '#/components/responses/defaultError'
        '409':
          description: >-
            The move is refused: `preview_stale`, `confirmation_mismatch`,
            `destination_not_permitted`, or the move engine's own code, in lower
            case (each is listed in the error reference).
            `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'
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:
    PitchClientMoveRequest:
      type: object
      properties:
        destination:
          description: >-
            Where the pitch goes: an existing client workspace, or a new client
            workspace created for it.
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - existing
                workspaceId:
                  type: string
                  format: uuid
                  description: A workspace `id` from `eligibleDestinations`.
              required:
                - kind
                - workspaceId
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - new
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: The new client's name.
                workspaceType:
                  type: string
                  enum:
                    - brand
                  description: Reseller clients are always brand workspaces.
                staff:
                  type: array
                  maxItems: 200
                  description: >-
                    The agency staff to give a role on the new client, from
                    `staffOptions` and `assignableRoles`. May be empty.
                  items:
                    type: object
                    properties:
                      userId:
                        type: string
                        description: A `userId` from `staffOptions`.
                      role:
                        type: string
                        enum:
                          - super_admin
                          - admin
                          - member
                          - viewer
                        description: A role from `assignableRoles`.
                    required:
                      - userId
                      - role
              required:
                - kind
                - name
                - workspaceType
        previewSignature:
          type: string
          minLength: 1
          maxLength: 256
          description: >-
            The `previewSignature` of the preview of this same destination,
            passed back unchanged. Needed for an existing workspace; a new
            client has none.
        acknowledgedWarnings:
          type: array
          maxItems: 32
          uniqueItems: true
          items:
            type: string
            enum:
              - SAME_WORKSPACE
              - DESTINATION_OWNER_MISSING
              - PROJECT_STATE_UNSUPPORTED
              - CREATOR_DOMAIN_CONFLICT
              - SOURCE_DOMAIN_CONFLICT
              - ACCESS_GRANTS_WILL_BE_REVOKED
              - ACCESS_BINDINGS_WILL_MOVE
              - STORAGE_OBJECT_MISSING
              - QUOTA_PROJECTS_EXCEEDED
              - QUOTA_PROMPTS_EXCEEDED
              - IN_FLIGHT_AGENT_RUNS
              - SAME_DOMAIN_PROJECTS
              - SCHEDULED_REPORTS_WILL_STOP
          description: >-
            The codes of the warnings the user confirmed: exactly the codes the
            preview listed, and `[]` when it listed none.
        confirmDomain:
          type: string
          minLength: 1
          maxLength: 2048
          description: The pitch's domain, as the user typed it.
      required:
        - destination
        - acknowledgedWarnings
        - confirmDomain
    PitchClientMoveResponse:
      type: object
      description: The pitch is a client project now.
      properties:
        success:
          type: boolean
        workspaceId:
          type: string
          format: uuid
          description: >-
            The client workspace the pitch moved into: the destination, or the
            new client's workspace.
        projectId:
          type: string
          format: uuid
          description: The pitch's id, which is the client project's id now.
      required:
        - success
        - workspaceId
        - projectId
    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
  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.