OpenChronology HTTP API

The timelines the caller owns or is a member of, most recently updated first (at most 100). Timelines moderators restricted are listed only for their owner.

Who: Signed in · API keys (timelines:read)

Responses

200

Your timelines.

object

• timelines array of TimelineListItem

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

429

Too many requests. Wait, then try again.

Creates a private timeline from a document (at most 16 MiB of JSON), owned by the caller. Accounts that may not supply data (read-only accounts) are refused with 403.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Request body

Responses

201

The new timeline.

TimelineMetadata

• id Uuid
• owner_id Uuid
• owner string

  Its owner’s username.

• slug string or null

  Its address is /<owner>/<slug>; without one, /<owner>/<id>.

• title string
• description string
• visibility "private" | "public"
• revision Revision
• event_count string · matches ^\d+$

  How many moments it has.

• event_generation string · matches ^\d+$

  A count, as a decimal string.

• star_count string · matches ^\d+$

  A count, as a decimal string.

• starred boolean

  Whether the caller starred it.

• role "admin" | "owner" | "writer" | "editor" | "contributor" | "viewer" | null

  The caller’s role; null for a public timeline they have none in.

• presentation TimePresentation or null
• plugins array or null
• tags array or null
• assets object or null
• comparison SavedComparison or null
• featured boolean
• upstream_id string or null (uuid)

  The timeline this was forked from.

• fork_base_revision_id string or null (uuid)
• head_revision_id string or null (uuid)
• allow_private_forks boolean
• publication_restricted boolean

  A copy of a private timeline, which must stay private.

• storage_bytes string · matches ^\d+$

  A count, as a decimal string.

• created_at string or null (date-time)
• updated_at string (date-time)
• retention_seconds string or null

  How long it keeps moments, in seconds as an exact rational; null for always.

• retention_applied_at string or null (date-time)
• retention_removed string or null
• keep_history boolean

  Whether it keeps saved history.

• history_since string or null
• content_labels array of string
• moderator_labels array of string
• labels array of "nudity" | "violence" | "disturbing"

  Its sensitive-content labels: its owner’s and moderators’.

• moderation object or null

  When moderators restricted it (seen only by its owner and administrators).

  • case Uuid
  • reason string
  • decided_at string (date-time)
  • appealed_at string or null (date-time)
  • appeal_outcome string or null
• preparing boolean

  A copy whose index is still being prepared: until it is ready, only its metadata, settings, sharing and deletion are available (others answer 409).

• canWrite boolean

  May save it.

• canEdit boolean

  May edit a copy of it (to save or propose).

• canPropose boolean

  May open pull requests on it.

• canShare boolean

  May manage its settings, members and deletion.

• canFork boolean
• first Rational or null

  With GET /api/timelines/{id}: its earliest moment’s time.

• last Rational or null

  With GET /api/timelines/{id}: its latest moment’s time.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

The storage the account (or the API key’s owner) uses and may use, so that importers can check that an import fits before writing.

Who: Signed in · API keys (timelines:read)

Responses

200

Storage used and allowed.

object

• usedBytes integer
• quotaBytes integer or null

  Null when no quota applies.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

429

Too many requests. Wait, then try again.

Its metadata, the caller’s permissions, and the times of its first and last moments. Available while a copy is being prepared.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

Responses

200

The timeline.

TimelineMetadata

• id Uuid
• owner_id Uuid
• owner string

  Its owner’s username.

• slug string or null

  Its address is /<owner>/<slug>; without one, /<owner>/<id>.

• title string
• description string
• visibility "private" | "public"
• revision Revision
• event_count string · matches ^\d+$

  How many moments it has.

• event_generation string · matches ^\d+$

  A count, as a decimal string.

• star_count string · matches ^\d+$

  A count, as a decimal string.

• starred boolean

  Whether the caller starred it.

• role "admin" | "owner" | "writer" | "editor" | "contributor" | "viewer" | null

  The caller’s role; null for a public timeline they have none in.

• presentation TimePresentation or null
• plugins array or null
• tags array or null
• assets object or null
• comparison SavedComparison or null
• featured boolean
• upstream_id string or null (uuid)

  The timeline this was forked from.

• fork_base_revision_id string or null (uuid)
• head_revision_id string or null (uuid)
• allow_private_forks boolean
• publication_restricted boolean

  A copy of a private timeline, which must stay private.

• storage_bytes string · matches ^\d+$

  A count, as a decimal string.

• created_at string or null (date-time)
• updated_at string (date-time)
• retention_seconds string or null

  How long it keeps moments, in seconds as an exact rational; null for always.

• retention_applied_at string or null (date-time)
• retention_removed string or null
• keep_history boolean

  Whether it keeps saved history.

• history_since string or null
• content_labels array of string
• moderator_labels array of string
• labels array of "nudity" | "violence" | "disturbing"

  Its sensitive-content labels: its owner’s and moderators’.

• moderation object or null

  When moderators restricted it (seen only by its owner and administrators).

  • case Uuid
  • reason string
  • decided_at string (date-time)
  • appealed_at string or null (date-time)
  • appeal_outcome string or null
• preparing boolean

  A copy whose index is still being prepared: until it is ready, only its metadata, settings, sharing and deletion are available (others answer 409).

• canWrite boolean

  May save it.

• canEdit boolean

  May edit a copy of it (to save or propose).

• canPropose boolean

  May open pull requests on it.

• canShare boolean

  May manage its settings, members and deletion.

• canFork boolean
• first Rational or null

  With GET /api/timelines/{id}: its earliest moment’s time.

• last Rational or null

  With GET /api/timelines/{id}: its latest moment’s time.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

429

Too many requests. Wait, then try again.

Replaces the timeline’s content with a document (at most 16 MiB of JSON), for writers. A revision other than the current one is refused with 409: fetch the timeline again and reconcile. For large timelines, save only what changed (PUT /api/timelines/{id}/changes).

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

The timeline as saved.

TimelineMetadata

• id Uuid
• owner_id Uuid
• owner string

  Its owner’s username.

• slug string or null

  Its address is /<owner>/<slug>; without one, /<owner>/<id>.

• title string
• description string
• visibility "private" | "public"
• revision Revision
• event_count string · matches ^\d+$

  How many moments it has.

• event_generation string · matches ^\d+$

  A count, as a decimal string.

• star_count string · matches ^\d+$

  A count, as a decimal string.

• starred boolean

  Whether the caller starred it.

• role "admin" | "owner" | "writer" | "editor" | "contributor" | "viewer" | null

  The caller’s role; null for a public timeline they have none in.

