Skip to main content
POST
/
v2
/
agents
/
Create a new agent
curl --request POST \
  --url https://api.orq.ai/v2/agents/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "path": "Default",
  "key": "<string>",
  "role": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "system_prompt": "<string>",
  "model": "<string>",
  "fallback_models": [
    "<string>"
  ],
  "settings": {
    "max_iterations": 15,
    "max_execution_time": 300,
    "tool_approval_required": "respect_tool",
    "tools": []
  },
  "memory_stores": [],
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ],
  "team_of_agents": []
}'
{
  "_id": "<string>",
  "key": "<string>",
  "workspace_id": "<string>",
  "project_id": "<string>",
  "created_by_id": "<string>",
  "updated_by_id": "<string>",
  "created": "<string>",
  "updated": "<string>",
  "role": "<string>",
  "description": "<string>",
  "system_prompt": "<string>",
  "instructions": "<string>",
  "status": "live",
  "settings": {
    "max_execution_time": 300,
    "max_iterations": 15,
    "tool_approval_required": "respect_tool",
    "tools": []
  },
  "model": {
    "id": "<string>",
    "integration_id": "<string>",
    "fallback_models": [
      "<string>"
    ],
    "max_tokens": 123,
    "temperature": 1
  },
  "version_hash": "<string>",
  "path": "Default",
  "memory_stores": [
    "<string>"
  ],
  "team_of_agents": [
    {
      "key": "<string>",
      "role": "<string>"
    }
  ],
  "metrics": {
    "total_cost": 0
  },
  "variables": {},
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ],
  "hidden_panels": [
    "model"
  ]
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
path
string
required

The path where the agent will be stored in the project structure

Example:

"Default"

​
key
string
required

Unique identifier for the agent within the workspace

​
role
string
required

The role or function of the agent

​
description
string
required

A brief description of what the agent does

​
instructions
string
required

Detailed instructions that guide the agent's behavior

​
model
string
required

The primary language model that powers the agent (e.g., "anthropic/claude-3-sonnet-20240229")

​
settings
object
required

Configuration settings for the agent's behavior

​
system_prompt
string

A custom system prompt template for the agent. If omitted, the default template is used.

Minimum length: 1
​
fallback_models
string[]

Optional array of fallback model IDs to use when the primary model fails. Models are tried in order. All models must support tool calling capabilities.

​
memory_stores
string[]

Optional array of memory store keys for the agent to access

​
knowledge_bases
object[]

Optional array of knowledge base configurations for the agent to access

​
team_of_agents
Team of agents · object[]

The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.

Response

Agent created successfully

​
_id
string
required
​
key
string
required
​
workspace_id
string
required
​
project_id
string
required
​
role
string
required
Minimum length: 1
​
description
string
required
​
instructions
string
required
​
status
enum<string>
required

The status of the agent. Live is the latest version of the agent. Draft is a version that is not yet published. Pending is a version that is pending approval. Published is a version that was live and has been replaced by a new version.

Available options:
live,
draft,
pending,
published
​
model
object
required
​
path
string
required

Entity storage path in the format: project/folder/subfolder/...

The first element identifies the project, followed by nested folders (auto-created as needed).

With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.

Example:

"Default"

​
memory_stores
string[]
required
​
team_of_agents
object[]
required

The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.

​
created_by_id
string | null
​
updated_by_id
string | null
​
created
string
​
updated
string
​
system_prompt
string
Minimum length: 1
​
settings
object
​
version_hash
string
​
metrics
object
​
variables
object

Extracted variables from agent instructions

​
knowledge_bases
object[]

Agent knowledge bases reference

​
hidden_panels
enum<string>[]

List of hidden collapsed panels in configuration. Duplicates are not allowed.