---
title: "Start an agent"
method: POST
path: "/api/v1/rest/agenti/{id}/runs"
tags: ["AI agents"]
---

# Start an agent

`POST /api/v1/rest/agenti/{id}/runs`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/agenti/{id}/runs`
- Auth: HTTP bearer

Queues a run of one of this organisation’s agents and returns a run id — it does NOT wait for the result, because a run makes several model calls and can take minutes. The agent runs with ITS OWN permissions and its own tool list, not yours, so it can do exactly what it was configured to do and nothing more. Confirm with the user before starting one: a run costs money and may send mail or change records, depending on how it was set up.

## Path parameters

- `id` string, uuid, required

## Headers

- `X-Tenant-Id` string, uuid

## Request body

- object
  - `task` string: What this particular run should deal with, in your own words. Omit to let the agent follow its standing instructions.

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `404`: Nothing with that id in this organisation.
- `409`: The record is in a state that does not allow it — under legal hold, already sent, already closed. `error.code` says which.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)