Interact with automation orchestrator programmatically

You can use the automation orchestrator REST API to manage workflows, executions, credentials, projects, and integrations programmatically. The API provides full parity with the web interface.

Why use the REST API

The automation orchestrator follows API-first design principles. The web interface consumes the same API endpoints that are available to you. The API is always complete and up to date.

Use the REST API when you need to:

  • Trigger, monitor, and retrieve results from workflows in CI/CD pipelines or scripts
  • Manage projects, credentials, and tools from external systems
  • Configure access control and authorization policies programmatically
  • Build integrations with IT service management (ITSM) or observability platforms
  • Enable AI-driven agentic automation through Model Context Protocol (MCP) clients

API access methods

The automation orchestrator provides three ways to interact with the REST API:

Direct HTTP requests
Use curl, httpie, or any HTTP client to call API endpoints directly.
Generated Python client
Use the syntara-api-client package, generated from the OpenAPI specification with openapi-python-client. The client provides type-safe methods for all API operations.

The generated client handles authentication and error responses automatically.

The automation orchestrator publishes an OpenAPI 3.1.0 specification that describes all available endpoints, request and response schemas, and authentication requirements. You can explore the API interactively, download the specification, or generate client libraries.

API request structure

All API endpoints use the /api/v1 path prefix. The full URL combines the automation orchestrator host, the version prefix, and the resource path:

https://orchestrator-host/api/v1/resource

For example, to list workflows:

GET https://orchestrator-host/api/v1/workflows

The REST API accepts and returns JSON (application/json) for all standard operations.

The automation orchestrator supports per-user rate limiting for inbound REST API requests. Service account requests authenticated with bearer tokens are rate-limited by client IP address, not by service account identity. When a client exceeds the configured rate limit, the API returns a 429 Too Many Requests response with a Retry-After header.

Authentication methods

The REST API uses JSON Web Token (JWT) authentication with the ES256 (ECDSA P-256) signing algorithm. You must obtain an access token before you can make API requests.

The automation orchestrator supports the following authentication methods:

Local authentication
Authenticate with a username and password to receive an access token and refresh token.
OpenID Connect (OIDC)
Authenticate through an external identity provider using the OAuth 2.0 authorization code flow.
OAuth 2.0 client credentials
Authenticate a service account by sending a POST request to /api/v1/auth/token with the client_credentials grant type. This method returns an access token without a refresh token and is intended for programmatic, noninteractive integrations.

Access tokens expire after a configurable period. Use the refresh token to obtain a new access token without re-authenticating. Service account tokens obtained through the client credentials grant do not include refresh tokens. Request a new token when the current one expires.

The generated Python client manages token lifecycle automatically.