Skip to content

APIs

AntFlow Server exposes several HTTP interfaces for different clients. They share a server and API base URL, but do not have interchangeable credentials, request formats, or responsibilities.

API families

Interface Resources and paths Clients
OGC API - Processes Landing page, conformance, processes, and jobs Process clients and integrations
Project API /projects and project-scoped process and job resources Users, the UI, and workflow automation
Job API /jobs and job status, results, logs, retries, and annotations Users and job integrations
Launcher API /launchers management; /launchers/me worker operations Users managing launchers and authenticated launcher workers
Support APIs Authentication, certificates, data access, monitoring, and health Users, operators, the UI, and launchers

Project process execution is an AntFlow extension, not a replacement request format for every OGC implementation. Launcher worker endpoints use a launcher token rather than the user API credential used in the examples below.

These families organize the documentation; they do not introduce Kubernetes API groups, apiVersion fields, or extra version prefixes into AntFlow URLs.

Base URL and discovery

All endpoint paths in this reference are relative to the Server API base URL, including any public exposure prefix. It is not necessarily the UI origin. Follow Access the API to select your own instance, the demo, or a locally port-forwarded Helm deployment and verify access.

The landing page at / provides links to resource discovery and documentation. Use service-desc for the machine-readable schema and service-doc for the interactive reference. By default, the same base URL exposes:

Resource Path Purpose
OpenAPI /openapi.json Operations, parameters, request/response schemas, and server version.
Swagger UI /docs Interactive exploration of the deployed contract.
ReDoc /redoc Rendered OpenAPI reference.

The resource pages describe the current source implementation. For a deployed release, check its OpenAPI info.version and contract: your instance can differ from these docs. Dynamic workflow inputs, launcher choices, and secret aliases come from the authenticated process description, not a universal OpenAPI body. Route registration alone does not prove an operation is implemented; unsupported root process operations are explicitly listed in the OGC reference.

Credentials and permissions

Client Credential and authorization
User or automation acting as a user GitLab personal token or Keycloak OAuth access token, according to the configured provider.
Administrator A user credential whose identity is configured as an administrator; not a separate universal admin API key.
Launcher worker Issued launcher registration token; valid only for the worker interfaces.
Public discovery/probes No application credential for the landing page, conformance, public encryption key, and health response.

Identity authentication, repository access, job ownership, group restrictions, and launcher eligibility are separate checks. Do not assume a valid token grants access to every resource. Public probe responses do not establish readiness to run a workflow. See Authentication and project access and the permissions documented for each family.

Requests and representations

  • Send JSON request bodies as Content-Type: application/json unless the operation documents a byte stream or storage redirect.
  • Use returned IDs and Link.href values. Correctly encode path and query values; preserve the instance's API prefix.
  • Dates are serialized as date-time strings. Use explicit time zones in requests.
  • Repeated query parameters are separate entries. Sorting parameters contain JSON objects, while cursor and page-number pagination are endpoint-specific.
  • Optional response fields can be omitted. Do not treat illustrative fields as always present or every model as interchangeable.

Process execution, user annotation updates, and worker job updates have different bodies. Their definitions are in Project API, Job API, and Launcher API. An HTTP GET is not always side-effect-free: the worker queue endpoint assigns jobs.

Errors

AntFlow returns both OGC exception objects and FastAPI-style errors. OGC exceptions contain type, optional title and detail, status, and instance. FastAPI errors typically use detail; validation errors can contain structured location/type information. Clients should inspect the HTTP status and returned body rather than require a single error shape everywhere.

Status Typical meaning
400 Invalid lifecycle operation, prohibited request fields, or inaccessible publication target.
401 Missing or invalid credential for the selected interface.
403 Authenticated but forbidden, including an expired launcher token.
404 Missing/inaccessible resource, unsupported root process, or results not ready.
409 Conflicting project publication or launcher registration.
422 Invalid request values or missing required workflow/search inputs.
500 Server failure; also the current failed-job results response.

Individual pages document operation-specific restrictions and success codes. Do not blindly retry execution submissions after connection failures: a job may have been created even if the client did not receive its response. Keep tokens, presigned URLs, secret values, and worker package bodies out of logs.