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

# Add to the golden set

> Add to the golden set: Remember this reply (message_sid, a message of ours that went out, the lead's message before it as the situation: 201, or 200 already_exists when the set held it and it was promoted to golden) or a pair typed by hand (situation, answer, kind), born golden. 409 message_not_sent, message_has_no_situation.

Contract:
- MCP tool `create_agent_example`, registry package `mcp.unibox/agent_examples`, mount `unibox.agent-memory`.
- Operation `create`, response envelope `create`.
- Flags: none.



## OpenAPI

````yaml /api-reference/unibox/openapi.yaml post /api/agent-examples
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/agent-examples:
    post:
      tags:
        - agent_examples
      summary: Add to the golden set
      description: >-
        Add to the golden set: Remember this reply (message_sid, a message of
        ours that went out, the lead's message before it as the situation: 201,
        or 200 already_exists when the set held it and it was promoted to
        golden) or a pair typed by hand (situation, answer, kind), born golden.
        409 message_not_sent, message_has_no_situation.


        Contract:

        - MCP tool `create_agent_example`, registry package
        `mcp.unibox/agent_examples`, mount `unibox.agent-memory`.

        - Operation `create`, response envelope `create`.

        - Flags: none.
      operationId: create_agent_example
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentExampleRequest'
      responses:
        '200':
          description: '`create` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentExampleResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    CreateAgentExampleRequest:
      type: object
      description: Request body of `create_agent_example`.
      properties:
        agent_sid:
          type: string
          minLength: 18
          maxLength: 18
          pattern: ^ub_ag_
          description: >-
            The AI SDR it is made for (ub_ag_…, block 10, 2026-10-30); left out,
            the team's default agent.
        message_sid:
          type: string
          minLength: 18
          maxLength: 18
          pattern: ^ub_ms_
          description: >-
            Remember this reply: a message of ours that went out (ub_ms_…)
            becomes a golden row, the lead's message before it the situation;
            promoted when held already. 409 message_not_sent,
            message_has_no_situation. Takes note, not the fields below.
        situation:
          type: string
          minLength: 1
          maxLength: 4000
          description: >-
            A pair typed by hand: what the lead wrote, 1..4000 chars, names as
            placeholders ({lead}, {lead_company}, {sender}). Required with
            answer.
        answer:
          type: string
          minLength: 1
          maxLength: 8000
          description: The team's answer to it, 1..8000 chars. Required with situation.
        kind:
          type: string
          enum:
            - reply
            - followup
          description: reply (default) or followup.
        context_before:
          type: string
          nullable: true
          maxLength: 1500
          description: Our message before the lead's, max 1500 chars.
        channel:
          type: string
          nullable: true
          enum:
            - linkedin
            - email
          description: The channel it answers on; omit for every channel.
        scenario_key:
          type: string
          nullable: true
          maxLength: 64
          description: The scenario the situation belongs to (interested, objection, ...).
        note:
          type: string
          nullable: true
          maxLength: 512
          description: When the row applies, in a person's words, max 512 chars.
    CreateAgentExampleResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - create
        item:
          type: object
          properties:
            sid:
              type: string
              description: Golden set row sid (ub_eg_…).
            team_sid:
              type: string
              description: Owning team (ts_tm_…, external - gs.service.id).
            agent_sid:
              type: string
              nullable: true
              description: >-
                The AI SDR whose Golden set the row is in (ub_ag_…, block 10,
                2026-10-30); null on a row from before, read as the team's
                default's.
            tier:
              type: string
              enum:
                - golden
                - auto
              description: >-
                golden: a person vouched for it (Remember, a pair by hand, a
                Keep, a promotion), picked ahead; auto: learned by rule from the
                team's own sends.
            source:
              type: string
              enum:
                - history
                - own_send
                - approved_edit
                - remembered
                - document
                - manual
              description: >-
                history (the history walk's harvest), own_send (a person's reply
                in a live thread), approved_edit (an agent draft a person
                edited), remembered, manual (a pair typed by hand), document
                (kept from a conversations upload, block AC5).
            kind:
              type: string
              enum:
                - reply
                - followup
              description: >-
                reply: the team's answer to the lead's message; followup: our
                message after the lead went quiet.
            situation:
              type: string
              description: >-
                What the answer responds to: the lead's message(s), or our
                unanswered message for a follow-up. Names are placeholders:
                {lead}, {lead_company}, {sender}.
            answer:
              type: string
              description: >-
                The team's answer as it went out (or as the person wrote it),
                names as placeholders.
            sender_profile_sid:
              type: string
              nullable: true
              description: >-
                The sender profile that answered (ub_sp_…); null on a pair typed
                by hand.
            conversation_sid:
              type: string
              nullable: true
              description: >-
                The thread the pair was read from (ub_cv_…); null on a pair
                typed by hand.
            message_sid:
              type: string
              nullable: true
              description: >-
                The outbound message the answer is (ub_ms_…); one row per
                message. Null on a pair typed by hand.
            document_sid:
              type: string
              nullable: true
              description: >-
                The conversations upload the dialogue was kept from (ub_cu_…,
                block AC5); null on every other source.
            channel:
              type: string
              nullable: true
              enum:
                - linkedin
                - email
              description: >-
                The channel the answer went on; null on a pair typed by hand
                (read on every channel).
            scenario_key:
              type: string
              nullable: true
              description: >-
                The classified scenario of the situation (interested, objection,
                ...) when known.
            context_before:
              type: string
              nullable: true
              description: >-
                Our message before the lead's, the context the situation reads
                against; null on a follow-up.
            draft_text:
              type: string
              nullable: true
              description: >-
                approved_edit only: the agent's draft before the person's edit,
                beside the answer they sent.
            note:
              type: string
              nullable: true
              description: A person's note on when the row applies, max 512 chars.
            seen_count:
              type: integer
              minimum: 1
              description: How often the same answer was met across the team's threads.
            used_count:
              type: integer
              minimum: 0
              description: How many agent turns the row was shown to.
            last_used_at:
              type: string
              nullable: true
              description: ISO 8601 UTC of the last turn that read it; null when none did.
            answered_at:
              type: string
              nullable: true
              description: ISO 8601 UTC, when the answer went out.
            embedding_state:
              type: string
              enum:
                - pending
                - ready
                - failed
              description: >-
                pending until the vector is written, ready when the pick can
                read it, failed after three tries (an edit of the situation
                sends it back to pending).
            embedding_model:
              type: string
              nullable: true
              description: provider/model that wrote the vector; null while pending.
            golden_by:
              type: object
              nullable: true
              properties:
                actor_type:
                  type: string
                  enum:
                    - user
                    - support
                    - api_key
                    - system
                    - agent
                actor_sid:
                  type: string
                  nullable: true
                team_sid:
                  type: string
                actor_name:
                  type: string
                  nullable: true
                  description: >-
                    The OAuth client that acted ("Claude", "n8n"); null for a
                    user, an API key or a system job.
                oauth_client_sid:
                  type: string
                  nullable: true
                  description: The acting OAuth client (id_oc_*); null off the OAuth path.
                reason:
                  type: string
                  nullable: true
                  description: >-
                    Why a system actor wrote the row (snapshot_capture_job,
                    ...); null otherwise.
                permissions:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Internal audit context: the grant set the actor held at
                    write time. Not a contract.
                cluster_id:
                  type: integer
                  nullable: true
                  description: 'Internal audit context: the cluster that served the write.'
                trace_id:
                  type: string
                  nullable: true
                  description: >-
                    Internal audit context: the trace id of the request that
                    wrote the row.
              required:
                - actor_type
                - actor_sid
                - team_sid
                - permissions
              description: Who made the row golden; null on an auto row.
            golden_at:
              type: string
              nullable: true
              description: ISO 8601 UTC, when it became golden; null on an auto row.
            proposed_at:
              type: string
              nullable: true
              description: >-
                Set while an edited draft waits for a person's Keep (From your
                edits): such a row is never picked. Null once in the set.
            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: The actor whose write bore the row (the system for the harvest).
            deleted_by:
              type: object
              nullable: true
              properties:
                actor_type:
                  type: string
                  enum:
                    - user
                    - support
                    - api_key
                    - system
                    - agent
                actor_sid:
                  type: string
                  nullable: true
                team_sid:
                  type: string
                actor_name:
                  type: string
                  nullable: true
                  description: >-
                    The OAuth client that acted ("Claude", "n8n"); null for a
                    user, an API key or a system job.
                oauth_client_sid:
                  type: string
                  nullable: true
                  description: The acting OAuth client (id_oc_*); null off the OAuth path.
                reason:
                  type: string
                  nullable: true
                  description: >-
                    Why a system actor wrote the row (snapshot_capture_job,
                    ...); null otherwise.
                permissions:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Internal audit context: the grant set the actor held at
                    write time. Not a contract.
                cluster_id:
                  type: integer
                  nullable: true
                  description: 'Internal audit context: the cluster that served the write.'
                trace_id:
                  type: string
                  nullable: true
                  description: >-
                    Internal audit context: the trace id of the request that
                    wrote the row.
              required:
                - actor_type
                - actor_sid
                - team_sid
                - permissions
              description: Who forgot it; null on a live row.
            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 once forgotten; null on a live row.
          required:
            - sid
            - team_sid
            - agent_sid
            - tier
            - source
            - kind
            - situation
            - answer
            - sender_profile_sid
            - conversation_sid
            - message_sid
            - document_sid
            - channel
            - scenario_key
            - context_before
            - draft_text
            - note
            - seen_count
            - used_count
            - last_used_at
            - answered_at
            - embedding_state
            - embedding_model
            - golden_by
            - golden_at
            - proposed_at
            - created_by
            - deleted_by
            - created_at
            - updated_at
            - deleted_at
        already_exists:
          type: boolean
        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
        - already_exists
        - 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.