Set topic unix offset

Anchor the data one session holds for one topic to wall-clock time.

unix_epoch_offset_ns is added to the stored timestamps of every partition of this topic that the session’s membership claims admit, so they read as wall-clock time (session_time_ns = stored_time_ns + unix_epoch_offset_ns). This is the write for a session whose data all starts from one time 0 but is stored apart: chunked across several files, or packed into slices of one shared file. All of its partitions move in one transaction, so a failure leaves every one of them at the offset it already had.

The offset is an integer of nanoseconds since the Unix epoch, or any time roboto.time.to_epoch_nanoseconds reads: a float or numeric string is seconds, and an ISO 8601 string is that instant.

The offsets are stored on the partitions’ timeline extents, which belong to the files rather than to the session: any other session holding the same data sees the same anchor. A membership’s declared time range is stored in anchored time, so it moves with its data, but only when everything the membership claims moved by one distance; a membership whose claim also covers data this write leaves alone (another topic in the same file or slice) keeps its declared range. To move a whole session at once, use the session’s own unix-offset endpoint, or declare its anchor_ns at ingest; the file’s timeline-offsets endpoint with no selector does the same in one call only when the whole session is one whole file.

Returns the updated timeline extent records.

The caller must hold session-view access in the org that owns the session, and edit access to every file behind the data being written. An unknown session yields a 404, and one the caller cannot view yields a 401. The topic is reached only through the session’s partitions, so both an unknown topic and one the session holds no data for yield a 404.

An offset yields a 400 when it cannot be read as a time, when it does not fall after the Unix epoch and below 263 ns, or when it would move the data it reaches, or a time range declared over that data, before the Unix epoch or past the largest storable instant (263 - 1 ns). A concurrent writer adding data to the session yields a 409; retry the request.

Access control

• Restricted tokens need the API scope api.everything_else

curl -X POST 'https://api.roboto.ai/v2/topics/id/string/unix-offset' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "session_id": "string",
  "unix_epoch_offset_ns": 0
}'

const response = await fetch("https://api.roboto.ai/v2/topics/id/string/unix-offset", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"session_id\": \"string\",\n  \"unix_epoch_offset_ns\": 0\n}"
});

import requests

response = requests.post(
    "https://api.roboto.ai/v2/topics/id/string/unix-offset",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"session_id\": \"string\",\n  \"unix_epoch_offset_ns\": 0\n}",
)

{
  "data": [
    {
      "created": null,
      "created_by": "string",
      "max_timestamp": null,
      "min_timestamp": null,
      "modified": null,
      "modified_by": "string",
      "org_id": "string",
      "timeline_extent_id": "string",
      "timeline_source_id": "string",
      "topic_part_id": "string",
      "unix_epoch_offset_ns": 0
    }
  ]
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}

{
  "error": {
    "error_code": 0,
    "message": "string",
    "stack_trace": "string"
  }
}