Reference

REST API


The Orcher REST API provides an HTTP/JSON interface for managing workflows, tasks, schedules, and system operations. It is served by the orchestrator itself, on the same process that serves the gRPC API.

Overview

The REST API is the primary interface for interacting with the Orcher orchestration platform from external applications, CLIs, and integrations.

Base URL: http://localhost:8080/api/v1

API Version: v1 (current stable)

Key Features

  • RESTful Design: Standard HTTP methods (GET, POST, PUT, DELETE)
  • JSON Format: All requests and responses use JSON
  • Authentication: One authentication layer shared with the gRPC API (API keys, OIDC)
  • Versioning: Versioned under /api/v1

Architecture

There is no separate API service: the orchestrator is one process with two listeners.

HTTP listener (HTTP_BIND_ADDR / --http-addr, default 127.0.0.1:8080)

  • REST API under /api/v1
  • Health checks: /health, /health/ready, /health/live
  • Prometheus metrics: /metrics

gRPC listener (GRPC_BIND_ADDR / --grpc-addr, default 127.0.0.1:50051)

  • Used by SDK clients, workers and the CLI
  • Workers long-poll this listener to pull workflow and task work

Both listeners share one authentication layer, and both read and write the same PostgreSQL database. To scale the REST API, run several orchestrator replicas behind a load balancer — every orchestrator serves REST.


Authentication

REST requests go through the same authentication layer as gRPC, configured in the orchestrator's [security] section (auth_mode = none, api-key, oidc, mtls or api-key-and-mtls). When auth_mode requires a client certificate (mtls, api-key-and-mtls), the orchestrator serves no REST API. Include your credential in the Authorization header:

1
GET /api/v1/workflows
2
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API keys are managed at /api/v1/api-keys (scope api-keys:manage) or with orcher api-key create|list|get|revoke; create the first one with orchestrator api-key create --name admin --scope '*'. Scopes: workflows:read, workflows:write, workers:run, namespaces:manage, api-keys:manage, *. See Authentication & OAuth for more.


Namespaces

All workflows and tasks execute within a namespace, providing logical isolation for multi-tenancy and environment separation. The default namespace is default. See Namespaces for details.

1
POST /api/v1/workflows/execute
2
{
3
"workflowName": "order-processor",
4
"namespace": "production",
5
...
6
}

Next Steps