• presentation TimePresentation or null
• plugins array or null
• tags array or null
• assets object or null
• comparison SavedComparison or null
• featured boolean
• upstream_id string or null (uuid)

  The timeline this was forked from.

• fork_base_revision_id string or null (uuid)
• head_revision_id string or null (uuid)
• allow_private_forks boolean
• publication_restricted boolean

  A copy of a private timeline, which must stay private.

• storage_bytes string · matches ^\d+$

  A count, as a decimal string.

• created_at string or null (date-time)
• updated_at string (date-time)
• retention_seconds string or null

  How long it keeps moments, in seconds as an exact rational; null for always.

• retention_applied_at string or null (date-time)
• retention_removed string or null
• keep_history boolean

  Whether it keeps saved history.

• history_since string or null
• content_labels array of string
• moderator_labels array of string
• labels array of "nudity" | "violence" | "disturbing"

  Its sensitive-content labels: its owner’s and moderators’.

• moderation object or null

  When moderators restricted it (seen only by its owner and administrators).

  • case Uuid
  • reason string
  • decided_at string (date-time)
  • appealed_at string or null (date-time)
  • appeal_outcome string or null
• preparing boolean

  A copy whose index is still being prepared: until it is ready, only its metadata, settings, sharing and deletion are available (others answer 409).

• canWrite boolean

  May save it.

• canEdit boolean

  May edit a copy of it (to save or propose).

• canPropose boolean

  May open pull requests on it.

• canShare boolean

  May manage its settings, members and deletion.

• canFork boolean
• first Rational or null

  With GET /api/timelines/{id}: its earliest moment’s time.

• last Rational or null

  With GET /api/timelines/{id}: its latest moment’s time.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Deletes the timeline and its saved history, for its owner (or an administrator).

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Responses

200

Deleted.

Ok

• ok true

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

429

Too many requests. Wait, then try again.

A cheap check of whether a timeline was saved since it was read.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

Responses

200

Its revision.

object

• id Uuid
• revision Revision

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

429

Too many requests. Wait, then try again.

For its owner (or an administrator): any of its visibility, private forking policy, retention period, whether it keeps saved history, sensitive-content labels and address. Turning saved history off deletes past revisions at once, apart from those forks and pull requests still use. A timeline goes public only if moderators have not restricted it, it is not a copy of a private timeline, and (for a comparison) all its sources are public. Changing anything but the address saves a new revision.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

The timeline with its new settings.

TimelineSettingsResult

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

For its owner (or an administrator).

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

Responses

200

Its members, by username.

object

• members array of TimelineMember

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

429

Too many requests. Wait, then try again.

For its owner (or an administrator). Viewers read a private timeline, contributors may also propose changes, writers may also save.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

Done.

Ok

• ok true

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

For its owner (or an administrator). The body names the member.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

Done.

Ok

• ok true

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

Its metadata and whole document, streamed as it is read (moments by ID, durations by start). With download=1, the document alone, as an .ochx file named after its title. Guests get public timelines only, through the browser fork limits (5,000 entries, 4 MiB) and its rate limit; larger timelines are read a window at a time with POST /api/timelines/{id}/query.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• download "1" in query

  With 1: the document alone, as an attachment.

Responses

200

The timeline and its document; with download=1, the document alone.

TimelineWithDocument or TimelineDocument

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

The document alone, streamed, as an attachment named by the end of the address (so browsers that name downloads after their address name it too). For signed-in callers.

Who: Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• name string in path required

  The file name to save it as.

Responses

200

The document.

TimelineDocument

• format "openchronology" required
• version 1 required
• title string required · at most 300 characters
• description string required · at most 20000 characters
• events array of Moment required

  Its moments; IDs unique.

• durations array of Duration
• relationships array of Relationship
• presentation TimePresentation
• plugins array of object · at most 32 items

  Installed plugins (at most 128 KiB in all), each with its manifest. Their scripts must compile.

  • manifest object required

    The plugin’s manifest (apiVersion 1).

  • enabled boolean required
  • settings object

    Values of the timeline-wide settings its manifest declares (such as the timeline’s background image address, or its theme’s colors and fonts), by key. Values for undeclared settings are dropped.

• tags array of string · at most 40 items

  The timeline’s tags: lowercased, without commas or control characters.

• assets object

  Copies of its images, by their HTTPS address: base64 data URIs of at most 2 MiB each and 8 MiB in all.

• comparison SavedComparison

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

The timeline as a desktop .och file (at most the server’s file limit, 64 MiB by default; 413 beyond it), for signed-in callers; ten a minute per client address. Comparisons cannot be downloaded: download their sources.

Who: Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

Responses

200

The SQLite file.

application/vnd.openchronology.sqlite

string

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

422

Converting it took too long.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Reads a bounded part of a timeline, by kind: moments in a range a page at a time, an overview of a range for drawing it, durations in a range, one event, the entities related to one, a search of its moments and durations, or the tags it uses. A read, so API keys need only timelines:read and sessions no CSRF token. Comparisons are read through their sources (409).

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

What the query reads.

TimelineQueryResult

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

The last (or first) eight distinct times its moments have, latest (or earliest) first: for following a timeline that grows at one end.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• direction "last" | "first" in query

  Which end to read.

Responses

200

Its times.

object

• revision Revision
• event_generation string · matches ^\d+$

  A count, as a decimal string.

• times array of Rational · at most 8 items

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

A sparse save, for writers: the settings and only the changed moments, durations and relationships (at most 5,000 events, and 5,000 relationships, per request; at most 16 MiB). Small changes apply in place. Without base, a stale revision is refused with 409; with it, the save merges onto what was saved since, and conflicts answer 409 with conflicts. A save the server stops as too slow answers 503: send fewer changes at a time.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

The timeline as saved.

TimelineMetadata

• id Uuid
• owner_id Uuid
• owner string

  Its owner’s username.

• slug string or null

  Its address is /<owner>/<slug>; without one, /<owner>/<id>.

• title string
• description string
• visibility "private" | "public"
• revision Revision
• event_count string · matches ^\d+$

  How many moments it has.

• event_generation string · matches ^\d+$

  A count, as a decimal string.

• star_count string · matches ^\d+$

  A count, as a decimal string.

• starred boolean

  Whether the caller starred it.

• role "admin" | "owner" | "writer" | "editor" | "contributor" | "viewer" | null

  The caller’s role; null for a public timeline they have none in.

• presentation TimePresentation or null
• plugins array or null
• tags array or null
• assets object or null
• comparison SavedComparison or null
• featured boolean
• upstream_id string or null (uuid)

  The timeline this was forked from.

