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

# Requests

> Base URL, content types, pagination, filtering, and field projection.

## Base URL

```
https://api.runflow.io
```

All endpoints live under `/v1/`. The public OpenAPI spec is at [`docs.runflow.io/api/openapi.public.json`](https://docs.runflow.io/api/openapi.public.json).

## Content types

| Method                                      | Content-Type       | Use                                                 |
| ------------------------------------------- | ------------------ | --------------------------------------------------- |
| `GET`                                       | n/a                | Read endpoints.                                     |
| `POST`, `PATCH`, `PUT`                      | `application/json` | All mutations.                                      |
| `POST /v1/asset-uploads/{id}/confirmations` | `application/json` | After uploading the file blob to the presigned URL. |

## Pagination

List endpoints return cursors, not page numbers. Pass `pq` (the cursor) and `limit` (page size, max 500).

```bash theme={"dark"}
curl https://api.runflow.io/v1/runs?limit=50 \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

The response includes `next_pq` and `prev_pq`. Pass `from_prev=true` to walk backward.

## Filtering

List endpoints accept a filter expression in `q`:

```bash theme={"dark"}
curl 'https://api.runflow.io/v1/runs?q=status_code:succeeded%20AND%20created_at>2026-04-01' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

Operators: `=`, `:`, `>`, `<`, `>=`, `<=`, `AND`, `OR`, `NOT`. String values are case-sensitive.

## Field projection

Trim the response to the fields you need with `fields`:

```bash theme={"dark"}
curl 'https://api.runflow.io/v1/runs?fields=id,status_code,model_id' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

## Sorting

```bash theme={"dark"}
curl 'https://api.runflow.io/v1/runs?sort_by=created_at:desc' \
  -H "Authorization: Bearer $RUNFLOW_API_KEY"
```

Multi-field sort: `sort_by=status_code:asc,created_at:desc`.

## Idempotency

Mutations are not idempotent by default. To retry safely, save the response of the first call and skip on duplicate.

## Related

<CardGroup cols={2}>
  <Card title="Errors" icon="triangle-exclamation" href="/concepts/errors">Status codes and the error envelope.</Card>
  <Card title="Runs" icon="play" href="/concepts/runs">Callbacks, polling, statuses.</Card>
</CardGroup>