Agent API

Use the AI agent programmatically to build and manage Workflows via the REST 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, then publish them when ready. All edits are saved as drafts until you explicitly publish.

Authentication is via API key. If you use a Scoped API Key with folder restrictions, the agent will only be able to access Workflows within that folder scope.

Chat

POST /: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

Name	Type	Description	Required
api_key	string	Workspace API key.
message	string	The instruction or question for the agent.
conversation_id	string	ID of an existing conversation to continue. Omit to start a new conversation.
mode	string	agent (default) or plan. In plan mode the agent outlines what it would do without making changes.

Example Request

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

{
  "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

POST /: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

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

Response

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

Required scope: workflow:update.

List Conversations

GET /:workspace/agent/conversations

Returns all agent conversations in the workspace.

Query

Name	Type	Description	Required
api_key	string	Workspace API key.
source	string	Filter by origin: api or web.
workflow	string	Filter by Workflow URL slug. Only returns conversations that reference this Workflow.

Example Request

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

Response

{
  "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

GET /:workspace/agent/conversations/:id

Returns the full conversation including all messages.

Example Request

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

Response

{
  "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".