• fork_base_revision_id string or null (uuid)
• head_revision_id string or null (uuid)
• allow_private_forks boolean
• publication_restricted boolean

  A copy of a private timeline, which must stay private.

• storage_bytes string · matches ^\d+$

  A count, as a decimal string.

• created_at string or null (date-time)
• updated_at string (date-time)
• retention_seconds string or null

  How long it keeps moments, in seconds as an exact rational; null for always.

• retention_applied_at string or null (date-time)
• retention_removed string or null
• keep_history boolean

  Whether it keeps saved history.

• history_since string or null
• content_labels array of string
• moderator_labels array of string
• labels array of "nudity" | "violence" | "disturbing"

  Its sensitive-content labels: its owner’s and moderators’.

• moderation object or null

  When moderators restricted it (seen only by its owner and administrators).

  • case Uuid
  • reason string
  • decided_at string (date-time)
  • appealed_at string or null (date-time)
  • appeal_outcome string or null
• preparing boolean

  A copy whose index is still being prepared: until it is ready, only its metadata, settings, sharing and deletion are available (others answer 409).

• canWrite boolean

  May save it.

• canEdit boolean

  May edit a copy of it (to save or propose).

• canPropose boolean

  May open pull requests on it.

• canShare boolean

  May manage its settings, members and deletion.

• canFork boolean
• first Rational or null

  With GET /api/timelines/{id}: its earliest moment’s time.

• last Rational or null

  With GET /api/timelines/{id}: its latest moment’s time.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Deletes every moment from lower to upper (both included) and the durations wholly inside, as one save, for writers. Durations that followed a deleted moment keep its time; links of deleted entities go. At most 200,000 moments at a time: more: true means send it again for the rest.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

What was deleted, and the timeline afterwards.

object

• removed object
  • moments integer
  • durations integer
• more boolean

  Whether the range holds more to delete.

• timeline TimelineMetadata

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Shifts and scales the times of every event, or of those a filter selects, for good, as one save, for writers. A duration’s fixed ends are mapped; ends that follow a moment move with it. A stale revision and comparisons are refused with 409. Other saves wait until it finishes; it carries on if the client goes away. With Accept: application/x-ndjson, the reply streams JSON lines as it works: {"progress": …} ({"reading": true}, {"done", "total"}, or {"rebuilding": stage, "done", "total"}), then {"result": …}, or {"error": {"status", "message"}} for a failure once streaming. Without it, the reply is the result alone.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

How many events (moments and durations) moved, and the timeline as saved.

object

• moved object
  • moments integer
  • durations integer
• timeline TimelineMetadata

application/x-ndjson

string

JSON lines: progress, then the result or an error.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

415

The body is not JSON (Content-Type: application/json).

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Converts a desktop .och SQLite file (at most the server’s file limit, 64 MiB by default; 413 beyond it) to a document, without saving anything. Ten conversions a minute per account; two at once per server.

Who: Signed in, with the CSRF token

Request body

Responses

200

The file’s document.

object

• document TimelineDocument

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

415

The body is not a SQLite timeline file.

422

Converting it took too long.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Converts a document (at most 16 MiB of JSON) to a desktop .och SQLite file (at most the server’s file limit, 64 MiB by default; 413 beyond it), keeping the images it embeds. Ten conversions a minute per account; two at once per server.

Who: Signed in, with the CSRF token

Request body

Responses

200

The SQLite file.

application/vnd.openchronology.sqlite

string

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

415

The body is not JSON (Content-Type: application/json).

422

Converting it took too long.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

A server-sent event stream of the revisions of one to eight timelines the caller may read. Each starts with a revision event per timeline, then one each time it is saved: event: revision with {"id", "revision"}. If the caller’s access to one changes, or their session does, an event: access with {"error"} (and the timeline’s id) ends the stream: connect again. A comment line every 25 seconds keeps it open. API keys and other origins are refused.

Who: Anyone · Signed in

Parameters

• timelines string in query required

  One to eight timeline IDs, separated by commas.

Responses

200

The event stream.

text/event-stream

string

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

503

The server’s storage, or a service it needs, is unavailable.

For a link to a public timeline on this site (its page, or one of its moments’ or durations’), the HTML to embed it. Cached for an hour; open to other origins.

Who: Anyone · Signed in

Parameters

• url string (uri) in query required

  The link: /timelines/<id> or /<owner>/<slug or id>, optionally followed by /moments/<id> or /durations/<id>, or a link fragment.

• format "json" in query

  Only json is available.

• maxwidth integer in query

  The widest it may be; at most 800 is given.

• maxheight integer in query

  The tallest it may be; at most 480 is given.

Responses

200

The embed.

OEmbed

• version "1.0"
• type "rich"
• provider_name string
• provider_url string (uri)
• title string
• author_name string

  The owner’s username.

• author_url string (uri)
• html string

  An <iframe> of the timeline’s embed page.

• width integer · ≥ 200, ≤ 800
• height integer · ≥ 160, ≤ 480
• thumbnail_url string (uri)

  Left out for a timeline with sensitive-content labels.

• thumbnail_width 1200
• thumbnail_height 630
• cache_age 3600

400

The request is malformed or a value is not allowed.

404

Not found, or not visible to this account.

501

Not the json format, or less room than 200 × 160.

Lists timelines a page at a time. With no search text, owner or starredBy, the public scope browses: public timelines of established accounts, and featured ones; readers who are not signed in, or whose accounts may be under 18, browse no labelled timelines. Text search uses PostgreSQL full-text search (websearch_to_tsquery, so quoted phrases and -exclusions work) over titles, tags, descriptions and moment text, and finds every account’s public timelines, established accounts’ first. A POST, so it counts as a read for API keys.

Who: Anyone · Signed in · API keys (timelines:read)

Request body

Responses

200

OK.

TimelineSearchPage

• timelines array of TimelineSearchResult required
• total integer required · ≥ 0

  How many timelines match in all.

• page integer required · ≥ 1
• limit integer required · ≥ 1
• pages integer required · ≥ 0

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

Stars (or unstars) a timeline the account can read. Starring twice, or unstarring an unstarred timeline, changes nothing. The timeline’s popularity and its owner’s standing are updated at once.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

OK.

object

• starred boolean required
• star_count string required · matches ^\d+$

  How many accounts have starred it now, as a decimal string.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

Copies the timeline’s saved head into a new timeline owned by the caller, linked to it as upstream so it can sync and propose pull requests. The fork starts private, and stays private when upstream is private. Its saved history and index read through to upstream’s instead of being copied, so it opens at once; a large copy may answer with preparing true while the rest of its index is copied. Anyone signed in may fork a public timeline; a private one needs its owner, or the owner’s *Allow invited readers to fork* setting.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

