Using the Envoy API

The Envoy control plane exposes a REST API under /api. Use it to manage tasks, connectors, job templates, jobs, runs, triggers, dashboards, metrics, and other product resources.

Programmatic clients should use API keys. Browser sessions use an HTTP cookie and are not intended as a replacement for service authentication.

Create an API key

An admin or superadmin creates and revokes API keys while signed in through a browser session. API keys cannot create or delete other API keys.

Create a named key from Settings, optionally set an expiration, and copy the value immediately. Envoy stores only its hash and a display prefix; the complete key is not shown again.

Store the key in a secret manager:

export ENVOY_ORIGIN="https://envoy.example.com"
export ENVOY_API_KEY="envoy_..."

Do not place keys in YAML definitions, URLs, shell history, source control, or support tickets.

Make a request

curl --fail-with-body \
  -H "Authorization: Bearer $ENVOY_API_KEY" \
  -H "Accept: application/json" \
  "$ENVOY_ORIGIN/api/tasks?limit=50&status=active"

The key acts with the role of the user who created it. A key owned by a viewer does not gain admin permissions.

Pagination and search

Collection endpoints return a shape similar to:

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

Use:

• limit for page size;
• cursor with the exact opaque value returned by the previous response;
• q for supported text search;
• sort and order for allowed server-side sorting;
• resource-specific filters such as status, type, or job_id.

Do not derive, decode, or modify cursors. Continue until nextCursor is absent. The server caps list pages; clients must not assume one request returns every row.

Create and run a task

Create a task record with YAML content:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $ENVOY_API_KEY" \
  -H "Content-Type: application/json" \
  --data @- \
  "$ENVOY_ORIGIN/api/tasks" <<'JSON'
{
  "name": "example/list-records",
  "description": "List a bounded set of records",
  "yaml_content": "name: example/list-records\nconnectors:\n  source:\n    type: sqlite\nsteps:\n  - name: read\n    type: call_method\n    config:\n      connector: source\n      method: find\n      args:\n        table: records\n        limit: 10\n"
}
JSON

To start a standalone run, send declared arguments and a connector mapping to POST /api/runs/trigger/{taskId}. Connector mapping values are stored connector IDs:

{
  "arguments": {
    "dry_run": true
  },
  "connector_mapping": {
    "source": 12
  }
}

Poll GET /api/runs/{id} until the status is terminal. Stop an active run with POST /api/runs/{id}/stop.

Start a job

Start the complete DAG:

curl --fail-with-body \
  -X POST \
  -H "Authorization: Bearer $ENVOY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}' \
  "$ENVOY_ORIGIN/api/jobs/42/run"

Run selected task keys with dependencies:

{
  "tasks": ["load_tickets"],
  "skip_deps": false
}

Use skip_deps: true only when required upstream state already exists and has been verified.

Errors and retries

Errors use an HTTP status and a JSON body such as:

{
  "error": "VALIDATION_ERROR",
  "message": "..."
}

Handle at least:

• 400 invalid input;
• 401 missing, invalid, or expired authentication;
• 403 authenticated but not permitted;
• 404 resource not found;
• 409 current state conflicts with the request;
• 429 rate limited;
• 5xx server or dependency failure.

Retry only idempotent reads automatically. For writes, use a stable business key, inspect the response, and reconcile target state before retrying. A network timeout does not prove the server did not accept a request.

NDJSON and streamed responses

Bundle export and import use application/x-ndjson. Process one line at a time rather than buffering a large response. Explorer exports may stream CSV or NDJSON and can be compressed when the client supports it.

Operational safeguards

• Use a separate key per automation and environment.
• Set expiration dates and rotate keys.
• Revoke keys when their owner or workload changes.
• Use HTTPS only.
• Keep base URLs configurable.
• Log request IDs and resource IDs, not authorization headers or full payloads.
• Use dry-run or validation endpoints before bulk writes.
• Preserve nextCursor exactly and page until completion.

The deployed OpenAPI document is the source for exact request and response schemas. Confirm an operation there before building automation around it.