# Using the Envoy API

> Source: https://docs.clonepartner.com/api/using-the-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:

```bash
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

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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:

```bash
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:

```json
{
  "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:

```json
{
  "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.