Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/omnigent-ai/omnigent/llms.txt

Use this file to discover all available pages before exploring further.

Two additional API groups complement the session-scoped endpoints: the agent registry (registered agent specs on the server) and the policy registry (a browsable catalog of available policy handlers). Server-wide default policies apply to every session on the server and are managed separately from session-level policies.

​
Agents

The agent registry contains all built-in agents registered on the server. These are the agents available when creating a new session — each entry has a stable id that you pass as agent_id when creating or forking sessions.

​
List Registered Agents

GET /v1/agents Returns built-in agents with cursor-based pagination. Session-scoped agents (uploaded with specific sessions) are excluded — only globally registered agents are returned. Query parameters:
​
limit
integer
default:"20"
Maximum agents to return. Range: 1–1000.
​
after
string
Cursor — return agents after this ID.
​
before
string
Cursor — return agents before this ID.
​
order
string
default:"desc"
Sort direction: "asc" or "desc".
Response: 
{
  "object": "list",
  "data": [
    {
      "id": "ag_abc123",
      "object": "agent",
      "name": "claude-native-ui",
      "version": 3,
      "description": "Claude Code with web UI integration",
      "harness": "claude-native",
      "created_at": 1700000000,
      "updated_at": 1700001000,
      "mcp_servers": [
        {
          "name": "github",
          "transport": "stdio",
          "command": "uvx",
          "args": ["mcp-server-github"]
        }
      ],
      "policies": [
        {
          "name": "block_long_sleep",
          "type": "function",
          "on": ["tool_call"],
          "description": "omnigent.policies.block_long_sleep"
        }
      ],
      "skills": [
        {
          "name": "triage-issues",
          "description": "Triage open GitHub issues in the repo."
        }
      ],
      "terminals": ["shell"]
    }
  ],
  "has_more": false
}
​
id
string
Unique agent identifier, e.g. "ag_abc123".
​
name
string
Human-readable agent name, e.g. "claude-native-ui".
​
version
integer
Monotonic version counter. Starts at 1 and increments on each update.
​
description
string
Optional free-text description of the agent’s purpose.
​
harness
string
The agent’s harness kind: "codex", "codex-native", "claude-native", "claude_sdk", "agents_sdk", etc. null when the bundle cannot be loaded.
​
mcp_servers
array
MCP servers the agent is connected to (secret fields omitted). Each entry has name, transport, and optionally url, command, args, description.
​
policies
array
Guardrails policies declared on the agent. Each entry has name, type, on (phase selectors), and description.
​
skills
array
Skills bundled in the agent spec (skills/<name>/SKILL.md). Each entry has name and description. Empty when the spec bundles no skills.
​
terminals
array
Terminal names declared in the spec’s terminals: block, e.g. ["shell"]. Empty when the spec declares no terminals.

​
Server-Wide Policies

Server-wide default policies apply to all sessions on the server. Creating or deleting them requires admin privileges.

​
List Default Policies

GET /v1/policies Returns all server-wide default policies. 
curl -H "Authorization: Bearer <token>" \
  http://localhost:6767/v1/policies
Response: 
{
  "object": "list",
  "data": [
    {
      "id": "pol_srv_abc",
      "name": "block_non_feature_branch_push",
      "type": "python",
      "handler": "github_mcp_policy.block_non_misc_push",
      "enabled": true,
      "created_at": 1700000000
    }
  ]
}

​
Create a Default Policy

POST /v1/policies Requires admin privileges.
​
name
string
required
Human-readable policy name. Must be globally unique, e.g. "block_non_feature_branch_push".
​
type
string
required
Handler discriminator: "python" or "url".
​
handler
string
required
Dotted import path (python) or HTTPS URL (url). Example: "github_mcp_policy.block_non_misc_push".
​
factory_params
object
Optional kwargs passed to the handler when it is a factory function. Only valid for type: "python", e.g. {"limit": 10}.

​
Get a Default Policy

GET /v1/policies/{policy_id} Returns a single server-wide policy.

​
Update a Default Policy

PATCH /v1/policies/{policy_id} Updates mutable fields. The type field is immutable. Requires admin privileges.
​
name
string
New policy name. null leaves unchanged.
​
handler
string
New handler path or URL. null leaves unchanged.
​
enabled
boolean
Enable or disable the policy. null leaves unchanged.

​
Delete a Default Policy

DELETE /v1/policies/{policy_id} Deletes a server-wide policy. Idempotent — deleting a missing policy returns 204. Requires admin privileges. 
curl -X DELETE \
  "http://localhost:6767/v1/policies/pol_srv_abc" \
  -H "Authorization: Bearer <token>"
Response: 
{ "deleted": true }

​
Policy Registry

The policy registry is a browsable catalog of all built-in and registered policy handlers available on the server. The web UI uses it to populate the “add policy” picker with available handlers, their descriptions, and their parameter schemas.

​
List the Policy Registry

GET /v1/policy-registry Returns the full catalog of available policy callables. 
curl -H "Authorization: Bearer <token>" \
  http://localhost:6767/v1/policy-registry
Response: 
{
  "object": "list",
  "data": [
    {
      "handler": "omnigent.policies.ask_on_os_tools",
      "kind": "python",
      "description": "Ask for approval before running any OS-level tool (bash, edit, read).",
      "params_schema": {}
    },
    {
      "handler": "omnigent.policies.block_long_sleep",
      "kind": "python",
      "description": "Deny shell sleep commands longer than a configured threshold.",
      "params_schema": {
        "type": "object",
        "properties": {
          "max_seconds": {
            "type": "integer",
            "description": "Maximum allowed sleep duration in seconds.",
            "default": 5
          }
        }
      }
    }
  ]
}
​
handler
string
Dotted import path of the policy callable, e.g. "omnigent.policies.ask_on_os_tools". Pass this as the handler field when attaching the policy to a session or creating a server-wide default policy.
​
kind
string
Handler type: "python" for dotted import paths. Future entries may include "url".
​
description
string
Human-readable description of what the policy does.
​
params_schema
object
JSON Schema for the factory_params the handler accepts. Empty object {} for handlers that take no parameters.

​
Policy Evaluation Order

Policies are evaluated in this order on every agent action:
  1. Session-level policies — attached via POST /v1/sessions/{id}/policies or by the agent’s sys_add_policy tool
  2. Agent spec policies — declared in the agent’s YAML policies: block
  3. Server-wide default policies — managed via POST /v1/policies
The first DENY or ASK verdict wins. Use session-level policies for per-task restrictions, agent spec policies for agent-wide guardrails, and server-wide policies for organisation-level controls. For the full policy authoring guide and built-in policy reference, see Policies guide and Built-in Policies.

Build docs developers (and LLMs) love

Get started for freeTalk to us