Documentation

Orqis API Reference

Full reference for the Orqis platform API. Build, chat with, and manage AI agents programmatically.

Overview

The Orqis API lets you create AI agents from OpenAPI specs and chat with them in natural language. Each agent wraps your existing API — the LLM decides which endpoints to call and how to call them based on the user's message.

Base URL

https://api.orqisai.com

Format

JSON (application/json)

Auth

X-Api-Key or Bearer JWT

Pro plan required — External API access via X-Api-Key is available on the Pro plan only. Free users can access the API via Supabase JWT from the dashboard.

Authentication

All endpoints require one of two authentication methods:

X-Api-KeyPro

Platform API key scoped to a single agent. Generated in Dashboard → Settings → API Keys.

X-Api-Key: oq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Bearer JWT

Supabase JWT token from the dashboard session. Used internally by the Orqis frontend.

Authorization: Bearer <supabase_jwt_token>

Note: Each X-Api-Key is scoped to one specific agent. Using it on a different agent's endpoint returns 403.

Providers & Models

When creating or chatting with an agent, pass api_provider and optionally model. If model is omitted, the default shown below is used.

googleGoogle Gemini

Default model

gemini-2.5-flash

Key format

AIzaSy…

Available models

gemini-2.5-flashgemini-2.5-progemini-2.0-flashgemini-1.5-progemini-1.5-flash

openaiOpenAI

Default model

gpt-4o-mini

Key format

sk-…

Available models

gpt-4ogpt-4o-minigpt-4-turbogpt-3.5-turbo

anthropicAnthropic Claude

Default model

claude-sonnet-4-6

Key format

sk-ant-…

Available models

claude-opus-4-6claude-sonnet-4-6claude-haiku-4-5-20251001

mistralMistral AI

Default model

mistral-small-latest

Key format

your Mistral key

Available models

mistral-small-latestmistral-medium-latestmistral-large-latestcodestral-latest

groqGroq

Default model

llama-3.3-70b-versatile

Key format

gsk_…

Available models

llama-3.3-70b-versatilellama-3.1-8b-instantmixtral-8x7b-32768gemma2-9b-it

Agents

GET/v3/agents

List all v3 agents belonging to the authenticated user.

Response 200

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Store Agent",
    "description": "Handles product queries",
    "configuration": {
      "engine_version": "v3",
      "api_provider": "google",
      "tools": [ ... ]
    },
    "created_at": "2026-01-15T10:30:00Z"
  }
]

Response codes

Status	Meaning
`200`	Array of agent objects.
`401`	Missing or invalid credentials.

POST/v3/agents

Create a new v3 agent from an OpenAPI specification. The spec is parsed and converted into callable tools.

Request body

Field	Type	Description
`agent_name`*	`string`	Display name for the agent.
`openapi_spec_content`*	`string`	Raw OpenAPI spec as a YAML or JSON string.
`agent_description`	`string`	Short description of what the agent does.
`api_provider`	`string`	LLM provider. One of `google`, `openai`, `anthropic`, `mistral`, `groq`. Default: `google`.
`api_key`	`string`	LLM API key. Omit to use the key already saved in your account for this provider.
`base_url`	`string`	Override the base URL from the OpenAPI spec.
`headers`	`object`	Custom HTTP headers sent with every API call the agent makes, e.g. `{"Authorization": "Bearer token"}`. Stored encrypted.

Response 201

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Store Agent",
  "configuration": { "engine_version": "v3", ... },
  "visualization": { "nodes": [...], "edges": [...] }
}

Response codes

Status	Meaning
`201`	Agent created successfully.
`400`	Invalid or unparseable OpenAPI spec.
`401`	Missing or invalid credentials.
`403`	Agent limit reached for your plan.

PATCH/agents/{agent_id}

Update the name or description of an existing agent.

Request body

Field	Type	Description
`name`	`string`	New display name.
`description`	`string`	New description.

Response codes

Status	Meaning
`200`	<code>{"status": "ok"}</code>
`401`	Missing or invalid credentials.
`404`	Agent not found or does not belong to you.

DELETE/agents/{agent_id}

Permanently delete an agent and all associated data (runs, API keys, headers).

Response codes

Status	Meaning
`200`	<code>{"status": "deleted"}</code>
`401`	Missing or invalid credentials.
`404`	Agent not found.

Chat

POST/v3/agents/{agent_id}/chatPro

Send a message to an agent. The agent reasons over the message, calls the appropriate API endpoints, and returns the final answer when done.

Request body

