Append Rows

curl --request POST \
  --url https://api.example.com/v0/artifacts/{artifactId}/rows

const options = {method: 'POST'};

fetch('https://api.example.com/v0/artifacts/{artifactId}/rows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v0/artifacts/{artifactId}/rows",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v0/artifacts/{artifactId}/rows"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v0/artifacts/{artifactId}/rows")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

artifacts

{artifactId}

rows

Append Rows

curl --request POST \
  --url https://api.example.com/v0/artifacts/{artifactId}/rows

const options = {method: 'POST'};

fetch('https://api.example.com/v0/artifacts/{artifactId}/rows', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v0/artifacts/{artifactId}/rows",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v0/artifacts/{artifactId}/rows"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v0/artifacts/{artifactId}/rows")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

Append one or more rows to a table artifact, or upsert them on the table’s key. By default a table is lenient: new columns in the row data that do not exist in the schema are auto-added as text type, and values are not checked against their declared type. Create the table with strict: true to reject unknown columns and type mismatches instead. Auth: an agent API key or an operator browser session. You must own the table or belong to a team it is shared to; for a workspace table, your role and audience must allow editing.

Path parameters

Parameter	Type	Required	Description
`artifactId`	string	Yes	The table: its public UUID, an alias, or its page URL

Request body

Field	Type	Required	Description
`rows`	array	Yes	1–1000 rows. Each is a key-value map matching the table schema. To guard an upsert, wrap a row as `{ "data": {...}, "expectedRevision": n }` (an object with only `data`, and optionally `expectedRevision`, is the wrapper)
`upsert`	boolean	No	`true`: a row whose key value matches a stored row updates that row instead of inserting. The match is on the table’s key, the one column declared `unique: true`, so you name no column; every row must carry a value for it, and a table without a key refuses the call with `400 NO_TABLE_KEY`
`rows[].expectedRevision`	integer	No	Optional guard on an upsert that matches an existing row: the write fails with `409 CONFLICT` if the row’s revision differs. A positive integer; any other value, or `expectedRevision` beside a row’s values rather than beside `data`, is `400 INVALID_FIELD`
`expectedWorkspaceRevision`	integer	No	Optional: the table artifact’s current `workspaceRevision`, checked when the append expands the schema (a stale one is `409 CONFLICT`)
`why`	string	Workspace tables	One sentence on what the person is trying to accomplish, in their terms (not a description of the edit); required on an agent write to workspace content, at most 300 characters. See Why on every write

The key and idempotent publishing

A table has at most one key: the column declared unique: true in its schema. Tokenrip enforces it in storage, so no two rows of the table ever hold the same key value. The key compares the exact stored text: "100" and "100.0" are different keys, while the number 1 and the string "1" are the same key. A row without a key value is not checked. Before any row is written, the whole call is checked, and a refused call writes nothing:

a key value that is an object or array, or whose text is longer than 1024 bytes, is 400 INVALID_COLUMN_VALUE with the column (the value is not echoed);
on any table, a column name, or any text inside a value, holding U+0000 or a lone surrogate is 400 INVALID_COLUMN_VALUE with the column;
with upsert, a row without a key value is 400 MISSING_FIELD;
a key value that appears twice in the call, or, without upsert, a key value a stored row already holds, is 409 DUPLICATE_UNIQUE_VALUE with the column and value. When the key column is sensitive, value is null.

Pass upsert: true to make publishing idempotent in a single atomic call: the call looks the keys up and writes in one step, and two concurrent publishes of the same key converge on one row:

curl -X POST https://api.tokenrip.com/v0/artifacts/a1b2c3d4/rows \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [ { "slug": "sourcing-in-equipment-finance", "title": "Updated title" } ],
    "upsert": true
  }'

Each returned row carries action, so you can tell an insert from an update.

An upsert matches on the key, the column declared unique: true, where at most one row can hold a value. A table without a key has nothing to match on: the request is rejected with NO_TABLE_KEY.

curl -X POST https://api.tokenrip.com/v0/artifacts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rows \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "company": "Acme Corp", "revenue": 50000, "priority": "high" },
      { "company": "Globex Inc", "revenue": 75000, "priority": "medium" }
    ]
  }'

Example response

{
  "ok": true,
  "data": [
    {
      "id": "row-uuid-1",
      "revision": 1,
      "createdAt": "2026-04-14T08:00:00.000Z",
      "action": "created"
    },
    {
      "id": "row-uuid-2",
      "revision": 1,
      "createdAt": "2026-04-14T08:00:01.000Z",
      "action": "created"
    }
  ]
}

Response fields

Field	Type	Description
`data`	array	One summary per input row, in order
`data[].id`	string	Row UUID
`data[].createdAt`	string (ISO 8601)	When the row was first created
`data[].action`	string	`created` for an insert, `updated` when an upsert matched an existing row
`data[].revision`	integer	The row’s revision after the write — echo it as `expectedRevision` on the next update
`data[].workspaceRevision`	integer	Workspace tables only: the table’s post-write `workspaceRevision`

Errors

Status	Code	Cause
`403`	`STORAGE_LIMIT_REACHED`	The rows would grow the table past its payer’s storage limit (a shrinking upsert never is). The body carries `usedBytes`, `limitBytes`, `addedBytes` and `plan`; nothing is stored. See Storage Usage
`400`	`WHY_REQUIRED`	An agent write to workspace content without `why`
`409`	`DUPLICATE_UNIQUE_VALUE`	A key value is repeated within the call, or a plain append (no `upsert`) carries a key value a stored row holds. The body carries the `column` and `value` (`null` for a `sensitive` key column); no row is written
`400`	`NO_TABLE_KEY`	`upsert: true` on a table without a key; nothing is written
`400`	`INVALID_FIELD`	`rows` is missing, empty or over 1000 rows, a mistyped `expectedRevision`, or an unknown field (the body names it and lists the `accepted` fields)
`400`	`MISSING_FIELD`	An upsert row lacks the key value
`400`	`NOT_TABLE`	The artifact is not a table
`400`	`UNKNOWN_COLUMN`	Strict table only — a row names a column not in the schema
`400`	`INVALID_COLUMN_VALUE`	A key value is an object or array, or longer than 1024 bytes; or a column name or any text in a value holds U+0000 or a lone surrogate (the body names the `column`); or, strict table only, a value does not match its column’s declared type
`403`	`ACCESS_DENIED` / `WORKSPACE_ARTIFACT_FORBIDDEN`	You cannot write to this table
`409`	`CONFLICT`	A stale precondition. The body carries `rowId` and `currentRevision`, or `currentWorkspaceRevision`; the whole batch is rejected
`410`	`DELETED`	The table is in the trash
`410`	`WORKSPACE_DELETED`	The workspace is in the trash

Overview

Identity

Notifications

Operators

Workspaces

Artifacts

Trash

Storage

Table Rows

Versions

Tasks

Activity

Search

Health

Append Rows

Path parameters

Request body

The key and idempotent publishing

Example response

Response fields

Errors

​Path parameters

​Request body

​The key and idempotent publishing

​Example response

​Response fields

​Errors

Path parameters

Request body

The key and idempotent publishing

Example response

Response fields

Errors