> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdialed.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API introduction

> Base URLs, conventions, authentication, pagination, and error shapes for the GetDialed Flows API

The GetDialed Flows API is a JSON REST API for managing connections, flow definitions, jobs, and executions, and for browsing the public catalog and template library.

## Base URLs

| Environment       | Base URL                         |
| ----------------- | -------------------------------- |
| Production        | `https://api.getdialed.ai/flows` |
| Local development | `http://localhost:8000`          |

All request and response bodies are JSON. Send `Content-Type: application/json` on requests with a body.

## Conventions

The API follows standard REST semantics:

| Method   | Used for                                    | Success status                                                                   |
| -------- | ------------------------------------------- | -------------------------------------------------------------------------------- |
| `GET`    | Reads                                       | `200`                                                                            |
| `POST`   | Creates                                     | `201` (resource creates); `200` for actions such as trigger and connection tests |
| `PUT`    | Full-replacement updates — send every field | `200`                                                                            |
| `DELETE` | Deletes and cancels                         | `204`, no body                                                                   |

## Authentication

Tenant-scoped endpoints accept either an `X-API-Key` header or a Clerk organization JWT in `Authorization: Bearer`. Catalog (`/catalog/*`) and template (`/templates/*`) endpoints are public and need no credentials. See [Authentication](/authentication) for both methods, header precedence, and role requirements on mutating endpoints.

```bash theme={null}
curl https://api.getdialed.ai/flows/definitions \
  -H "X-API-Key: $GETDIALED_API_KEY"
```

## Pagination and filtering

All list endpoints accept the same query parameters:

| Parameter | Type    | Default | Constraints                   |
| --------- | ------- | ------- | ----------------------------- |
| `limit`   | integer | `50`    | min 1, max 50,000             |
| `skip`    | integer | `0`     | min 0                         |
| `status`  | string  | none    | Valid values vary by resource |

```bash theme={null}
curl "https://api.getdialed.ai/flows/definitions?status=active&limit=10&skip=0" \
  -H "X-API-Key: $GETDIALED_API_KEY"
```

Results are returned in insertion order; there is no sort parameter. Valid `status` values per resource:

| Resource          | Status values                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------- |
| Catalog platforms | `active`, `inactive`, `coming_soon`                                                       |
| Templates         | `active`, `draft`, `archived`                                                             |
| Connections       | `active`, `expired`, `revoked`                                                            |
| Definitions       | `active`, `draft`, `archived`                                                             |
| Jobs              | `pending`, `scheduled`, `running`, `completed`, `partially_failed`, `failed`, `cancelled` |
| Executions        | `pending`, `running`, `completed`, `failed`, `cancelled`                                  |

## Errors

Errors return a JSON body with a `detail` field:

| Status | Meaning                                                                       | Example body                                                                                             |
| ------ | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `400`  | Bad request — invalid operation, e.g. triggering a non-active definition      | `{"detail": "Cannot trigger definition with status 'draft'. Only active definitions can be triggered."}` |
| `401`  | Missing or invalid credentials                                                | `{"detail": "Authentication required"}`                                                                  |
| `403`  | Authenticated but not permitted — e.g. non-admin token on a mutating endpoint | `{"detail": "Admin role required"}`                                                                      |
| `404`  | Resource doesn't exist, or belongs to another account                         | `{"detail": "Definition not found: def_abc12345"}`                                                       |
| `409`  | Conflict — duplicate resource or invalid state transition                     | `{"detail": "Can only cancel pending or scheduled jobs"}`                                                |
| `422`  | Validation error — malformed request body or invalid expressions              | See below                                                                                                |
| `503`  | Service unavailable — workflow start failed; retry                            | `{"detail": "Workflow start failed, records cleaned up"}`                                                |

A `422` takes one of two shapes. Field-level validation failures use the standard list form:

```json theme={null}
{
  "detail": [
    {"loc": ["body", "name"], "msg": "Field required", "type": "missing"}
  ]
}
```

When a definition's [expressions](/concepts/expressions) fail validation, the body pinpoints each bad expression instead:

```json theme={null}
{
  "detail": {
    "expression_errors": [
      "Invalid expression '{{invalid..path}}' in step 'step_1', task 0, field 'parameters.message'"
    ]
  }
}
```

<Note>
  `404` is returned both when a resource doesn't exist and when it belongs to a different account — the API never reveals other tenants' resource IDs.
</Note>

## Endpoint reference

The endpoint pages in this tab are generated from the API's OpenAPI specification, so parameters, schemas, and response shapes always match the running API. New here? Start with the [quickstart](/quickstart) or [build your first flow](/guides/build-your-first-flow).