---
search:
  tags:
    - Files
    - POST
seo:
  description: >-
    Calibrate timelines on a file. Reference for the POST
    /v1/files/id/{fs_node_id}/timeline-offsets endpoint in the Roboto REST API.
sidebar:
  label: Set file timeline offsets
  badge: POST
title: Set file timeline offsets
type: openapi-operation
---
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`

`POST /v1/files/id/{fs_node_id}/timeline-offsets`