> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/developer/rest-api/agent-api.md).

# 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`.

## Analyze Media

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

Analyze an image or video and get back structured detail about what it contains: objects present, a suggested computer vision task, candidate classes, and (for video) motion notes. The media is passed by HTTPS URL; the URL is fetched server-side, so it must be publicly reachable.

Images up to 15 MB and video up to a roughly 14 MiB analysis budget are supported. To analyze a local file, or a video larger than the budget, upload and trim it first through the MCP [`media_upload`](/developer/mcp-server.md) tools, which store it in your Asset Library and return a URL you can pass here.

**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>url</code></td><td>string</td><td>HTTPS URL of the image or video to analyze.</td><td>true</td></tr><tr><td><code>media_type</code></td><td>string</td><td><code>image</code> or <code>video</code>.</td><td>true</td></tr><tr><td><code>question</code></td><td>string</td><td>Optional question to focus the analysis.</td><td>false</td></tr></tbody></table>

**Example Request**

```bash
curl -X POST "https://api.roboflow.com/my-workspace/agent/media/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "'"$ROBOFLOW_API_KEY"'",
    "url": "https://example.com/street.jpg",
    "media_type": "image"
  }'
```

Required scope: `model:infer`. This endpoint consumes credits and is subject to the same `AGENT_DISABLED` workspace kill switch as the other agent endpoints.

## 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"`.