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

# Update agent hosts

> Replace who hosts an AI SDR's meetings (by sid): the sender profile itself (kept whatever the list says; its link is the agent's link to offer) and colleagues by team member sid or free name, each with their own booking link, how the reply introduces them, and the scenarios they host (a key hosted once; a scenario nobody names is the sender's). Read the agent first and send the whole list back: a row left out is gone. No calendar and no booking: the reply sends the host's link as the Rules say.

Contract:
- MCP tool `update_agent_hosts`, registry package `mcp.unibox/agents`, mount `unibox.agent`.
- Operation `update`, response envelope `update`.
- Flags: none.



## OpenAPI

````yaml /api-reference/unibox/openapi.yaml patch /api/agents/{sid}/hosts
openapi: 3.0.3
info:
  title: 'GetSales public contract: gs.service.unibox'
  description: >-
    The team inbox and the AI SDR: every LinkedIn and email thread in one place
    (conversations, messages, the timeline events), the manual tasks a thread
    spawns, the sender profiles the team speaks through with their LinkedIn
    account and mailboxes, and the one agent per team with its scenarios, plans
    and runs.


    GENERATED. This document is projected from the Zod MCP tool registry in
    `product/mcp/gs.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 `gs.service.unibox`, 125 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.
  version: '1.0'
  contact:
    name: GetSales
    url: https://getsales.io
    email: support@getsales.io
  license:
    name: Proprietary
    url: https://getsales.io/terms
servers:
  - url: https://beta.getsales.io/unibox/v1
    description: >-
      Production (the gateway path on the beta ring; the origin is provisioned
      per DEPLOY_MAP.md)
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: agent_answers
    description: >-
      Registry package `mcp.unibox/agent_answers`, served on MCP mount
      `unibox.knowledge`.
  - name: agent_conversation_uploads
    description: >-
      Registry package `mcp.unibox/agent_conversation_uploads`, served on MCP
      mount `unibox.agent-memory`.
  - name: agent_examples
    description: >-
      Registry package `mcp.unibox/agent_examples`, served on MCP mount
      `unibox.agent-memory`.
  - name: agent_hints
    description: >-
      Registry package `mcp.unibox/agent_hints`, served on MCP mount
      `unibox.agent-memory`.
  - name: agent_plans
    description: >-
      Registry package `mcp.unibox/agent_plans`, served on MCP mount
      `unibox.agent`.
  - name: agent_runs
    description: >-
      Registry package `mcp.unibox/agent_runs`, served on MCP mount
      `unibox.agent-memory`.
  - name: agent_scenarios
    description: >-
      Registry package `mcp.unibox/agent_scenarios`, served on MCP mount
      `unibox.agent`.
  - name: agent_source_parses
    description: >-
      Registry package `mcp.unibox/agent_source_parses`, served on MCP mount
      `unibox.knowledge`.
  - name: agent_sources
    description: >-
      Registry package `mcp.unibox/agent_sources`, served on MCP mount
      `unibox.knowledge`.
  - name: agent_tests
    description: >-
      Registry package `mcp.unibox/agent_tests`, served on MCP mount
      `unibox.agent-memory`.
  - name: agents
    description: >-
      Registry package `mcp.unibox/agents`, served on MCP mount
      `unibox.website`.
  - name: conversation_events
    description: >-
      Registry package `mcp.unibox/conversation_events`, served on MCP mount
      `unibox.inbox`.
  - name: conversations
    description: >-
      Registry package `mcp.unibox/conversations`, served on MCP mount
      `unibox.inbox`.
  - name: messages
    description: >-
      Registry package `mcp.unibox/messages`, served on MCP mount
      `unibox.inbox`.
  - name: sender_profiles
    description: >-
      Registry package `mcp.unibox/sender_profiles`, served on MCP mount
      `unibox.sender-profiles`.
  - name: tasks
    description: Registry package `mcp.unibox/tasks`, served on MCP mount `unibox.inbox`.
  - name: timeline
    description: >-
      Registry package `mcp.unibox/timeline`, served on MCP mount
      `unibox.inbox`.
paths:
  /api/agents/{sid}/hosts:
    patch:
      tags:
        - agents
      summary: Update agent hosts
      description: >-
        Replace who hosts an AI SDR's meetings (by sid): the sender profile
        itself (kept whatever the list says; its link is the agent's link to
        offer) and colleagues by team member sid or free name, each with their
        own booking link, how the reply introduces them, and the scenarios they
        host (a key hosted once; a scenario nobody names is the sender's). Read
        the agent first and send the whole list back: a row left out is gone. No
        calendar and no booking: the reply sends the host's link as the Rules
        say.


        Contract:

        - MCP tool `update_agent_hosts`, registry package `mcp.unibox/agents`,
        mount `unibox.agent`.

        - Operation `update`, response envelope `update`.

        - Flags: none.
      operationId: update_agent_hosts
      parameters:
        - name: sid
          in: path
          required: true
          description: The agent (ub_ag_…).
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^ub_ag_
            description: The agent (ub_ag_…).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentHostsRequest'
      responses:
        '200':
          description: '`update` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAgentHostsResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    UpdateAgentHostsRequest:
      type: object
      description: Request body of `update_agent_hosts`.
      properties:
        hosts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                minLength: 1
                maxLength: 32
                description: >-
                  Stable inside the list: sender for the sender profile's row, a
                  minted handle (host_...) for a person; send it back to keep
                  the row.
              kind:
                type: string
                enum:
                  - sender
                  - person
                description: Default person; one sender row is kept whatever the list says.
              member_sid:
                type: string
                nullable: true
                minLength: 18
                maxLength: 18
                pattern: ^us_mb_
                description: >-
                  A team member (us_mb_...) when the host is one; null for a
                  free name.
              name:
                type: string
                nullable: true
                maxLength: 120
                description: >-
                  The name shown and said; a member's is read at the member when
                  null.
              link:
                type: string
                nullable: true
                maxLength: 512
                description: >-
                  Their own booking link, a URL; the sender row's is the team's
                  link to offer (the campaign's and the table's win over it).
              introduced_as:
                type: string
                nullable: true
                maxLength: 255
                description: >-
                  How the reply introduces them when they are not the sender
                  ("Peter, our co-founder, runs the demos"); said once, the
                  first time the call comes up.
              scenario_keys:
                type: array
                items:
                  type: string
                  maxLength: 64
                maxItems: 40
                description: >-
                  The platform keys and the team's own rows' sids this host
                  hosts; a key hosted by one host at most (the first that names
                  it keeps it). A scenario nobody names is the sender's.
          maxItems: 20
          description: >-
            The whole list, at most 20 rows; the sender row may be left out (it
            is kept with no link) or sent with its link.
      required:
        - hosts
    UpdateAgentHostsResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - update
        item:
          type: object
          properties:
            sid:
              type: string
              description: >-
                Agent sid (ub_ag_…). Stable for the life of the agent; a
                playtable or a workflow picks an agent by it.
            team_sid:
              type: string
              description: >-
                Owning team (ts_tm_…, external - gs.service.id). Many agents per
                team since block 10 (2026-10-30), at most 20.
            state:
              type: string
              enum:
                - setup_required
                - 'on'
                - 'off'
              description: >-
                setup_required = provisioned but disabled, inbox classifies
                only; on = planning and acting per the mode ladder; off =
                classification continues, nothing is planned or sent.
            mode:
              type: string
              enum:
                - copilot
                - autopilot
                - 'off'
              description: >-
                FALLBACK autonomy. The effective mode of a thread is the
                per-thread override, else the owning automation, else this.
            name:
              type: string
              description: Display name, 1..255 chars. The first agent ships as "AI SDR".
            is_default:
              type: boolean
              description: >-
                The team's default (block 10, 2026-10-30): exactly one agent per
                team carries it. A thread with no agent of its own, a playtable
                or a workflow that picks none, falls to it. Moved with
                update_agent {is_default: true}; never taken off directly.
            knowledge:
              type: object
              properties:
                booking_mode:
                  type: string
                  enum:
                    - link
                    - native
                  description: >-
                    link sends the host's link (default, the only live mode; the
                    sender host's since block AC4, where the Playbook goal's
                    link stood from 2026-10-19 and the knowledge's calendar link
                    before); native (slots in thread) is accepted but inert.
                source_urls:
                  type: array
                  items:
                    type: string
                    maxLength: 2048
                  maxItems: 20
                  description: Up to 20 sites scraped into the knowledge pack.
                interview_transcript_ref:
                  type: string
                  nullable: true
                  maxLength: 255
                  description: >-
                    Reference to the gs.agents.sdr setup-interview session, max
                    255 chars. A pointer, never a copy of the transcript.
              description: >-
                The questions and answers it answers from, the booking mode, the
                sites read. Its prose became the Brief on 2026-10-20.
            brief:
              type: object
              properties:
                text:
                  type: string
                  maxLength: 49152
                  description: >-
                    The Brief in markdown, the team's own words, max 49152
                    chars. A line in brackets ("- [a topic it should leave to
                    you]") is a slot still open: the model never reads it.
                compact:
                  type: string
                  nullable: true
                  maxLength: 8192
                  description: >-
                    [ro] The copy the model reads, max 8192 chars, written by
                    the compaction after a save that moved the text; null until
                    it lands (the text without its slots is read meanwhile).
                digest:
                  type: string
                  nullable: true
                  maxLength: 400
                  description: >-
                    [ro] The classifier's digest, max 400 chars, written by the
                    same compaction; null until it lands.
              required:
                - text
                - compact
                - digest
              description: >-
                The Brief (2026-10-20): the team's one markdown document every
                turn reads. A row stored before it reads its old offer, ICP,
                goal, general context and tone composed into the five sections.
            settings:
              type: object
              properties:
                max_auto_messages_per_conversation:
                  type: integer
                  minimum: 1
                  maximum: 20
                  description: >-
                    Agent-authored sends allowed on one thread. 1..20, default
                    4; the gate parks the next send for approval once it is
                    spent.
                followups_for_synced_threads:
                  type: boolean
                  description: >-
                    Default false: threads an external sequencer already follows
                    up on are left alone (double-touch protection).
                escalation_triggers:
                  type: array
                  items:
                    type: string
                    enum:
                      - pricing_question
                      - call_request
                      - legal_or_security
                      - multiple_reschedules
                      - low_confidence
                      - unknown_question
                      - job_seeker
                      - support_request
                  description: >-
                    Built-in hand-offs on; default: all but pricing_question and
                    call_request. Six judged by the classifier,
                    multiple_reschedules at the third, low_confidence under 0.5.
                    A firing stops the agent; a task names it; the thread goes
                    needs_you.
                classification_merge_seconds:
                  type: integer
                  minimum: 10
                  maximum: 600
                  description: >-
                    Debounce window that merges an inbound burst into ONE
                    classify run. 10..600, default 60.
                messages_recency_days:
                  type: integer
                  minimum: 1
                  maximum: 365
                  description: >-
                    How far back the thread tail is read into LLM context.
                    1..365, default 30.
                custom_escalation_triggers:
                  type: array
                  items:
                    type: string
                    minLength: 3
                    maxLength: 255
                  maxItems: 10
                  description: >-
                    The team's own hand-offs in words, each finishing: hand the
                    thread to a person when the lead ... Up to 10, 3..255 chars,
                    distinct; default none. They hand off like the built-in
                    ones, the task titled <lead>: <condition>. Replaced whole.
                after_person_message:
                  type: string
                  enum:
                    - plan_followups
                    - only_when_asked
                  description: >-
                    After a person on the team writes in a thread the AI SDR
                    works on, it stops sending there. plan_followups (default):
                    it plans the follow-ups for them, in their words, as a plan
                    waiting for their OK. only_when_asked: nothing until Make
                    follow-ups.
                person_followups_count:
                  type: integer
                  minimum: 1
                  maximum: 3
                  description: >-
                    How many follow-ups it plans after a person's message. 1..3,
                    default 2.
                person_followups_every_days:
                  type: integer
                  minimum: 1
                  maximum: 30
                  description: >-
                    Days between those follow-ups, counted from the person's
                    message; each goes at ten in the morning of the workspace's
                    day, never on a weekend. 1..30, default 3.
                person_followups_then:
                  type: string
                  enum:
                    - task
                    - agent_continues
                  description: >-
                    What ends them when none is answered: task (default) opens a
                    task for the person and the thread is theirs again;
                    agent_continues lets the AI SDR follow up on its own, under
                    its caps.
                reply_split:
                  type: string
                  enum:
                    - one_message
                    - two_or_three
                  description: >-
                    How a long LinkedIn reply goes out (2026-10-19):
                    two_or_three (default) cuts it at its paragraphs or
                    sentences into two or three messages a few seconds apart, as
                    a person sends them; one_message sends it whole. An email
                    never splits.
                credits_cap_per_conversation:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  description: >-
                    The credits the agent may spend on one thread (its turns'
                    model cost at 25 credits a dollar), 1..1000, default 40. At
                    the cap the thread is handed to a person with a task;
                    closing the task lets it go on, and the meter keeps
                    counting.
                handoff_notify_email:
                  type: boolean
                  description: >-
                    Default true: a hand-off (a trigger that fired, the credits
                    cap) is also told by email to the thread's sender profile
                    assignee, else the workspace owner. The task in the inbox is
                    always there.
                reply_language:
                  type: string
                  enum:
                    - lead
                    - en
                    - de
                    - es
                    - fr
                    - pt
                    - ru
                    - ar
                    - hi
                    - zh
                  description: >-
                    The language the agent writes in (2026-10-19): lead
                    (default) mirrors the language they write in; a code pins
                    every reply to that language whatever they write.
                learning:
                  type: object
                  properties:
                    from_history:
                      type: boolean
                      description: >-
                        Default true: after a sender profile's history walk, its
                        threads are paired by rule into the set.
                    from_own_sends:
                      type: boolean
                      description: >-
                        Default true: a person's own reply in a live thread
                        joins the set.
                    from_approved_edits:
                      type: boolean
                      description: >-
                        Default true: an agent draft a person edited before it
                        went joins the set, the person's words as the answer.
                    edits_join:
                      type: string
                      enum:
                        - after_ok
                        - on_its_own
                      description: >-
                        after_ok (default): an edited draft waits under From
                        your edits for a Keep; on_its_own: it joins at once.
                  description: >-
                    The golden set's roads (2026-10-20): what it learns from
                    (the history walk, a person's own replies, the drafts a
                    person edited) and whether an edit waits for a Keep.
              description: >-
                The behavior caps the mode gate and the planners enforce
                server-side.
            created_by:
              type: object
              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: >-
                Actor that provisioned the row (actor_type is system: the
                bootstrap job).
            rules:
              type: object
              properties:
                reply_words:
                  type: object
                  properties:
                    linkedin:
                      type: object
                      properties:
                        min:
                          type: integer
                          minimum: 5
                          maximum: 200
                          description: >-
                            The fewest words a reply runs on this channel,
                            5..200.
                        max:
                          type: integer
                          minimum: 5
                          maximum: 200
                          description: The most, 5..200, at least the min.
                      description: >-
                        Default 15 to 60: short replies get an answer about
                        twice as often.
                    email:
                      type: object
                      properties:
                        min:
                          type: integer
                          minimum: 5
                          maximum: 200
                          description: >-
                            The fewest words a reply runs on this channel,
                            5..200.
                        max:
                          type: integer
                          minimum: 5
                          maximum: 200
                          description: The most, 5..200, at least the min.
                      description: >-
                        Default 25 to 80: the middle half of the replies people
                        write back by email in the corpus.
                  description: The length band per channel, in words.
                meeting_ask:
                  type: string
                  enum:
                    - suggest_call_link_on_request
                    - ask_their_time
                    - suggest_call_with_link
                  description: >-
                    How it asks for the meeting: suggest_call_link_on_request
                    (default: a call suggested in one line, the link only when
                    they ask or say yes), ask_their_time (their time asked for,
                    no link), suggest_call_with_link (the call with the link in
                    the same message).
                confirm_named_time:
                  type: boolean
                  description: >-
                    Default true: a time they name is confirmed in one line and
                    nothing else is asked; a person puts it on the calendar.
                answer_then_call:
                  type: boolean
                  description: >-
                    Default true: a question before the call is answered in
                    short, then the ask.
                acknowledge_low_signal:
                  type: boolean
                  description: >-
                    Default true: a lead who only says thanks gets one friendly
                    line and the thread resumes its workflow.
                reply_delay_minutes:
                  type: object
                  properties:
                    min:
                      type: integer
                      minimum: 0
                      maximum: 60
                    max:
                      type: integer
                      minimum: 0
                      maximum: 60
                  description: >-
                    The wait before a reply on autopilot, a uniform pick between
                    the two, in minutes, 0..60; default 1 to 2.
                quiet_hours:
                  type: object
                  properties:
                    from:
                      type: string
                      description: '"HH:MM" 24h.'
                    to:
                      type: string
                      description: '"HH:MM" 24h; a to before the from spans midnight.'
                  description: >-
                    When no reply goes, in the lead's zone (the workspace's
                    today); default 22:00 to 07:00. from equal to to is never
                    quiet.
                weekends:
                  type: boolean
                  description: >-
                    Default true: it replies on weekends; false keeps the
                    weekend quiet.
                followups:
                  type: integer
                  minimum: 0
                  maximum: 6
                  description: >-
                    How many follow-ups when the lead goes quiet, 0..6; default
                    3 (the corpus: blocks climb with the fourth).
                followup_days:
                  type: integer
                  minimum: 1
                  maximum: 14
                  description: Days between them, 1..14; default 4.
                something_new:
                  type: boolean
                  description: >-
                    Default true: every follow-up brings something new (a proof,
                    a shorter ask, an easy way out), never a bump.
                checks:
                  type: object
                  properties:
                    unfilled_fields:
                      type: boolean
                      description: >-
                        A placeholder a template left ({{first_name}},
                        [Company]); refused as unfilled_field.
                    same_text_twice:
                      type: boolean
                      description: >-
                        A text the thread already carries from us; refused as
                        same_text_twice.
                    link_before_reply:
                      type: boolean
                      description: >-
                        A booking link before the lead ever wrote; refused as
                        link_before_reply.
                    stop_words:
                      type: boolean
                      description: >-
                        The Stop words of the golden set; refused as
                        words_caught.
                    long_dashes:
                      type: boolean
                      description: An em or en dash; refused as words_caught.
                    template_after_reply:
                      type: boolean
                      description: >-
                        The sequence's template sent after the lead replied; the
                        runner's check step.
                    signature_block:
                      type: boolean
                      description: >-
                        An email reply that ends in a signature block of its own
                        (the mailbox appends the team's); refused as
                        signature_block. Email only.
                  description: >-
                    The checks before it sends, each on (default) or off. Stop
                    after a no is the platform's and always on.
              description: >-
                The Rules (block AC4, 2026-10-26): what every reply keeps to; a
                row written before them reads as the corpus defaults. Read and
                changed on get_agent_rules / update_agent_rules too.
            hosts:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    minLength: 1
                    maxLength: 32
                    description: >-
                      Stable inside the list: sender for the sender profile's
                      row, a minted handle (host_...) for a person; send it back
                      to keep the row.
                  kind:
                    type: string
                    enum:
                      - sender
                      - person
                    description: >-
                      sender: the sender profile itself (one row, always kept);
                      person: a colleague.
                  member_sid:
                    type: string
                    nullable: true
                    minLength: 18
                    maxLength: 18
                    pattern: ^us_mb_
                    description: >-
                      A team member (us_mb_...) when the host is one; null for a
                      free name.
                  name:
                    type: string
                    nullable: true
                    maxLength: 120
                    description: >-
                      The name shown and said; a member's is read at the member
                      when null.
                  link:
                    type: string
                    nullable: true
                    maxLength: 512
                    description: >-
                      Their own booking link, a URL; the sender row's is the
                      team's link to offer (the campaign's and the table's win
                      over it).
                  introduced_as:
                    type: string
                    nullable: true
                    maxLength: 255
                    description: >-
                      How the reply introduces them when they are not the sender
                      ("Peter, our co-founder, runs the demos"); said once, the
                      first time the call comes up.
                  scenario_keys:
                    type: array
                    items:
                      type: string
                      maxLength: 64
                    maxItems: 40
                    description: >-
                      The platform keys and the team's own rows' sids this host
                      hosts; a key hosted by one host at most (the first that
                      names it keeps it). A scenario nobody names is the
                      sender's.
                required:
                  - id
                  - kind
                  - member_sid
                  - name
                  - link
                  - introduced_as
                  - scenario_keys
              description: >-
                Who hosts the meetings (block AC4): the sender row first,
                always, then colleagues; replaced whole on update_agent_hosts.
            goal:
              type: object
              nullable: true
              properties:
                kind:
                  type: string
                  enum:
                    - call
                    - signup
                    - webinar
                    - custom
                  description: >-
                    What the offer asks for: call (the stage after a yes books
                    it), signup, webinar or custom (no stage after the yes, no
                    link).
                words:
                  type: string
                  maxLength: 512
                  description: What it is, in the team's words; empty = the kind alone.
              required:
                - kind
                - words
              description: >-
                The agent's goal (block 10 step 10.3, 2026-10-30): the kind of
                what the offer asks for (call, signup, webinar, custom) and its
                words. Null = a call with no words. The link is never here: it
                is the sender host's (hosts[0].link), and a custom goal carries
                none.
            golden_set:
              type: object
              properties:
                words:
                  type: array
                  items:
                    type: object
                    properties:
                      never:
                        type: string
                        minLength: 1
                        maxLength: 64
                        description: >-
                          A word or a phrase the agent never writes, matched
                          whole and in any case, max 64 chars.
                      instead:
                        type: string
                        nullable: true
                        maxLength: 128
                        description: >-
                          What it says instead, max 128 chars; null: leave it
                          out.
                    required:
                      - never
                  description: The Words, up to 50, one entry per word in any case.
                voice:
                  type: object
                  nullable: true
                  properties:
                    summary:
                      type: string
                      nullable: true
                      description: >-
                        The team's voice in a few sentences, as the model reads
                        it; null while the set has not formed one and a person
                        set a line alone (block AC5).
                    length:
                      type: string
                      nullable: true
                      description: How long their replies run.
                    questions:
                      type: string
                      nullable: true
                      description: How they ask.
                    register:
                      type: string
                      nullable: true
                      description: The register they write in.
                    sign_off:
                      type: string
                      nullable: true
                      description: How they sign off.
                    formed_from:
                      type: integer
                      nullable: true
                      description: How many replies it was formed from.
                    formed_at:
                      type: string
                      nullable: true
                      description: ISO 8601 UTC, when it was formed.
                    model:
                      type: string
                      nullable: true
                      description: What formed it.
                    pinned:
                      type: array
                      items:
                        type: string
                      description: >-
                        The lines a person set (update_agent_voice, block AC5),
                        among length, questions, register, sign_off: theirs,
                        kept when the voice forms again.
                  required:
                    - summary
                  description: >-
                    The voice formed from the golden set, a minute after it
                    changed, with the lines a person set (update_agent_voice);
                    null until it has rows or a line.
              required:
                - words
                - voice
              description: >-
                The golden set's Words and voice (2026-10-20); the rows are
                search_agent_examples. A row written before it reads as no Words
                and no voice.
            setup:
              type: object
              properties:
                skipped:
                  type: array
                  items:
                    type: string
                    enum:
                      - brief
                      - knowledge
                      - golden_set
                      - test
                      - go_live
                  description: >-
                    The advised steps the team skipped on the way to go live, in
                    the steps' order.
              required:
                - skipped
              description: >-
                The advised steps to go live the team skipped (2026-10-20);
                include readiness says where each step stands.
            llm_config:
              type: object
              nullable: true
              properties:
                classification_model:
                  type: string
                  nullable: true
                  maxLength: 128
                  description: >-
                    Per-team override of the classify model, max 128 chars. null
                    = platform default.
                agent_model:
                  type: string
                  nullable: true
                  maxLength: 128
                  description: >-
                    Per-team override of the strategize / draft model, max 128
                    chars. null = platform default.
              description: >-
                Per-team model routing; null (the normal case) = platform
                defaults.
            setup_completed_at:
              type: string
              nullable: true
              description: >-
                ISO 8601 UTC, stamped the first time state left setup_required.
                null = setup never finished.
            created_at:
              type: string
              description: ISO 8601 UTC.
            updated_at:
              type: string
              description: ISO 8601 UTC.
            deleted_at:
              type: string
              nullable: true
              description: >-
                ISO 8601 UTC. Null on every agent a search lists; stamped by
                delete_agent.
          required:
            - sid
            - team_sid
            - state
            - mode
            - name
            - is_default
            - knowledge
            - brief
            - settings
            - created_by
            - rules
            - hosts
            - goal
            - golden_set
            - setup
            - llm_config
            - setup_completed_at
            - created_at
            - updated_at
            - deleted_at
        updated_fields:
          type: array
          items:
            type: string
        previous_values:
          type: object
          additionalProperties: {}
        kept_fields:
          type: array
          items:
            type: string
          description: >-
            The fields this write did not change because the person's own value
            stands on them (stamped person); read the item for what landed.
        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
        - item
        - updated_fields
        - previous_values
        - 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'
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gs.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.