Agents

Agents — called personas in the API — configure how Hadiq.io responds to users. Each agent can have a custom system prompt, access to specific document sets, and a set of enabled tools. Agents are the persona_id you pass when creating a chat session.

Create an agent

POST /api/persona

Creates a new agent. Any authenticated user with basic access can create agents.

Request body

string

required

Display name for the agent.

string

required

Short description shown in the agent picker UI.

string

required

The system prompt injected before every conversation. Use this to set tone, persona, constraints, and capabilities.

string

required

Additional task-level instructions appended to the system prompt.

boolean

required

When true, injects the current date and time into the system prompt.

boolean

default:"false"

When true, the system_prompt fully replaces the default Onyx base system prompt instead of prepending to it.

boolean

required

When true, the agent is visible to all users in your tenant.

array

required

IDs of document sets this agent searches. Pass an empty array for a general-purpose agent with no scoped knowledge.

array

required

IDs of tools enabled for this agent (e.g. search tool, image generation tool). Pass an empty array to disable tools.

string

Override the LLM provider (e.g. openai, anthropic).

string

Override the model version (e.g. gpt-4o, claude-3-5-sonnet-20241022).

array

Suggested starter prompts shown to users when opening a new chat with this agent.

Show starter message fields

string

Short label shown on the button.

string

Longer description shown in a tooltip.

string

The actual message sent when the user clicks the starter.

array

UUIDs of users who can access this agent when is_public is false.

array

Group IDs that can access this agent when is_public is false.

string (ISO 8601)

Only search documents updated after this date.

array

Label IDs to tag this agent with for organization.

boolean

default:"false"

Feature this agent prominently in the UI.

integer

Sort order in the agent list. Lower values appear first.

array

IDs of hierarchy nodes (folders, spaces, channels) to scope search to.

array

IDs of individual documents to attach for scoped search.

array

IDs of user-uploaded files to attach.

Response

Returns a PersonaSnapshot with the created agent’s full details.

integer

Unique agent ID. Use this as persona_id when creating chat sessions.

string

Agent name.

string

Agent description.

boolean

Whether the agent is publicly visible.

boolean

Whether this is a built-in Hadiq.io agent (cannot be deleted).

array

Tools enabled for this agent.

array

Document sets this agent searches.

string

The agent’s system prompt.

curl -X POST https://cloud.hadiq.io/api/persona \
  -H "Authorization: Bearer hadiqk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HR Assistant",
    "description": "Answers questions about HR policies and benefits.",
    "system_prompt": "You are a helpful HR assistant with access to company HR policies.",
    "task_prompt": "Always cite the specific policy section when answering.",
    "datetime_aware": true,
    "replace_base_system_prompt": false,
    "is_public": true,
    "document_set_ids": [3, 7],
    "tool_ids": [1]
  }'

import requests

resp = requests.post(
    "https://cloud.hadiq.io/api/persona",
    headers={"Authorization": "Bearer hadiqk-..."},
    json={
        "name": "HR Assistant",
        "description": "Answers questions about HR policies and benefits.",
        "system_prompt": "You are a helpful HR assistant with access to company HR policies.",
        "task_prompt": "Always cite the specific policy section when answering.",
        "datetime_aware": True,
        "replace_base_system_prompt": False,
        "is_public": True,
        "document_set_ids": [3, 7],
        "tool_ids": [1],
    },
)
agent = resp.json()
print("Created agent ID:", agent["id"])

Update an agent

PATCH /api/persona/{persona_id}

Updates an existing agent. Accepts the same fields as the create request. You can only update agents you own or have edit access to.

This endpoint cannot update display_priority or builtin_persona. Use the admin display-priority endpoint to reorder agents.

Path parameters

integer

required

ID of the agent to update.

Request body

Same as create an agent. All fields may be updated.

curl -X PATCH https://cloud.hadiq.io/api/persona/12 \
  -H "Authorization: Bearer hadiqk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HR Assistant v2",
    "description": "Updated HR assistant with broader document access.",
    "system_prompt": "You are a helpful HR assistant.",
    "task_prompt": "",
    "datetime_aware": true,
    "is_public": true,
    "document_set_ids": [3, 7, 9],
    "tool_ids": [1]
  }'

