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

# Invoke a published agent

> Run a published agent with a single request: POST the user message as text and get the agent's reply as JSON.

Invoke runs a published agent version against a single message and returns the agent's reply. It is the simplest way to call an agent from your own code.

```text theme={null}
POST https://api.usegradient.dev/v1/agents/<agent-uuid>/versions/<n>/invoke
```

The call is stateless and starts from an empty transcript. The engine drives the graph, following any `agent_swap` handoffs and resolving tool calls, until the turn settles, then returns the final assistant text. For a multi-turn conversation where you keep and replay the transcript yourself, use [Turn](/api/agents/turn) instead.

## Path parameters

| Segment        | Description                                                                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<agent-uuid>` | The agent's UUID. This is the agent id, not its display name, so agents can safely share names. Find it in the console or via the MCP `list_agents` tool. |
| `<n>`          | A published version, a positive integer such as `1` or `2`. The mutable `draft` is rejected here; publish first.                                          |

## Request

* **Header:** `Authorization: Bearer $GRADIENT_API_KEY`. The key needs the `agents:invoke` scope. See [Authentication](/api/authentication).
* **Header:** `content-type: text/plain`.
* **Body:** the user's message as plain UTF-8 text, up to 1 MB. It must not be empty.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST \
    https://api.usegradient.dev/v1/agents/<agent-uuid>/versions/1/invoke \
    -H "authorization: Bearer $GRADIENT_API_KEY" \
    -H "content-type: text/plain" \
    --data-raw 'I need to book a follow-up visit'
  ```

  ```json Response theme={null}
  {
    "output": "Happy to help you book a follow-up. Can I get your date of birth to find your record?"
  }
  ```
</CodeGroup>

## Response

On success the engine returns `200` with a single field:

| Field    | Type   | Description                                   |
| -------- | ------ | --------------------------------------------- |
| `output` | string | The agent's assistant reply for this message. |

## Errors

| Status | Meaning                                                                                                                    |
| ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The agent id is not a UUID, the version is not a published positive integer, or the body is empty, too large, or not UTF-8 |
| `401`  | Missing or invalid key, or the key lacks `agents:invoke`                                                                   |
| `404`  | No such agent or version for this organization                                                                             |
| `402`  | Billing blocks the request (for example, an exhausted trial)                                                               |

Every invoke is recorded as a production trace, so calls made this way show up alongside [chat](/run/chat) and voice conversations in the console.