REST API

Configure and control a Tangle project over HTTP and JSON. Tokens, scopes, conventions, errors and every route of /api/v1.

tangle-core serves a REST API at http://<host>:7340/api/v1. Every action the designer, dashboards and assistants can take is available here, with the same validation, scope checks and audit log. Request and response bodies use the Tangle contract types (the same JSON as the project file).

#Base URL and documentation

The OpenAPI document is generated from the same route table that serves the API, so it always matches the running core. Its component schemas are the contract types. The /api/docs page loads its viewer from a public CDN, so the browser that opens it needs internet access.

By default tangle-core listens on 127.0.0.1:7340 (this machine only). To accept other machines, start it with --listen 0.0.0.0:7340 --allow-remote --insecure-http (see CLI). There is no TLS yet: use remote access on trusted networks only.

#Authentication

Send an API token in the Authorization header:

GET /api/v1/project HTTP/1.1
Host: 127.0.0.1:7340
Authorization: Bearer tgl_0f3c...

Create tokens on the machine that runs tangle-core:

tangle-core token create --name stage-script --scopes read,control
tangle-core token list
tangle-core token revoke stage-script

• The secret (tgl_ followed by 64 hex characters) is printed once. Only its SHA-256 hash is stored, in tokens.json in the Tangle data folder.
• Without --scopes, a token gets read,control.
• A revoked token stops working at once, without restarting tangle-core.
• For clients that cannot set headers (a browser EventSource), pass the token as ?token=<token> in the query string.
• A missing, unknown or revoked token gets 401 with a WWW-Authenticate: Bearer header.

For a core installed as a boot service, manage its tokens with sudo tangle-core token ... (macOS, Linux). See CLI.

Note: REST and MCP access for third-party software is part of Tangle Pro and Ultimate (and the demo mode). On other editions these requests get 403 not_licensed. The built-in designer and dashboards always work. See Licensing.

#Scopes

Scopes do not include each other: a token that should read and configure needs read,configure. A token without the scope a route needs gets 403 missing_scope.

#Dashboard sessions

Browsers that open a dashboard get a short-lived session token from POST /api/v1/dashboards/{id}/session (no token needed to call it). Session tokens start with tgd_, last 12 hours and carry the read and control scopes. See Dashboards.

#Conventions

#JSON and resource ids

• Send content-type: application/json. A body that is not JSON gets 400 invalid_json.
• Every resource has an id: lowercase letters, digits, ., _ and -, starting with a letter or digit, at most 128 characters.
• Times are milliseconds since the Unix epoch (UTC), unless a field says otherwise.
• Cross-origin requests are allowed from any origin (requests carry bearer tokens, never cookies). The ETag header is exposed to browsers.

#Errors

Errors use RFC 9457 problem details, with content type application/problem+json and a stable machine-readable code:

{
  "type": "https://tangle.dev/problems/device_not_found",
  "title": "Not found",
  "status": 404,
  "detail": "device proj-9 does not exist",
  "code": "device_not_found"
}

Validation errors (422) add an errors array with one entry per problem. not_primary adds primary.

#ETags and If-Match

GET on a single resource (and on /project) returns a strong ETag. Send it back in If-Match on PUT or DELETE to make sure nobody changed the resource since you read it. If it changed, the request fails with 412 precondition_failed and nothing is applied.

• If-Match: * matches any existing version.
• A PUT with an If-Match (other than *) on a resource that does not exist fails with 412.
• Successful writes return the new ETag.

#Dry runs

Add ?dryRun=true (or ?dryRun, ?dryRun=1) to any create, replace or delete. Core validates the change against the whole project and returns what would happen, without applying it:

{
  "dryRun": true,
  "result": { "id": "pj-2", "name": "Projector 2", "moduleId": "misc.pjlink.projector", "room": "hall" },
  "changes": [{ "op": "create", "kind": "device", "id": "pj-2" }]
}

result is the resource as it would be (absent for a delete). changes lists contract ProjectChange entries (op: create, update or delete; kind; id; parent for tracks and cues, such as show or show/lights).

#How changes are applied

• Each write is atomic. Core applies the change to a copy of the project, validates the whole result (schema and cross-references, such as a scene pointing at a device that no longer exists), then swaps it in. A mistake changes nothing and the 422 lists each problem.
• Changes are saved to the project file (JSON or YAML, following its extension) and recorded in audit.log in the log folder, with the token name and surface.
• Devices are started or stopped to match.
• Device settings are checked against the module's configSchema. Secret settings (marked x-secret in the module) are removed from the body and stored in the OS credential store, never in the project file.
• Notification channel secrets (passwords, tokens, webhook URLs) also go to the credential store. The project keeps ********; send ******** back to keep the stored value.
• A dashboard PIN sent as access.pin is stored as a salted hash and never returned.
• Every project change publishes a project.changed event.

#Live timelines

Editing a timeline, or one of its tracks or cues, while it plays is refused with 409 timeline_running. Add ?allowLive=true to edit it anyway. Network discovery is always refused while any timeline plays (409 show_mode), because a scan floods the show network.

MCP assistants have an extra protection: without the live scope, every change and control action is refused while a timeline plays. REST clients are not subject to it. See MCP.

#Redundancy: 409 not_primary

In a redundant cluster, only the primary accepts writes and control. A backup answers changes, intents, transport, automation runs, and alert acknowledgement or silencing with 409:

{
  "type": "https://tangle.dev/problems/not_primary",
  "title": "Conflict",
  "status": 409,
  "detail": "this node is a backup; send changes to the primary",
  "code": "not_primary",
  "primary": "http://10.0.0.1:7340"
}

