# REST API

> The same actions as the MCP tools over plain HTTP, for scripts, CRMs and scheduled jobs.

Source: https://rivomi.com/docs/tools/rest



Every MCP tool and every REST endpoint calls the same function, so they can't give different answers.
The [tool reference](/tools) maps each tool to its endpoint.

|                         |                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------ |
| **Base URL**            | `https://rivomi.com/api/v1`                                                          |
| **Auth**                | `Authorization: Bearer <API key>` (see [API keys](/connect/authentication#api-keys)) |
| **Schema**              | [`/api/v1/openapi.json`](https://rivomi.com/api/v1/openapi.json), OpenAPI 3.1        |
| **Browsable reference** | [`/api/v1/docs`](https://rivomi.com/api/v1/docs)                                     |

The OpenAPI document is authoritative for paths, parameters and response shapes. Generate a
client from it rather than copying shapes from this page.

## First call [#first-call]

```bash
export RIVOMI=https://rivomi.com
curl "$RIVOMI/api/v1/workspace" -H "Authorization: Bearer $RIVOMI_KEY"
```

## Paging [#paging]

Every list endpoint takes `limit` (default 25, maximum 200) and `offset`, and returns:

```json
{ "total": 412, "count": 25, "offset": 0, "has_more": true, "next_offset": 25, "items": [] }
```

Loop until `has_more` is `false`, passing `next_offset` as the next `offset`.

## Idempotency [#idempotency]

`POST /v1/agents/{id}/run`, `POST /v1/lists/{id}/process` and `POST /v1/imports` accept an
`Idempotency-Key` header. A repeat with the same key within 24 hours replays the first response
instead of spending again. Send one on every call you might retry:

```bash
curl -X POST "$RIVOMI/api/v1/agents/$AGENT_ID/run" \
  -H "Authorization: Bearer $RIVOMI_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Errors [#errors]

Errors are JSON with a sentence written for the caller and a stable code:

```json
{ "error": "This key needs the write scope. Create one under Settings › API.", "code": "insufficient_scope" }
```

Status codes and codes are listed in [Errors and limits](/reference/errors).