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

> Rename a play, re-aim its audience, change a find_people play's prompt or cap, pick the workflow of a people play that waits for one (once; fixed after), change the cadence, flip the switch, set the ceiling. enabled true is the consent and makes the play due now (422 on a people play with no workflow yet); enabled false stops the next run and cancels nothing in flight; cadence manual switches it off. The sources are fixed at birth. Nothing changed is 422 nothing_to_update.

Contract:
- MCP tool `update_play`, registry package `mcp.playtables/plays`, mount `playtables.pipeline`.
- Operation `update`, response envelope `update`.
- Flags: none.



## OpenAPI

````yaml /api-reference/playtables/openapi.yaml patch /api/plays/{sid}
openapi: 3.0.3
info:
  title: 'GetSales public contract: gs.service.playtables'
  description: >-
    The data platform and the outreach engine: tables of people and companies,
    their enrichment columns, cells and runs, the data sources that feed them,
    sender profiles, the stoplist, the activity feed, the credit ledger, and the
    multichannel workflows with their per-person journeys and tasks.


    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.playtables`, 142
    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/playtables/v1
    description: >-
      Production (the gateway path on the beta ring; the origin is provisioned
      per DEPLOY_MAP.md)
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: activities
    description: >-
      Registry package `mcp.playtables/activities`, served on MCP mount
      `playtables.journeys`.
  - name: activity_objects
    description: >-
      Registry package `mcp.playtables/activity_objects`, served on MCP mount
      `playtables.people`.
  - name: companies
    description: >-
      Registry package `mcp.playtables/companies`, served on MCP mount
      `playtables.people`.
  - name: credit_ledger_entries
    description: >-
      Registry package `mcp.playtables/credit_ledger_entries`, served on MCP
      mount `id.billing`.
  - name: data_source_items
    description: >-
      Registry package `mcp.playtables/data_source_items`, served on MCP mount
      `playtables.sources`.
  - name: data_sources
    description: >-
      Registry package `mcp.playtables/data_sources`, served on MCP mount
      `playtables.sources`.
  - name: notes
    description: >-
      Registry package `mcp.playtables/notes`, served on MCP mount
      `playtables.pipeline`.
  - name: people
    description: >-
      Registry package `mcp.playtables/people`, served on MCP mount
      `playtables.people`.
  - name: pipeline_stages
    description: >-
      Registry package `mcp.playtables/pipeline_stages`, served on MCP mount
      `playtables.pipeline`.
  - name: plays
    description: >-
      Registry package `mcp.playtables/plays`, served on MCP mount
      `playtables.pipeline`.
  - name: playtable_field_values
    description: >-
      Registry package `mcp.playtables/playtable_field_values`, served on MCP
      mount `playtables.columns`.
  - name: playtable_fields
    description: >-
      Registry package `mcp.playtables/playtable_fields`, served on MCP mount
      `playtables.columns`.
  - name: playtable_runs
    description: >-
      Registry package `mcp.playtables/playtable_runs`, served on MCP mount
      `playtables.columns`.
  - name: playtable_views
    description: >-
      Registry package `mcp.playtables/playtable_views`, served on MCP mount
      `playtables.tables`.
  - name: playtables
    description: >-
      Registry package `mcp.playtables/playtables`, served on MCP mount
      `playtables.tables`.
  - name: result_pages
    description: >-
      Registry package `mcp.playtables/result_pages`, served on MCP mount
      `playtables.tables`.
  - name: sender_profiles
    description: >-
      Registry package `mcp.playtables/sender_profiles`, served on MCP mount
      `playtables.sources`.
  - name: stoplist_entries
    description: >-
      Registry package `mcp.playtables/stoplist_entries`, served on MCP mount
      `playtables.stoplist`.
  - name: tags
    description: >-
      Registry package `mcp.playtables/tags`, served on MCP mount
      `playtables.pipeline`.
  - name: workflow_attachments
    description: >-
      Registry package `mcp.playtables/workflow_attachments`, served on MCP
      mount `playtables.workflows`.
  - name: workflow_records
    description: >-
      Registry package `mcp.playtables/workflow_records`, served on MCP mount
      `playtables.journeys`.
  - name: workflow_sources
    description: >-
      Registry package `mcp.playtables/workflow_sources`, served on MCP mount
      `playtables.workflows`.
  - name: workflow_tasks
    description: >-
      Registry package `mcp.playtables/workflow_tasks`, served on MCP mount
      `playtables.journeys`.
  - name: workflow_versions
    description: >-
      Registry package `mcp.playtables/workflow_versions`, served on MCP mount
      `playtables.workflows`.
  - name: workflows
    description: >-
      Registry package `mcp.playtables/workflows`, served on MCP mount
      `playtables.workflows`.
paths:
  /api/plays/{sid}:
    patch:
      tags:
        - plays
      summary: Update play
      description: >-
        Rename a play, re-aim its audience, change a find_people play's prompt
        or cap, pick the workflow of a people play that waits for one (once;
        fixed after), change the cadence, flip the switch, set the ceiling.
        enabled true is the consent and makes the play due now (422 on a people
        play with no workflow yet); enabled false stops the next run and cancels
        nothing in flight; cadence manual switches it off. The sources are fixed
        at birth. Nothing changed is 422 nothing_to_update.


        Contract:

        - MCP tool `update_play`, registry package `mcp.playtables/plays`, mount
        `playtables.pipeline`.

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

        - Flags: none.
      operationId: update_play
      parameters:
        - name: sid
          in: path
          required: true
          description: Play sid (pt_pl_…).
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^pt_pl_
            description: Play sid (pt_pl_…).
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePlayRequest'
      responses:
        '200':
          description: '`update` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePlayResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    UpdatePlayRequest:
      type: object
      description: Request body of `update_play`.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: New name of the play (1..255).
        audience:
          description: A new audience, validated like at create; null = the whole tab.
        action:
          type: object
          properties:
            prompt:
              type: string
              nullable: true
              maxLength: 2000
            per_company_limit:
              type: integer
              nullable: true
              minimum: 1
              maximum: 25
            workflow_sid:
              type: string
              minLength: 18
              maxLength: 18
              pattern: ^wf_wf_
              description: >-
                add_to_workflow: the workflow of a play that still waits for
                one; births the play's manual source there. Picked once: another
                workflow is refused (422), reset the play (delete_play) to pick
                again.
            moments:
              type: object
              properties:
                birthday:
                  type: object
                  properties:
                    'on':
                      type: boolean
                      description: The moment's switch.
                    do:
                      type: string
                      enum:
                        - send_message
                        - add_to_workflow
                      description: >-
                        While on: a message (the template, sent as the person's
                        connected sender profile) or the workflow the person
                        enters.
                    template:
                      type: string
                      nullable: true
                      maxLength: 2000
                      description: >-
                        The message, in the workflow template grammar
                        ({{people.first_name}}).
                    workflow_sid:
                      type: string
                      nullable: true
                      description: 'wf_wf_…: the workflow, when the Do is a workflow.'
                  required:
                    - 'on'
                    - do
                    - template
                    - workflow_sid
                work_anniversary:
                  type: object
                  properties:
                    'on':
                      type: boolean
                      description: The moment's switch.
                    do:
                      type: string
                      enum:
                        - send_message
                        - add_to_workflow
                      description: >-
                        While on: a message (the template, sent as the person's
                        connected sender profile) or the workflow the person
                        enters.
                    template:
                      type: string
                      nullable: true
                      maxLength: 2000
                      description: >-
                        The message, in the workflow template grammar
                        ({{people.first_name}}).
                    workflow_sid:
                      type: string
                      nullable: true
                      description: 'wf_wf_…: the workflow, when the Do is a workflow.'
                  required:
                    - 'on'
                    - do
                    - template
                    - workflow_sid
                job_change:
                  type: object
                  properties:
                    'on':
                      type: boolean
                      description: The moment's switch.
                    do:
                      type: string
                      enum:
                        - send_message
                        - add_to_workflow
                      description: >-
                        While on: a message (the template, sent as the person's
                        connected sender profile) or the workflow the person
                        enters.
                    template:
                      type: string
                      nullable: true
                      maxLength: 2000
                      description: >-
                        The message, in the workflow template grammar
                        ({{people.first_name}}).
                    workflow_sid:
                      type: string
                      nullable: true
                      description: 'wf_wf_…: the workflow, when the Do is a workflow.'
                  required:
                    - 'on'
                    - do
                    - template
                    - workflow_sid
              description: 'congratulate: one moment''s keys move alone, the others stay.'
            do:
              type: string
            like:
              type: object
              properties:
                'on':
                  type: boolean
                reaction:
                  type: string
                  enum:
                    - ai
                    - like
                    - celebrate
                    - support
                    - love
                    - insightful
                    - funny
                  description: >-
                    ai = the AI reads the post and picks one of the six; else
                    always this one. One reaction a post, never changed later.
            comment:
              type: object
              properties:
                'on':
                  type: boolean
                brief:
                  type: string
                  nullable: true
                  maxLength: 2000
                  description: What the AI writes the comment from; required while on.
            per_person_weekly_cap:
              type: integer
              minimum: 1
              maximum: 14
            sender_profile_sid:
              type: string
              nullable: true
            pages:
              type: array
              nullable: true
              items:
                type: string
          description: >-
            A find_people play's prompt and cap, the workflow of a people play
            that waits for one, or a typed action's keys merged deep over the
            stored ones; the sources are fixed at birth.
        watch:
          type: object
          nullable: true
          properties:
            profile_days:
              anyOf:
                - type: number
                  enum:
                    - 7
                - type: number
                  enum:
                    - 14
                - type: number
                  enum:
                    - 30
                - type: number
                  enum:
                    - 90
                - {}
              description: >-
                The LinkedIn profile every N days: 7 | 14 | 30 | 90; null = not
                watched.
            company_days:
              anyOf:
                - type: number
                  enum:
                    - 30
                - type: number
                  enum:
                    - 90
                - {}
              description: 'The company page every N days: 30 | 90; null = not watched.'
            posts_days:
              anyOf:
                - type: number
                  enum:
                    - 1
                - type: number
                  enum:
                    - 3
                - type: number
                  enum:
                    - 7
                - {}
              description: 'The person''s posts every N days: 1 | 3 | 7; null = not watched.'
            moments:
              type: boolean
              description: >-
                The network's moments (birthdays, work anniversaries, job
                changes) through the sender profiles' catch-up feed, daily,
                free.
          description: The whole block, or null for nothing.
        mode:
          type: string
          enum:
            - ask_me
            - automatic
          description: >-
            ask_me (the act waits for approval as a task in the Signals feed) |
            automatic (it goes out by itself).
        cadence:
          type: string
          enum:
            - manual
            - daily
          description: manual switches the play off.
        enabled:
          type: boolean
          description: >-
            The switch: true records the consent (enabled_by, enabled_at) and
            makes the play due now; false stops the next run, nothing in flight
            is cancelled.
        daily_credit_limit:
          type: integer
          nullable: true
          minimum: 1
          description: >-
            find_people only: the credits one day may spend; null = no ceiling.
            422 on an add_to_workflow play.
    UpdatePlayResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - update
        item:
          type: object
          properties:
            sid:
              type: string
              description: Play sid (pt_pl_…).
            team_sid:
              type: string
              description: Owning team (ts_tm_…).
            playtable_sid:
              type: string
              description: >-
                The table the play lives in (pt_tb_…): its tab, and the scope of
                its audience.
            catalog_key:
              type: string
              nullable: true
              enum:
                - keep_fresh
                - congratulate
                - on_job_change
                - engage_posts
                - on_website_visit
                - find_people_empty
                - top_up_thin
                - top_up_silent
                - top_up_no_reply
                - top_up_exhausted
                - find_decision_maker
                - reengage_dormant
                - reach_untouched
              description: >-
                The playbook entry the row was born from; null = a play saved
                from a view's filter.
            name:
              type: string
              description: The play's name, 1..255.
            object_type:
              type: string
              enum:
                - people
                - company
              description: 'What the audience selects: people, or company (accounts).'
            action_type:
              type: string
              enum:
                - find_people
                - add_to_workflow
                - refresh
                - congratulate
                - on_job_change
                - engage_posts
                - on_website_visit
              description: >-
                find_people (a company audience); every other kind runs on a
                people audience: add_to_workflow, refresh (Keep data fresh),
                congratulate, on_job_change, engage_posts, on_website_visit.
            action:
              anyOf:
                - type: object
                  properties:
                    prompt:
                      type: string
                      nullable: true
                      description: >-
                        Who to find at each account ("owner, founder, VP and
                        up"); planned once into a Sales Navigator filter by the
                        play's source. null = everyone the page gives.
                    per_company_limit:
                      type: integer
                      nullable: true
                      description: >-
                        People taken per account, 1..25; null = the whole first
                        page.
                    data_source_sid:
                      type: string
                      nullable: true
                      description: >-
                        The play's own find_people source (ds_sc_…), born at the
                        first run that had accounts; its queue and funnel are
                        read with get_data_source. null until then.
                  required:
                    - prompt
                    - per_company_limit
                    - data_source_sid
                - type: object
                  properties:
                    workflow_sid:
                      type: string
                      nullable: true
                      description: >-
                        The workflow the audience enters (wf_wf_…); null while
                        the play waits for one (picked once, with update_play),
                        and fixed from then on.
                    workflow_source_sid:
                      type: string
                      nullable: true
                      description: >-
                        The play's own manual source in that workflow (wf_sr_…),
                        born when the workflow is picked; its entry counters are
                        read with search_workflow_sources.
                  required:
                    - workflow_sid
                    - workflow_source_sid
                - type: object
                  properties:
                    moments:
                      type: object
                      properties:
                        birthday:
                          type: object
                          properties:
                            'on':
                              type: boolean
                              description: The moment's switch.
                            do:
                              type: string
                              enum:
                                - send_message
                                - add_to_workflow
                              description: >-
                                While on: a message (the template, sent as the
                                person's connected sender profile) or the
                                workflow the person enters.
                            template:
                              type: string
                              nullable: true
                              maxLength: 2000
                              description: >-
                                The message, in the workflow template grammar
                                ({{people.first_name}}).
                            workflow_sid:
                              type: string
                              nullable: true
                              description: >-
                                wf_wf_…: the workflow, when the Do is a
                                workflow.
                          required:
                            - 'on'
                            - do
                            - template
                            - workflow_sid
                        work_anniversary:
                          type: object
                          properties:
                            'on':
                              type: boolean
                              description: The moment's switch.
                            do:
                              type: string
                              enum:
                                - send_message
                                - add_to_workflow
                              description: >-
                                While on: a message (the template, sent as the
                                person's connected sender profile) or the
                                workflow the person enters.
                            template:
                              type: string
                              nullable: true
                              maxLength: 2000
                              description: >-
                                The message, in the workflow template grammar
                                ({{people.first_name}}).
                            workflow_sid:
                              type: string
                              nullable: true
                              description: >-
                                wf_wf_…: the workflow, when the Do is a
                                workflow.
                          required:
                            - 'on'
                            - do
                            - template
                            - workflow_sid
                        job_change:
                          type: object
                          properties:
                            'on':
                              type: boolean
                              description: The moment's switch.
                            do:
                              type: string
                              enum:
                                - send_message
                                - add_to_workflow
                              description: >-
                                While on: a message (the template, sent as the
                                person's connected sender profile) or the
                                workflow the person enters.
                            template:
                              type: string
                              nullable: true
                              maxLength: 2000
                              description: >-
                                The message, in the workflow template grammar
                                ({{people.first_name}}).
                            workflow_sid:
                              type: string
                              nullable: true
                              description: >-
                                wf_wf_…: the workflow, when the Do is a
                                workflow.
                          required:
                            - 'on'
                            - do
                            - template
                            - workflow_sid
                      description: >-
                        A switch per moment with its own Do under it; a kind
                        absent is off.
                  required:
                    - moments
                - type: object
                  properties:
                    do:
                      type: string
                      enum:
                        - pause_and_ask
                        - remove_from_workflows
                        - move_to_workflow
                      description: For a person in a workflow whose title or company moved.
                    workflow_sid:
                      type: string
                      nullable: true
                      description: >-
                        wf_wf_…: where move_to_workflow moves the person
                        (required then).
                  required:
                    - do
                    - workflow_sid
                - type: object
                  properties:
                    like:
                      type: object
                      properties:
                        'on':
                          type: boolean
                        reaction:
                          type: string
                          enum:
                            - ai
                            - like
                            - celebrate
                            - support
                            - love
                            - insightful
                            - funny
                          description: >-
                            ai = the AI reads the post and picks one of the six;
                            else always this one. One reaction a post, never
                            changed later.
                      required:
                        - 'on'
                        - reaction
                    comment:
                      type: object
                      properties:
                        'on':
                          type: boolean
                        brief:
                          type: string
                          nullable: true
                          maxLength: 2000
                          description: >-
                            What the AI writes the comment from; required while
                            on.
                      required:
                        - 'on'
                        - brief
                    per_person_weekly_cap:
                      type: integer
                      minimum: 1
                      maximum: 14
                      description: At most this many acts a week per person.
                    sender_profile_sid:
                      type: string
                      nullable: true
                      description: >-
                        ub_sp_…: who acts on a person connected to no sender
                        profile (the connected one acts otherwise; the social
                        workspace is the team's); null = the team's first that
                        can.
                  required:
                    - like
                    - comment
                    - per_person_weekly_cap
                    - sender_profile_sid
                - type: object
                  properties:
                    do:
                      type: string
                      enum:
                        - pause_and_ask
                        - add_to_workflow
                      description: >-
                        On a visit of a key page or a form: pause the journey
                        and ask, or the workflow named.
                    workflow_sid:
                      type: string
                      nullable: true
                      description: 'wf_wf_…: required when the Do is a workflow.'
                    pages:
                      type: array
                      nullable: true
                      items:
                        type: string
                      description: >-
                        Path prefixes of the team's site (/pricing) that count;
                        null = every visit the snippet reports.
                  required:
                    - do
                    - workflow_sid
                    - pages
                - type: object
                  properties: {}
                  description: >-
                    Keep data fresh acts on nothing: the refresh of what it
                    watches is the deed.
              description: >-
                The action's parameters, the shape of its action_type: the sids
                of the sources a find_people or add_to_workflow play owns; the
                moments of a congratulate play; the Do of on_job_change and
                on_website_visit; the like, the comment and the weekly cap of
                engage_posts; {} for refresh.
            audience:
              description: >-
                The tab's own filter AST (the §4.18 tree a saved view carries:
                {field: "signals", op: {in: ["no_engagement"]}},
                pipeline_stage_category, tag_sids, record.<slug> cells, and/or
                or and); null = the whole tab.
            watch:
              type: object
              nullable: true
              properties:
                profile_days:
                  anyOf:
                    - type: number
                      enum:
                        - 7
                    - type: number
                      enum:
                        - 14
                    - type: number
                      enum:
                        - 30
                    - type: number
                      enum:
                        - 90
                    - {}
                  description: >-
                    The LinkedIn profile every N days: 7 | 14 | 30 | 90; null =
                    not watched.
                company_days:
                  anyOf:
                    - type: number
                      enum:
                        - 30
                    - type: number
                      enum:
                        - 90
                    - {}
                  description: 'The company page every N days: 30 | 90; null = not watched.'
                posts_days:
                  anyOf:
                    - type: number
                      enum:
                        - 1
                    - type: number
                      enum:
                        - 3
                    - type: number
                      enum:
                        - 7
                    - {}
                  description: >-
                    The person's posts every N days: 1 | 3 | 7; null = not
                    watched.
                moments:
                  type: boolean
                  description: >-
                    The network's moments (birthdays, work anniversaries, job
                    changes) through the sender profiles' catch-up feed, daily,
                    free.
              required:
                - profile_days
                - company_days
                - posts_days
                - moments
              description: >-
                What the play keeps refreshed and how often; null = nothing
                (2026-10-13).
            cadence:
              type: string
              enum:
                - manual
                - daily
              description: >-
                manual: runs on run_play; daily: runs by itself every day while
                enabled.
            mode:
              type: string
              enum:
                - ask_me
                - automatic
              description: >-
                ask_me: the act waits for approval as a task in the Signals
                feed; automatic: it goes out by itself. The plays that act are
                born asking (2026-10-13).
            enabled:
              type: boolean
              description: The switch of a daily play; a manual play is always false.
            enabled_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 gave the consent (switched the play on).
            enabled_at:
              type: string
              nullable: true
              description: 'ISO 8601 UTC: when.'
            daily_credit_limit:
              type: integer
              nullable: true
              description: >-
                The plays that spend (find_people, and a watching play's reads):
                the credits one day may spend; null = no ceiling (the queue's
                room and the 500-row cap still bound a run). 422 on
                add_to_workflow.
            last_run_at:
              type: string
              nullable: true
              description: ISO 8601 UTC.
            last_run_counts:
              type: object
              nullable: true
              properties:
                matched:
                  type: integer
                  minimum: 0
                  description: >-
                    Rows the audience matched at the run (the tab's count under
                    the filter).
                acted:
                  type: integer
                  minimum: 0
                  description: >-
                    Accounts appended to the queue, or people entered or
                    re-entered.
                skipped:
                  type: integer
                  minimum: 0
                  description: >-
                    Left alone: already queued or searched, in flight, held at
                    the door, past the ceiling or the 500-row cap.
                credits:
                  type: integer
                  minimum: 0
                  description: >-
                    What the run committed: the walk's estimate for the accounts
                    appended (one credit per account); 0 for an add_to_workflow
                    play.
              required:
                - matched
                - acted
                - skipped
                - credits
              description: What the last run did; null before the first run.
            next_run_at:
              type: string
              nullable: true
              description: >-
                ISO 8601 UTC: when the daily sweep runs it next; null on a
                manual or switched-off play.
            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
            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
            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 = live.
          required:
            - sid
            - team_sid
            - playtable_sid
            - catalog_key
            - name
            - object_type
            - action_type
            - action
            - watch
            - cadence
            - mode
            - enabled
            - enabled_by
            - enabled_at
            - daily_credit_limit
            - last_run_at
            - last_run_counts
            - next_run_at
            - created_by
            - deleted_by
            - 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.