# Agent API

The Agent API lets you interact with the Roboflow AI agent through `api.roboflow.com`. You can send natural-language instructions to create or edit [Workflows](https://docs.roboflow.com/workflows/create-a-workflow), then publish them when ready. All edits are saved as drafts until you explicitly publish.

Authentication is via [API key](/developer/rest-api/authenticate-with-the-rest-api.md). If you use a [Scoped API Key](/developer/authentication/scoped-api-keys.md) with folder restrictions, the agent will only be able to access Workflows within that folder scope.

## Chat

<mark style="color:green;">`POST`</mark> `/:workspace/agent/chat`

Send a message to the AI agent. The agent can create new Workflows, edit existing ones, and answer questions about your workspace. Workflow changes are saved as drafts.

You can start a new conversation or continue an existing one by passing `conversation_id`.

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Body**

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>api_key</code></td><td>string</td><td>Workspace API key.</td><td>true</td></tr><tr><td><code>message</code></td><td>string</td><td>The instruction or question for the agent.</td><td>true</td></tr><tr><td><code>conversation_id</code></td><td>string</td><td>ID of an existing conversation to continue. Omit to start a new conversation.</td><td>false</td></tr><tr><td><code>mode</code></td><td>string</td><td><code>agent</code> (default) or <code>plan</code>. In plan mode the agent outlines what it would do without making changes.</td><td>false</td></tr></tbody></table>

**Example Request**

```bash
curl -X POST "https://api.roboflow.com/my-workspace/agent/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "'"$ROBOFLOW_API_KEY"'",
    "message": "Build me a workflow that detects cars and counts them"
  }'
```

**Response**

```json
{
  "text": "I created a workflow called 'Car Counter' that ...",
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Car Counter",
      "url": "car-counter",
      "specification": { ... }
    }
  ],
  "conversation_id": "conv_xyz789"
}
```

| Field             | Description                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `text`            | The agent's response text.                                                                                        |
| `workflows`       | Workflows created or modified during this turn. Each includes `id`, `name`, `url`, and the draft `specification`. |
| `conversation_id` | The conversation ID. Pass this back in subsequent requests to continue the conversation.                          |

Required scopes: `workflow:create` and `workflow:update`.

## Publish a Workflow

<mark style="color:green;">`POST`</mark> `/:workspace/agent/workflows/:workflowUrl/publish`

Deploys the latest draft version of a Workflow that was created or edited by the agent. If there is no unpublished draft, the endpoint returns `400`.

**Example Request**

```bash
curl -X POST "https://api.roboflow.com/my-workspace/agent/workflows/car-counter/publish?api_key=$ROBOFLOW_API_KEY"
```

**Response**

```json
{
  "workflowId": "wf_abc123",
  "workflowUrl": "car-counter",
  "versionId": "v-1700000000",
  "status": "published"
}
```

Required scope: `workflow:update`.

## List Conversations

<mark style="color:green;">`GET`</mark> `/:workspace/agent/conversations`

Returns all agent conversations in the workspace.

**Query**

<table><thead><tr><th>Name</th><th>Type</th><th>Description</th><th data-type="checkbox">Required</th></tr></thead><tbody><tr><td><code>api_key</code></td><td>string</td><td>Workspace API key.</td><td>true</td></tr><tr><td><code>source</code></td><td>string</td><td>Filter by origin: <code>api</code> or <code>web</code>.</td><td>false</td></tr><tr><td><code>workflow</code></td><td>string</td><td>Filter by Workflow URL slug. Only returns conversations that reference this Workflow.</td><td>false</td></tr></tbody></table>

**Example Request**

```bash
curl "https://api.roboflow.com/my-workspace/agent/conversations?api_key=$ROBOFLOW_API_KEY&source=api"
```

**Response**

```json
{
  "conversations": [
    {
      "id": "conv_xyz789",
      "name": "Car Counter",
      "source": "api",
      "workflowIds": ["wf_abc123"],
      "created_on": "2026-05-14T20:00:00.000Z",
      "updated_on": "2026-05-14T20:05:00.000Z"
    }
  ]
}
```

Required scope: `workflow:read`.

## Get a Conversation

<mark style="color:green;">`GET`</mark> `/:workspace/agent/conversations/:id`

Returns the full conversation including all messages.

**Example Request**

```bash
curl "https://api.roboflow.com/my-workspace/agent/conversations/conv_xyz789?api_key=$ROBOFLOW_API_KEY"
```

**Response**

```json
{
  "id": "conv_xyz789",
  "name": "Car Counter",
  "type": "agent",
  "source": "api",
  "created_on": "2026-05-14T20:00:00.000Z",
  "updated_on": "2026-05-14T20:05:00.000Z",
  "workflowIds": ["wf_abc123"],
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "parts": [{ "type": "text", "text": "Build me a workflow that detects cars" }]
    },
    {
      "id": "msg_2",
      "role": "assistant",
      "parts": [{ "type": "text", "text": "I created a workflow called ..." }]
    }
  ]
}
```

Required scope: `workflow:read`.

## Error Responses

All endpoints return errors as `{ "error": "..." }` with an appropriate HTTP status code.

| Status | Meaning                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------- |
| `400`  | Bad request (missing `message`, no draft to publish, etc.)                                         |
| `401`  | API key missing or invalid.                                                                        |
| `402`  | Insufficient credits.                                                                              |
| `403`  | Insufficient scopes, Workflow outside folder scope, or agent features disabled for this workspace. |
| `404`  | Workflow or conversation not found.                                                                |
| `500`  | Internal server error.                                                                             |

When agent features are disabled at the workspace level, chat and publish endpoints return `403` with `"error_type": "AGENT_DISABLED"`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/rest-api/agent-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.