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

# Teach the agent (preview, then commit)

> Teach the AI SDR from what a person said: about one of its replies (run_sid, a row of search_agent_runs) or about the agent at large (no run: "we do not work with agencies", on agent_sid or the team's default). Two calls, one tool. The first, without proposal, is the preview: the composer says where the fix belongs (a Knowledge answer, the reply as the golden set should hold it, a line of the Brief, a line of the voice, a field of the Rules with its value, or a line on a step of the scenario the reply came from), drafts it in that place's own shape and explains in a sentence; place asks for one place's draft; nothing is written, and result.commit_token comes back. Show the draft; then the second call, with proposal (the draft as it is or as the person edited it) and commit_token, adds it through the place's own verb: result.applied says what was added and what stood before (Undo through that verb), result.hints_resolved the reply's open hints it resolved. 503 composer_unavailable; 409 fix_not_routed (say it another way, or pick the place); 422 invalid_commit_token or commit_token_expired (preview again); 409 brief_section_missing, scenario_missing, scenario_step_missing, scenario_step_full; 422 a Rules value out of range. The agent's own token is 403.

Contract:
- MCP tool `route_agent_fix`, registry package `mcp.unibox/agents`, mount `ai-sdr.training`.
- Operation `action`, response envelope `action`.
- Flags: none.



## OpenAPI

````yaml /api-reference/unibox/openapi.yaml post /api/agents/fix
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`, 97 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://api2.getsales.io/unibox/v1
    description: Production
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: agent_answers
    description: >-
      Registry package `mcp.unibox/agent_answers`, served on MCP mount
      `ai-sdr.training`.
  - name: agent_conversation_uploads
    description: >-
      Registry package `mcp.unibox/agent_conversation_uploads`, served on MCP
      mount `ai-sdr.training`.
  - name: agent_examples
    description: >-
      Registry package `mcp.unibox/agent_examples`, served on MCP mount
      `ai-sdr.training`.
  - name: agent_hints
    description: >-
      Registry package `mcp.unibox/agent_hints`, served on MCP mount
      `ai-sdr.training`.
  - name: agent_plans
    description: >-
      Registry package `mcp.unibox/agent_plans`, served on MCP mount
      `ai-sdr.agents`.
  - name: agent_runs
    description: >-
      Registry package `mcp.unibox/agent_runs`, served on MCP mount
      `ai-sdr.agents`.
  - name: agent_scenarios
    description: >-
      Registry package `mcp.unibox/agent_scenarios`, served on MCP mount
      `ai-sdr.agents`.
  - name: agent_source_parses
    description: >-
      Registry package `mcp.unibox/agent_source_parses`, served on MCP mount
      `ai-sdr.training`.
  - name: agent_sources
    description: >-
      Registry package `mcp.unibox/agent_sources`, served on MCP mount
      `ai-sdr.training`.
  - name: agent_tests
    description: >-
      Registry package `mcp.unibox/agent_tests`, served on MCP mount
      `ai-sdr.training`.
  - name: agents
    description: >-
      Registry package `mcp.unibox/agents`, served on MCP mount
      `workspace.team`.
  - name: conversations
    description: Registry package `mcp.unibox/conversations`, served on MCP mount `inbox`.
  - name: messages
    description: Registry package `mcp.unibox/messages`, served on MCP mount `inbox`.
  - name: sender_profile_variables
    description: >-
      Registry package `mcp.unibox/sender_profile_variables`, served on MCP
      mount `sender-profiles`.
  - name: sender_profiles
    description: >-
      Registry package `mcp.unibox/sender_profiles`, served on MCP mount
      `sender-profiles`.
  - name: tasks
    description: Registry package `mcp.unibox/tasks`, served on MCP mount `inbox`.
  - name: timeline
    description: Registry package `mcp.unibox/timeline`, served on MCP mount `inbox`.
paths:
  /api/agents/fix:
    post:
      tags:
        - agents
      summary: Teach the agent (preview, then commit)
      description: >-
        Teach the AI SDR from what a person said: about one of its replies
        (run_sid, a row of search_agent_runs) or about the agent at large (no
        run: "we do not work with agencies", on agent_sid or the team's
        default). Two calls, one tool. The first, without proposal, is the
        preview: the composer says where the fix belongs (a Knowledge answer,
        the reply as the golden set should hold it, a line of the Brief, a line
        of the voice, a field of the Rules with its value, or a line on a step
        of the scenario the reply came from), drafts it in that place's own
        shape and explains in a sentence; place asks for one place's draft;
        nothing is written, and result.commit_token comes back. Show the draft;
        then the second call, with proposal (the draft as it is or as the person
        edited it) and commit_token, adds it through the place's own verb:
        result.applied says what was added and what stood before (Undo through
        that verb), result.hints_resolved the reply's open hints it resolved.
        503 composer_unavailable; 409 fix_not_routed (say it another way, or
        pick the place); 422 invalid_commit_token or commit_token_expired
        (preview again); 409 brief_section_missing, scenario_missing,
        scenario_step_missing, scenario_step_full; 422 a Rules value out of
        range. The agent's own token is 403.


        Contract:

        - MCP tool `route_agent_fix`, registry package `mcp.unibox/agents`,
        mount `ai-sdr.training`.

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

        - Flags: none.
      operationId: route_agent_fix
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RouteAgentFixRequest'
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteAgentFixResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    RouteAgentFixRequest:
      type: object
      description: Request body of `route_agent_fix`.
      properties:
        agent_sid:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^ub_ag_
          description: >-
            The AI SDR the fix is about (ub_ag_…) when no run is named; left
            out, the team's default. With run_sid the run's own agent is the
            one, whatever is sent here.
        run_sid:
          type: string
          nullable: true
          minLength: 18
          maxLength: 18
          pattern: ^ub_rn_
          description: >-
            The run whose reply the fix is about (ub_rn_…), a row of the
            Analyzer's log (search_agent_runs with filter.outcome); left out,
            the fix is about the agent at large.
        text:
          type: string
          minLength: 1
          maxLength: 2000
          description: >-
            What the person said, typed or dictated, as they said it (1..2000
            chars): about the reply, or about the agent ("we do not work with
            agencies").
        place:
          type: string
          nullable: true
          enum:
            - knowledge
            - golden_set
            - brief
            - voice
            - rules
            - scenario
          description: >-
            The place the person picked, for its draft: knowledge (a fact),
            golden_set (the reply as it should have gone; a run needed), brief
            (a standing rule), voice (one of its four lines), rules (a setting),
            scenario (a step's line). Left out, the composer picks.
        proposal:
          anyOf:
            - type: object
              properties:
                place:
                  type: string
                  enum:
                    - knowledge
                title:
                  type: string
                  minLength: 1
                  maxLength: 120
                  description: >-
                    The question leads ask, as they put it, which the answer
                    answers (1..120 chars).
                text:
                  type: string
                  minLength: 1
                  maxLength: 1200
                  description: >-
                    The answer: plain sentences that stand on their own (1..1200
                    chars).
              required:
                - place
                - title
                - text
            - type: object
              properties:
                place:
                  type: string
                  enum:
                    - golden_set
                situation:
                  type: string
                  minLength: 1
                  maxLength: 2000
                  description: >-
                    What the lead wrote, the message the reply answered (1..2000
                    chars).
                answer:
                  type: string
                  minLength: 1
                  maxLength: 2000
                  description: >-
                    The reply as it should have gone, exactly as it would go out
                    (1..2000 chars).
              required:
                - place
                - situation
                - answer
            - type: object
              properties:
                place:
                  type: string
                  enum:
                    - brief
                section:
                  type: string
                  minLength: 1
                  maxLength: 300
                  description: >-
                    The Brief's section the line goes under, by its own heading
                    as the preview named it.
                line:
                  type: string
                  minLength: 1
                  maxLength: 300
                  description: >-
                    The line added at the end of that section, one or two plain
                    sentences (1..300 chars).
              required:
                - place
                - section
                - line
            - type: object
              properties:
                place:
                  type: string
                  enum:
                    - voice
                line:
                  type: string
                  minLength: 1
                  maxLength: 16
                  description: >-
                    Which of the voice's four lines the fix sets: length,
                    questions, register or sign_off (AgentVoiceValue::LINES, a
                    list on the Value, not an enum).
                text:
                  type: string
                  minLength: 1
                  maxLength: 160
                  description: >-
                    The whole line as it should read from now on, in a few words
                    to the agent (1..160 chars); set and pinned as
                    update_agent_voice sets it.
              required:
                - place
                - line
                - text
            - type: object
              properties:
                place:
                  type: string
                  enum:
                    - rules
                field:
                  type: string
                  minLength: 1
                  maxLength: 64
                  description: >-
                    The Rules field by its dotted path as the preview named it:
                    reply_words.linkedin.max, meeting_ask,
                    reply_delay_minutes.min, quiet_hours.from, weekends,
                    followups, followup_days, checks.stop_words and the rest of
                    the Rules on get_agent.
                value:
                  anyOf:
                    - type: string
                    - type: number
                    - type: boolean
                  description: >-
                    The new value within what the field takes (a whole number in
                    its range, true or false, a choice of the enum, a time as
                    HH:MM); the Rules refuse one outside it (422).
              required:
                - place
                - field
                - value
            - type: object
              properties:
                place:
                  type: string
                  enum:
                    - scenario
                scenario:
                  type: string
                  minLength: 1
                  maxLength: 64
                  description: >-
                    The scenario the line goes on: a platform scenario's key
                    (info_request) or the team's own scenario's sid (ub_sc_…),
                    as the preview named it.
                step:
                  type: string
                  minLength: 1
                  maxLength: 32
                  description: >-
                    The id of the step the line goes on (reply, playbook,
                    nudge…), one of the scenario's steps as the preview listed
                    them.
                line:
                  type: string
                  minLength: 1
                  maxLength: 300
                  description: >-
                    The instruction added under the step's instructions, one or
                    two plain sentences to the agent (1..300 chars).
              required:
                - place
                - scenario
                - step
                - line
            - {}
          description: >-
            The commit: the preview's result.proposal as drafted or as the
            person edited it, in its place's own shape (one of the six objects
            here, place first). Left out, the call is the preview and writes
            nothing.
        commit_token:
          type: string
          nullable: true
          maxLength: 512
          description: >-
            The preview's result.commit_token, required with proposal: minted
            for this text, agent and run, good for fifteen minutes (422
            invalid_commit_token, commit_token_expired: ask for the draft
            again).
      required:
        - text
    RouteAgentFixResponse:
      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: {}
        result:
          type: object
          properties:
            preview:
              type: boolean
              description: >-
                true: the draft, nothing written (place, proposal, sentence,
                commit_token); false: written (applied, hints_resolved).
            agent_sid:
              type: string
              description: The AI SDR the fix is about or landed on (ub_ag_…).
            run_sid:
              type: string
              nullable: true
              description: >-
                The run the fix is about (ub_rn_…); null for a fix said with no
                reply in front.
            place:
              type: string
              enum:
                - knowledge
                - golden_set
                - brief
                - voice
                - rules
                - scenario
              description: 'Preview: where the fix belongs.'
            proposal:
              anyOf:
                - type: object
                  properties:
                    place:
                      type: string
                      enum:
                        - knowledge
                    title:
                      type: string
                      minLength: 1
                      maxLength: 120
                      description: >-
                        The question leads ask, as they put it, which the answer
                        answers (1..120 chars).
                    text:
                      type: string
                      minLength: 1
                      maxLength: 1200
                      description: >-
                        The answer: plain sentences that stand on their own
                        (1..1200 chars).
                  required:
                    - place
                    - title
                    - text
                - type: object
                  properties:
                    place:
                      type: string
                      enum:
                        - golden_set
                    situation:
                      type: string
                      minLength: 1
                      maxLength: 2000
                      description: >-
                        What the lead wrote, the message the reply answered
                        (1..2000 chars).
                    answer:
                      type: string
                      minLength: 1
                      maxLength: 2000
                      description: >-
                        The reply as it should have gone, exactly as it would go
                        out (1..2000 chars).
                  required:
                    - place
                    - situation
                    - answer
                - type: object
                  properties:
                    place:
                      type: string
                      enum:
                        - brief
                    section:
                      type: string
                      minLength: 1
                      maxLength: 300
                      description: >-
                        The Brief's section the line goes under, by its own
                        heading as the preview named it.
                    line:
                      type: string
                      minLength: 1
                      maxLength: 300
                      description: >-
                        The line added at the end of that section, one or two
                        plain sentences (1..300 chars).
                  required:
                    - place
                    - section
                    - line
                - type: object
                  properties:
                    place:
                      type: string
                      enum:
                        - voice
                    line:
                      type: string
                      minLength: 1
                      maxLength: 16
                      description: >-
                        Which of the voice's four lines the fix sets: length,
                        questions, register or sign_off (AgentVoiceValue::LINES,
                        a list on the Value, not an enum).
                    text:
                      type: string
                      minLength: 1
                      maxLength: 160
                      description: >-
                        The whole line as it should read from now on, in a few
                        words to the agent (1..160 chars); set and pinned as
                        update_agent_voice sets it.
                  required:
                    - place
                    - line
                    - text
                - type: object
                  properties:
                    place:
                      type: string
                      enum:
                        - rules
                    field:
                      type: string
                      minLength: 1
                      maxLength: 64
                      description: >-
                        The Rules field by its dotted path as the preview named
                        it: reply_words.linkedin.max, meeting_ask,
                        reply_delay_minutes.min, quiet_hours.from, weekends,
                        followups, followup_days, checks.stop_words and the rest
                        of the Rules on get_agent.
                    value:
                      anyOf:
                        - type: string
                        - type: number
                        - type: boolean
                      description: >-
                        The new value within what the field takes (a whole
                        number in its range, true or false, a choice of the
                        enum, a time as HH:MM); the Rules refuse one outside it
                        (422).
                  required:
                    - place
                    - field
                    - value
                - type: object
                  properties:
                    place:
                      type: string
                      enum:
                        - scenario
                    scenario:
                      type: string
                      minLength: 1
                      maxLength: 64
                      description: >-
                        The scenario the line goes on: a platform scenario's key
                        (info_request) or the team's own scenario's sid
                        (ub_sc_…), as the preview named it.
                    step:
                      type: string
                      minLength: 1
                      maxLength: 32
                      description: >-
                        The id of the step the line goes on (reply, playbook,
                        nudge…), one of the scenario's steps as the preview
                        listed them.
                    line:
                      type: string
                      minLength: 1
                      maxLength: 300
                      description: >-
                        The instruction added under the step's instructions, one
                        or two plain sentences to the agent (1..300 chars).
                  required:
                    - place
                    - scenario
                    - step
                    - line
              description: >-
                Preview: its draft in the place's own shape; pass it back as it
                is or as the person edited it.
            sentence:
              type: string
              description: >-
                Preview: the composer's one line on what goes where ("Suggested:
                ..."), a value to show the person.
            commit_token:
              type: string
              description: 'Preview: the token the commit carries back.'
            expires_at:
              type: string
              description: 'Preview: ISO 8601 UTC, when the token lapses (fifteen minutes).'
            applied:
              type: object
              properties:
                place:
                  type: string
                  enum:
                    - knowledge
                    - golden_set
                    - brief
                    - voice
                    - rules
                    - scenario
                  description: Where it was added.
                sid:
                  type: string
                  nullable: true
                  description: >-
                    The answer (ub_an_…) or the golden row (ub_eg_…) it became;
                    scenario: the scenario's key or sid the line went on; null
                    for a Brief line, a voice line and a Rules field.
                section:
                  type: string
                  nullable: true
                  description: >-
                    Where inside the place: brief: the section the line went
                    under, by its heading; voice: the line set (length,
                    questions, register, sign_off); rules: the field's path;
                    scenario: the step's id; null otherwise.
                line:
                  type: string
                  nullable: true
                  description: >-
                    What was added, as words: brief and scenario: the line;
                    voice: the line's text; rules: the value (on or off for a
                    switch); null otherwise.
                was:
                  anyOf:
                    - type: string
                    - type: number
                    - type: boolean
                    - {}
                  description: >-
                    What stood before, for Undo: voice: the line's text (null
                    when none, so Undo lets the line go with update_agent_voice;
                    learned on that tool when was_pinned is false); rules: the
                    value before (put back with update_agent_rules); scenario:
                    default when the agent had no version of it
                    (reset_agent_scenario), default_steps when its version
                    followed the default's steps (update_agent_scenario with
                    steps null), null when the steps were its own (the line out
                    of the step's instructions); null otherwise.
                was_pinned:
                  type: boolean
                  description: 'Voice: whether the text before was a person''s (pinned).'
              required:
                - place
                - sid
                - section
                - line
                - was
              description: >-
                Commit: what was added. It is taken back through the place's own
                verbs: delete_agent_answer, forget_agent_examples with
                filter.sid, update_agent with the Brief, update_agent_voice,
                update_agent_rules; a scenario as `was` says.
            hints_resolved:
              type: array
              items:
                type: string
              description: >-
                Commit: the hints (ub_hn_…) the fix resolved (block AC7,
                2026-10-27): the open ones of the place the reply hit, Knowledge
                for a missing answer, the Golden set for a missing dialogue,
                resolved by what the fix became with this run named on the
                hint's history; [] otherwise, and without a run.
          required:
            - preview
            - agent_sid
            - run_sid
        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'
    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.