Skip to main content
POST
Create a record set

Authorizations

X-API-Key
string
header
required

Body

application/json

Start a chunked upload.

Uploading records happens in three steps:

  1. Create a record set (this request). You get back an id and a chunk_size.
  2. POST /record-sets/{record_set_id}/records once per chunk, in any order, until every record has been sent.
  3. POST /record-sets/{record_set_id}/seal with the total number of records you sent. Sealing validates the count and finalises the upload's content hash.

A sealed record set is then passed to a flow trigger as record_set_id. Each record set is used by exactly one trigger. Record sets that are never sealed, or never triggered, expire automatically along with their staged records.

chunk_size is fixed for the whole upload and defaults to the largest chunk the API accepts. Every chunk except the final one must contain exactly this many records, because it is what turns a chunk index into each row's position in the set.

chunk_size
integer

Number of records in every chunk except the last. Fixed for the whole upload.

metadata
Metadata · object

Arbitrary labels stored with the record set and returned on read.

Response

Successful Response

A record set's manifest and current progress.

status moves open -> sealed -> consumed: open accepts chunks, sealed is complete and ready to trigger, and consumed means a trigger has claimed it (each record set is used exactly once). received_count and chunk_count track what has arrived so far, content_hash identifies the sealed contents, batch_id points at the batch that consumed it, and staging_expires_at is when an untriggered record set and its staged records are reclaimed.

id
string
required
status
string
required
chunk_size
integer
required
received_count
integer
required
chunk_count
integer
required
expected_count
integer | null
required
content_hash
string | null
required
batch_id
string | null
required
metadata
Metadata · object
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
sealed_at
string<date-time> | null
required
consumed_at
string<date-time> | null
required
staging_expires_at
string<date-time>
required