primary is null while the backup does not know the primary yet. Reads work on every node. See Redundancy.

#Routes

Scope is the scope the token needs. Paths are relative to http://<host>:7340.

#Project and modules

#Project library

#Project resources

Each resource type supports the same five routes:

Create, replace and delete accept ?dryRun and ?allowLive; replace and delete accept If-Match.

The fields of each type are described in Project file. Notes per resource:

• Tracks and cues live inside their timeline: a missing parent timeline or track gets 404. Changing them counts as changing the timeline (timeline_running applies).
• Dashboards: a POST or PUT publishes the dashboard directly. Core increases version, keeps the published version in the dashboard's history, and screens showing it reload. To edit without affecting screens, use the draft routes.
• Notification channels: Slack and Teams channels need settings.webhookUrl.

#Live state

#Intents

Request body:

Without ?wait, core answers 202 Accepted as soon as the intent is accepted, with a Location: /api/v1/intents/{intentId} header. With ?wait=5s (or 500ms, or a number of seconds; at most 60 s) it answers 200 with the final status, or the latest status when the time runs out.

Response (IntentStatus):

#Timelines

TimelineState fields: timelineId, status (stopped, playing, paused, waiting), positionMs, sampledAt (when positionMs was sampled, for interpolation), lastCueId, nextCueId, chasing, clockLost, anchor. See Timelines.

#Devices: tests, discovery, logs and removal

#Dashboards

Besides the resource routes, dashboards have a draft and a version history. Drafts and published versions are kept in the Tangle data folder.

Dashboard checks name the page and widget at fault, for example page main, widget w1: unknown widget type knob.

The session route follows the dashboard's access.mode: open dashboards get a session at once; pin dashboards need the right PIN (401 pin_required or wrong_pin, 429 too_many_attempts after 5 wrong PINs in a minute); panels dashboards answer 403 panels_only (enrolled panels use their own API token). A session stops working when it expires or when the dashboard switches to panels.

#Automations

See Automations.

#Variables, controls and functions

#Listeners

Besides the resource routes:

See Listeners.

#Device creator and community

See Device creator.

#Maps, plans and images

#Lighting

#Sentinel (monitoring)

Monitoring is part of Tangle Pro and Ultimate. See Sentinel.

Alert ids look like <ruleId>/<subject kind>:<subject id>, for example offline/device:proj-1. Acknowledging and silencing run on the primary only (409 not_primary on a backup).

#License

See Licensing.

#Event stream (SSE)

GET /api/v1/events?topics=<list> streams live events as Server-Sent Events. topics is required: a comma-separated list of <event type>:<subject id> or <event type>:*.

curl -N "http://127.0.0.1:7340/api/v1/events?topics=device.state:*,timeline.state:show" \
  -H "Authorization: Bearer $TOKEN"

event: device.state:proj-1
data: {"type":"device.state","deviceId":"proj-1","capability":"tangle.power","values":{"on":true},"at":1760000000000}

• Each SSE event name is the topic; the data is the event JSON (contract TangleEvent).
• A client that falls behind gets an event named lagged with {"missed": n}.
• A keep-alive comment is sent every 15 seconds.
• The topics are the same as on the WebSocket. See WebSocket events for the list and each event's fields.

In a browser, use EventSource with ?token=:

const es = new EventSource(`/api/v1/events?topics=device.status:*&token=${token}`);
es.addEventListener("device.status:proj-1", (e) => console.log(JSON.parse(e.data)));

#Examples

Set a shell variable with your token first:

export TOKEN=tgl_...

Read the project:

curl http://127.0.0.1:7340/api/v1/project -H "Authorization: Bearer $TOKEN"

Recall a scene in a room and wait up to 5 s for the result:

curl -X POST "http://127.0.0.1:7340/api/v1/intents?wait=5s" \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"name":"scene.recall","target":{"kind":"room","id":"room-a"},"params":{"scene":"presentation"}}'

Check a new device before adding it, then add it:

curl -X POST "http://127.0.0.1:7340/api/v1/devices?dryRun=true" \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"id":"pj-2","name":"Projector 2","moduleId":"misc.pjlink.projector","room":"room-a","config":{"host":"10.0.0.21"}}'

curl -X POST http://127.0.0.1:7340/api/v1/devices \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"id":"pj-2","name":"Projector 2","moduleId":"misc.pjlink.projector","room":"room-a","config":{"host":"10.0.0.21"}}'

Update a scene safely (read its ETag, then send it back):

curl -i http://127.0.0.1:7340/api/v1/scenes/presentation -H "Authorization: Bearer $TOKEN"
# ETag: "3f2a9c1d0b7e4a55"

curl -X PUT http://127.0.0.1:7340/api/v1/scenes/presentation \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -H 'If-Match: "3f2a9c1d0b7e4a55"' \
  -d '{"id":"presentation","name":"Presentation","actions":[{"deviceId":"pj-2","capability":"tangle.power","action":"on"}]}'

Start a timeline and jump in a cue list:

curl -X POST http://127.0.0.1:7340/api/v1/timelines/show/transport \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" -d '{"op":"play"}'

curl -X POST http://127.0.0.1:7340/api/v1/timelines/show/transport \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" -d '{"op":"seek","positionMs":90000}'

Push a metric from a script:

curl -X POST http://127.0.0.1:7340/api/v1/sentinel/metrics \
  -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '[{"name":"room.temperature","value":31.5,"labels":{"room":"server"}}]'