Skip to main content
GET
/
v2
/
agents
/
{agent_key}
Retrieve agent
curl --request GET \
  --url https://api.orq.ai/v2/agents/{agent_key} \
  --header 'Authorization: Bearer <token>'
{
  "_id": "<string>",
  "key": "<string>",
  "display_name": "<string>",
  "workspace_id": "<string>",
  "project_id": "<string>",
  "role": "<string>",
  "description": "<string>",
  "instructions": "<string>",
  "status": "live",
  "model": {
    "id": "<string>",
    "integration_id": "<string>",
    "parameters": {
      "name": "<string>",
      "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": "none",
      "verbosity": "<string>",
      "seed": 123,
      "stop": "<string>",
      "stream_options": {
        "include_usage": true
      },
      "thinking": {
        "type": "disabled"
      },
      "temperature": 1,
      "top_p": 0.5,
      "top_k": 123,
      "tool_choice": "none",
      "parallel_tool_calls": true,
      "modalities": [
        "text"
      ],
      "guardrails": [
        {
          "id": "orq_pii_detection",
          "execute_on": "input"
        }
      ],
      "fallbacks": [
        {
          "model": "openai/gpt-4o-mini"
        }
      ],
      "retry": {
        "count": 3,
        "on_codes": [
          429,
          500,
          502,
          503,
          504
        ]
      },
      "cache": {
        "type": "exact_match",
        "ttl": 3600
      },
      "load_balancer": {
        "type": "weight_based",
        "models": {
          "type": "weight_based",
          "models": [
            {
              "model": "openai/gpt-4o",
              "weight": 0.7
            },
            {
              "model": "anthropic/claude-3-5-sonnet",
              "weight": 0.3
            }
          ]
        }
      },
      "timeout": {
        "call_timeout": 30000
      }
    },
    "retry": {
      "count": 3,
      "on_codes": [
        429,
        500,
        502,
        503,
        504
      ]
    },
    "fallback_models": [
      "<string>"
    ]
  },
  "path": "Default",
  "memory_stores": [
    "<string>"
  ],
  "team_of_agents": [
    {
      "key": "<string>",
      "role": "<string>"
    }
  ],
  "created_by_id": "<string>",
  "updated_by_id": "<string>",
  "created": "<string>",
  "updated": "<string>",
  "system_prompt": "<string>",
  "settings": {
    "max_execution_time": 600,
    "max_iterations": 100,
    "max_cost": 0,
    "tool_approval_required": "respect_tool",
    "tools": []
  },
  "version_hash": "<string>",
  "metrics": {
    "total_cost": 0
  },
  "variables": {},
  "knowledge_bases": [
    {
      "knowledge_id": "customer-knowledge-base"
    }
  ],
  "source": "internal"
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
agent_key
string
required

The unique key of the agent to retrieve

Response

Agent successfully retrieved. Returns the complete agent manifest with all configuration details, including models, tools, knowledge bases, and execution settings.

​
_id
string
required
​
key
string
required

Unique identifier for the agent within the workspace

​
display_name
string
required
​
workspace_id
string
required
​
project_id
string
required
​
role
string
required
Minimum string 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 string length: 1
​
settings
object
​
version_hash
string
​
metrics
object
​
variables
object

Extracted variables from agent instructions

​
knowledge_bases
object[]

Agent knowledge bases reference

​
source
enum<string>
Available options:
internal,
external,
experiment