--- title: "Create playtable field" method: POST path: "/api/playtable-fields" tags: ["playtable_fields"] --- # Create playtable field `POST /api/playtable-fields` ## Request - Base URL: `https://beta.getsales.io/playtables/v1` - URL: `https://beta.getsales.io/playtables/v1/api/playtable-fields` - Auth: HTTP bearer and API key in header `Team-SID` Add a column to a playtable: the tool that shapes a table. category is derived from the type prefix, never sent. Patterns. Find people (a company grid): type action_find_people with payload.prompt saying who to find at each company (1 credit per company searched, a miss free); switch config.auto_run on (its default condition is a company with no people yet) so a company that lands later is searched by itself, and a playtable run searches the companies already there. Add as column: a scalar whose payload.template is one lone variable such as {{record.enrich.company.employees}}; existing rows backfill free, every future run re-derives it; never touch the action field for this. Composed text: a template with {{people.first_name}} or {{company.name}} (catalog attributes) and record. (a column of this tab), each refused unless it exists. action_waterfall: config.preset_sid (a gtm-api preset) or hand-built payload.steps, never both. Formulas and templates form dependency edges; a cycle rolls the save back with 422 and context.cycle_path. Idempotent on (playtable_sid, slug): a duplicate answers already_exists true with the existing row (check item.type). Nothing paid runs on create (a playtable run, estimate first, or auto_run does); a scalar formula backfill is free. At most 100 live columns per object_type: the 101st is 422 (context.limit). Contract: - MCP tool `create_playtable_field`, registry package `mcp.playtables/playtable_fields`, mount `playtables.columns`. - Operation `create`, response envelope `create`. - Flags: none. ## Request body - CreatePlaytableFieldRequest: Request body of `create_playtable_field`. - `playtable_sid` string, required: Owner playtable sid (pt_tb_…). - `object_type` 'people' | 'company', required: Object grid this field belongs to: people or company rows. Fixed at create. - `type` 'scalar_text' | 'scalar_number' | 'scalar_currency' | 'scalar_date' | 'scalar_url' | 'scalar_checkbox' | 'scalar_select' | 'scalar_multiselect' | 'scalar_image' | 'widget_data_source' | 'widget_tags' | 'widget_active_workflows' | 'widget_notes' | 'widget_company' | 'widget_linkedin_id' | 'widget_linkedin_channel' | 'widget_work_email' | 'widget_personal_email' | 'widget_email_channel' | 'widget_phones' | 'widget_phone_channel' | 'widget_last_touch' | 'widget_activity' | 'widget_deal_size' | 'widget_website' | 'widget_people_summary' | 'widget_ai_sdr' | 'action_ai_research' | 'action_waterfall' | 'action_gtm_tool' | 'action_find_people', required: The category derives from the prefix. Scalar and the generic action types fit both grids; action_find_people is company-only. Widgets: data_source, tags, last_touch, activity on both; deal_size, website, people_summary company-only; the rest people-only. - `name` string, required: Display label; slug is derived from it when slug is omitted. - `slug` string: Template-variable name, immutable after create: formulas read record., prompts {{record.}}. Default: the slugified name (a collision takes _2). - `payload` union: Shape must match type. REQUIRED for action_* types; default: {} (widget) / all-null scalar payload. - object - `formula` string, nullable, required: CEL expression, NO {{ }} braces (those are for templates). Reference paths extract typed values: record.(.|[N])* - e.g. "record.enrich.contact_info.websites[0].url" (extraction column - the "Add as column" case; backfills all rows on save, re-derives on every source run; absent path → empty cell), and on a people grid company.record.(.|[N])* - the linked account's cell in this playtable (a Companies-tab column; on the company grid the account is the row itself). A company.record reference is checked against the Companies tab at save, backfilled the same way, and is NOT re-derived when the account's cell changes later (no cross-object dependency: a snapshot until the column's next recalc). Full CEL computes: operators, ?: conditions, has(), string concat - e.g. 'record.employees > 50 ? 100 : 40'. Syntax errors 422 at save; runtime failures land as cell error_msg. Evaluated backend-side; null = manually-entered column. Setting/changing it recomputes EVERY cell including pinned ones. When template is set, this is server-GENERATED from it - send the template instead of hand-writing CEL. - `template` string, nullable, required: The unified authoring source - prose + {{record.…}} / {{people.}} / {{company.}} / {{company.record.…}} variables, as in a flow-node message: "Hey {{people.first_name}}, saw {{company.name}}!". record. is THIS tab's columns only ({{record.full_name}} is refused unless a column has that slug); people. the person's catalog (full_name, first_name, company_name, ln_nickname, work_email, timezone, pipeline_stage_name...); company. the linked account's (name, domain, website, ln_nickname, people_count...); company.record. the company tab's columns. An attribute outside the catalogs is refused at save (unknown template variable people.title); people.role and people.headline are derived (the title and the profile line the enrichment, the search record or the inbox observed), and {{record.data_source.position}} still reads the raw record. Compiled into formula on every save: absent value → empty string; a LONE variable ({{record.enrich.company.employees}}) → the bare typed reference (numbers stay numbers); stray braces → 422 on payload.template. Round-trips verbatim. null = formula authored as CEL; template:"" clears both. - `nl_formula` string, nullable, required: Natural-language source of truth the formula was compiled from - agents edit THIS and regenerate formula. - `options` string[], nullable, required: Option labels for scalar_select / scalar_multiselect (min 1); null for every other scalar type. - `currency` string, nullable, required: ISO-4217 code (e.g. USD) for scalar_currency only; null = render default USD; null for every other scalar type. - `option_colors` object, nullable, required: Option name → #rrggbb hex for scalar_select / scalar_multiselect only; keys ⊆ options (min 1 entry - send null instead of an empty map). - object: Always {} - widget rendering is type-driven (widget_active_workflows and the two channel widgets carry their own knobs, below). - object - `workflow_sid` string, nullable, required: null = All workflows: a cell counts the lead's live journeys by state. A wf_wf_ sid = Specific workflow: the column is pinned to it, a cell shows the lead's record there, finished too; a live workflow (422 relation_not_found). A pin outlives its workflow. - object - `stats_view` 'all' | 'last' | 'select', required: Whose numbers the cell shows: all = every sender profile's facts summed, no face; last = the sender profile that touched the person on that channel last, its face and counters (the default); select = the one named by sender_profile_sid. - `sender_profile_sid` string, nullable, required: The sender profile of a select view (ub_sp_): required under select, null otherwise (422 validation_failed). It must name a live sender profile of the team (422 relation_not_found); a deleted pick is kept until another is set. - object - `prompt` string, required: Twig-templated research instruction; the template's variables, an unknown one 422. What the source found on a person (the role, the location) is in the Data source cell: {{record.data_source}} (its slug on a new table) reads it whole. - `model` string, required: 'auto' (gtm-api routes the call) or a concrete gtm-api model id; validated against the gtm-api registry at save. - `output` 'text' | 'number' | 'select' | 'json', required: Cell shape: text | number (non-numeric model answer → cell error) | select (one of payload.options) | json (extract values into columns via extraction formulas record..; push onto people/company attributes via output_mapping). - `options` string[], nullable, required: Required (min 1) when output=select; null otherwise. - `output_mapping` object[], nullable, required: Project a 'json' result onto people/company attributes, fill-if-empty (max 20); null = no attribute writes. Columns pull via extraction formulas instead. - `path` string, required: JSON path into the tool/model result, e.g. $.email or $.techs[0].name. - `target` string, required: Entity-attribute target ONLY: people. or company. (writable-attribute registries; fill-if-empty at projection); validated at save. No record. targets: columns pull via extraction formulas (record..), never via push mapping. - `web_search` boolean: Default false: the model answers with the vendor's server-side web search on. A per-model capability: 422 relation_not_found at save, and web_search_not_supported on a preview, for a model without it. - object - `steps` object[], required: 1..10 ordered gtm-api tool steps, first accepted result wins; pass [] when config.preset_sid materializes them server-side (never both). - `tool_sid` string, required: The step: a gtm-api tool registry sid, an integration-platform step (in:{provider}.{operation}, in:tool.{sid}) or the row itself (row:people.work_email: the row's own address, free, verified unless already ok; people, once). Price validated at save. - `params` object, required: Tool params; string values may be Twig templates over the same variable namespace. - `stop_on_first` boolean, required: true (default) = stop at the first step returning a non-empty accepted result; false = run all, first non-empty wins. - `output_mapping` object[], nullable, required: Winning step's result → people/company attributes, fill-if-empty (max 20); null = no attribute writes. - `path` string, required: JSON path into the tool/model result, e.g. $.email or $.techs[0].name. - `target` string, required: Entity-attribute target ONLY: people. or company. (writable-attribute registries; fill-if-empty at projection); validated at save. No record. targets: columns pull via extraction formulas (record..), never via push mapping. - `verify` object, nullable: One in:{provider}.email.verify step on every email a finder returns, no params. valid accepts and ends the chain, so does catch_all while accept_catch_all is on; invalid, unknown or a failure rejects, the next finder runs. null = none, first found wins. - `tool_sid` string, required: The step: a gtm-api tool registry sid, an integration-platform step (in:{provider}.{operation}, in:tool.{sid}) or the row itself (row:people.work_email: the row's own address, free, verified unless already ok; people, once). Price validated at save. - `params` object, required: Tool params; string values may be Twig templates over the same variable namespace. - `accept_catch_all` boolean: true (default): a catch-all address is accepted the moment the verifier says so and the chain stops there. false = catch-all emails are rejected like invalid ones (safe to send only) and the next finder runs. Meaningful only with verify set. - object - `tool_sid` string, required: gtm-api tool registry sid (external format); existence + price validated at save. - `params` object, required: Tool params; string values may be Twig templates over the same variable namespace. - `output_mapping` object[], nullable, required: Tool result → people/company attributes, fill-if-empty (max 20); null = no attribute writes. - `path` string, required: JSON path into the tool/model result, e.g. $.email or $.techs[0].name. - `target` string, required: Entity-attribute target ONLY: people. or company. (writable-attribute registries; fill-if-empty at projection); validated at save. No record. targets: columns pull via extraction formulas (record..), never via push mapping. - object - `prompt` string, nullable, required: Who to find at each company, in words; null = everyone there. With data_source_sid null on create the server births a find_people source; a new text on update births a new search and parks the old. 422 prohibited beside a picked data_source_sid. - `per_company_limit` integer, required: People taken per company, 1..25 (one search page, by relevance). Default 1. Mirrored onto the column's own search; read from a picked one. - `data_source_sid` string, nullable, required: The find_people source the cells search (ds_sc_). null on create = the server makes one for the column (the sid comes back). A sid = a find_people search of the SAME table, as is (422 other_table elsewhere, relation_not_found when gone). Never null stored. - `qualify` object, nullable: Check on save: {on, criterion} the column's own search takes at every save, judging the people the walk finds before they land (data_sources.qualify); null or absent = no check. 422 prohibited beside a picked data_source_sid (it has its own gate). - `on` boolean, required: The switch. `on` with no criterion is refused (422 on qualify.criterion, rule required_if). - `criterion` string, nullable, required: Who passes, in the user's words ("a decision maker at a marketing agency, not a freelancer"). Trimmed; null while the check is off. - `config` object: Action fields only. Omit for defaults (auto_run:false, everything else null). - `auto_run` boolean, required: Action auto-fires when a row enters the table / the cell is empty (paid: empty→queued only). Default false. - `run_condition` union, required: Per-row filter-AST gate (§4.18 atoms, strict mode); unmet → cell status run_condition_not_met; null = always run. - object - `and` object[], required - object - `or` object[], required - object - `not` object, required: Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. - object - `any` object, required - `path` string, required: Array-valued path - the only way to reach inside an array. - `where` object, required: Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. - object - `field` string, required: Namespaced path: record. or a built-in object attribute; element-relative inside any.where. - `op` object, required - `eq` union - string - number - boolean - `ne` union - string - number - boolean - `in` union[] - union - … - `nin` union[] - union - … - `gt` union - number - string - `gte` union - number - string - `lt` union - number - string - `lte` union - number - string - `is_null` boolean - `contains` string - `not_contains` string - `contains_any` string[] - `not_contains_any` string[] - `starts_with` string - unknown - `nl_condition` string, nullable, required: Natural-language source of truth for run_condition - agents edit THIS and regenerate the AST. - `daily_credit_limit` integer, nullable, required: Max credits this field may spend per UTC day (int > 0, enforced at run time); null = no cap. - `preset_sid` string, nullable, required: gtm-api preset sid (external) that materializes waterfall steps at save; action_waterfall only, mutually exclusive with hand-built steps. null otherwise. - `add_to_default_view` boolean: true also appends the column to its grid's default view, so people see it without an update_playtable_view call. Idempotent: a column already in the layout stays where it is. Default false: the column exists but no view shows it. ## Response `200` `create` success envelope. - CreatePlaytableFieldResponse - `success` true, required - `operation` 'create', required - `item` object, required - `sid` string, required - `team_sid` string, required - `playtable_sid` string, required - `object_type` 'people' | 'company', required: Object grid this field belongs to: people or company rows. Fixed at create. - `name` string, required: Display label, freely editable. - `slug` string, required: Template-variable name ({{record.}}); unique per playtable, IMMUTABLE after create. - `category` 'scalar' | 'widget' | 'action', required: scalar = data column (optional free formula) | widget = live CRM projection, no cells | action = paid executor. Derived from the type prefix - never user-supplied. - `type` 'scalar_text' | 'scalar_number' | 'scalar_currency' | 'scalar_date' | 'scalar_url' | 'scalar_checkbox' | 'scalar_select' | 'scalar_multiselect' | 'scalar_image' | 'widget_data_source' | 'widget_tags' | 'widget_active_workflows' | 'widget_notes' | 'widget_company' | 'widget_linkedin_id' | 'widget_linkedin_channel' | 'widget_work_email' | 'widget_personal_email' | 'widget_email_channel' | 'widget_phones' | 'widget_phone_channel' | 'widget_last_touch' | 'widget_activity' | 'widget_deal_size' | 'widget_website' | 'widget_people_summary' | 'widget_ai_sdr' | 'action_ai_research' | 'action_waterfall' | 'action_gtm_tool' | 'action_find_people', required: The category derives from the prefix. Scalar and the generic action types fit both grids; action_find_people is company-only. Widgets: data_source, tags, last_touch, activity on both; deal_size, website, people_summary company-only; the rest people-only. - `payload` union, required: Per-type payload; the discriminator is the row's type column, not an inner key - the shape must match type (scalar / widget / active_workflows / channel / ai_research / waterfall / gtm_tool / find_people branches) or the save fails with 422. - object - `formula` string, nullable, required: CEL expression, NO {{ }} braces (those are for templates). Reference paths extract typed values: record.(.|[N])* - e.g. "record.enrich.contact_info.websites[0].url" (extraction column - the "Add as column" case; backfills all rows on save, re-derives on every source run; absent path → empty cell), and on a people grid company.record.(.|[N])* - the linked account's cell in this playtable (a Companies-tab column; on the company grid the account is the row itself). A company.record reference is checked against the Companies tab at save, backfilled the same way, and is NOT re-derived when the account's cell changes later (no cross-object dependency: a snapshot until the column's next recalc). Full CEL computes: operators, ?: conditions, has(), string concat - e.g. 'record.employees > 50 ? 100 : 40'. Syntax errors 422 at save; runtime failures land as cell error_msg. Evaluated backend-side; null = manually-entered column. Setting/changing it recomputes EVERY cell including pinned ones. When template is set, this is server-GENERATED from it - send the template instead of hand-writing CEL. - `template` string, nullable, required: The unified authoring source - prose + {{record.…}} / {{people.}} / {{company.}} / {{company.record.…}} variables, as in a flow-node message: "Hey {{people.first_name}}, saw {{company.name}}!". record. is THIS tab's columns only ({{record.full_name}} is refused unless a column has that slug); people. the person's catalog (full_name, first_name, company_name, ln_nickname, work_email, timezone, pipeline_stage_name...); company. the linked account's (name, domain, website, ln_nickname, people_count...); company.record. the company tab's columns. An attribute outside the catalogs is refused at save (unknown template variable people.title); people.role and people.headline are derived (the title and the profile line the enrichment, the search record or the inbox observed), and {{record.data_source.position}} still reads the raw record. Compiled into formula on every save: absent value → empty string; a LONE variable ({{record.enrich.company.employees}}) → the bare typed reference (numbers stay numbers); stray braces → 422 on payload.template. Round-trips verbatim. null = formula authored as CEL; template:"" clears both. - `nl_formula` string, nullable, required: Natural-language source of truth the formula was compiled from - agents edit THIS and regenerate formula. - `options` string[], nullable, required: Option labels for scalar_select / scalar_multiselect (min 1); null for every other scalar type. - `currency` string, nullable, required: ISO-4217 code (e.g. USD) for scalar_currency only; null = render default USD; null for every other scalar type. - `option_colors` object, nullable, required: Option name → #rrggbb hex for scalar_select / scalar_multiselect only; keys ⊆ options (min 1 entry - send null instead of an empty map). - object: Always {} - widget rendering is type-driven (widget_active_workflows and the two channel widgets carry their own knobs, below). - object - `workflow_sid` string, nullable, required: null = All workflows: a cell counts the lead's live journeys by state. A wf_wf_ sid = Specific workflow: the column is pinned to it, a cell shows the lead's record there, finished too; a live workflow (422 relation_not_found). A pin outlives its workflow. - object - `stats_view` 'all' | 'last' | 'select', required: Whose numbers the cell shows: all = every sender profile's facts summed, no face; last = the sender profile that touched the person on that channel last, its face and counters (the default); select = the one named by sender_profile_sid. - `sender_profile_sid` string, nullable, required: The sender profile of a select view (ub_sp_): required under select, null otherwise (422 validation_failed). It must name a live sender profile of the team (422 relation_not_found); a deleted pick is kept until another is set. - object - `prompt` string, required: Twig-templated research instruction; the template's variables, an unknown one 422. What the source found on a person (the role, the location) is in the Data source cell: {{record.data_source}} (its slug on a new table) reads it whole. - `model` string, required: 'auto' (gtm-api routes the call) or a concrete gtm-api model id; validated against the gtm-api registry at save. - `output` 'text' | 'number' | 'select' | 'json', required: Cell shape: text | number (non-numeric model answer → cell error) | select (one of payload.options) | json (extract values into columns via extraction formulas record..; push onto people/company attributes via output_mapping). - `options` string[], nullable, required: Required (min 1) when output=select; null otherwise. - `output_mapping` object[], nullable, required: Project a 'json' result onto people/company attributes, fill-if-empty (max 20); null = no attribute writes. Columns pull via extraction formulas instead. - `path` string, required: JSON path into the tool/model result, e.g. $.email or $.techs[0].name. - `target` string, required: Entity-attribute target ONLY: people. or company. (writable-attribute registries; fill-if-empty at projection); validated at save. No record. targets: columns pull via extraction formulas (record..), never via push mapping. - `web_search` boolean: Default false: the model answers with the vendor's server-side web search on. A per-model capability: 422 relation_not_found at save, and web_search_not_supported on a preview, for a model without it. - object - `steps` object[], required: 1..10 ordered gtm-api tool steps, first accepted result wins; pass [] when config.preset_sid materializes them server-side (never both). - `tool_sid` string, required: The step: a gtm-api tool registry sid, an integration-platform step (in:{provider}.{operation}, in:tool.{sid}) or the row itself (row:people.work_email: the row's own address, free, verified unless already ok; people, once). Price validated at save. - `params` object, required: Tool params; string values may be Twig templates over the same variable namespace. - `stop_on_first` boolean, required: true (default) = stop at the first step returning a non-empty accepted result; false = run all, first non-empty wins. - `output_mapping` object[], nullable, required: Winning step's result → people/company attributes, fill-if-empty (max 20); null = no attribute writes. - `path` string, required: JSON path into the tool/model result, e.g. $.email or $.techs[0].name. - `target` string, required: Entity-attribute target ONLY: people. or company. (writable-attribute registries; fill-if-empty at projection); validated at save. No record. targets: columns pull via extraction formulas (record..), never via push mapping. - `verify` object, nullable: One in:{provider}.email.verify step on every email a finder returns, no params. valid accepts and ends the chain, so does catch_all while accept_catch_all is on; invalid, unknown or a failure rejects, the next finder runs. null = none, first found wins. - `tool_sid` string, required: The step: a gtm-api tool registry sid, an integration-platform step (in:{provider}.{operation}, in:tool.{sid}) or the row itself (row:people.work_email: the row's own address, free, verified unless already ok; people, once). Price validated at save. - `params` object, required: Tool params; string values may be Twig templates over the same variable namespace. - `accept_catch_all` boolean: true (default): a catch-all address is accepted the moment the verifier says so and the chain stops there. false = catch-all emails are rejected like invalid ones (safe to send only) and the next finder runs. Meaningful only with verify set. - object - `tool_sid` string, required: gtm-api tool registry sid (external format); existence + price validated at save. - `params` object, required: Tool params; string values may be Twig templates over the same variable namespace. - `output_mapping` object[], nullable, required: Tool result → people/company attributes, fill-if-empty (max 20); null = no attribute writes. - `path` string, required: JSON path into the tool/model result, e.g. $.email or $.techs[0].name. - `target` string, required: Entity-attribute target ONLY: people. or company. (writable-attribute registries; fill-if-empty at projection); validated at save. No record. targets: columns pull via extraction formulas (record..), never via push mapping. - object - `prompt` string, nullable, required: Who to find at each company, in words; null = everyone there. With data_source_sid null on create the server births a find_people source; a new text on update births a new search and parks the old. 422 prohibited beside a picked data_source_sid. - `per_company_limit` integer, required: People taken per company, 1..25 (one search page, by relevance). Default 1. Mirrored onto the column's own search; read from a picked one. - `data_source_sid` string, nullable, required: The find_people source the cells search (ds_sc_). null on create = the server makes one for the column (the sid comes back). A sid = a find_people search of the SAME table, as is (422 other_table elsewhere, relation_not_found when gone). Never null stored. - `qualify` object, nullable: Check on save: {on, criterion} the column's own search takes at every save, judging the people the walk finds before they land (data_sources.qualify); null or absent = no check. 422 prohibited beside a picked data_source_sid (it has its own gate). - `on` boolean, required: The switch. `on` with no criterion is refused (422 on qualify.criterion, rule required_if). - `criterion` string, nullable, required: Who passes, in the user's words ("a decision maker at a marketing agency, not a freelancer"). Trimmed; null while the check is off. - `config` object, required - `auto_run` boolean, required: Action auto-fires when a row enters the table / the cell is empty (paid: empty→queued only). Default false. - `run_condition` union, required: Per-row filter-AST gate (§4.18 atoms, strict mode); unmet → cell status run_condition_not_met; null = always run. - object - `and` object[], required - object - `or` object[], required - object - `not` object, required: Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. - object - `any` object, required - `path` string, required: Array-valued path - the only way to reach inside an array. - `where` object, required: Recursive node: the same object shape repeats here. A static OpenAPI document cannot express the cycle, so this level is documented as an open object. - object - `field` string, required: Namespaced path: record. or a built-in object attribute; element-relative inside any.where. - `op` object, required - `eq` union - … - `ne` union - … - `in` union[] - … - `nin` union[] - … - `gt` union - … - `gte` union - … - `lt` union - … - `lte` union - … - `is_null` boolean - `contains` string - `not_contains` string - `contains_any` string[] - `not_contains_any` string[] - `starts_with` string - unknown - `nl_condition` string, nullable, required: Natural-language source of truth for run_condition - agents edit THIS and regenerate the AST. - `daily_credit_limit` integer, nullable, required: Max credits this field may spend per UTC day (int > 0, enforced at run time); null = no cap. - `preset_sid` string, nullable, required: gtm-api preset sid (external) that materializes waterfall steps at save; action_waterfall only, mutually exclusive with hand-built steps. null otherwise. - `backfill` object, nullable, required: The formula column's backfill ledger (see PlaytableFieldBackfill); null on a column with no formula. - `status` 'queued' | 'running' | 'done' | 'failed', required - `scanned` integer, required: Objects the scan has visited so far. - `total` integer, nullable, required: The scan size, known once the job starts (null while queued). - `queued_at` string, nullable, required: ISO 8601 UTC: when the column started owing its backfill. - `started_at` string, nullable, required: ISO 8601 UTC: when the job took it. - `finished_at` string, nullable, required: ISO 8601 UTC: when it ended, done or failed. - `error` string, nullable, required: A reason token (backfill_failed) on failed, never an exception message. - `created_by` object, required - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required - `actor_sid` string, nullable, required - `team_sid` string, required - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path. - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract. - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write. - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row. - `deleted_by` object, nullable, required - `actor_type` 'user' | 'support' | 'api_key' | 'system' | 'agent', required - `actor_sid` string, nullable, required - `team_sid` string, required - `actor_name` string, nullable: The OAuth client that acted ("Claude", "n8n"); null for a user, an API key or a system job. - `oauth_client_sid` string, nullable: The acting OAuth client (id_oc_*); null off the OAuth path. - `reason` string, nullable: Why a system actor wrote the row (snapshot_capture_job, ...); null otherwise. - `permissions` object, required: Internal audit context: the grant set the actor held at write time. Not a contract. - `cluster_id` integer, nullable: Internal audit context: the cluster that served the write. - `trace_id` string, nullable: Internal audit context: the trace id of the request that wrote the row. - `created_at` string, required - `updated_at` string, required - `deleted_at` string, nullable, required - `already_exists` boolean, required - `meta` object, required - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header. - `span_id` string, required: 16 hex chars, root span of this request. - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time. - `duration_ms` integer, required: Server-side wall clock. - `team_sid` string, nullable: 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` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends. ## Other responses - `4XX`: 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. - `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable. --- [API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-playtables/revisions/aa394506515d?raw)