Field	Type	Description
`message`*	`string`	The user message to send.
`api_provider`	`string`	Override the LLM provider for this request.
`model`	`string`	Override the LLM model, e.g. `gpt-4o` or `gemini-1.5-pro`.
`base_url`	`string`	Override the API base URL for this request.
`headers`	`object`	Override request headers for this call only (not saved).
`default_tools`	`string[]`	Names of default tools to activate for this call, e.g. `["google_search"]`.

Response 200

{
  "status": "completed",
  "output": "Found 12 products under $50. The cheapest is...",
  "actions": [
    {
      "tool": "get_products",
      "toolInput": "{ \"max_price\": 50 }",
      "timestamp": 1718000000000
    }
  ],
  "visualization": { "nodes": [...], "edges": [...] }
}

Interrupt response (write operations)

When the agent is about to perform a write (POST/PUT/DELETE) operation, it pauses and returns an interrupt requiring confirmation before proceeding.

{
  "status": "interrupted",
  "output": "",
  "actions": [],
  "interrupt": {
    "tool": "create_order",
    "input": { "product_id": "abc", "quantity": 2 },
    "question": "About to create an order. Approve?"
  }
}

Use POST /v3/agents/{agent_id}/confirm to approve or cancel.

Response codes

Status	Meaning
`200`	Completed or interrupted (check <code>status</code> field).
`400`	Missing message or agent not a v3 agent.
`401`	Missing or invalid credentials.
`403`	API access requires Pro plan, or key scoped to a different agent, or run limit reached.
`404`	Agent not found.

Examples

curl -X POST https://api.orqisai.com/v3/agents/AGENT_ID/chat \
  -H "X-Api-Key: oq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "Show me all products under $50"}'

POST/v3/agents/{agent_id}/chat/streamPro

SSEServer-Sent Events

Same as /chat but streams the response token by token. Use this for real-time output in your UI. The request body is identical to the sync endpoint.

Stream event format

data: {"type": "start"}

data: {"type": "action", "tool": "get_products", "input": {"max_price": 50}}

data: {"type": "token", "content": "Found "}
data: {"type": "token", "content": "12 products..."}

data: {"type": "done", "output": "Found 12 products under $50. The cheapest is..."}

Event types

Field	Type	Description
`start`	`event`	Agent has started processing.
`action`	`event`	Agent is calling a tool. Includes `tool` and `input`.
`token`	`event`	A streamed text token. Append `content` to your output buffer.
`interrupted`	`event`	Write operation requires confirmation. Includes `interrupt` object.
`done`	`event`	Stream complete. Includes full `output` string.
`error`	`event`	An error occurred. Includes `message`.

Examples

curl -X POST https://api.orqisai.com/v3/agents/AGENT_ID/chat/stream \
  -H "X-Api-Key: oq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{"message": "Show me all products under $50"}'

POST/v3/agents/{agent_id}/confirmPro

Resume a paused agent after an interrupt. Call this after receiving "status": "interrupted" to approve or cancel the pending write operation.

Request body

Field	Type	Description
`approved`*	`boolean`	`true` to proceed with the action, `false` to cancel.
`api_provider`	`string`	Override LLM provider.
`model`	`string`	Override LLM model.

Response codes

Status	Meaning
`200`	Returns a standard chat response with final output.
`400`	No pending interrupt found for this agent.
`401`	Missing or invalid credentials.
`403`	Plan or scope restriction.

Example

// Approve the pending write
curl -X POST https://api.orqisai.com/v3/agents/AGENT_ID/confirm \
  -H "X-Api-Key: oq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"approved": true}'

Headers

Manage the custom HTTP headers that are sent with every API call the agent makes (e.g. Authorization, X-API-Key). Header values are stored Fernet-encrypted in a dedicated table. Values are never returned — only key names.

GET/agents/{agent_id}/headers

Check whether headers are saved and list the key names (values are never returned).

Response 200

{ "has_headers": true, "header_names": ["Authorization", "X-Tenant-ID"] }

PUT/agents/{agent_id}/headers

Save (or replace) the headers for this agent. All values are encrypted before storage.

Request body

Field	Type	Description
`headers`*	`object`	Key-value map of header names and values, e.g. `{"Authorization": "Bearer sk-..."}`

Response 200

{ "ok": true, "header_names": ["Authorization"] }

Response codes

Status	Meaning
`200`	Headers saved successfully.
`401`	Missing or invalid credentials.
`404`	Agent not found.
`500`	Encryption key not configured on server.

DELETE/agents/{agent_id}/headers

Remove all saved headers for this agent.

Response codes

Status	Meaning
`200`	<code>{"ok": true}</code>
`404`	Agent not found.

Default Tools

Default tools extend agents with capabilities beyond their OpenAPI spec — such as web search, Slack, or GitHub.

Available tools

google_search

Web search via Serper API · requires Serper API key

tavily_search

AI-optimized web search · requires Tavily API key

