Write records

POST /1/indexes/:index/records

Requires a write or admin key.

Request

type WriteBatch = {
	operations: WriteOperation[];
};

type WriteOperation =
	| { action: 'upsert'; record: RecordInput }
	| { action: 'delete'; objectID: string; version?: number };

type RecordInput = {
	objectID: string;
	version?: number;
	[attribute: string]: AttributeValue | undefined;
};

• Up to 1,000 operations per batch, 5,000,000 bytes total.
• Each record is capped at 100,000 bytes.
• objectID is required and at most 512 characters.
• version, if omitted, is assigned by the server at accept time. Pass your own to get last-writer-wins semantics — see Versions and last-writer-wins.

Response

type WriteResult = {
	dataVersion: number;
	applied: number;
	ignoredAsStale: number;
	queued?: { taskId: string };
};

applied and ignoredAsStale always sum to the number of operations you sent. queued is present only when the primary was momentarily overloaded and the write was accepted onto the overflow queue instead of applied directly — see Overflow below.

Example

curl -X POST https://api.usesuo.com/1/indexes/library/records \
  -H "x-suo-key: suo_write_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "operations": [
      { "action": "upsert", "record": { "objectID": "item-482", "userId": "user_9f2", "title": "The gentle art of note-taking" } },
      { "action": "delete", "objectID": "item-401" }
    ]
  }'

{ "dataVersion": 482, "applied": 2, "ignoredAsStale": 0 }

Overflow

Writes go directly to the index's primary. If the primary is momentarily overloaded, the API accepts the write onto a queue and answers with a 202 and a taskId instead of dataVersion directly:

{ "dataVersion": 0, "applied": 0, "ignoredAsStale": 0, "queued": { "taskId": "task_7f2c1a94" } }

Poll Tasks with that taskId to confirm the write applied. This is the exception, not the normal path — most writes apply directly and return a real dataVersion immediately.

Deleting a record

{ "operations": [{ "action": "delete", "objectID": "item-401" }] }

A delete becomes a versioned tombstone, kept for 30 days so a delayed, older upsert cannot resurrect it. To clear an entire partition instead of individual records, see Clear a partition.