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

# Search email stop-list

> List the workspace's stop-list: the addresses no mailbox of the team sends to, each with its origin (manual, bounce, unsubscribe, complaint) and reason. Every send checks the list by itself, so use this to see why someone was skipped, to check one address (filter address eq, page_size 1), to probe a list before a send (address in) and to audit lifts (a deleted_at range; deleted_by is who lifted). include source_email_message brings the message behind an automatic row. Not for why an address bounced (search_email_bounce_log). Requires can_view_email_suppressions.

Contract:
- MCP tool `search_email_suppressions`, registry package `mcp.email/email_suppressions`, mount `email.deliverability`.
- Operation `search`, response envelope `search`.
- Flags: read only.



## OpenAPI

````yaml /api-reference/email/openapi.yaml post /api/email-suppressions/search
openapi: 3.0.3
info:
  title: 'GTM API public contract: gtm.service.email'
  description: >-
    Connected mailboxes and everything driven through them: Google, Microsoft
    and IMAP/SMTP accounts with their limits, warmup and health, the mirrored
    inbox (threads, messages, folders), sending now or on a schedule (a repeat
    under the caller's own key is answered by the first send), the stop-list,
    bounces and engagement, the sign-in applications mailboxes connect through,
    and tracking and sending domains.


    GENERATED. This document is projected from the Zod MCP tool registry in
    `product/mcp/gtm.mcp` (one tool per public endpoint, 1:1). Do not edit it by
    hand; edit the tool definition and regenerate with `pnpm openapi:public`.


    Surface: the public `/api` contract of `gtm.service.email`, 65 operations.
    This is the only OpenAPI document the platform publishes. Internal
    (`/internal`) and health endpoints are deliberately absent: they are not
    part of any contract, they can change without notice, and the service source
    is their only description.


    Conventions:

    - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header.

    - Every success body is an MCP envelope: `success: true` plus one typed
    `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`,
    `group_by`, `action`), and a `meta` block with `trace_id` for support.

    - Every failure is the same `McpError` envelope with a code from a fixed
    16-code taxonomy, so a client maps errors once.

    - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward
    `cursor`; `page_size: 0` returns counts only.

    - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`)
    travel as JSON text and array-valued ones repeat as `name[]=value`.

    - The MCP-only `_meta` field (usage analytics) never reaches the backend and
    is not part of this contract.

    - A workspace may own several email servers, each with its own mailboxes and
    data, behind this one address. The `Email-Box-SID` header names the server a
    call is for (`em_bx_...`, listed by `POST /api/email-boxes/search` of
    gtm.service.id); without it the call goes to the workspace's primary server.
    A sid belongs to the server that answered it: on another server it is
    `not_found`. A workspace with no server serving yet answers 409 `conflict`,
    reason `email_box_not_ready`.
  version: '1.0'
  contact:
    name: GTM API
    url: https://gtm-api.com
    email: support@gtm-api.com
  license:
    name: Proprietary
    url: https://gtm-api.com/license
servers:
  - url: https://app.gtm-api.com/email/v4
    description: Production, through the app.gtm-api.com gateway
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: email_account_activity_log
    description: >-
      Registry package `mcp.email/email_account_activity_log`, served on MCP
      mount `email.accounts`.
  - name: email_account_health
    description: >-
      Registry package `mcp.email/email_account_health`, served on MCP mount
      `email.accounts`.
  - name: email_account_sync_runs
    description: >-
      Registry package `mcp.email/email_account_sync_runs`, served on MCP mount
      `email.accounts`.
  - name: email_accounts
    description: >-
      Registry package `mcp.email/email_accounts`, served on MCP mount
      `email.accounts`.
  - name: email_bounce_log
    description: >-
      Registry package `mcp.email/email_bounce_log`, served on MCP mount
      `email.deliverability`.
  - name: email_box_settings
    description: >-
      Registry package `mcp.email/email_box_settings`, served on MCP mount
      `email.infrastructure`.
  - name: email_domains
    description: >-
      Registry package `mcp.email/email_domains`, served on MCP mount
      `email.infrastructure`.
  - name: email_engagements
    description: >-
      Registry package `mcp.email/email_engagements`, served on MCP mount
      `email.deliverability`.
  - name: email_folders
    description: >-
      Registry package `mcp.email/email_folders`, served on MCP mount
      `email.messaging`.
  - name: email_messages
    description: >-
      Registry package `mcp.email/email_messages`, served on MCP mount
      `email.messaging`.
  - name: email_oauth_apps
    description: >-
      Registry package `mcp.email/email_oauth_apps`, served on MCP mount
      `email.infrastructure`.
  - name: email_sending_domains
    description: >-
      Registry package `mcp.email/email_sending_domains`, served on MCP mount
      `email.infrastructure`.
  - name: email_suppressions
    description: >-
      Registry package `mcp.email/email_suppressions`, served on MCP mount
      `email.deliverability`.
  - name: email_threads
    description: >-
      Registry package `mcp.email/email_threads`, served on MCP mount
      `email.messaging`.
  - name: email_tracking_domains
    description: >-
      Registry package `mcp.email/email_tracking_domains`, served on MCP mount
      `email.infrastructure`.
paths:
  /api/email-suppressions/search:
    post:
      tags:
        - email_suppressions
      summary: Search email stop-list
      description: >-
        List the workspace's stop-list: the addresses no mailbox of the team
        sends to, each with its origin (manual, bounce, unsubscribe, complaint)
        and reason. Every send checks the list by itself, so use this to see why
        someone was skipped, to check one address (filter address eq, page_size
        1), to probe a list before a send (address in) and to audit lifts (a
        deleted_at range; deleted_by is who lifted). include
        source_email_message brings the message behind an automatic row. Not for
        why an address bounced (search_email_bounce_log). Requires
        can_view_email_suppressions.


        Contract:

        - MCP tool `search_email_suppressions`, registry package
        `mcp.email/email_suppressions`, mount `email.deliverability`.

        - Operation `search`, response envelope `search`.

        - Flags: read only.
      operationId: search_email_suppressions
      parameters:
        - $ref: '#/components/parameters/EmailBoxSid'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchEmailSuppressionsRequest'
      responses:
        '200':
          description: '`search` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEmailSuppressionsResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  parameters:
    EmailBoxSid:
      name: Email-Box-SID
      in: header
      required: false
      description: >-
        Email server (em_bx_...) the call is for, from search_email_boxes.
        Omitted: the primary server.
      schema:
        type: string
        pattern: ^em_bx_[A-Za-z0-9]{12}$
  schemas:
    SearchEmailSuppressionsRequest:
      type: object
      description: Request body of `search_email_suppressions`.
      properties:
        filter:
          type: object
          properties:
            sid:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
            address:
              type: object
              properties:
                eq:
                  type: string
                in:
                  type: array
                  items:
                    type: string
              additionalProperties: false
              description: 'Exact address, any case; in: probe a list before a send.'
            origin:
              type: object
              properties:
                eq:
                  type: string
                  enum:
                    - manual
                    - bounce
                    - unsubscribe
                    - complaint
                ne:
                  type: string
                  enum:
                    - manual
                    - bounce
                    - unsubscribe
                    - complaint
                in:
                  type: array
                  items:
                    type: string
                    enum:
                      - manual
                      - bounce
                      - unsubscribe
                      - complaint
                nin:
                  type: array
                  items:
                    type: string
                    enum:
                      - manual
                      - bounce
                      - unsubscribe
                      - complaint
              additionalProperties: false
            created_at:
              type: object
              properties:
                gte:
                  type: string
                lte:
                  type: string
                gt:
                  type: string
                lt:
                  type: string
              additionalProperties: false
              description: When the address was stopped.
            deleted_at:
              type: object
              properties:
                gte:
                  type: string
                lte:
                  type: string
                is_null:
                  type: boolean
              additionalProperties: false
              description: >-
                Default: the live list. A range reads lifted rows: who re-opened
                which address, and when.
        include:
          type: array
          items:
            type: string
            enum:
              - source_email_message
          description: Relations to eager-load (see entity Includes).
        sort:
          type: object
          properties:
            field:
              type: string
              enum:
                - created_at
                - address
                - deleted_at
            direction:
              type: string
              enum:
                - asc
                - desc
              description: Default desc.
          required:
            - field
        page_size:
          type: integer
          minimum: 0
          maximum: 500
          description: >-
            0..500, default 50. page_size=0 = count-only, page_size=1 =
            getFirst.
        cursor:
          type: string
          nullable: true
          description: >-
            Opaque forward cursor from a previous response
            pagination.next_cursor.
    SearchEmailSuppressionsResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - search
        items:
          type: array
          items:
            type: object
            properties:
              item:
                type: object
                properties:
                  sid:
                    type: string
                  team_sid:
                    type: string
                  address:
                    type: string
                  origin:
                    type: string
                    enum:
                      - manual
                      - bounce
                      - unsubscribe
                      - complaint
                    description: >-
                      Who put it on the stop-list: a person (manual), a bounce,
                      an unsubscribe or a complaint.
                  reason:
                    type: string
                    nullable: true
                  source_email_message_sid:
                    type: string
                    nullable: true
                  created_by:
                    type: object
                    nullable: true
                    properties:
                      actor_type:
                        type: string
                        enum:
                          - user
                          - support
                          - api_key
                          - system
                          - agent
                      actor_sid:
                        type: string
                        nullable: true
                      team_sid:
                        type: string
                      actor_name:
                        type: string
                        nullable: true
                        description: >-
                          The OAuth client that acted ("Claude", "n8n"); null
                          for a user, an API key or a system job.
                      oauth_client_sid:
                        type: string
                        nullable: true
                        description: >-
                          The acting OAuth client (id_oc_*); null off the OAuth
                          path.
                      reason:
                        type: string
                        nullable: true
                        description: >-
                          Why a system actor wrote the row
                          (snapshot_capture_job, ...); null otherwise.
                      permissions:
                        type: object
                        additionalProperties: {}
                        description: >-
                          Internal audit context: the grant set the actor held
                          at write time. Not a contract.
                      cluster_id:
                        type: integer
                        nullable: true
                        description: >-
                          Internal audit context: the cluster that served the
                          write.
                      trace_id:
                        type: string
                        nullable: true
                        description: >-
                          Internal audit context: the trace id of the request
                          that wrote the row.
                    required:
                      - actor_type
                      - actor_sid
                      - team_sid
                      - permissions
                  deleted_by:
                    type: object
                    nullable: true
                    properties:
                      actor_type:
                        type: string
                        enum:
                          - user
                          - support
                          - api_key
                          - system
                          - agent
                      actor_sid:
                        type: string
                        nullable: true
                      team_sid:
                        type: string
                      actor_name:
                        type: string
                        nullable: true
                        description: >-
                          The OAuth client that acted ("Claude", "n8n"); null
                          for a user, an API key or a system job.
                      oauth_client_sid:
                        type: string
                        nullable: true
                        description: >-
                          The acting OAuth client (id_oc_*); null off the OAuth
                          path.
                      reason:
                        type: string
                        nullable: true
                        description: >-
                          Why a system actor wrote the row
                          (snapshot_capture_job, ...); null otherwise.
                      permissions:
                        type: object
                        additionalProperties: {}
                        description: >-
                          Internal audit context: the grant set the actor held
                          at write time. Not a contract.
                      cluster_id:
                        type: integer
                        nullable: true
                        description: >-
                          Internal audit context: the cluster that served the
                          write.
                      trace_id:
                        type: string
                        nullable: true
                        description: >-
                          Internal audit context: the trace id of the request
                          that wrote the row.
                    required:
                      - actor_type
                      - actor_sid
                      - team_sid
                      - permissions
                    description: Who lifted it.
                  created_at:
                    type: string
                    nullable: true
                  updated_at:
                    type: string
                    nullable: true
                  deleted_at:
                    type: string
                    nullable: true
                    description: When it was lifted; null while the address is stopped.
                required:
                  - sid
                  - team_sid
                  - address
                  - origin
                  - reason
                  - source_email_message_sid
                  - created_by
                  - deleted_by
                  - created_at
                  - updated_at
                  - deleted_at
              included:
                type: object
                properties:
                  source_email_message:
                    type: object
                    nullable: true
                    properties:
                      sid:
                        type: string
                      team_sid:
                        type: string
                      email_account_sid:
                        type: string
                      email_thread_sid:
                        type: string
                      internet_message_id:
                        type: string
                        description: RFC 5322 Message-ID.
                      provider_message_id:
                        type: string
                        nullable: true
                      direction:
                        type: string
                        enum:
                          - inbound
                          - outbound
                      status:
                        type: string
                        enum:
                          - received
                          - scheduled
                          - sending
                          - sent
                          - failed
                          - bounced
                        description: >-
                          Inbound is always received. Outbound: scheduled,
                          sending, sent or failed, and bounced once a bounce is
                          matched.
                      kind:
                        type: string
                        enum:
                          - regular
                          - bounce_notification
                        description: >-
                          bounce_notification is a bounce report stored as a
                          mailbox row; searches leave it out by default.
                      in_reply_to_email_message_sid:
                        type: string
                        nullable: true
                      bounce_type:
                        type: string
                        nullable: true
                        enum:
                          - hard
                          - soft
                          - policy
                      bounce_code:
                        type: string
                        nullable: true
                      bounce_diagnostic:
                        type: string
                        nullable: true
                      from:
                        type: object
                        properties:
                          email:
                            type: string
                            description: Lowercase address.
                          display_name:
                            type: string
                            nullable: true
                        required:
                          - email
                      to:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      cc:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      bcc:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      reply_to:
                        type: array
                        items:
                          type: object
                          properties:
                            email:
                              type: string
                              description: Lowercase address.
                            display_name:
                              type: string
                              nullable: true
                          required:
                            - email
                      subject:
                        type: string
                        nullable: true
                      snippet:
                        type: string
                        nullable: true
                        description: The first words of the text, for lists.
                      is_body_synced:
                        type: boolean
                        description: >-
                          false: the body is still at the provider;
                          get_email_message fetches it.
                      attachments:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: >-
                                The attachment id within the message: the
                                attachment_id of get_email_message_attachment.
                            name:
                              type: string
                            mime:
                              type: string
                            size:
                              type: integer
                              minimum: 0
                              description: >-
                                Bytes; the provider's estimate until the first
                                fetch.
                            content_id:
                              type: string
                              nullable: true
                              description: cid of an inline image.
                            is_inline:
                              type: boolean
                          required:
                            - id
                            - name
                            - mime
                            - size
                        description: >-
                          Metadata only; the bytes come from
                          get_email_message_attachment.
                      has_attachments:
                        type: boolean
                      email_folder_sids:
                        type: array
                        items:
                          type: string
                      folder_role:
                        type: string
                        nullable: true
                        enum:
                          - inbox
                          - sent
                          - drafts
                          - trash
                          - spam
                          - archive
                          - starred
                          - important
                          - custom
                      is_read:
                        type: boolean
                      client_reference:
                        type: string
                        nullable: true
                        description: The caller's own key of the message.
                      first_opened_at:
                        type: string
                        nullable: true
                      opens_count:
                        type: integer
                      first_clicked_at:
                        type: string
                        nullable: true
                      clicks_count:
                        type: integer
                      unsubscribed_at:
                        type: string
                        nullable: true
                      sent_at:
                        type: string
                        nullable: true
                        description: >-
                          When it was sent or received; on a scheduled row, when
                          it is due.
                      scheduled_at:
                        type: string
                        nullable: true
                      created_by:
                        type: object
                        nullable: true
                        properties:
                          actor_type:
                            type: string
                            enum:
                              - user
                              - support
                              - api_key
                              - system
                              - agent
                          actor_sid:
                            type: string
                            nullable: true
                          team_sid:
                            type: string
                          actor_name:
                            type: string
                            nullable: true
                            description: >-
                              The OAuth client that acted ("Claude", "n8n");
                              null for a user, an API key or a system job.
                          oauth_client_sid:
                            type: string
                            nullable: true
                            description: >-
                              The acting OAuth client (id_oc_*); null off the
                              OAuth path.
                          reason:
                            type: string
                            nullable: true
                            description: >-
                              Why a system actor wrote the row
                              (snapshot_capture_job, ...); null otherwise.
                          permissions:
                            type: object
                            additionalProperties: {}
                            description: >-
                              Internal audit context: the grant set the actor
                              held at write time. Not a contract.
                          cluster_id:
                            type: integer
                            nullable: true
                            description: >-
                              Internal audit context: the cluster that served
                              the write.
                          trace_id:
                            type: string
                            nullable: true
                            description: >-
                              Internal audit context: the trace id of the
                              request that wrote the row.
                        required:
                          - actor_type
                          - actor_sid
                          - team_sid
                          - permissions
                      body_html:
                        type: string
                        nullable: true
                        description: >-
                          As stored, not sanitized. Null in a search row unless
                          include_bodies.
                      body_text:
                        type: string
                        nullable: true
                      headers:
                        anyOf:
                          - type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                value:
                                  type: string
                              required:
                                - name
                                - value
                          - type: object
                            additionalProperties:
                              type: object
                              properties:
                                name:
                                  type: string
                                value:
                                  type: string
                              required:
                                - name
                                - value
                          - {}
                        description: >-
                          The stored headers, each { name, value }. Today an
                          object keyed by position ("0", "1", ...), not an
                          array.
                      body_html_sanitized:
                        type: string
                        nullable: true
                        description: >-
                          get_email_message with sanitize only: HTML safe to
                          render, the quoted history marked data-quoted.
                      body_text_unquoted:
                        type: string
                        nullable: true
                        description: >-
                          get_email_message with sanitize only: the text above
                          the first quote.
                      created_at:
                        type: string
                        nullable: true
                      updated_at:
                        type: string
                        nullable: true
                      is_flagged:
                        type: boolean
                      is_answered:
                        type: boolean
                      deleted_at:
                        type: string
                        nullable: true
                    required:
                      - sid
                      - team_sid
                      - email_account_sid
                      - email_thread_sid
                      - internet_message_id
                      - provider_message_id
                      - direction
                      - status
                      - kind
                      - in_reply_to_email_message_sid
                      - bounce_type
                      - bounce_code
                      - bounce_diagnostic
                      - from
                      - to
                      - cc
                      - bcc
                      - reply_to
                      - subject
                      - snippet
                      - is_body_synced
                      - attachments
                      - has_attachments
                      - email_folder_sids
                      - folder_role
                      - is_read
                      - client_reference
                      - first_opened_at
                      - opens_count
                      - first_clicked_at
                      - clicks_count
                      - unsubscribed_at
                      - sent_at
                      - scheduled_at
                      - created_by
                      - body_html
                      - body_text
                      - headers
                      - body_html_sanitized
                      - body_text_unquoted
                      - created_at
                      - updated_at
                      - is_flagged
                      - is_answered
                      - deleted_at
                    description: >-
                      The message that bounced, was unsubscribed from or
                      complained about.
            required:
              - item
              - included
        pagination:
          type: object
          properties:
            next_cursor:
              type: string
              nullable: true
            has_more:
              type: boolean
            total_count:
              type: integer
              nullable: true
          required:
            - next_cursor
            - has_more
            - total_count
        applied_filters:
          type: object
          additionalProperties: {}
        includes:
          type: array
          items:
            type: string
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
        counts:
          type: object
          properties:
            total_count:
              type: integer
            groups:
              type: object
              properties:
                origin:
                  type: object
                  additionalProperties:
                    type: number
          required:
            - total_count
            - groups
      required:
        - success
        - operation
        - items
        - pagination
        - applied_filters
        - includes
        - meta
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
                - nothing_to_update
                - not_found
                - relation_not_found
                - invalid_transition
                - limit_exceeded
                - payment_required
                - duplicate_rejected
                - conflict
                - delete_blocked
                - unauthorized
                - forbidden
                - rate_limited
                - internal_error
                - service_unavailable
                - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    rule:
                      type: string
                    message:
                      type: string
                  required:
                    - rule
                    - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: >-
                      Machine-readable blocker type (active_flow, pending_tasks,
                      …).
                  severity:
                    type: string
                    enum:
                      - hard
                      - soft
                    description: >-
                      hard = external action required; soft = acknowledge is
                      enough.
                  description:
                    type: string
                  entity_sid:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                  - type
                  - severity
                  - description
                  - entity_sid
                  - resolution
                  - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
            - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - error
  responses:
    McpClientError:
      description: >-
        MCP error envelope. `error.code` is one of validation_failed,
        nothing_to_update, not_found, relation_not_found, invalid_transition,
        limit_exceeded, payment_required, duplicate_rejected, conflict,
        delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
          examples:
            validation_failed:
              summary: '422: a field of the request failed validation'
              value:
                success: false
                error:
                  code: validation_failed
                  message: Validation failed
                  recoverable: true
                  field_errors:
                    page_size:
                      - rule: max
                        message: The page size field must not be greater than 1000.
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
            unauthorized:
              summary: '401: no bearer token, or one that does not verify'
              value:
                success: false
                error:
                  code: unauthorized
                  message: Authentication required
                  recoverable: true
                  context:
                    reason: missing_or_invalid_token
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: null
                  actor_type: null
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
          examples:
            service_unavailable:
              summary: >-
                503: something the call depends on did not answer; the same call
                can be made again
              value:
                success: false
                error:
                  code: service_unavailable
                  message: 'Service unavailable: upstream unavailable'
                  recoverable: true
                  context:
                    reason: upstream_unavailable
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
            internal_error:
              summary: >-
                500: a fault on our side; a retry does not help, report
                meta.trace_id
              value:
                success: false
                error:
                  code: internal_error
                  message: Internal error
                  recoverable: false
                  context:
                    reason: internal_error
                meta:
                  trace_id: 019a7c2e-5b1d-7c3a-9f4e-2a6b8d0c1e3f
                  span_id: 5f0c9a2e7b4d1c38
                  timestamp: '2026-11-13T09:30:00Z'
                  duration_ms: 41
                  team_sid: ts_tm_Bv9nK4xP1sD7
                  actor_type: api_key
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gtm.service.id. Its `access_identity` claim
        carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is
        authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: >-
        Team scope for tokens that do not carry one. Ignored when the token
        already names a team.

````

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