Set file timeline offsets

Calibrate timelines on a file.

Each entry’s unix_epoch_offset_ns is added to stored partition times to place them in Unix-epoch time (session_time_ns = stored_time_ns + unix_epoch_offset_ns). It is a non-negative integer of nanoseconds, or any value roboto.time.to_epoch_nanoseconds reads: a float or numeric string is seconds, and an ISO 8601 string is the instant at which stored time 0 occurred. Selectors narrow which extents an entry touches:

1. topic_name restricts the entry to one topic on this file.
2. timeline_source_name or timeline_source_id restricts the entry to a specific timeline source within the selected scope.
3. An entry with no selectors targets every timeline extent on the file.

When a session declares an explicit time range over this file, that range is stored in anchored time and moves with the data it names: it shifts by the same distance when every partition in the session’s slice of the file carries one offset before this write and one after. Partitions that disagree on either side leave no single distance to move by, so the range stays where it is; that is what happens when an entry’s selectors reach only part of the slice, or when the slice already sat at more than one offset. Every session holding data this write moved has its aggregate bounds recomputed.

Returns the updated timeline extent records. An extent already carrying the offset an entry assigns is left untouched and omitted, so re-stating an anchor that already holds returns an empty list.

At least one entry is required; an empty request yields a 400. All entries apply in a single transaction. Two conditions yield a 404, each with its own message: the file carries no registered topic data to offset at all, or the entries’ selectors together reach no extent on it. An entry that reaches nothing while another entry reaches something is skipped without error. An entry whose offset would move the data it reaches before the Unix epoch or past the largest storable instant (2**63 - 1 ns) yields a 400, and nothing in the request is written. The caller must hold edit access to the file; an unknown file yields a 404.

Access control

• Restricted tokens need the API scope api.everything_else

curl -X POST 'https://api.roboto.ai/v1/files/id/string/timeline-offsets' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "offsets": [
    {
      "unix_epoch_offset_ns": 0,
      "topic_name": null,
      "timeline_source_name": null,
      "timeline_source_id": null
    }
  ]
}'

const response = await fetch("https://api.roboto.ai/v1/files/id/string/timeline-offsets", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"offsets\": [\n    {\n      \"unix_epoch_offset_ns\": 0,\n      \"topic_name\": null,\n      \"timeline_source_name\": null,\n      \"timeline_source_id\": null\n    }\n  ]\n}"
});

import requests

response = requests.post(
    "https://api.roboto.ai/v1/files/id/string/timeline-offsets",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"offsets\": [\n    {\n      \"unix_epoch_offset_ns\": 0,\n      \"topic_name\": null,\n      \"timeline_source_name\": null,\n      \"timeline_source_id\": null\n    }\n  ]\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"
  }
}