Data sources API

Lists the source presets: ready-made, tested configurations of the json data source (docs/sources.md, Presets). Each says which cards it fills, the fields a person fills in (with help, a pattern and an example), the secrets it needs and how to get each, how often it refreshes and how long a card keeps its last data, and whose data it reads under which terms.

Create a source from one with POST /api/sources and preset, settings and secrets, and preview it with POST /api/sources/test.

One source preset, as the list shows it.

Lists the project's data sources, newest first, at most 200 a page. A data source keeps one card's dynamic properties current from an outside address on a schedule (docs/sources.md). Each source shows its status: the last attempt, the last success, the last change written, the next run, the failure count and the last error.

Secrets are never returned; each is shown as set with a masked hint. next_cursor is passed back as after for the next page, null when there are no more.

Creates a data source that writes one card's dynamic properties from an outside address. kind selects the adapter (ics reads an iCalendar or webcal:// address); config holds the kind's settings and secrets its credentials, which are stored sealed and shown only as a masked hint.

Or name a preset (GET /api/source-presets) and give its settings and secrets instead of kind and config: the source is a json source whose config the preset builds, shown back with its preset and settings, and the refresh interval and stale period default to the preset's. A preset fills only the cards it lists (source_target_unsupported).

The source runs within seconds and then every refresh_seconds. A failed run never writes: the card keeps its last good document and the source's status shows the error. One source writes one card (source_target_taken), the card must be one the kind can fill (source_target_unsupported), and an organization has at most 200 sources (source_limit_reached).

Use POST /api/sources/test first to see the document the source would write. Appends source.created. An exact retry with the same Idempotency-Key returns this same answer for twenty-four hours.

Previews a data source without saving or writing anything: fetches the address, shapes the answer for the target card and validates the document against the card, then returns the document, whether the card accepts it (valid, with validation_error naming the path when it does not), the run's warnings and counts.

Pass source_id to test a saved source with the other members as overrides (settings override a preset source's own); otherwise target and either kind and config, or preset, settings and secrets, are required. A secret a saved source keeps is used as stored, unless the override changes where it points (source_secret_required).

A fetch or shaping failure is source_test_failed with the fixed source_error. At most 30 previews a minute per organization.

One data source with its status. ETag is the revision, for If-Match on the next change.

Changes a data source. config replaces the whole config; secrets merges (a string sets or replaces one, null removes it).

A source made from a preset takes settings instead of config: each setting named replaces its value, null removes an optional one, the others keep theirs, and the config is built again from the preset (config on such a source is invalid_request at config, and settings on another is invalid_request at settings). Its secrets are named as the preset names them.

A secret not sent keeps its value unless the change points the source somewhere its stored scope does not cover (source_secret_required at secrets.<name>: enter it again).

A change to the target, config, secrets, refresh_seconds or enabled resets the failure count and runs the source within seconds; a rename does not. enabled false stops the schedule and keeps the card's last document. If-Match guards the revision. Appends source.updated.

Deletes the data source. The card keeps the last document the source wrote. If-Match guards the revision. Appends source.deleted.

The room mapping of a data source that reads a booking system's rooms (kind momentus): which rooms it offers that no screen shows (summary.unmapped_rooms), and which screens read a room or area document without a value that names one (screens with status missing or unknown, with a suggestion when the value is a room written another way).

The rooms are those of the source's last good refresh; nothing is fetched. A kind with no rooms answers source_has_no_rooms.

Syncs the source now, inline (up to 60 seconds), and returns it with its new status. A failed sync answers 200 with status.state error and the error; it never writes. A refresh starts the source over: the failure count resets and the address is read in full. source_busy (Retry-After) while a scheduled sync holds the source.

At most 6 refreshes a minute per source.