import requests

resp = requests.patch(
    "https://cloud.hadiq.io/api/persona/12",
    headers={"Authorization": "Bearer hadiqk-..."},
    json={
        "name": "HR Assistant v2",
        "description": "Updated HR assistant with broader document access.",
        "system_prompt": "You are a helpful HR assistant.",
        "task_prompt": "",
        "datetime_aware": True,
        "is_public": True,
        "document_set_ids": [3, 7, 9],
        "tool_ids": [1],
    },
)
print(resp.json())

Get an agent

GET /api/persona/{persona_id}

Returns the full details of a single agent.

Path parameters

integer

required

The agent to retrieve.

Response

Returns a FullPersonaSnapshot, which extends PersonaSnapshot with search_start_date.

curl https://cloud.hadiq.io/api/persona/12 \
  -H "Authorization: Bearer hadiqk-..."

import requests

resp = requests.get(
    "https://cloud.hadiq.io/api/persona/12",
    headers={"Authorization": "Bearer hadiqk-..."},
)
print(resp.json())

List agents

GET /api/agents

Returns a paginated list of agents available to the authenticated user.

Query parameters

integer

default:"0"

Page number (0-indexed).

integer

default:"10"

Items per page. Maximum 1000.

boolean

default:"false"

Include soft-deleted agents.

boolean

default:"false"

When true, only returns agents you can edit.

boolean

default:"true"

Include the built-in default agents.

Response

array

Page of MinimalPersonaSnapshot objects.

Show snapshot fields

integer

Agent ID.

string

Agent name.

string

Agent description.

boolean

Whether the agent is publicly visible.

boolean

Whether the agent appears in the agent picker.

boolean

Whether the agent is featured.

boolean

Whether this is a built-in agent.

array

Tools available to the agent.

array

Document sets the agent searches.

string

Model override, if set.

integer

Total number of agents matching the query.

curl "https://cloud.hadiq.io/api/agents?page_num=0&page_size=20" \
  -H "Authorization: Bearer hadiqk-..."

import requests

resp = requests.get(
    "https://cloud.hadiq.io/api/agents",
    headers={"Authorization": "Bearer hadiqk-..."},
    params={"page_num": 0, "page_size": 20},
)
data = resp.json()
print(f"Total agents: {data['total_items']}")
for agent in data["items"]:
    print(agent["id"], agent["name"])

Delete an agent

DELETE /api/persona/{persona_id}

Soft-deletes an agent. The agent is hidden from users but its data is retained. You can only delete agents you own.

Path parameters

integer

required

The agent to delete.

Returns 204 No Content on success.

curl -X DELETE https://cloud.hadiq.io/api/persona/12 \
  -H "Authorization: Bearer hadiqk-..."

import requests

requests.delete(
    "https://cloud.hadiq.io/api/persona/12",
    headers={"Authorization": "Bearer hadiqk-..."},
)

Admin: list agents (paginated)

GET /api/admin/agents

Admin version of the agents list endpoint, with the same query parameters as GET /api/agents. Returns PersonaSnapshot objects (more detailed than MinimalPersonaSnapshot). Requires admin or curator role.

Error codes

Status	Cause
`400`	User knowledge is disabled but `user_file_ids` were provided, or vector DB is disabled and document sets were provided.
`403`	Insufficient permissions to create, edit, or delete the agent.
`404`	Agent not found.

Overview

Endpoints

Create an agent

Request body

Response

Update an agent

Path parameters

Request body

Get an agent

Path parameters

Response

List agents

Query parameters

Response

Delete an agent

Path parameters

Admin: list agents (paginated)

Error codes

​Create an agent

​Request body

​Response

​Update an agent

​Path parameters

​Request body

​Get an agent

​Path parameters

​Response

​List agents

​Query parameters

​Response

​Delete an agent

​Path parameters

​Admin: list agents (paginated)

​Error codes

Create an agent

Request body

Response

Update an agent

Path parameters

Request body

Get an agent

Path parameters

Response

List agents

Query parameters

Response

Delete an agent

Path parameters

Admin: list agents (paginated)

Error codes