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

# Preview moving a pitch into a client workspace

> What moving the pitch into a destination would do, changing nothing. `destination` is `{ "kind": "existing", "workspaceId" }` with an id from `GET /api/mcp/pitches/{pitchId}/client-move`, or `{ "kind": "new" }` for a new client workspace. An existing workspace gets the engine's signed preview: what moves (`counts`), the `blockers` that stop it, the `warnings` the user must confirm, and a `previewSignature` that the move takes back unchanged. A new client is previewed on the source side alone (no signature). 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). Refusals: 409 `destination_not_permitted` for a workspace the pitch cannot move into; other refusals carry the move engine's own code, in lower case.



## OpenAPI

````yaml /api-reference/openapi.json post /api/mcp/pitches/{pitchId}/client-move/preview
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/preview:
    post:
      tags:
        - Projects
      summary: Preview moving a pitch into a client workspace
      description: >-
        What moving the pitch into a destination would do, changing nothing.
        `destination` is `{ "kind": "existing", "workspaceId" }` with an id from
        `GET /api/mcp/pitches/{pitchId}/client-move`, or `{ "kind": "new" }` for
        a new client workspace. An existing workspace gets the engine's signed
        preview: what moves (`counts`), the `blockers` that stop it, the
        `warnings` the user must confirm, and a `previewSignature` that the move
        takes back unchanged. A new client is previewed on the source side alone
        (no signature). 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). Refusals: 409
        `destination_not_permitted` for a workspace the pitch cannot move into;
        other refusals carry the move engine's own code, in lower case.
      operationId: previewPitchClientMove
      parameters:
        - $ref: '#/components/parameters/pitchId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PitchClientMovePreviewRequest'
      responses:
        '200':
          description: The preview of the move.
          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/json:
              schema:
                $ref: '#/components/schemas/PitchClientMovePreview'
        '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 for this destination:
            `destination_not_permitted` (a workspace the pitch cannot move
            into), or the move engine's own code, in lower case (each is listed
            in the error reference).
          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'
        '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.
  schemas:
    PitchClientMovePreviewRequest:
      type: object
      properties:
        destination:
          description: >-
            Where the pitch would go. A new client's preview needs only its
            staff, if any.
          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
                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
      required:
        - destination
    PitchClientMovePreview:
      type: object
      description: >-
        What the move would do; nothing changed. An existing destination also
        carries `project`, `destinationWorkspace`, `accessCarrierSummary` and
        the `previewSignature` the move takes back; a new client's preview has
        the source side alone.
      properties:
        destination:
          type: object
          properties:
            kind:
              type: string
              enum:
                - existing
                - new
          required:
            - kind
        counts:
          type: object
          description: >-
            What moves with the pitch: `prompts`, `visibilityReports`,
            `sharedReports`, `contentPieces`, `conversations`, `messages`,
            `agentRuns`, `projectMembers`, `ga4Links` and `gscLinks`, each a
            count.
          additionalProperties:
            type: integer
        warnings:
          type: array
          items:
            type: object
            properties:
              code:
                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
              message:
                type: string
            required:
              - code
              - message
          description: >-
            What the user must confirm before the pitch moves: send exactly
            these codes as `acknowledgedWarnings`.
        blockers:
          type: array
          items:
            type: object
            properties:
              code:
                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
              message:
                type: string
            required:
              - code
              - message
          description: 'What stops the move: it is refused until none remain.'
        previewSignature:
          type: string
          description: 'An existing destination only: pass it back unchanged with the move.'
        project:
          type: object
          description: >-
            An existing destination only: the pitch (`id`, `name`, `domain`,
            `sourceWorkspace`).
        destinationWorkspace:
          type: object
          description: >-
            An existing destination only: the workspace (`id`, `name`, `slug`,
            `owner`, `workspaceType`, plan fields where you may see billing, and
            `usage` against its limits).
        accessCarrierSummary:
          type: object
          description: >-
            An existing destination only: the access grants (`willBeRemoved`)
            and bindings (`willMove`) the move affects, by category.
      required:
        - destination
        - counts
        - warnings
        - blockers
    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
    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.