201

The new fork’s metadata (without time bounds).

TimelineMetadata

• id Uuid
• owner_id Uuid
• owner string

  Its owner’s username.

• slug string or null

  Its address is /<owner>/<slug>; without one, /<owner>/<id>.

• title string
• description string
• visibility "private" | "public"
• revision Revision
• event_count string · matches ^\d+$

  How many moments it has.

• event_generation string · matches ^\d+$

  A count, as a decimal string.

• star_count string · matches ^\d+$

  A count, as a decimal string.

• starred boolean

  Whether the caller starred it.

• role "admin" | "owner" | "writer" | "editor" | "contributor" | "viewer" | null

  The caller’s role; null for a public timeline they have none in.

• presentation TimePresentation or null
• plugins array or null
• tags array or null
• assets object or null
• comparison SavedComparison or null
• featured boolean
• upstream_id string or null (uuid)

  The timeline this was forked from.

• fork_base_revision_id string or null (uuid)
• head_revision_id string or null (uuid)
• allow_private_forks boolean
• publication_restricted boolean

  A copy of a private timeline, which must stay private.

• storage_bytes string · matches ^\d+$

  A count, as a decimal string.

• created_at string or null (date-time)
• updated_at string (date-time)
• retention_seconds string or null

  How long it keeps moments, in seconds as an exact rational; null for always.

• retention_applied_at string or null (date-time)
• retention_removed string or null
• keep_history boolean

  Whether it keeps saved history.

• history_since string or null
• content_labels array of string
• moderator_labels array of string
• labels array of "nudity" | "violence" | "disturbing"

  Its sensitive-content labels: its owner’s and moderators’.

• moderation object or null

  When moderators restricted it (seen only by its owner and administrators).

  • case Uuid
  • reason string
  • decided_at string (date-time)
  • appealed_at string or null (date-time)
  • appeal_outcome string or null
• preparing boolean

  A copy whose index is still being prepared: until it is ready, only its metadata, settings, sharing and deletion are available (others answer 409).

• canWrite boolean

  May save it.

• canEdit boolean

  May edit a copy of it (to save or propose).

• canPropose boolean

  May open pull requests on it.

• canShare boolean

  May manage its settings, members and deletion.

• canFork boolean
• first Rational or null

  With GET /api/timelines/{id}: its earliest moment’s time.

• last Rational or null

  With GET /api/timelines/{id}: its latest moment’s time.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

Like a fork, but the copy has no upstream link or merge ancestry: an independent timeline owned by the caller. It shares saved history with its source the same way.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

201

The new copy’s metadata (without time bounds).

TimelineMetadata

• id Uuid
• owner_id Uuid
• owner string

  Its owner’s username.

• slug string or null

  Its address is /<owner>/<slug>; without one, /<owner>/<id>.

• title string
• description string
• visibility "private" | "public"
• revision Revision
• event_count string · matches ^\d+$

  How many moments it has.

• event_generation string · matches ^\d+$

  A count, as a decimal string.

• star_count string · matches ^\d+$

  A count, as a decimal string.

• starred boolean

  Whether the caller starred it.

• role "admin" | "owner" | "writer" | "editor" | "contributor" | "viewer" | null

  The caller’s role; null for a public timeline they have none in.

• presentation TimePresentation or null
• plugins array or null
• tags array or null
• assets object or null
• comparison SavedComparison or null
• featured boolean
• upstream_id string or null (uuid)

  The timeline this was forked from.

• fork_base_revision_id string or null (uuid)
• head_revision_id string or null (uuid)
• allow_private_forks boolean
• publication_restricted boolean

  A copy of a private timeline, which must stay private.

• storage_bytes string · matches ^\d+$

  A count, as a decimal string.

• created_at string or null (date-time)
• updated_at string (date-time)
• retention_seconds string or null

  How long it keeps moments, in seconds as an exact rational; null for always.

• retention_applied_at string or null (date-time)
• retention_removed string or null
• keep_history boolean

  Whether it keeps saved history.

• history_since string or null
• content_labels array of string
• moderator_labels array of string
• labels array of "nudity" | "violence" | "disturbing"

  Its sensitive-content labels: its owner’s and moderators’.

• moderation object or null

  When moderators restricted it (seen only by its owner and administrators).

  • case Uuid
  • reason string
  • decided_at string (date-time)
  • appealed_at string or null (date-time)
  • appeal_outcome string or null
• preparing boolean

  A copy whose index is still being prepared: until it is ready, only its metadata, settings, sharing and deletion are available (others answer 409).

• canWrite boolean

  May save it.

• canEdit boolean

  May edit a copy of it (to save or propose).

• canPropose boolean

  May open pull requests on it.

• canShare boolean

  May manage its settings, members and deletion.

• canFork boolean
• first Rational or null

  With GET /api/timelines/{id}: its earliest moment’s time.

• last Rational or null

  With GET /api/timelines/{id}: its latest moment’s time.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

Merges what upstream saved since its latest common ancestor with the fork into the fork, entity by entity, and records a sync checkpoint with both parents. Does nothing when upstream is already an ancestor. Refused with 409 when the fork has no upstream, the revision is stale, the two have several equally good common ancestors, fields conflict (listed in conflicts), or upstream no longer keeps the revision they last shared. A public fork cannot sync a private upstream.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

The fork’s metadata after syncing.

TimelineMetadata

• id Uuid
• owner_id Uuid
• owner string

  Its owner’s username.

• slug string or null

  Its address is /<owner>/<slug>; without one, /<owner>/<id>.

• title string
• description string
• visibility "private" | "public"
• revision Revision
• event_count string · matches ^\d+$

  How many moments it has.

• event_generation string · matches ^\d+$

  A count, as a decimal string.

• star_count string · matches ^\d+$

  A count, as a decimal string.

• starred boolean

  Whether the caller starred it.

• role "admin" | "owner" | "writer" | "editor" | "contributor" | "viewer" | null

  The caller’s role; null for a public timeline they have none in.

• presentation TimePresentation or null
• plugins array or null
• tags array or null
• assets object or null
• comparison SavedComparison or null
• featured boolean
• upstream_id string or null (uuid)

  The timeline this was forked from.

• fork_base_revision_id string or null (uuid)
• head_revision_id string or null (uuid)
• allow_private_forks boolean
• publication_restricted boolean

  A copy of a private timeline, which must stay private.

• storage_bytes string · matches ^\d+$

  A count, as a decimal string.

