> ## 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 account at provider

> Search one mailbox at its provider (Gmail, Microsoft or the IMAP server) for mail the mirror may not hold: older than the backfill window, or matched by words of the body. The hits are mirrored by the call, so each is a normal message afterwards: read it with get_email_message, answer it with send_email_message. result.items are the messages without bodies, in the provider's order, at most 50; truncated says the provider had more; sources says which were already mirrored. search_email_messages stays the cheap search of what is mirrored: try it first. An inactive or hosted mailbox answers 409 account_not_searchable; 503 provider_unavailable carries retry_after. Requires can_view_email_accounts.

Contract:
- MCP tool `search_email_account_provider`, registry package `mcp.email/email_accounts`, mount `email.accounts`.
- Operation `action`, response envelope `action`.
- Flags: none.



## OpenAPI

````yaml /api-reference/email/openapi.yaml post /api/email-accounts/{sid}/search-provider
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-accounts/{sid}/search-provider:
    post:
      tags:
        - email_accounts
      summary: Search email account at provider
      description: >-
        Search one mailbox at its provider (Gmail, Microsoft or the IMAP server)
        for mail the mirror may not hold: older than the backfill window, or
        matched by words of the body. The hits are mirrored by the call, so each
        is a normal message afterwards: read it with get_email_message, answer
        it with send_email_message. result.items are the messages without
        bodies, in the provider's order, at most 50; truncated says the provider
        had more; sources says which were already mirrored.
        search_email_messages stays the cheap search of what is mirrored: try it
        first. An inactive or hosted mailbox answers 409 account_not_searchable;
        503 provider_unavailable carries retry_after. Requires
        can_view_email_accounts.


        Contract:

        - MCP tool `search_email_account_provider`, registry package
        `mcp.email/email_accounts`, mount `email.accounts`.

        - Operation `action`, response envelope `action`.

        - Flags: none.
      operationId: search_email_account_provider
      parameters:
        - name: sid
          in: path
          required: true
          description: Path segment `{sid}`.
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^em_ac_
        - $ref: '#/components/parameters/EmailBoxSid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchEmailAccountProviderRequest'
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEmailAccountProviderResponse'
        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:
    SearchEmailAccountProviderRequest:
      type: object
      description: Request body of `search_email_account_provider`.
      properties:
        q:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Words, matched where the provider matches them: subject, body,
            participants. Plain words, not the provider's query syntax.
        email_folder_sid:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^em_fd_
          description: >-
            Search this folder of the mailbox alone. Default: the whole mailbox
            (the inbox on a plain IMAP server).
        since:
          type: string
          nullable: true
          description: ISO 8601 date, inclusive.
        before:
          type: string
          nullable: true
          description: ISO 8601 date, after since.
        limit:
          type: integer
          nullable: true
          minimum: 1
          maximum: 50
          description: 1 to 50. Default 20.
      required:
        - q
    SearchEmailAccountProviderResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - action
        action:
          type: string
          description: kebab-case verb; matches the route segment.
        item:
          type: object
          nullable: true
          properties:
            sid:
              type: string
            team_sid:
              type: string
            email_sending_domain_sid:
              type: string
              nullable: true
              description: 'gtm_hosted only: the sending domain the mailbox is minted on.'
            provider:
              type: string
              enum:
                - google
                - microsoft
                - imap_smtp
                - gtm_hosted
            address:
              type: string
            display_name:
              type: string
              nullable: true
            aliases:
              type: array
              nullable: true
              items:
                type: string
              description: >-
                Send-as addresses (google, microsoft); from_email of a send must
                be the address or one of these.
            status:
              type: string
              enum:
                - connecting
                - active
                - reconnect_required
                - disconnected
                - subscription_required
              description: >-
                connecting: first sync running. active. reconnect_required: the
                provider refused the credential, sync and sending stopped.
                disconnected: detached, data kept. subscription_required: held,
                no free seat on its server.
            sending_paused_at:
              type: string
              nullable: true
              description: Set while sending is paused; sync goes on.
            sending_paused_reason:
              type: string
              nullable: true
              enum:
                - manual
                - bounce_rate
                - complaint_rate
                - provider_block
                - warmup_guard
                - provider_quota
              description: >-
                manual: a person or an agent. The rest are the platform's own;
                provider_quota lifts itself at sending_paused_until.
            connection:
              type: object
              nullable: true
              properties:
                imap_host:
                  type: string
                imap_port:
                  type: integer
                imap_encryption:
                  type: string
                  enum:
                    - ssl
                    - starttls
                    - none
                imap_username:
                  type: string
                smtp_host:
                  type: string
                smtp_port:
                  type: integer
                smtp_encryption:
                  type: string
                  enum:
                    - ssl
                    - starttls
                    - none
                smtp_username:
                  type: string
              required:
                - imap_host
                - imap_port
                - imap_encryption
                - imap_username
                - smtp_host
                - smtp_port
                - smtp_encryption
                - smtp_username
              description: >-
                IMAP and SMTP servers of an imap_smtp mailbox. No secrets: a
                password is never read back.
            sending_limits:
              type: object
              properties:
                daily_limit:
                  type: integer
                  description: Sends a day, 1 to 2000.
                min_interval_seconds:
                  type: integer
                  description: Seconds between sends of the queue, 0 to 3600.
                sending_window:
                  type: object
                  nullable: true
                  properties:
                    time_zone:
                      type: string
                      description: >-
                        IANA time zone; also the day boundary of the daily
                        limit.
                    days:
                      type: array
                      items:
                        type: integer
                      description: ISO weekdays, 1 Monday to 7 Sunday.
                    start:
                      type: string
                      description: HH:MM.
                    end:
                      type: string
                      description: HH:MM.
                  required:
                    - time_zone
                    - days
                    - start
                    - end
                  description: 'Null: send at any time, the day is the UTC day.'
              required:
                - daily_limit
                - min_interval_seconds
                - sending_window
            warmup_config:
              type: object
              properties:
                enabled:
                  type: boolean
                ramp_start_daily:
                  type: integer
                  description: The cap of day 1, 1 to 100.
                ramp_step_per_day:
                  type: integer
                  description: Added each day, 1 to 50.
                target_daily:
                  type: integer
                  description: Where the ramp ends, 5 to 2000.
              required:
                - enabled
                - ramp_start_daily
                - ramp_step_per_day
                - target_daily
              description: >-
                The warmup ramp: while on, the day cap is the smaller of
                daily_limit and the ramp.
            signature_html:
              type: string
              nullable: true
            track_opens:
              type: boolean
            track_clicks:
              type: boolean
            email_tracking_domain_sid:
              type: string
              nullable: true
            email_oauth_app_sid:
              type: string
              nullable: true
              description: >-
                The team's sign-in application the grant came through; null: the
                platform's, or none.
            backfill_days:
              type: integer
              description: Days of history mirrored at connect.
            last_messages_sync_at:
              type: string
              nullable: true
            last_folders_sync_at:
              type: string
              nullable: true
            connected_at:
              type: string
              nullable: true
            reconnect_required_at:
              type: string
              nullable: true
            sync_config:
              type: object
              nullable: true
              additionalProperties: {}
              description: 'Sync cadence per track: messages, folders, health_check.'
            webhook_config:
              type: object
              nullable: true
              additionalProperties: {}
              description: >-
                Which event families this mailbox emits: email-messages,
                email-threads, email-engagements, email-accounts,
                email-account-health.
            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
            sending_paused_until:
              type: string
              nullable: true
              description: When a provider_quota pause lifts itself.
            reconnect_reason:
              type: string
              nullable: true
              description: >-
                Why it needs a reconnect: provider_auth_dead, imap_auth_failed,
                imap_app_password_required, imap_disabled, google_admin_blocked,
                provider_policy_blocked, scope_insufficient,
                mailbox_not_enabled, smtp_auth_rejected or
                smtp_web_login_required.
            email_box_sid:
              type: string
              nullable: true
              description: The email server the mailbox lives on.
            label:
              type: string
              nullable: true
              description: The customer's own tag.
            address_domain:
              type: string
              description: The part of address after the @.
            sent_today:
              type: integer
              description: >-
                Sends counted on the mailbox's current day; 0 once that day is
                over.
            daily_cap_today:
              type: integer
              description: 'Today''s cap: the smaller of daily_limit and the warmup ramp.'
            warmup_day:
              type: integer
              nullable: true
              description: Day N of the ramp; null when warmup is off or done.
            auth_suspect:
              type: object
              nullable: true
              properties:
                since:
                  type: string
                failures:
                  type: integer
                next_try_at:
                  type: string
                  nullable: true
                source:
                  type: string
                  nullable: true
              required:
                - since
                - failures
                - next_try_at
                - source
              description: >-
                The provider is refusing the sign-in and the platform is still
                probing before it calls the mailbox dead. Null when the last
                sign-in was accepted.
            subscription_hold_reason:
              type: string
              nullable: true
              enum:
                - server_full
                - server_suspended
              description: >-
                Why it is held: server_full (no free seat) or server_suspended
                (the server is not serving).
            created_at:
              type: string
              nullable: true
            updated_at:
              type: string
              nullable: true
            deleted_at:
              type: string
              nullable: true
          required:
            - sid
            - team_sid
            - email_sending_domain_sid
            - provider
            - address
            - display_name
            - aliases
            - status
            - sending_paused_at
            - sending_paused_reason
            - connection
            - sending_limits
            - warmup_config
            - signature_html
            - track_opens
            - track_clicks
            - email_tracking_domain_sid
            - email_oauth_app_sid
            - backfill_days
            - last_messages_sync_at
            - last_folders_sync_at
            - connected_at
            - reconnect_required_at
            - sync_config
            - webhook_config
            - created_by
            - sending_paused_until
            - reconnect_reason
            - email_box_sid
            - label
            - address_domain
            - sent_today
            - daily_cap_today
            - warmup_day
            - auth_suspect
            - subscription_hold_reason
            - created_at
            - updated_at
            - deleted_at
        result:
          type: object
          properties:
            q:
              type: string
            folder:
              type: object
              nullable: true
              properties:
                sid:
                  type: string
                name:
                  type: string
                role:
                  type: string
                  enum:
                    - inbox
                    - sent
                    - drafts
                    - trash
                    - spam
                    - archive
                    - starred
                    - important
                    - custom
                provider_folder_id:
                  type: string
              required:
                - sid
                - name
                - role
                - provider_folder_id
            folder_provider_id:
              type: string
              nullable: true
              description: The folder the provider was asked in.
            provider_hits:
              type: integer
            fetched:
              type: integer
              description: Messages this search mirrored for the first time.
            truncated:
              type: boolean
            items:
              type: array
              items:
                type: object
                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
            sources:
              type: object
              additionalProperties:
                type: string
              description: >-
                Message sid to local (mirrored before) or provider (fetched by
                this search).
          required:
            - q
            - folder
            - folder_provider_id
            - provider_hits
            - fetched
            - truncated
            - items
            - sources
        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
        - operation
        - action
        - item
        - result
        - 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.