HTTP API

danio's own interface, the command line, the Blender add-on, plugins, and the devices that join a workspace all call the same HTTP API. Your own scripts can use it too.

Every endpoint is under /api/v1/ and speaks JSON. The parameters, responses and required permission of each endpoint are in the OpenAPI description; this page covers the conventions and the most-used endpoints.

Addresses

For setting the port, see Configuration.

Tokens and permissions

Send the token with the request:

Authorization: Bearer <token>

An integration token is shown only once, when it is made. Use Rotate to replace it; the old one stops working at once.

There are 9 workspace permissions, and an access level is a combination of them:

The level None has no permissions, Viewer has the first two, Workstation adds job.submit and project.edit, and Admin has all of them.

In the OpenAPI description, each endpoint's x-required-permission names the one it needs. Besides the 9 above, there are four other values:

When the permission is not enough, the answer is 403 with the error code forbidden, naming what is missing. GET /api/v1/me returns the identity and permissions of the current token.

Errors

On an error the answer is application/problem+json:

{
  "type": "urn:danio:error:version-conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "…"
}

type is a stable error code for programs to act on; detail is for people, in the language of the request's Accept-Language: Chinese when the header is missing or starts with zh, English otherwise. Fields that failed validation are listed in errors; when a submission's checks fail, the reasons are listed in checks.

Retries and concurrency

• Submitting a task (POST /api/v1/jobs), updating a task (POST /api/v1/jobs/{id}/versions) and comparing a draft (POST /api/v1/jobs/{id}/versions/draft) can carry an Idempotency-Key, a value you choose. Retrying with the same key within 24 hours returns the first result and doesn't register the task twice. Only successful results are remembered; a retry after a failure runs again.
• The same three endpoints can carry X-Danio-Request, an ID you choose. The submit.progress events carry it, so you can tell which ones are yours.
• When updating a task, send baseVersion. If a newer version exists, the answer is 409 with the error code version-conflict; compare again against the newest version.
• Reading a project returns an ETag. When changing it (PATCH /api/v1/projects/{id}), send it back in If-Match. If someone changed it first, the answer is 412.

Lists

GET /api/v1/jobs and GET /api/v1/projects are paged: limit says how many items a page has, and the next in the answer goes into the next request's cursor. An empty next means the last page. The task list can also be filtered with project (a project ID), name (a task name, unique only within a project) and blend (a Blend file ID).

The {id} in a path accepts only IDs. To look something up by name, use a query parameter.

Event stream

GET /api/v1/events is a long-lived Server-Sent Events connection. It needs workspace.view:

curl -N -H "Authorization: Bearer $TOKEN" http://127.0.0.1:7421/api/v1/events

Each event has an id, an event (its type) and data (JSON). The id is a string; don't compare it as a number. The connection sends a : ping comment line every 15 seconds to keep itself alive.

When you reconnect, send the last Last-Event-ID you received and danio replays what you missed. It keeps the last 1024 events. When it can't replay (danio restarted, or you were away too long), it sends a reset event first; read the state again then.

The events listed in the OpenAPI description:

The stream carries other events too. Ignore any event type you don't know.

The OpenAPI description

The full description of the API is OpenAPI 3.1 JSON. You can get it in two ways:

# from the command line, in Chinese by default
danio openapi > openapi.json

# in English
danio openapi --lang en > openapi.json

# from a running danio, with any valid token
curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:7421/api/openapi.json?lang=en" -o openapi.json

lang can be zh-CN or en. When it is missing, danio picks by Accept-Language, by the same rule as error messages.

In the command-line output, info.version is dev; a running danio gives its own version.

Under Settings → API, API reference opens the same description in the interface, where you can browse it.

Generic OpenAPI tools can generate a client from it, such as openapi-typescript and openapi-python-client.

Common endpoints

The permissions in the tables are the ones needed when you call with a workspace token. The local token has no limit. For the full list and the parameters, see the OpenAPI description.

Status and identity

Projects and tasks

Devices and tokens

Plugins

Example

List tasks, then pause one:

curl -H "Authorization: Bearer $TOKEN" "http://192.168.1.20:7420/api/v1/jobs?limit=20"

curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://192.168.1.20:7420/api/v1/jobs/<task ID>/pause

Replace 192.168.1.20:7420 with your host's workspace address.