• created_at string or null (date-time)
• updated_at string (date-time)
• retention_seconds string or null

  How long it keeps moments, in seconds as an exact rational; null for always.

• retention_applied_at string or null (date-time)
• retention_removed string or null
• keep_history boolean

  Whether it keeps saved history.

• history_since string or null
• content_labels array of string
• moderator_labels array of string
• labels array of "nudity" | "violence" | "disturbing"

  Its sensitive-content labels: its owner’s and moderators’.

• moderation object or null

  When moderators restricted it (seen only by its owner and administrators).

  • case Uuid
  • reason string
  • decided_at string (date-time)
  • appealed_at string or null (date-time)
  • appeal_outcome string or null
• preparing boolean

  A copy whose index is still being prepared: until it is ready, only its metadata, settings, sharing and deletion are available (others answer 409).

• canWrite boolean

  May save it.

• canEdit boolean

  May edit a copy of it (to save or propose).

• canPropose boolean

  May open pull requests on it.

• canShare boolean

  May manage its settings, members and deletion.

• canFork boolean
• first Rational or null

  With GET /api/timelines/{id}: its earliest moment’s time.

• last Rational or null

  With GET /api/timelines/{id}: its latest moment’s time.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

Returns a public timeline’s saved head whole, for an editor to keep as an in-memory draft rather than on the server. Only timelines of at most 5,000 entries (stack entries included) and 4 MiB qualify; larger ones are refused with 413, and nothing is truncated. Comparisons are refused with 409. At most four copies are made at once (429 when busy), and copies are rate limited by address. Anyone may copy one, guests included: it reads, and keeps nothing on the server.

Who: Anyone · Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

OK.

BrowserFork

• document TimelineDocument required
• source object required

  What was copied.

  • id Uuid
  • revision Revision
  • savedRevision Uuid

    The saved revision copied.

• limits object required

  The limits a browser copy is held to.

  • events 5000
  • bytes 4194304

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

A page of the timeline’s saved checkpoints, newest first, twenty per page. A past revision whose content is not kept (the timeline stopped keeping saved history) is listed with available false.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• page integer in query

  The page, from 1.

Responses

200

OK.

HistoryPage

• revisions array of HistoryRevision required · at most 20 items
• page integer required · ≥ 1
• more boolean required

  Whether there is a next page.

• keepHistory boolean required

  Whether the timeline keeps saved history.

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

The timeline as it was saved at that checkpoint, streamed as {"document": …}. With download=1 it is the bare document, sent as an attachment named timeline-<saved>.ochx. Only this timeline’s checkpoints are found; one whose content is not kept answers 409.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• saved Uuid in path required

  The saved revision’s ID (from the history list).

• download "1" in query

  1 to download the document as an .ochx file.

Responses

200

The saved document; with download=1, the bare document as an .ochx attachment (Content-Disposition set).

object or TimelineDocument

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

The timeline’s pull requests, newest first, twelve per page. POST …/proposals/search takes the same request as a body, with a chosen page size.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• page integer in query

  The page, from 1.

Responses

200

OK.

ProposalPage

• proposals array of ProposalSummary required
• total integer required · ≥ 0
• page integer required · ≥ 1
• pages integer required · ≥ 0

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

Offers changes to the timeline, either from a saved revision of one of its forks (sourceTimelineId and sourceRevisionId; needs write access to the fork) or as a whole proposed document made on its current revision (baseRevision and document). The proposal is pinned to those revisions: later saves to the fork do not change it. Needs contributor access, or any signed-in account on a public timeline. Both the timeline and the fork must keep saved history. An author may have at most 100 open pull requests per timeline. New accounts may first be asked for human verification (428). Answers with the pull request, as GET does.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

201

The pull request opened.

Proposal

• id Uuid
• timeline_id Uuid
• author_id Uuid
• author string

  The author’s username.

• title string
• body string

  Its description, as plain text.

• status "open" | "merged" | "rejected" | "closed"
• revision Revision

  The pull request’s own revision: send it with updates and resolutions.

• base_revision Revision

  The timeline revision it is based on.

• base_revision_id Uuid

  The saved revision it is based on.

• source_revision_id Uuid

  The saved revision it proposes.

• source_timeline_id Uuid or null

  The fork it came from, if any.

• from_fork boolean
• resolved_by Uuid or null
• merged_revision Revision or null

  The timeline revision its merge made.

• merged_revision_id Uuid or null
• created_at string (date-time)
• updated_at string (date-time)
• changes ProposalChanges
• canMerge boolean
• canUpdate boolean
• canClose boolean
• upstreamRevision Revision

  The timeline’s current revision: a rebase is needed when it differs from base_revision.

• source object or null

  The source fork, when it came from one the caller can read.

  • id Uuid
  • title string
  • head_revision_id Uuid
  • canWrite boolean

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

428

Human verification is needed first: answer the challenge and send its token in X-Challenge.

429

Too many requests. Wait, then try again.

The timeline’s pull requests, newest first. A POST so the desktop app can send it without a query string; it counts as a read for API keys.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

Request body

Responses

200

OK.

ProposalPage

• proposals array of ProposalSummary required
• total integer required · ≥ 0
• page integer required · ≥ 1
• pages integer required · ≥ 0

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

The pull request with its pinned revisions, a summary of what it changes (computed from saved history), and what the caller may do with it.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• proposal Uuid in path required

  The pull request’s ID.

Responses

200

OK.

Proposal

• id Uuid
• timeline_id Uuid
• author_id Uuid
• author string

  The author’s username.

• title string
• body string

  Its description, as plain text.

• status "open" | "merged" | "rejected" | "closed"
• revision Revision

  The pull request’s own revision: send it with updates and resolutions.

• base_revision Revision

  The timeline revision it is based on.

• base_revision_id Uuid

  The saved revision it is based on.

• source_revision_id Uuid

  The saved revision it proposes.

• source_timeline_id Uuid or null

  The fork it came from, if any.

• from_fork boolean
• resolved_by Uuid or null
• merged_revision Revision or null

  The timeline revision its merge made.

• merged_revision_id Uuid or null
• created_at string (date-time)
• updated_at string (date-time)
• changes ProposalChanges
• canMerge boolean
• canUpdate boolean
• canClose boolean
• upstreamRevision Revision

  The timeline’s current revision: a rebase is needed when it differs from base_revision.

• source object or null

  The source fork, when it came from one the caller can read.

  • id Uuid
  • title string
  • head_revision_id Uuid
  • canWrite boolean

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

