---
title: "Write playtable field value"
method: POST
path: "/api/playtable-field-values/write"
tags: ["playtable_field_values"]
---

# Write playtable field value

`POST /api/playtable-field-values/write`

## Request

- Base URL: `https://beta.getsales.io/playtables/v1`
- URL: `https://beta.getsales.io/playtables/v1/api/playtable-field-values/write`
- Auth: HTTP bearer and API key in header `Team-SID`

Write a cell by natural key (column sid + row sid), not by cell sid: the way to fill an EMPTY cell, which has no row and no sid until written (update_playtable_field_value needs one). Same semantics as update: the cell finalizes as done (value null = a manual clear), error_msg clears, a formula cell is pinned, the first write over a system value snapshots it for reset. Works on an existing cell too. 404 on another team's column, 422 when the row is outside its table, 409 while the cell runs.

Contract:
- MCP tool `write_playtable_field_value`, registry package `mcp.playtables/playtable_field_values`, mount `playtables.columns`.
- Operation `update`, response envelope `update`.
- Flags: none.

## Request body

- WritePlaytableFieldValueRequest: Request body of `write_playtable_field_value`.
  - `playtable_field_sid` string, required: The column (pt_fd_…); the table and the object type derive from it. Unknown or another team's: 404.
  - `object_sid` string, required: The row: a person (cr_pp_…) or a company (cr_co_…) that belongs to the column's table (422 otherwise).
  - `value` string, nullable, required: The value to write, canonical string (max 65535). The key is required: null clears the cell, which stays done with value null, never empty.

## Response `200`

`update` success envelope.

- WritePlaytableFieldValueResponse
  - `success` true, required
  - `operation` 'update', required
  - `item` object, required
    - `sid` string, required
    - `team_sid` string, required
    - `playtable_sid` string, required
    - `object_type` 'people' | 'company', required
    - `object_sid` string, required
    - `playtable_field_sid` string, required
    - `value` string, nullable, required
    - `is_value_from_formula` boolean, required
    - `original_value` string, nullable, required: The system-produced value the FIRST manual overwrite snapshotted, what reset restores; null unless is_overwritten. The list surface nulls it like meta: read it on get, update, write and reset.
    - `is_overwritten` boolean, required: The current value is a manual write over a system-produced one: the edited marker, and the one state reset accepts.
    - `is_not_valid` boolean, required: A manually written value that could not be converted to the column's type (text in a number column), stored raw and flagged; system writers coerce or null instead.
    - `status` 'empty' | 'queued' | 'running' | 'done' | 'error' | 'run_condition_not_met', required
    - `cost` number, nullable, required
    - `provider_sid` string, nullable, required
    - `meta` object, nullable, required
      - `run_sid` string, nullable, required
      - `steps` object[], required
        - `step_index` number, required
        - `tool_sid` string, required
        - `status` 'success' | 'failed' | 'skipped', required
        - `cost` number, required
        - `error` string, nullable, required
        - `finished_at` string, nullable, required
        - `verdict` string, nullable
        - `email` string, nullable
    - `error_msg` string, nullable, required
    - `finished_at` string, nullable, required
    - `created_at` string, required
    - `updated_at` string, required
  - `updated_fields` string[], required
  - `previous_values` object, required
  - `kept_fields` string[]: 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` 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)