# Developer API

> Start workflows from your own code, pass them inputs, and read what each run did. A small REST API with JSON bodies and API-key authentication.

Web page: https://docs.lodol.com/docs/api

The developer API lets your own systems use the workflows you've built in Lodol: list them, start runs with the inputs they need, follow each run to its result, and stop or delete a run. Workflows themselves are built in Lodol, or by your [AI tool](https://docs.lodol.com/docs/build-with-ai.md).

<Cards>
  <Card title="Quickstart" description="Create a key, start a run and read its result, in about five minutes." href="/docs/api/quickstart" />
  <Card title="Authentication" description="API keys, scopes and what each key is allowed to do." href="/docs/api/authentication" />
</Cards>

## Base URL

Every endpoint is under one base URL:

```txt
https://api-prod.lodol.com/api/v1
```

## Endpoints

| Endpoint | What it does | Scope |
| --- | --- | --- |
| [`GET /workflows`](https://docs.lodol.com/docs/api/workflows.md#list-workflows) | List the workspace's workflows | `workflows:read` |
| [`GET /workflows/:id`](https://docs.lodol.com/docs/api/workflows.md#get-a-workflow) | Get one workflow, with its steps | `workflows:read` |
| [`DELETE /workflows/:id`](https://docs.lodol.com/docs/api/workflows.md#delete-a-workflow) | Delete a workflow for good | `workflows:delete` |
| [`POST /workflows/:id/run-async`](https://docs.lodol.com/docs/api/runs.md#run-a-workflow) | Start a run | `workflows:execute` |
| [`GET /executions`](https://docs.lodol.com/docs/api/runs.md#list-runs) | List runs | `executions:read` |
| [`GET /executions/:id`](https://docs.lodol.com/docs/api/runs.md#get-a-run) | Get a run's status and results | `executions:read` |
| [`POST /executions/:id/stop`](https://docs.lodol.com/docs/api/runs.md#stop-a-run) | Stop a run | `workflows:execute` |
| [`DELETE /executions/:id`](https://docs.lodol.com/docs/api/runs.md#delete-a-run) | Delete a finished run for good | `executions:delete` |

The API calls a run an **execution**: run IDs are `execution_id`, and their endpoints are under `/executions`.

## Requests and responses

- **Authentication.** Send your API key as a bearer token: `Authorization: Bearer sk_live_…`. See [Authentication](https://docs.lodol.com/docs/api/authentication.md).
- **JSON.** Request bodies are JSON, sent with `Content-Type: application/json`. Every response is JSON.
- **Timestamps** are ISO 8601 with an offset, such as `2026-03-17T08:00:00+00:00`.
- **Errors** have a JSON body with an `error` message and a standard HTTP status. See [Errors and retries](https://docs.lodol.com/docs/api/errors.md).
- **Retries.** Send an `Idempotency-Key` with each run you start, so retrying a request never starts the same run twice. See [Idempotency](https://docs.lodol.com/docs/api/errors.md#idempotency).
- **Limits.** Requests are rate-limited per workspace, by plan. See [Limits](https://docs.lodol.com/docs/api/limits.md).

## Paging through lists

[List runs](https://docs.lodol.com/docs/api/runs.md#list-runs) returns results a page at a time. Pass `limit` (1 to 100, default 20) for the page size, and `after` with the last ID of the page you have to get the next one.

```bash
# First page
curl "https://api-prod.lodol.com/api/v1/executions?limit=20" \
  -H "Authorization: Bearer $LODOL_API_KEY"

# Next page: after = the last execution_id of the previous page
curl "https://api-prod.lodol.com/api/v1/executions?limit=20&after=683b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer $LODOL_API_KEY"
```

## Version

This is version 1 of the API, named in the path as `/api/v1`.