Project API¶

The Project API discovers workflows from GitLab and exposes their process definitions at a selected Git reference. Use a user API credential; repository access is resolved according to the instance's authentication and project-access policy.

Paths are relative to the API base URL. Project-scoped paths share this base:

/projects/{project_path}/ref/{project_ref}

These identifiers can contain slashes. Use returned resource links and correctly encode path values; a # in a process ID must not become a URL fragment. Submitting from a branch resolves and stores a commit reference for the job.

Project discovery and publication¶

Search parameters¶

Follow pagination.next_page or pagination.prev_page rather than constructing cursors. The links preserve topics and search text. Search visibility follows the token-selection policy.

Publication request¶

POST /projects/publish accepts ProjectPublishData:

Publication verifies that the server's GitLab token can access the project. It does not change GitLab visibility, push a package, or run a workflow. The response contains the GitLab project id and the publication groups. An inaccessible project returns 400, a non-administrator 403, and an already published project 409.

DELETE /projects/publish takes the project path as a query parameter, not a JSON body. It also requires administrator access and verifies server repository access. See Published project access for the access model and Token selection for personal-token fallback limitations.

Project-scoped operations¶

The paths in this table are suffixes appended to the project base above.

The process and job list routes also accept a trailing slash. For individual job operations, use the links returned for the job; authorization is checked against the job ID, not established merely by a project/ref path.

Job bodies, lifecycle restrictions, results, and errors are shared with the Job API. The project job list uses repeated process_id, not the root list's process_id_list, and supports list_status, before, after, limit (1–10000), query, and repeated tags. It does not expose the root list's order_by, message, or id_launcher filters.

Project resources¶

ProjectList¶

Project and ProjectDetails¶

Preview assets, when available, are exposed through a preview link. Internal discovery fields are not a public file-list contract. Optional fields can be omitted; use the deployed OpenAPI schemas for exact serialization.

ProcessDescription¶

The process list supports include_errors (boolean, omitted by default) and limit (optional integer). With error reporting enabled, invalid CWL files can appear in errors as objects with id and optional detail. Discovery returns workflow summaries, not every CommandLineTool as a runnable process.

The description is identity- and instance-dependent: eligible launcher names, secret aliases, and publication-storage choices can differ between users. The default AntFlow additional-input prefix is antflow_config:; do not assume that a name or launcher choice from another deployment is valid here. See CWL reference for types and form annotations.

ApplicationPackage and CarbonScore¶

GET .../package accepts cwl_format (default yaml, supported formats yaml and json) and optional job_id. Supplying a job ID requires access to that job and uses its stored commit and execution configuration.

The carbon response is {"score": "A"}, with possible scores A through E or ? when no applicable resource information is available. It is a resource-requirement-derived indicator, not a measured emissions report.

Execution request¶

The JSON body is a flat object whose keys are declared process input names. For the calculator workflow, the shape is:

{
  "operands": [3, 2],
  "antflow_config:launcher": "<eligible-launcher-name>"
}

This is a template: replace the launcher with a choice from your description. For other workflows, use their own input names and types. Secret values are vault aliases. Do not wrap this object in inputs or execution_content.

A successful submission returns 201, a StatusInfo JSON body, a Location header pointing to job status, and a monitor link. accepted means queued, not already running. Missing eligible launchers or invalid inputs can return 404 or 422. Submission stores a job and can consume compute and storage.

For a runnable procedure with your own project, follow Run a workflow through the API.