Launcher API¶

The Launcher API has two distinct audiences: users registering and managing launchers, and launcher workers claiming jobs and reporting execution. They share the /launchers prefix but use different credentials and request models. All paths are relative to the API base URL.

Operations	Credential
Registration, listing, rotation, and management	User API credential in `Authorization: Bearer …`.
`/launchers/me` worker operations and launcher data access	Issued launcher token in `Authorization: Bearer …`.

The worker authenticator uses the Bearer header; do not assume the user API's alternative header works here. Missing or invalid launcher tokens return 401; expired launcher tokens return 403. A launcher ID is not an authentication token.

Management operations¶

Method	Path	Success	Request and response
`GET`	`/launchers/`	`200`	Array of `LauncherInfo`, filtered by identity, groups, and administrator access.
`POST`	`/launchers/`	`201`	`LauncherPostRequest` → `LauncherTokenResponse`.
`POST`	`/launchers/rotate`	`200`	`LauncherRotateRequest` → `LauncherTokenResponse`.
`PATCH`	`/launchers/{id_launcher}`	`200`	`LauncherPatchRequest` → `LauncherInfo`.
`DELETE`	`/launchers/{id_launcher}`	`200`	Removes the registration; JSON response with `detail`.

id_launcher is the id from LauncherInfo. Management updates and deletion require ownership or administrator access; inaccessible registrations return 404. Deleting a registration does not stop an already running launcher process or guarantee cancellation of its infrastructure jobs.

LauncherPostRequest¶

Field	Type	Required	Meaning
`name`	string	Yes	Launcher registration name.
`expiration_date`	date-time or null	Personal launchers: yes	Token expiration. Use an explicit time zone.
`is_transverse`	boolean	No; default `false`	Register a shared rather than personal launcher.
`groups`	array of strings or null	No	Group restrictions for shared launchers.

Personal registrations are owned by the authenticated user, require an expiration date, and cannot supply groups. Only administrators may create transverse launchers. A transverse launcher's expiration is optional; empty or absent groups have no group restriction. Group names are normalized to paths when the instance enables that setting.

A duplicate registration name in the applicable ownership scope returns 409. Personal registrations missing expiration or specifying groups return 400; non-administrators requesting a transverse registration get 403.

For the UI and a runnable registration request, follow Launcher registration.

LauncherRotateRequest¶

Field	Type	Required	Meaning
`name`	string	Yes	Name of the registration to rotate.
`expiration_date`	date-time or null	Non-administrators: yes	New token expiration.

Rotation selects by name, not launcher ID. Owners rotate their own registrations; administrators have broader lookup access. Only administrators may omit expiration. Rotation replaces the stored token: update the worker's credential before expecting it to reconnect. A missing registration returns 404.

LauncherPatchRequest¶

Management patch accepts optional nullable name and groups. Supply only the fields you intend to change. groups is invalid for a personal launcher; an empty patch returns 400. This body does not set worker flavors, change execution backends, or rotate the token.

LauncherTokenResponse¶

Field	Type	Meaning
`name`	string	Registration name.
`token`	string	Newly issued launcher credential, returned only at issuance or rotation.
`expiration_date`	date-time or null	Expiration, or no expiration where permitted.

Store the token securely. Listing and reading registrations do not retrieve it. Do not log issuance responses or use a launcher token as a user credential.

LauncherInfo¶

Field	Type	Meaning
`id`, `name`	strings	Registration identity and display name.
`user_id`	string or null	Owner; null for transverse registrations.
`flavors`	array of strings	Advertised execution capabilities.
`last_seen`	date-time	Last-seen timestamp.
`expiration_date`	date-time or null	Credential expiration.
`groups`	array of strings or null	Group restrictions.
`active`	boolean	Computed from last-seen time and configured launcher TTL.
`expired`	boolean	Computed from expiration date.

active and expired are different checks. A registration can exist while its worker is unavailable. Process eligibility also considers group access and requested flavors; listing a registration does not guarantee it can run a particular workflow.

Worker operations¶

Method	Path	Success	Request and response
`GET`	`/launchers/me`	`200`	Authenticated worker's `LauncherInfo`.
`PATCH`	`/launchers/me`	`200`	`LauncherSelfPatchRequest` → `LauncherInfo`.
`GET`	`/launchers/me/queue`	`200`	Array of `Job`; claims and assigns queued work.
`GET`	`/launchers/me/jobs`	`200`	Array of assigned `Job`; updates last-seen time.
`GET`	`/launchers/me/jobs/{job_id}`	`200`	One `Job`; rejects work assigned to another launcher with `403`.
`GET`	`/launchers/me/jobs/{job_id}/package`	`200`	Worker `ApplicationPackage`; requires assignment to this launcher.
`PUT`	`/launchers/me/jobs/{job_id}`	`201`	Worker `Job` JSON body → updated `Job`.

Queue reads assign work

GET /launchers/me/queue is part of the worker protocol, not a read-only diagnostic endpoint. Calling it can assign jobs to the authenticated launcher. Use /launchers/me or the registration list when inspecting configuration.

LauncherSelfPatchRequest has one optional nullable field, flavors (array of strings). An empty patch returns 400. Only advertise capabilities that the configured worker can actually satisfy; patching flavors does not install software or change its runner.

Worker query parameters¶

The queue accepts optional message, limit (1–10000), and repeated order_by JSON strings. The assigned-job list also accepts repeated list_status, repeated process_id_list, project_path, project_ref, before, and after. Unlike the user list, it has no query or tags parameter. Sorting values use the Job API sorting format.

Job¶

The worker model uses internal lifecycle states, not just the five user-facing OGC statuses. A worker update is a validated job object, not a partial user annotation body:

Field	Type	Required	Meaning
`type`	string	Yes	`process`.
`jobID`	string	Yes	Assigned job identifier.
`status`	string	Yes	Internal state from the list below.
`project_path`, `project_ref`	strings	Yes	Workflow repository and submitted reference.
`processID`	string	Yes	Process identifier.
`progress`	integer, 0–100	Yes	Reported execution progress.
`message`	string or null	No	Worker status/error message.
`created`, `started`, `finished`, `updated`	date-time or null	No	Lifecycle timestamps.
`user_id`, `s3_path`	string or null	No	Submitting user and publication path.
`application_package`	Worker `ApplicationPackage` or null	No	Package when included.

Additional job metadata is allowed. Internal states are accepted, pending_run, running, finalizing_run, successful, pending_dismissed, dismissed, and failed. See status mapping for how users observe these states.

Workers must only report jobs assigned to them. Update bodies cannot modify env, secrets, execution_content, or application_package: those fields are removed before persistence. A running update does not override a pending or completed dismissal. Do not assume arbitrary state transitions are a supported public job-control interface.

Worker ApplicationPackage¶

Field	Type	Meaning
`main`	string	Main CWL workflow identifier.
`content`	string	Serialized CWL for execution.
`env`	object	Execution environment.

This differs from the user package's source field. Retrieval uses the job's stored commit when available. Repository credentials and fallback follow Token use after submission. Worker responses and packages can contain sensitive execution data: never log their complete bodies.

Worker data access¶

Launcher storage URLs use /launchers/{id_launcher}/data/{job_id}/{file_path}. Use the registration ID and issued launcher token, not a user token. They share the proxy, redirect, upload, and probe behavior documented in Data access, including its server-token requirement for launcher storage access. Package retrieval and publication storage access are distinct operations.