wolfram_alpha

Computation & math queries · requires Wolfram Alpha API key

slack

Send Slack messages · requires Slack User Token

github

GitHub repo operations · requires GitHub Token

GET/agents/default-tools

List all available default tools and their descriptions.

Response 200

{
  "tools": [
    { "name": "google_search", "description": "Search the web using Google..." },
    { "name": "tavily_search", "description": "..." }
  ]
}

POST/agents/{agent_id}/tools

Add a default tool to an agent.

Request body

Field	Type	Description
`tool_name`*	`string`	Name of the tool, e.g. `google_search`.
`api_provider`	`string`	LLM provider to use when attaching the tool. Default: `google`.
`api_key`	`string`	LLM API key. Omit to use saved key.

Response codes

Status	Meaning
`200`	<code>{"status":"ok", "default_tools":[...], "visualization":{...}}</code>
`400`	Unknown tool name.
`404`	Agent not found.

DELETE/v3/agents/{agent_id}/tools/{tool_name}

Remove a default tool from a v3 agent.

Response codes

Status	Meaning
`200`	<code>{"status":"ok", "default_tools":[...]}</code>
`404`	Agent or tool not found.

Account & Plan

GET/users/me/plan

Return the authenticated user's current plan, limits, usage, and cancellation state.

Response 200

{
  "plan": "pro",
  "limits": { "agents": 5, "runs_per_month": 1000, "api_access": true },
  "usage": { "agents": 2, "runs_this_month": 47 },
  "cancel_at_period_end": false,
  "cancel_at": null
}

Plan	Agents	Runs / month	API access
`free`	1	50	No
`pro`	5	1,000	Yes

PUT/users/me/llm-key

Save or replace the encrypted LLM API key for a provider in your account.

Request body

Field	Type	Description
`provider`*	`string`	One of `google`, `openai`, `anthropic`, `mistral`, `groq`.
`api_key`*	`string`	Your LLM provider API key. Stored encrypted — never returned.

Response codes

Status	Meaning
`200`	<code>{"status":"ok","provider":"google"}</code>
`401`	Missing or invalid credentials.

GET/users/me/llm-key

Check if a key is saved for a provider (value is never returned).

Query params

Field	Type	Description
`provider`	`string`	Provider to check. Default: `google`.

Response 200

{ "has_key": true, "provider": "google" }

DELETE/users/me/llm-key

Remove the saved LLM key for a provider.

Query params

Field	Type	Description
`provider`	`string`	Default: `google`.

Response codes

Status	Meaning
`200`	<code>{"status":"deleted","provider":"google"}</code>

API Keys

Platform API keys (oq_…) allow external applications to chat with a specific agent. Each key is scoped to one agent and requires a Pro plan.The full key is shown only once on creation — store it securely.

POST/users/me/api-keysPro

Create a new platform API key scoped to one agent.

Request body

Field	Type	Description
`name`*	`string`	A label to identify this key, e.g. `production` or `my-app`.
`agent_id`*	`string`	The agent this key is scoped to.

Response 201

{
  "key": "oq_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",  // shown once only
  "prefix": "oq_xxxxxxxxxxxxx",
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-01-15T10:30:00Z"
}

Response codes

Status	Meaning
`201`	Key created. Save the full key — it cannot be retrieved again.
`403`	Pro plan required, or limit of 5 keys per agent reached.
`409`	An active key already exists for this agent.

GET/users/me/api-keys

List all your active platform API keys. Key values are never returned.

Response 200

[
  {
    "id": "...",
    "name": "production",
    "prefix": "oq_xxxxxxxxxxxxx",
    "agent_id": "550e8400-...",
    "created_at": "2026-01-15T10:30:00Z",
    "last_used_at": "2026-04-07T09:12:00Z"
  }
]

DELETE/users/me/api-keys/{key_id}

Permanently revoke a platform API key. Any application using it will immediately lose access.

Response codes

Status	Meaning
`200`	<code>{"status":"revoked"}</code>
`404`	Key not found or does not belong to you.

Error Codes

All errors return a JSON body with a detail string describing the problem.

{ "detail": "Agent limit reached (1/1). Your FREE plan allows 1 agent(s)." }

Status	Meaning
`200`	Success.
`201`	Resource created.
`400`	Bad request — invalid parameters, malformed spec, or wrong engine version.
`401`	Missing or invalid authentication.
`403`	Forbidden — plan restriction, key scoped to a different agent, or limit reached.
`404`	Resource not found or not owned by you.
`409`	Conflict — e.g. API key already exists for this agent.
`429`	Rate limit — monthly run limit reached.
`500`	Internal server error. Contact support if this persists.
`503`	Service unavailable — billing or encryption not configured on server.