Replaces an open pull request’s title, description and proposed changes: a new saved revision of the same fork, or a new proposed document on the same base. Only its author, while still allowed to contribute, may. revision is the pull request’s revision as last read; a stale one answers 409. To move a document proposal onto a newer upstream revision, rebase it instead.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

• proposal Uuid in path required

  The pull request’s ID.

Request body

Responses

200

The pull request updated.

Proposal

• id Uuid
• timeline_id Uuid
• author_id Uuid
• author string

  The author’s username.

• title string
• body string

  Its description, as plain text.

• status "open" | "merged" | "rejected" | "closed"
• revision Revision

  The pull request’s own revision: send it with updates and resolutions.

• base_revision Revision

  The timeline revision it is based on.

• base_revision_id Uuid

  The saved revision it is based on.

• source_revision_id Uuid

  The saved revision it proposes.

• source_timeline_id Uuid or null

  The fork it came from, if any.

• from_fork boolean
• resolved_by Uuid or null
• merged_revision Revision or null

  The timeline revision its merge made.

• merged_revision_id Uuid or null
• created_at string (date-time)
• updated_at string (date-time)
• changes ProposalChanges
• canMerge boolean
• canUpdate boolean
• canClose boolean
• upstreamRevision Revision

  The timeline’s current revision: a rebase is needed when it differs from base_revision.

• source object or null

  The source fork, when it came from one the caller can read.

  • id Uuid
  • title string
  • head_revision_id Uuid
  • canWrite boolean

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

The pull request’s proposed timeline, whole, to view, edit or export. 409 when its revision is no longer kept.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• proposal Uuid in path required

  The pull request’s ID.

Responses

200

The proposed timeline.

object

• document TimelineDocument required

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

merge applies the pull request’s changes to the timeline, entity by entity, as a new revision; reject declines it; both need write access. close withdraws it, by its author or a writer. rebase (author only) remakes it on the timeline’s current revision, keeping it open; a document pull request must be rebased before it can merge once upstream has changed. Fields changed on both sides refuse a merge or rebase with 409 and conflicts (field names such as moment example.metadata.title); nothing is saved. A resolved pull request cannot be reopened.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

• proposal Uuid in path required

  The pull request’s ID.

Request body

Responses

200

The pull request after the action.

Proposal

• id Uuid
• timeline_id Uuid
• author_id Uuid
• author string

  The author’s username.

• title string
• body string

  Its description, as plain text.

• status "open" | "merged" | "rejected" | "closed"
• revision Revision

  The pull request’s own revision: send it with updates and resolutions.

• base_revision Revision

  The timeline revision it is based on.

• base_revision_id Uuid

  The saved revision it is based on.

• source_revision_id Uuid

  The saved revision it proposes.

• source_timeline_id Uuid or null

  The fork it came from, if any.

• from_fork boolean
• resolved_by Uuid or null
• merged_revision Revision or null

  The timeline revision its merge made.

• merged_revision_id Uuid or null
• created_at string (date-time)
• updated_at string (date-time)
• changes ProposalChanges
• canMerge boolean
• canUpdate boolean
• canClose boolean
• upstreamRevision Revision

  The timeline’s current revision: a rebase is needed when it differs from base_revision.

• source object or null

  The source fork, when it came from one the caller can read.

  • id Uuid
  • title string
  • head_revision_id Uuid
  • canWrite boolean

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

Comments oldest first, fifty at a time. Pass the previous page’s next as after for the next page.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• proposal Uuid in path required

  The pull request’s ID.

• after string in query

  Return comments after this comment ID (0 for the first page).

Responses

200

OK.

ProposalCommentPage

• comments array of ProposalComment required · at most 50 items
• next string or null required

  Send as after for the next page; null on the last.

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

Adds a plain-text comment. Anyone signed in who can read the timeline may comment, on open and resolved pull requests alike. New accounts may first be asked for human verification (428).

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

• proposal Uuid in path required

  The pull request’s ID.

Request body

Responses

201

The comment was added.

object

• id string required · matches ^\d+$

  The new comment’s ID.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

413

Too large, or over the account’s storage.

428

Human verification is needed first: answer the challenge and send its token in X-Challenge.

429

Too many requests. Wait, then try again.

The same as GET …/comments, with after in the body, for the desktop app. Counts as a read for API keys.

Who: Anyone · Signed in · API keys (timelines:read)

Parameters

• id Uuid in path required

  The timeline's ID.

• proposal Uuid in path required

  The pull request’s ID.

Request body

Responses

200

OK.

ProposalCommentPage

• comments array of ProposalComment required · at most 50 items
• next string or null required

  Send as after for the next page; null on the last.

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

Deletes one of the caller’s own comments, at any time.

Who: Signed in, with the CSRF token · API keys (timelines:write)

Parameters

• id Uuid in path required

  The timeline's ID.

• proposal Uuid in path required

  The pull request’s ID.

• comment string in path required

  The comment’s ID.

Responses

200

Deleted.

Ok

• ok true

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

409

It conflicts with the current state, such as a stale revision.

429

Too many requests. Wait, then try again.

Who is signed in (or user: null), the CSRF token to send with changes, and what this server offers. When nobody is signed in, csrf is the sign-in token, set as the oc_login cookie too: signing in, registering and the other steps before a session send it as X-CSRF-Token.

Who: Anyone · Signed in

Responses

200

The session.

Session

• server boolean required

  Whether the server has storage. Without it, only browser timelines work.

• dashboard true required
• user SessionUser or null required
• csrf string or null required · matches ^[a-f0-9]{64}$

  Signed in: the session’s CSRF token, sent as X-CSRF-Token with every change. Signed out: the sign-in token (also the oc_login cookie), sent the same way by sign-in requests. Null without server storage.

• providers array of SignInProvider required

  The sign-in providers this server offers.

• security object

  Which account-security features the server offers (it needs email and an encryption key configured). Absent without server storage.

  • email boolean
  • mfa boolean
  • registration boolean
• challenge "mfa" | "email" | null

  A sign-in step this browser has pending (mfa: a two-factor code; email: an email address to confirm), or null.

• fileExchange boolean required

  Whether the server converts SQLite (.och) timeline files.

• fileLimit integer

  The largest .och file the server converts, in bytes (TIMELINE_FILE_BYTES, 64 MiB by default).

• compareLimit integer

  How many timelines this account (or a guest) may compare at once.

• entryLimit integer or null

  How many moments (and durations, relationships) a timeline may hold; null for no limit.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

Signs out the account’s other browser and desktop sessions at once, keeping this one. API keys are not affected. No body.

Who: Signed in, with the CSRF token

Responses

200

Signed out.

Ok

• ok true

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

503

