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 '{
  "key": "<string>",
  "display_name": "<string>",
  "role": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "system_prompt": "<string>",
  "path": "Default",
  "model": "<string>",
  "fallback_models": [
    "<string>"
  ],
  "settings": {
    "max_iterations": 15,
    "max_execution_time": 300,
    "tool_approval_required": "respect_tool",
    "tools": [],
    "evaluators": [
      {
        "id": "<string>",
        "sample_rate": 50,
        "execute_on": "input"
      }
    ],
    "guardrails": [
      {
        "id": "<string>",
        "sample_rate": 50,
        "execute_on": "input"
      }
    ]
  },
  "memory_stores": [],
  "knowledge_bases": [],
  "team_of_agents": [],
  "variables": {}
}'
{
  "_id": "<string>",
  "key": "<string>",
  "display_name": "<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>",
    "parameters": {
      "audio": {
        "voice": "alloy",
        "format": "wav"
      },
      "frequency_penalty": 123,
      "max_tokens": 123,
      "max_completion_tokens": 123,
      "logprobs": true,
      "top_logprobs": 10,
      "n": 2,
      "presence_penalty": 123,
      "response_format": {
        "type": "text"
      },
      "reasoning_effort": "<string>",
      "verbosity": "<string>",
      "seed": 123,
      "stop": "<string>",
      "stream_options": {
        "include_usage": true
      },
      "thinking": {
        "type": "enabled",
        "budget_tokens": 123,
        "thinking_level": "low"
      },
      "temperature": 1,
      "top_p": 123,
      "top_k": 123,
      "tool_choice": "none",
      "parallel_tool_calls": true,
      "modalities": [
        "text"
      ]
    },
    "retry": {
      "count": 3,
      "on_codes": [
        429,
        500,
        502,
        503,
        504
      ]
    },
    "fallback_models": [
      "<string>"
    ]
  },
  "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"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
key
string
required

Unique identifier for the agent within the workspace

Required string length: 1 - 255
​
role
string
required

The role or function of the agent

Minimum length: 1
​
description
string
required

A brief description of what the agent does

Minimum length: 1
​
instructions
string
required

Detailed instructions that guide the agent's behavior

​
path
string
required

The path where the agent will be stored in the project structure. 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"

​
model
required

Model configuration for agent execution. Can be a simple model ID string or a configuration object with optional behavior parameters and retry settings.

A model ID string (e.g., openai/gpt-4o or anthropic/claude-haiku-4-5-20251001). The agent can be run with a wide range of models with different capabilities, performance characteristics, and price points. Only models that support tool calling (function_calling) can be used to run agents. See (supported models)[/docs/proxy/supported-models] documentation for the complete list of available models.

​
settings
object
required

Configuration settings for the agent's behavior

​
display_name
string

agent display name within the workspace

Maximum length: 255
​
system_prompt
string

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

Minimum length: 1
​
fallback_models
(string | Fallback Model Configuration · object)[]

Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.

​
memory_stores
string[]

Optional array of memory store identifiers for the agent to access. Accepts both memory store IDs and keys.

​
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.

​
variables
object

Response

Agent created successfully

​
_id
string
required
​
key
string
required
​
display_name
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

Array of memory store identifiers. Accepts both memory store IDs and keys.

​
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