API

Lightning's API lets a program manage an instance's users, projects, credentials and collections, and read its workflows, runs and logs.

Authenticate

Send a token in the Authorization header on every request:

Authorization: Bearer <token>

Two kinds of token work:

• The service account's access token, for automation that sets up an instance. Service accounts explains how to get one. It carries only the token grants it asked for, and the routes table lists the grant each route needs.
• A personal access token, which you create in Lightning under your profile at Personal Access Tokens. It acts with your own permissions on your projects and lasts until you revoke it. /api/users takes only the service account's token. It answers a personal access token with 403 forbidden, and a project repo connection's token with 403 insufficient_scope naming users:read or users:write.

Conventions

• Send request bodies as JSON with Content-Type: application/json. Responses are JSON, except GET /api/provision/yaml.
• Ids are UUIDs.
• A PUT on a route the table marks "create or replace" takes an id you choose. It answers 201 when it creates the record and 200 when it replaces one.
• Send only the keys a route accepts. A route can refuse any other key with a 422 whose entry has the code unknown_key.
• Lists that page take page, from 1, and page_size, which defaults to 10 and is at most 100. Their links give the next and prev pages.

Errors

Every error from /api is an RFC 9457 problem document, except those from the token endpoint, which Service accounts covers. Its content type is application/problem+json when your Accept header names that type, and application/json otherwise.

{
  "type": "about:blank",
  "status": 400,
  "title": "Bad Request",
  "code": "invalid_parameter",
  "detail": "A path or query parameter is not valid. See errors.",
  "errors": [{ "path": "id", "code": "type", "detail": "is not a UUID" }]
}

Branch on code. It is stable, and each one always comes with the same status. title and detail are for people and can change.

errors appears when the problem is in specific parts of the request. Each entry has a code, a detail, and one member that says where the problem is:

• pointer: a JSON Pointer into the request body, such as #/members/0/email.
• parameter: a query parameter's name.
• header: a request header's name, in lower case.
• path: a path segment, named as in the routes table, such as id or project_id.

These are the codes most callers handle. The full list, entry codes included, is in LightningWeb.API.Codes.

What you hear for a record you name

Lightning checks a request in this order, and the first check that fails answers:

1. The token: 401, or 400 for a header it can't read.
2. The token grant: 403 insufficient_scope.
3. Your permission on the project or record: 403 forbidden.
4. The id: 400 invalid_parameter if it isn't a UUID, 404 not_found if no such record exists.
5. The body: 400 or 422.

A caller without permission hears 403 whether the record exists or not, and whether the id is a UUID or not. Only a caller who may learn which records exist hears 404 or 400 for the id:

A record in another project counts as missing. A project scheduled for deletion answers 409 scheduled_for_deletion, but only to a caller who would otherwise be allowed.

Routes

"Session only" routes serve Lightning's own web app and take no token. A route "not open to the service account" answers its token with 403 forbidden.

Accounts

Projects

Credentials

The service account must send project_id to list credentials at /api/credentials.

Workflows and runs

The service account must send project_id to list work orders, runs or log lines at the top level.

Lightning's web app