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. An upsert identical to the stored record counts as applied without being re-indexed, and dataVersion only advances when at least one operation changed something — see Unchanged records. 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.