The server’s storage, or a service it needs, is unavailable.

Ends this session. No body.

Who: Signed in, with the CSRF token

Responses

200

Signed out.

Ok

• ok true

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

503

The server’s storage, or a service it needs, is unavailable.

Before signing in, send X-CSRF-Token equal to the sign-in token: the csrf that GET /api/session returns along with its oc_login cookie (valid ten minutes). A caller that is already signed in sends its session’s CSRF token instead.

A signed-in browser gets the session cookie; the desktop app (X-OC-Client: desktop) gets a session token instead. Signing in replaces the caller’s previous session.

When the account needs another step, the answer is a SignInStep instead, with the oc_challenge cookie (five minutes): mfa asks for POST /api/auth/mfa/complete, email for POST /api/auth/email/enroll.

After three failures in fifteen minutes from the client address or for the account, it asks for human verification (428) instead of locking the account. Ten attempts a minute per client address and per account (429).

Who: Signed in, with the CSRF token

Parameters

• X-OC-Client "desktop" in header

  Send desktop from the desktop app: the sign-in then returns a session token (a bearer credential) instead of setting the session cookie.

• X-Challenge string in header

  The answer to the challenge a 428 carried: base64url of the JSON of a HumanChallengeAnswer. Each answer works once, for the action it was issued for, within ten minutes.

Request body

Responses

200

Signed in, or the next step.

SignedIn or SignInStep

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

428

Human verification is needed first: answer the challenge and send its token in X-Challenge.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Before signing in, send X-CSRF-Token equal to the sign-in token: the csrf that GET /api/session returns along with its oc_login cookie (valid ten minutes). A caller that is already signed in sends its session’s CSRF token instead.

Makes a pending registration and emails a confirmation, which POST /api/auth/email/verify accepts in this browser within 24 hours; the account exists only then, and no session is made here. The answer is the same whether or not the username or email is taken. Always asks for human verification (428). Unavailable (503) until the server has email and an encryption key configured.

Who: Signed in, with the CSRF token

Parameters

• X-Challenge string in header

  The answer to the challenge a 428 carried: base64url of the JSON of a HumanChallengeAnswer. Each answer works once, for the action it was issued for, within ten minutes.

Request body

Responses

200

Registration pending its email confirmation.

Registered

• message string required
• verificationRequired true required

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

428

Human verification is needed first: answer the challenge and send its token in X-Challenge.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

The mfa step of a sign-in: send an authenticator or recovery code. Needs the oc_challenge cookie the sign-in set, in the same browser (oc_login), within five minutes; five wrong codes close the step, and signing in starts again.

Before signing in, send X-CSRF-Token equal to the sign-in token: the csrf that GET /api/session returns along with its oc_login cookie (valid ten minutes). A caller that is already signed in sends its session’s CSRF token instead.

Signs in as the sign-in began: a browser session cookie, or a desktop token.

Who: Signed in, with the CSRF token

Request body

Responses

200

Signed in.

any

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

The email step of a sign-in: an account without a confirmed email address (such as one new from a sign-in provider) gives one, and confirms it with the emailed link (POST /api/auth/email/verify) before it can sign in. Needs the oc_challenge cookie of that step. A new account gives its year of birth here too; one under 13 is closed.

Before signing in, send X-CSRF-Token equal to the sign-in token: the csrf that GET /api/session returns along with its oc_login cookie (valid ten minutes). A caller that is already signed in sends its session’s CSRF token instead.

Always asks for human verification (428), since it sends email to an address the requester types. The answer is the same whether or not another account has the address.

Who: Signed in, with the CSRF token

Parameters

• X-Challenge string in header

  The answer to the challenge a 428 carried: base64url of the JSON of a HumanChallengeAnswer. Each answer works once, for the action it was issued for, within ten minutes.

Request body

Responses

200

Confirmation sent.

AccountMessage

• message string required

  What happened, for people.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

428

