Documentation by ClonePartner

Start typing to search.

API Reference

Using the API

View Markdown

Authenticate to the Envoy REST API with API keys, page through collections with cursors, and handle the standard error shape.

Using the API

The Envoy control plane exposes a REST API under /api on the same origin as the web UI. It manages tasks, connectors, job templates, jobs, runs, triggers, metrics, dashboards, users, and API keys. This page covers the conventions every endpoint shares; for endpoint-by-endpoint request and response schemas, use the generated API reference, which is built from the same OpenAPI document the server serves at /api/docs/openapi.yaml (interactive viewer at /api/docs).

Prerequisites

  • A running Envoy server and its base URL (the examples use https://your-envoy.example.com).
  • An admin or superadmin account to create an API key.

Authentication

Use an API key for API access. Send an Authorization: Bearer <key> header on every request.

Create an API key

An admin or superadmin creates keys from Settings → API Keys. Create a named key, optionally with an expires_at date; the response includes the full key once. Envoy stores only a SHA-256 hash and a display prefix, so copy the value immediately.

Keys look like envoy_ followed by 48 hex characters. Store the key in a secret manager and export it for your tooling:

export ENVOY_API_KEY="envoy_..."

A key acts with the role of the user who created it — a key created by a viewer does not gain admin permissions. Failed authentication returns 401 with error: "AUTH_ERROR" and a message such as Invalid API key or API key expired.

Pagination

Collection endpoints share the parseListParams conventions:

Query param Description
cursor Opaque cursor from a previous response. Do not derive or modify it.
limit Page size. Defaults to 50 on most routes; capped at 200.
sort Sort column; each route allows a specific set.
order asc or desc (default desc).
q Text search over the route's search columns.

List responses return:

{
  "result": [],
  "nextCursor": "opaque-value",
  "prevCursor": null,
  "total": 125
}

Page until nextCursor is absent — the server caps page size, so never assume one request returns every row.

Make a request

List job runs for a Job, one page at a time:

curl --fail-with-body \
  -H "Authorization: Bearer $ENVOY_API_KEY" \
  -H "Accept: application/json" \
  "https://your-envoy.example.com/api/jobs?limit=50"

A successful response is the paginated shape above with one Job per result entry. Pass cursor=<nextCursor> to fetch the next page.

Errors

Every error is JSON with a stable error code and a human-readable message:

{
  "error": "VALIDATION_ERROR",
  "message": "Name is required"
}

Codes you should handle:

Status error Meaning
400 VALIDATION_ERROR (and service-specific codes) Invalid input.
401 AUTH_ERROR Missing, invalid, or expired authentication.
403 FORBIDDEN Authenticated but not permitted.
404 NOT_FOUND Resource (or API route) not found.
409 CONFLICT A unique constraint failed — for example, a record with that name already exists.
429 — Rate limited (auth and public endpoints).
500 INTERNAL_ERROR Unhandled server error.
503 DB_QUERY_TIMEOUT Database query timed out.

Retry idempotent reads freely. For writes, inspect the response and reconcile state before retrying — a network timeout does not prove the server rejected the request.

Verify it worked

GET /api/health requires no authentication and confirms the server is reachable:

curl "https://your-envoy.example.com/api/health"

It returns { "status": "ok", ... } with active-run counts and executor info. An authenticated smoke test is GET /api/tasks?limit=1 with your Bearer header — a 200 with a result array confirms the key works.