Documentation - Dooor OS

Agents

Agents are AI-powered assistants deployed as containers in your workspace. Each agent has a configurable personality (soul), model, tools, and cron jobs. Agents expose a chat endpoint and can be integrated via the OpenAI-compatible API.

List Agents

GET/workspaces/{wsId}/agents

Returns a paginated list of agents in the workspace.

Query Parameters

Name	Type	Required	Description
page	integer	optional	Page number starting at 1. Default: 1
limit	integer	optional	Items per page. Default: 20, max: 100
status	string	optional	Filter by status: active \| inactive \| deploying \| failed \| stopped
search	string	optional	Full-text search on name and description

Response

json

{
  "data": [
    {
      "id": "agt_01hx...",
      "slug": "support-agent",
      "name": "Support Agent",
      "status": "active",
      "modelProvider": "GEMINI",
      "modelName": "gemini-3-flash-preview",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents?page=1&limit=20" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Create Agent

POST/workspaces/{wsId}/agents

Creates a new agent in the workspace. The agent is not deployed until you call the deploy endpoint.

Request Body

Name	Type	Required	Description
name	string	required	Agent display name. 1-255 characters.
slug	string	optional	URL-friendly identifier. Auto-generated from name if omitted.
description	string	optional	Short description of what the agent does.
templateId	UUID	optional	Optionally create the agent from an existing template.
soul	string	optional	Personality / system prompt content for the agent.
modelProvider	string	optional	Model provider: GEMINI \| OPENAI. Default: GEMINI.
modelName	string	optional	Model identifier. Default: "gemini-3-flash-preview".
tools	array	optional	List of tool names to enable for the agent.
cronJobs	array	optional	Scheduled cron job configurations for the agent.
knowledgeConfig	object	optional	Knowledge base configuration (vector store settings).
cpuLimitMillicores	integer	optional	CPU limit in millicores. Range: 100-4000.
memoryLimitMi	integer	optional	Memory limit in MiB. Range: 128-4096.

Response

json

{
  "id": "agt_01hx...",
  "slug": "support-agent",
  "name": "Support Agent",
  "description": "Handles customer support queries",
  "status": "inactive",
  "modelProvider": "GEMINI",
  "modelName": "gemini-3-flash-preview",
  "soul": "You are a helpful and friendly support agent.",
  "tools": ["web_search"],
  "cpuLimitMillicores": 500,
  "memoryLimitMi": 512,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents" \
  -H "Authorization: Bearer dor_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "slug": "support-agent",
    "description": "Handles customer support queries",
    "modelProvider": "GEMINI",
    "modelName": "gemini-3-flash-preview",
    "soul": "You are a helpful and friendly support agent.",
    "tools": ["web_search"],
    "cpuLimitMillicores": 500,
    "memoryLimitMi": 512
  }'

Get Agent

GET/workspaces/{wsId}/agents/{agentId}

Retrieves full details for a single agent. The agentId path parameter accepts either the agent UUID or its slug.

Response

json

{
  "id": "agt_01hx...",
  "slug": "support-agent",
  "name": "Support Agent",
  "description": "Handles customer support queries",
  "status": "active",
  "modelProvider": "GEMINI",
  "modelName": "gemini-3-flash-preview",
  "soul": "You are a helpful and friendly support agent.",
  "tools": ["web_search"],
  "cronJobs": [],
  "knowledgeConfig": null,
  "channels": {},
  "cpuLimitMillicores": 500,
  "memoryLimitMi": 512,
  "composioEntityId": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T14:30:00Z"
}

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Update Agent

PATCH/workspaces/{wsId}/agents/{agentId}

Partially updates an agent. All fields are optional - only provided fields are updated.

Request Body

Name	Type	Required	Description
name	string	optional	New display name. 1-255 characters.
slug	string	optional	New URL-friendly identifier.
description	string	optional	Updated description.
soul	string	optional	Updated personality / system prompt.
modelProvider	string	optional	Model provider: GEMINI \| OPENAI.
modelName	string	optional	Model identifier.
tools	array	optional	Updated list of tool names.
cronJobs	array	optional	Updated cron job configurations.
knowledgeConfig	object	optional	Updated knowledge base configuration.
status	string	optional	Agent status: active \| inactive \| stopped.
channels	object	optional	Channel integrations configuration (Slack, WhatsApp, etc.).
composioEntityId	string	optional	Composio entity ID for tool integrations.
cpuLimitMillicores	integer	optional	CPU limit in millicores. Range: 100-4000.
memoryLimitMi	integer	optional	Memory limit in MiB. Range: 128-4096.

bash

curl -X PATCH "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}" \
  -H "Authorization: Bearer dor_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"soul": "You are a concise and direct support agent.", "modelName": "gemini-3-flash-preview"}'

Delete Agent

DELETE/workspaces/{wsId}/agents/{agentId}

Soft-deletes an agent - the running container is stopped and the agent is marked as deleted. The agent record is retained for audit purposes.

DELETE/workspaces/{wsId}/agents/{agentId}/permanent

Permanently deletes an agent and all its data including sessions, messages, and knowledge base entries. This action cannot be undone.

Warning: Permanent deletion removes all agent data including conversation history and knowledge base content. Use soft-delete unless you need to fully purge the agent.

bash

# Soft delete (recommended)
curl -X DELETE "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}" \
  -H "Authorization: Bearer dor_sk_your_key_here"

# Permanent delete
curl -X DELETE "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/permanent" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Deploy Agent

POST/workspaces/{wsId}/agents/{agentId}/deploy

Deploys the agent as a container on the Dooor OS runtime. The agent status transitions to deploying and then to active once ready.

Response

json

{
  "agentId": "agt_01hx...",
  "deploymentId": "dep_01hx...",
  "status": "deploying",
  "message": "Agent deployment started",
  "estimatedReadyAt": "2025-01-15T10:02:00Z"
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/deploy" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Stop Agent

POST/workspaces/{wsId}/agents/{agentId}/stop

Stops a running agent. The container is terminated and the agent status is set to stopped.

Response

json

{
  "id": "agt_01hx...",
  "status": "stopped",
  "stoppedAt": "2025-01-15T11:00:00Z"
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/stop" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Restart Agent

POST/workspaces/{wsId}/agents/{agentId}/restart

Restarts a stopped or failed agent. Equivalent to stop followed by deploy, but preserves the existing configuration and sessions.

Response

json

{
  "id": "agt_01hx...",
  "status": "deploying",
  "restartedAt": "2025-01-15T11:05:00Z"
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/restart" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Chat with Agent

POST/workspaces/{wsId}/agents/{agentId}/run

Sends a prompt to an active agent and returns its response. Pass a sessionId to continue an existing conversation. Omit it to start a new session. Authentication uses an API key (Bearer token).

Auth: This endpoint accepts API keys (dor_sk_...) in the Authorization: Bearer header. The agent must be in active status before accepting requests.

Request Body

Name	Type	Required	Description
prompt	string	required	The user message to send to the agent.
sessionId	UUID	optional	Session UUID to continue a multi-turn conversation. Omit to start a new session.

Response

json

{
  "response": "Hello! I'm here to help. Could you provide your order number?",
  "sessionId": "sess_01hx...",
  "agentId": "agt_01hx..."
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/run" \
  -H "Authorization: Bearer dor_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello, I need help with my order.",
    "sessionId": "sess_01hx..."
  }'

Agent Stats

GET/workspaces/{wsId}/agents/stats

Returns aggregate counts for agents in the workspace, broken down by status.

Response

json

{
  "total": 8,
  "running": 5,
  "stopped": 2,
  "deploying": 0,
  "failed": 1
}

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/stats" \
  -H "Authorization: Bearer dor_sk_your_key_here"

List Templates

GET/workspaces/{wsId}/agents/templates

Returns the list of available agent templates. Templates provide pre-configured souls, tools, and resource limits for common agent archetypes.

Response

json

[
  {
    "id": "tpl_01hx...",
    "name": "Customer Support",
    "description": "Handles inbound support queries with escalation logic",
    "modelProvider": "GEMINI",
    "modelName": "gemini-3-flash-preview",
    "tools": ["web_search", "knowledge_base"],
    "cpuLimitMillicores": 500,
    "memoryLimitMi": 512
  }
]

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/templates" \
  -H "Authorization: Bearer dor_sk_your_key_here"

List Sessions

GET/workspaces/{wsId}/agents/{agentId}/sessions

Returns all conversation sessions for a given agent. Each session groups a sequence of messages from a single user interaction.

Response

json

[
  {
    "id": "sess_01hx...",
    "agentId": "agt_01hx...",
    "messageCount": 6,
    "createdAt": "2025-01-20T09:00:00Z",
    "lastMessageAt": "2025-01-20T09:05:30Z"
  }
]

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/sessions" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Get Session Messages

GET/workspaces/{wsId}/agents/sessions/{sessionId}/messages

Returns the full message history for a specific session, ordered by creation time ascending.

Response

json

[
  {
    "id": "msg_01hx...",
    "sessionId": "sess_01hx...",
    "role": "user",
    "content": "Hello, I need help with my order.",
    "createdAt": "2025-01-20T09:00:00Z"
  },
  {
    "id": "msg_02hx...",
    "sessionId": "sess_01hx...",
    "role": "assistant",
    "content": "Hello! I'm here to help. Could you provide your order number?",
    "createdAt": "2025-01-20T09:00:01Z"
  }
]

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/sessions/{sessionId}/messages" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Agents

List Agents

GET/workspaces/{wsId}/agents

Returns a paginated list of agents in the workspace.

Query Parameters

Name	Type	Required	Description
page	integer	optional	Page number starting at 1. Default: 1
limit	integer	optional	Items per page. Default: 20, max: 100
status	string	optional	Filter by status: active \| inactive \| deploying \| failed \| stopped
search	string	optional	Full-text search on name and description

Response

json

{
  "data": [
    {
      "id": "agt_01hx...",
      "slug": "support-agent",
      "name": "Support Agent",
      "status": "active",
      "modelProvider": "GEMINI",
      "modelName": "gemini-3-flash-preview",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents?page=1&limit=20" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Create Agent

POST/workspaces/{wsId}/agents

Creates a new agent in the workspace. The agent is not deployed until you call the deploy endpoint.

Request Body

Name	Type	Required	Description
name	string	required	Agent display name. 1-255 characters.
slug	string	optional	URL-friendly identifier. Auto-generated from name if omitted.
description	string	optional	Short description of what the agent does.
templateId	UUID	optional	Optionally create the agent from an existing template.
soul	string	optional	Personality / system prompt content for the agent.
modelProvider	string	optional	Model provider: GEMINI \| OPENAI. Default: GEMINI.
modelName	string	optional	Model identifier. Default: "gemini-3-flash-preview".
tools	array	optional	List of tool names to enable for the agent.
cronJobs	array	optional	Scheduled cron job configurations for the agent.
knowledgeConfig	object	optional	Knowledge base configuration (vector store settings).
cpuLimitMillicores	integer	optional	CPU limit in millicores. Range: 100-4000.
memoryLimitMi	integer	optional	Memory limit in MiB. Range: 128-4096.

Response

json

{
  "id": "agt_01hx...",
  "slug": "support-agent",
  "name": "Support Agent",
  "description": "Handles customer support queries",
  "status": "inactive",
  "modelProvider": "GEMINI",
  "modelName": "gemini-3-flash-preview",
  "soul": "You are a helpful and friendly support agent.",
  "tools": ["web_search"],
  "cpuLimitMillicores": 500,
  "memoryLimitMi": 512,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents" \
  -H "Authorization: Bearer dor_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "slug": "support-agent",
    "description": "Handles customer support queries",
    "modelProvider": "GEMINI",
    "modelName": "gemini-3-flash-preview",
    "soul": "You are a helpful and friendly support agent.",
    "tools": ["web_search"],
    "cpuLimitMillicores": 500,
    "memoryLimitMi": 512
  }'

Get Agent

GET/workspaces/{wsId}/agents/{agentId}

Retrieves full details for a single agent. The agentId path parameter accepts either the agent UUID or its slug.

Response

json

{
  "id": "agt_01hx...",
  "slug": "support-agent",
  "name": "Support Agent",
  "description": "Handles customer support queries",
  "status": "active",
  "modelProvider": "GEMINI",
  "modelName": "gemini-3-flash-preview",
  "soul": "You are a helpful and friendly support agent.",
  "tools": ["web_search"],
  "cronJobs": [],
  "knowledgeConfig": null,
  "channels": {},
  "cpuLimitMillicores": 500,
  "memoryLimitMi": 512,
  "composioEntityId": null,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T14:30:00Z"
}

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Update Agent

PATCH/workspaces/{wsId}/agents/{agentId}

Partially updates an agent. All fields are optional - only provided fields are updated.

Request Body

Name	Type	Required	Description
name	string	optional	New display name. 1-255 characters.
slug	string	optional	New URL-friendly identifier.
description	string	optional	Updated description.
soul	string	optional	Updated personality / system prompt.
modelProvider	string	optional	Model provider: GEMINI \| OPENAI.
modelName	string	optional	Model identifier.
tools	array	optional	Updated list of tool names.
cronJobs	array	optional	Updated cron job configurations.
knowledgeConfig	object	optional	Updated knowledge base configuration.
status	string	optional	Agent status: active \| inactive \| stopped.
channels	object	optional	Channel integrations configuration (Slack, WhatsApp, etc.).
composioEntityId	string	optional	Composio entity ID for tool integrations.
cpuLimitMillicores	integer	optional	CPU limit in millicores. Range: 100-4000.
memoryLimitMi	integer	optional	Memory limit in MiB. Range: 128-4096.

bash

curl -X PATCH "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}" \
  -H "Authorization: Bearer dor_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"soul": "You are a concise and direct support agent.", "modelName": "gemini-3-flash-preview"}'

Delete Agent

DELETE/workspaces/{wsId}/agents/{agentId}

Soft-deletes an agent - the running container is stopped and the agent is marked as deleted. The agent record is retained for audit purposes.

DELETE/workspaces/{wsId}/agents/{agentId}/permanent

Permanently deletes an agent and all its data including sessions, messages, and knowledge base entries. This action cannot be undone.

Warning: Permanent deletion removes all agent data including conversation history and knowledge base content. Use soft-delete unless you need to fully purge the agent.

bash

# Soft delete (recommended)
curl -X DELETE "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}" \
  -H "Authorization: Bearer dor_sk_your_key_here"

# Permanent delete
curl -X DELETE "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/permanent" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Deploy Agent

POST/workspaces/{wsId}/agents/{agentId}/deploy

Deploys the agent as a container on the Dooor OS runtime. The agent status transitions to deploying and then to active once ready.

Response

json

{
  "agentId": "agt_01hx...",
  "deploymentId": "dep_01hx...",
  "status": "deploying",
  "message": "Agent deployment started",
  "estimatedReadyAt": "2025-01-15T10:02:00Z"
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/deploy" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Stop Agent

POST/workspaces/{wsId}/agents/{agentId}/stop

Stops a running agent. The container is terminated and the agent status is set to stopped.

Response

json

{
  "id": "agt_01hx...",
  "status": "stopped",
  "stoppedAt": "2025-01-15T11:00:00Z"
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/stop" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Restart Agent

POST/workspaces/{wsId}/agents/{agentId}/restart

Restarts a stopped or failed agent. Equivalent to stop followed by deploy, but preserves the existing configuration and sessions.

Response

json

{
  "id": "agt_01hx...",
  "status": "deploying",
  "restartedAt": "2025-01-15T11:05:00Z"
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/restart" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Chat with Agent

POST/workspaces/{wsId}/agents/{agentId}/run

Sends a prompt to an active agent and returns its response. Pass a sessionId to continue an existing conversation. Omit it to start a new session. Authentication uses an API key (Bearer token).

Auth: This endpoint accepts API keys (dor_sk_...) in the Authorization: Bearer header. The agent must be in active status before accepting requests.

Request Body

Name	Type	Required	Description
prompt	string	required	The user message to send to the agent.
sessionId	UUID	optional	Session UUID to continue a multi-turn conversation. Omit to start a new session.

Response

json

{
  "response": "Hello! I'm here to help. Could you provide your order number?",
  "sessionId": "sess_01hx...",
  "agentId": "agt_01hx..."
}

bash

curl -X POST "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/run" \
  -H "Authorization: Bearer dor_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Hello, I need help with my order.",
    "sessionId": "sess_01hx..."
  }'

Agent Stats

GET/workspaces/{wsId}/agents/stats

Returns aggregate counts for agents in the workspace, broken down by status.

Response

json

{
  "total": 8,
  "running": 5,
  "stopped": 2,
  "deploying": 0,
  "failed": 1
}

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/stats" \
  -H "Authorization: Bearer dor_sk_your_key_here"

List Templates

GET/workspaces/{wsId}/agents/templates

Returns the list of available agent templates. Templates provide pre-configured souls, tools, and resource limits for common agent archetypes.

Response

json

[
  {
    "id": "tpl_01hx...",
    "name": "Customer Support",
    "description": "Handles inbound support queries with escalation logic",
    "modelProvider": "GEMINI",
    "modelName": "gemini-3-flash-preview",
    "tools": ["web_search", "knowledge_base"],
    "cpuLimitMillicores": 500,
    "memoryLimitMi": 512
  }
]

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/templates" \
  -H "Authorization: Bearer dor_sk_your_key_here"

List Sessions

GET/workspaces/{wsId}/agents/{agentId}/sessions

Returns all conversation sessions for a given agent. Each session groups a sequence of messages from a single user interaction.

Response

json

[
  {
    "id": "sess_01hx...",
    "agentId": "agt_01hx...",
    "messageCount": 6,
    "createdAt": "2025-01-20T09:00:00Z",
    "lastMessageAt": "2025-01-20T09:05:30Z"
  }
]

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/{agentId}/sessions" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Get Session Messages

GET/workspaces/{wsId}/agents/sessions/{sessionId}/messages

Returns the full message history for a specific session, ordered by creation time ascending.

Response

json

[
  {
    "id": "msg_01hx...",
    "sessionId": "sess_01hx...",
    "role": "user",
    "content": "Hello, I need help with my order.",
    "createdAt": "2025-01-20T09:00:00Z"
  },
  {
    "id": "msg_02hx...",
    "sessionId": "sess_01hx...",
    "role": "assistant",
    "content": "Hello! I'm here to help. Could you provide your order number?",
    "createdAt": "2025-01-20T09:00:01Z"
  }
]

bash

curl -X GET "https://os-develop.dooor.ai/api/v1/workspaces/{wsId}/agents/sessions/{sessionId}/messages" \
  -H "Authorization: Bearer dor_sk_your_key_here"

Agents#

List Agents#

Query Parameters

Response

Create Agent#

Request Body

Response

Get Agent#

Response

Update Agent#

Request Body

Delete Agent#

Deploy Agent#

Response

Stop Agent#

Response

Restart Agent#

Response

Chat with Agent#

Request Body

Response

Agent Stats#

Response

List Templates#

Response

List Sessions#

Response

Get Session Messages#

Response

Agents#

List Agents#

Query Parameters

Response

Create Agent#

Request Body

Response

Get Agent#

Response

Update Agent#

Request Body

Delete Agent#

Deploy Agent#

Response

Stop Agent#

Response

Restart Agent#

Response

Chat with Agent#

Request Body

Response

Agent Stats#

Response

List Templates#

Response

List Sessions#

Response

Get Session Messages#

Response

Agents

List Agents

Create Agent

Get Agent

Update Agent

Delete Agent

Deploy Agent

Stop Agent

Restart Agent

Chat with Agent

Agent Stats

List Templates

List Sessions

Get Session Messages

Agents

List Agents

Create Agent

Get Agent

Update Agent

Delete Agent

Deploy Agent

Stop Agent

Restart Agent

Chat with Agent

Agent Stats

List Templates

List Sessions

Get Session Messages