Human verification is needed first: answer the challenge and send its token in X-Challenge.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Accepts the token from an emailed confirmation link (/login#verify=…): it completes a registration (making the account), confirms an email address given at sign-in, or completes an email change. It works only in the browser that asked for it (its oc_verify cookie), within 24 hours.

Confirming signs the account out everywhere; sign in afterwards.

Before signing in, send X-CSRF-Token equal to the sign-in token: the csrf that GET /api/session returns along with its oc_login cookie (valid ten minutes). A caller that is already signed in sends its session’s CSRF token instead.

Who: Signed in, with the CSRF token

Request body

Responses

200

Confirmed.

AccountMessage

• message string required

  What happened, for people.

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Emails a reset link (/login#reset=…, valid 30 minutes, once) to an account with that confirmed address and a password. The answer is the same for every address.

Before signing in, send X-CSRF-Token equal to the sign-in token: the csrf that GET /api/session returns along with its oc_login cookie (valid ten minutes). A caller that is already signed in sends its session’s CSRF token instead.

Always asks for human verification (428). Limited per client address and per email address (429).

Who: Signed in, with the CSRF token

Parameters

• X-Challenge string in header

  The answer to the challenge a 428 carried: base64url of the JSON of a HumanChallengeAnswer. Each answer works once, for the action it was issued for, within ten minutes.

Request body

Responses

200

A link is sent if the account is eligible.

AccountMessage

• message string required

  What happened, for people.

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

428

Human verification is needed first: answer the challenge and send its token in X-Challenge.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Sets a new password with the token from a reset link. It signs the account out everywhere, revokes its API keys and pending desktop approvals, and does not turn two-factor authentication off.

Before signing in, send X-CSRF-Token equal to the sign-in token: the csrf that GET /api/session returns along with its oc_login cookie (valid ten minutes). A caller that is already signed in sends its session’s CSRF token instead.

Who: Signed in, with the CSRF token

Request body

Responses

200

Password reset.

AccountMessage

• message string required

  What happened, for people.

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Begins signing in with Google, GitHub or Facebook, or with link: true, linking one to the signed-in account (which needs a sign-in within the last five minutes). Send the browser to the url returned; the provider returns it to GET /api/auth/{provider}/callback within ten minutes.

Before signing in, send X-CSRF-Token equal to the sign-in token: the csrf that GET /api/session returns along with its oc_login cookie (valid ten minutes). A caller that is already signed in sends its session’s CSRF token instead.

Who: Signed in, with the CSRF token

Parameters

• provider SignInProvider in path required

  The sign-in provider. Only providers this server configures work (see providers in GET /api/session).

Request body

Responses

200

Where to send the browser.

object

• url string (uri) required

  The provider’s authorization page, to send the browser to.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

404

Not found, or not visible to this account.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Where the provider sends the browser back: not called directly. It needs the oc_oauth cookie of the browser that started, and is used once.

It answers with a redirect (303): to the return location when signed in, linked or cancelled (?auth_cancelled=1), or to /login?step=mfa|email&returnTo=… when the sign-in needs another step. Signing in replaces the browser’s previous session. A failure answers with a JSON error instead.

Who: Anyone

Parameters

• provider SignInProvider in path required

  The sign-in provider. Only providers this server configures work (see providers in GET /api/session).

• state string in query required

  The state the sign-in started with.

• code string in query

  The provider’s authorization code.

• error string in query

  Set by the provider when the person cancelled or it refused.

Responses

303

Back to the site.

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

409

It conflicts with the current state, such as a stale revision.

502

The provider could not be reached or did not verify the identity.

503

The server’s storage, or a service it needs, is unavailable.

The desktop app’s Sign in using your browser: it shows userCode and opens verificationUri, where a signed-in browser approves it (POST /api/auth/device/approve), then polls POST /api/auth/device/poll with deviceCode, which it keeps to itself. The request expires in ten minutes. Send an empty JSON object.

Who: Anyone

Request body

Responses

200

The pending desktop sign-in.

DeviceSignIn

• deviceCode string required · matches ^[a-f0-9]{64}$

  The desktop app’s secret for polling. Keep it out of the browser.

• userCode string required · matches ^[A-Z2-9]{10}$

  The code the desktop app shows, to match in the browser.

• verificationUri string (uri) required

  The page that approves it: <origin>/connect/desktop/<userCode>.

• interval 3 required

  Seconds between polls, at least.

• expiresIn 600 required

  Seconds until it expires.

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Answers {pending: true} until a browser approves, then a desktop session token, once. Poll at most every three seconds: a faster poll, an expired request or a used one is refused (400).

Who: Anyone

Request body

Responses

200

Still waiting, or signed in (with token).

object or SignedIn

400

The request is malformed or a value is not allowed.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

503

The server’s storage, or a service it needs, is unavailable.

Approves the desktop app showing userCode, signing it in to this account. Needs a sign-in within the last five minutes.

Who: Signed in, with the CSRF token

Request body

Responses

200

Approved.

Ok

• ok true

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Gives a new authenticator key, to enter in an authenticator app; POST /api/auth/mfa/enable turns it on within ten minutes, from this session. Needs a confirmed email address. Like every security change, it needs a live session, the current password when the account has one (else 401) or, for an account without a password, a sign-in within the last five minutes (else 403), and, with two-factor authentication on, a fresh code from the authenticator or a recovery code (else 401).

Who: Signed in, with the CSRF token

Request body

Responses

200

The authenticator key.

TwoFactorSetup

• secret string required · matches ^[A-Z2-7]+$

  The authenticator key, in base32.

• uri string required

  The same key as an otpauth://totp/… link (SHA-1, six digits, 30 seconds).

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Confirms the key from POST /api/auth/mfa/setup with a code from the authenticator, and gives ten recovery codes, shown only once. Signs out the account’s other sessions. Like every security change, it needs a live session, the current password when the account has one (else 401) or, for an account without a password, a sign-in within the last five minutes (else 403), and, with two-factor authentication on, a fresh code from the authenticator or a recovery code (else 401).

Who: Signed in, with the CSRF token

Request body

Responses

200

Turned on.

RecoveryCodes

• message string required
• recoveryCodes array of string required · at least 10 items, at most 10 items

  Ten one-time recovery codes, shown only once. Store them offline.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Turns two-factor authentication off and removes the recovery codes. Signs out the account’s other sessions. Like every security change, it needs a live session, the current password when the account has one (else 401) or, for an account without a password, a sign-in within the last five minutes (else 403), and, with two-factor authentication on, a fresh code from the authenticator or a recovery code (else 401).

Who: Signed in, with the CSRF token

Request body

Responses

200

Turned off.

AccountMessage

• message string required

  What happened, for people.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Gives ten new recovery codes, shown only once; the old ones stop working. Signs out the account’s other sessions. Like every security change, it needs a live session, the current password when the account has one (else 401) or, for an account without a password, a sign-in within the last five minutes (else 403), and, with two-factor authentication on, a fresh code from the authenticator or a recovery code (else 401).

Who: Signed in, with the CSRF token

Request body

Responses

200

The new recovery codes.

RecoveryCodes

• message string required
• recoveryCodes array of string required · at least 10 items, at most 10 items

  Ten one-time recovery codes, shown only once. Store them offline.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Sets a new password (or a first one, for an account made with a sign-in provider). Signs the account out everywhere, this session included, and revokes its API keys. Like every security change, it needs a live session, the current password when the account has one (else 401) or, for an account without a password, a sign-in within the last five minutes (else 403), and, with two-factor authentication on, a fresh code from the authenticator or a recovery code (else 401).

Who: Signed in, with the CSRF token

Request body

Responses

200

Changed; sign in again.

AccountMessage

• message string required

  What happened, for people.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Emails a confirmation to the new address, which POST /api/auth/email/verify accepts in this browser within 24 hours; the old address is told and stays until then. Confirming signs the account out everywhere. Like every security change, it needs a live session, the current password when the account has one (else 401) or, for an account without a password, a sign-in within the last five minutes (else 403), and, with two-factor authentication on, a fresh code from the authenticator or a recovery code (else 401).

Who: Signed in, with the CSRF token

Request body

Responses

200

Confirmation sent.

AccountMessage

• message string required

  What happened, for people.

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

Removes a provider from the ways to sign in to this account. An account keeps at least one: a password or another provider (409). Linking is POST /api/auth/{provider}/start with link: true. Like every security change, it needs a live session, the current password when the account has one (else 401) or, for an account without a password, a sign-in within the last five minutes (else 403), and, with two-factor authentication on, a fresh code from the authenticator or a recovery code (else 401).

Who: Signed in, with the CSRF token

Request body

Responses

200

Unlinked.

Ok

• ok true

400

The request is malformed or a value is not allowed.

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

409

It conflicts with the current state, such as a stale revision.

413

Too large, or over the account’s storage.

429

Too many requests. Wait, then try again.

503

The server’s storage, or a service it needs, is unavailable.

The account’s API keys, newest first (at most 100), revoked and expired ones included.

Who: Signed in

Responses

200

The keys.

object

• keys array of ApiKey required

401

Sign in first.

403

Not allowed: the CSRF token is missing or stale, the account lacks the role, or an API key lacks the scope.

503

The server’s storage, or a service it needs, is unavailable.