Skip to main contentPOST
GET
GET
GET
GET
GET
GET
POST
GET
PUT
PATCH
DELETE
GET
PUT
GET
POST
PATCH
GET
GET
POST
POST
PATCH
GET
GET
POST
GET
PUT
PATCH
DELETE
GET
GET
POST
GET
PUT
PATCH
DELETE
GET
POST
POST
GET
DELETE
POST
GET
GET
POST
GET
PATCH
DELETE
GET
GET
GET
POST
POST
GET
POST
GET
POST
GET
GET
DELETE
POST
GET
GET
POST
GET
POST
GET
PUT
PATCH
DELETE
GET
POST
POST
GET
POST
POST
POST
POST
POST
GET
GET
POST
POST
DELETE
POST
PUT
POST
GET
GET
GET
POST
POST
DELETE
PUT
GET
GET
POST
DELETE
PATCH
PATCH
PATCH
POST
POST
PATCH
GET
POST
GET
PUT
PATCH
DELETE
GET
PUT
PATCH
DELETE
GET
POST
GET
GET
DELETE
GET
GET
PUT
PATCH
DELETE
GET
GET
POST
GET
POST
PATCH
DELETE
AIP
API reference
Explore AIP public API authentication, Agent conversations, and business resource endpoints.
OpenAPI JSON
AIP Public API uses keys created in the workbench. Single-Agent conversation keys call /agent/* using the saved Agent configuration; Profile API keys access resources belonging to the current business identity according to their permissions. Start with the API quickstart and read conversation events and SSE for result handling.
The definitions below come from the Backplane OpenAPI snapshot and group parameters, request bodies, and responses by resource.
131 public endpoints are included in this snapshot. Parameters, responses, and authentication come directly from OpenAPI JSON; endpoint descriptions retain the source language.
Download OpenAPI JSON · View upstream OpenAPI JSON
Snapshot date: 2026-10-16 · Format: Swagger / OpenAPI 2.0 · Base URL: https://backend.hast.so/api/public/v1.
The download contains AIP public endpoints and their referenced models. Import it into API tools supporting Swagger 2.0. The upstream specification also includes other services.
Authentication
Authenticate with an API key created in AIP. Single-Agent keys use /agent/*; Profile keys require the permissions for each resource. Use Authorization: Bearer hast_pk_... and keep the key on your server.
JSON
{
"description": "Personal API key as `Bearer hast_pk_*` for `/api/public/v1`.",
"in": "header",
"name": "Authorization",
"type": "apiKey"
}Agent conversations
POST /api/public/v1/agent/promptsSend a message to the key's bound Agent
Omit session_id to create a conversation; include it to continue. request_id makes retries idempotent. Only the saved Agent configuration is used. A 202 response is accepted, not completed; poll conversation events for the returned request_id.
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Conversation message",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"prompt": {
"maxLength": 65536,
"type": "string"
},
"request_id": {
"maxLength": 128,
"type": "string"
},
"session_id": {
"maxLength": 128,
"type": "string"
}
},
"required": [
"prompt"
],
"type": "object"
}
}Responses
202 Accepted
JSON
{
"properties": {
"after_event_id": {
"type": "integer"
},
"event_url": {
"type": "string"
},
"request_id": {
"type": "string"
},
"run_id": {
"type": "string"
},
"session_id": {
"type": "string"
}
},
"type": "object"
}GET /api/public/v1/agent/sessionsList the bound Agent's conversations
Includes historical conversations belonging to this Agent only. Session IDs can be used with the conversation events tool.
Request format: No request body format specified; Response format: application/json.
Parameters
limit · query · Optional
JSON
{
"description": "Page size (1-100)",
"in": "query",
"name": "limit",
"type": "integer"
}cursor · query · Optional
JSON
{
"description": "Next cursor from the previous page",
"in": "query",
"name": "cursor",
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": "string"
},
"sessions": {
"items": {
"properties": {
"canceled_at": {
"type": "string"
},
"completed_at": {
"type": "string"
},
"created_at": {
"type": "string"
},
"event_cursor": {
"type": "integer"
},
"failed_at": {
"type": "string"
},
"mode": {
"type": "string"
},
"runtime_provider": {
"type": "string"
},
"session_id": {
"type": "string"
},
"status": {
"type": "string"
},
"task_origin": {
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"model": {
"type": "string"
},
"output_tokens": {
"type": "integer"
},
"pricing": {
"properties": {
"cache_read_usd_per_token": {
"type": "string"
},
"cache_write_usd_per_token": {
"type": "string"
},
"input_usd_per_token": {
"type": "string"
},
"output_usd_per_token": {
"type": "string"
}
},
"type": "object"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}GET /api/public/v1/agent/sessions/{session_id}/eventsRead the bound Agent's conversation messages and status
Returns user/assistant messages and run lifecycle events, without configuration or tool traces. Poll using next_after until the matching run_id completes, fails or is interrupted. An empty filtered page may still have has_more=true.
Request format: No request body format specified; Response format: application/json.
Parameters
session_id · path · Required
JSON
{
"description": "Conversation ID",
"in": "path",
"name": "session_id",
"required": true,
"type": "string"
}after · query · Optional
JSON
{
"description": "Last consumed sequence",
"in": "query",
"name": "after",
"type": "integer"
}limit · query · Optional
JSON
{
"description": "Page size (1-200)",
"in": "query",
"name": "limit",
"type": "integer"
}Responses
200 OK
JSON
{
"properties": {
"events": {
"items": {
"discriminator": "type",
"properties": {
"created_at": {
"example": "2026-08-16T12:00:00Z",
"format": "date-time",
"type": "string"
},
"data": {
"allOf": [
{
"properties": {
"attempt": {
"minimum": 1,
"type": "integer"
},
"attempts": {
"minimum": 1,
"type": "integer"
},
"channel": {
"enum": [
"stdout",
"stderr",
"progress"
],
"type": "string"
},
"code": {
"type": "string"
},
"context_window": {
"minimum": 0,
"type": "integer"
},
"cost": {},
"delta": {
"type": "string"
},
"duration_ms": {
"minimum": 0,
"type": "integer"
},
"error": {
"type": "string"
},
"exit_code": {
"type": "integer"
},
"files": {
"items": {
"type": "string"
},
"type": "array"
},
"final_message_id": {
"type": "string"
},
"finish_reason": {
"type": "string"
},
"input": {},
"is_error": {
"type": "boolean"
},
"kind": {
"type": "string"
},
"last": {
"properties": {
"cache_read_tokens": {
"minimum": 0,
"type": "integer"
},
"cache_write_tokens": {
"minimum": 0,
"type": "integer"
},
"input_tokens": {
"minimum": 0,
"type": "integer"
},
"output_tokens": {
"minimum": 0,
"type": "integer"
},
"reasoning_tokens": {
"minimum": 0,
"type": "integer"
},
"total_tokens": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"cache_read_tokens",
"cache_write_tokens",
"input_tokens",
"output_tokens",
"reasoning_tokens",
"total_tokens"
],
"type": "object"
},
"message": {
"type": "string"
},
"message_id": {
"type": "string"
},
"model": {
"type": "string"
},
"model_config": {
"properties": {
"model": {
"type": "string"
},
"model_source": {
"enum": [
"hast",
"codex_account"
],
"type": "string"
},
"reasoning_effort": {
"type": "string"
}
},
"type": "object"
},
"model_source": {
"type": "string"
},
"modified_at": {
"format": "date-time",
"type": "string"
},
"name": {
"type": "string"
},
"operation": {
"enum": [
"update",
"delete"
],
"type": "string"
},
"options": {
"items": {},
"type": "array"
},
"output": {},
"parent_tool_call_id": {
"type": "string"
},
"path": {
"type": "string"
},
"plan_id": {
"type": "string"
},
"prompt": {
"type": "string"
},
"reason": {
"type": "string"
},
"reasoning_id": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"role": {
"enum": [
"user",
"assistant",
"system"
],
"type": "string"
},
"scope": {
"type": "string"
},
"size_bytes": {
"minimum": 0,
"type": "integer"
},
"status": {
"enum": [
"starting",
"ready",
"failed",
"released",
"succeeded",
"interrupted"
],
"type": "string"
},
"steps": {
"items": {
"properties": {
"status": {
"enum": [
"pending",
"in_progress",
"completed"
],
"example": "in_progress",
"type": "string"
},
"step": {
"type": "string"
}
},
"required": [
"status",
"step"
],
"type": "object"
},
"type": "array"
},
"text": {
"type": "string"
},
"tokens_after": {
"minimum": 0,
"type": "integer"
},
"tokens_before": {
"minimum": 0,
"type": "integer"
},
"tool_call_id": {
"type": "string"
},
"total": {
"properties": {
"cache_read_tokens": {
"minimum": 0,
"type": "integer"
},
"cache_write_tokens": {
"minimum": 0,
"type": "integer"
},
"input_tokens": {
"minimum": 0,
"type": "integer"
},
"output_tokens": {
"minimum": 0,
"type": "integer"
},
"reasoning_tokens": {
"minimum": 0,
"type": "integer"
},
"total_tokens": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"cache_read_tokens",
"cache_write_tokens",
"input_tokens",
"output_tokens",
"reasoning_tokens",
"total_tokens"
],
"type": "object"
},
"turn_type": {
"type": "string"
}
},
"type": "object"
}
],
"description": "Data is the HAST-owned payload union; Type selects its required shape as\ndefined in docs/reference/task-agent-event-v2.md."
},
"engine": {
"enum": [
"codex_cli",
"pi_agent_cli"
],
"example": "codex_cli",
"type": "string"
},
"event_id": {
"example": "evt_123",
"type": "string"
},
"replayable": {
"example": true,
"type": "boolean"
},
"run_id": {
"example": "run_123",
"type": "string"
},
"schema_version": {
"enum": [
2
],
"example": 2,
"type": "integer"
},
"sequence": {
"description": "Sequence is a positive durable order, or null for volatile events.",
"example": 42,
"minimum": 1,
"type": "integer",
"x-nullable": true
},
"session_id": {
"example": "session_123",
"type": "string"
},
"source": {
"enum": [
"runtime",
"backplane",
"workspace"
],
"example": "runtime",
"type": "string"
},
"task_id": {
"example": "task_123",
"type": "string"
},
"type": {
"enum": [
"runtime.status",
"run.queued",
"run.started",
"run.retrying",
"run.completed",
"run.failed",
"run.interrupted",
"message.started",
"message.delta",
"message.completed",
"reasoning.started",
"reasoning.delta",
"reasoning.completed",
"tool.started",
"tool.updated",
"tool.completed",
"plan.updated",
"plan.completed",
"usage.updated",
"file.changed",
"input.requested",
"context.compacted",
"warning",
"error"
],
"example": "message.completed",
"type": "string"
}
},
"required": [
"created_at",
"data",
"engine",
"event_id",
"replayable",
"schema_version",
"sequence",
"source",
"task_id",
"type"
],
"type": "object"
},
"type": "array"
},
"has_more": {
"example": true,
"type": "boolean"
},
"next_after": {
"example": 42,
"format": "int64",
"type": "integer",
"x-nullable": true
}
},
"type": "object"
}Integration guides
GET /api/public/v1/guidesDiscover Agent-facing Hast AIP guides
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}GET /api/public/v1/guides/{topic}Read a detailed Hast AIP guide for Agents
Request format: No request body format specified; Response format: application/json.
Parameters
topic · path · Required
JSON
{
"description": "Topic from GET /guides",
"in": "path",
"name": "topic",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}Models
GET /api/public/v1/modelsList Task Agent Models
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}Agent configurations
GET /api/public/v1/webhooksList public Task Agent Webhooks
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"properties": {
"hooks": {
"items": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"created_at": {
"type": "string"
},
"created_by": {
"properties": {
"account_id": {
"type": "string"
},
"api_key_id": {
"type": "string"
},
"api_key_name": {
"type": "string"
},
"email": {
"type": "string"
},
"profile_id": {
"type": "string"
}
},
"type": "object"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"pagination": {
"additionalProperties": {},
"type": "object"
},
"policy_options": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}POST /api/public/v1/webhooksCreate a public Task Agent Webhook
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Webhook request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"http_request": {
"additionalProperties": {},
"type": "object"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"example": "hast/auto",
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"example": "medium",
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"example": "read_only",
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
},
"value": {
"example": "write-only",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"example": "active",
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"example": "Support Agent",
"type": "string"
}
},
"type": "object"
}
}Responses
201 Created
JSON
{
"properties": {
"hook": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"created_at": {
"type": "string"
},
"created_by": {
"properties": {
"account_id": {
"type": "string"
},
"api_key_id": {
"type": "string"
},
"api_key_name": {
"type": "string"
},
"email": {
"type": "string"
},
"profile_id": {
"type": "string"
}
},
"type": "object"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"policy_options": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}GET /api/public/v1/webhooks/{hook_id}Read a public Task Agent Webhook
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Webhook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"hook": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"created_at": {
"type": "string"
},
"created_by": {
"properties": {
"account_id": {
"type": "string"
},
"api_key_id": {
"type": "string"
},
"api_key_name": {
"type": "string"
},
"email": {
"type": "string"
},
"profile_id": {
"type": "string"
}
},
"type": "object"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"policy_options": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}PUT /api/public/v1/webhooks/{hook_id}Update a public Task Agent Webhook
Request format: application/json; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Webhook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Webhook request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"http_request": {
"additionalProperties": {},
"type": "object"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"example": "hast/auto",
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"example": "medium",
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"example": "read_only",
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
},
"value": {
"example": "write-only",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"example": "active",
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"example": "Support Agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"hook": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"created_at": {
"type": "string"
},
"created_by": {
"properties": {
"account_id": {
"type": "string"
},
"api_key_id": {
"type": "string"
},
"api_key_name": {
"type": "string"
},
"email": {
"type": "string"
},
"profile_id": {
"type": "string"
}
},
"type": "object"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"policy_options": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}PATCH /api/public/v1/webhooks/{hook_id}Update a public Task Agent Webhook
Request format: application/json; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Webhook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Webhook request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"http_request": {
"additionalProperties": {},
"type": "object"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"example": "hast/auto",
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"example": "medium",
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"example": "read_only",
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
},
"value": {
"example": "write-only",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"example": "active",
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"example": "Support Agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"hook": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"created_at": {
"type": "string"
},
"created_by": {
"properties": {
"account_id": {
"type": "string"
},
"api_key_id": {
"type": "string"
},
"api_key_name": {
"type": "string"
},
"email": {
"type": "string"
},
"profile_id": {
"type": "string"
}
},
"type": "object"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"policy_options": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}DELETE /api/public/v1/webhooks/{hook_id}Delete a public Task Agent Webhook
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Webhook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}Responses
204 No Content
GET /api/public/v1/webhooks/{hook_id}/channelsRead Webhook channels and final reply configuration
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Webhook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}Responses
PUT /api/public/v1/webhooks/{hook_id}/channelsReplace Webhook channels and final reply configuration
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Webhook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}body · body · Required
JSON
{
"description": "Bindings and final reply policy",
"in": "body",
"name": "body",
"required": true,
"schema": {
"properties": {
"connection_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"memory_project_ids": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
}Responses
GET /api/public/v1/webhooks/{hook_id}/emailRead an Agent email channel
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Agent ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"connection": {
"properties": {
"binding_version": {
"type": "integer"
},
"bound_hook_id": {
"type": "string"
},
"bound_hook_status": {
"type": "string"
},
"bound_hook_title": {
"type": "string"
},
"created_at": {
"type": "string"
},
"email_address": {
"type": "string"
},
"email_hook_id": {
"type": "string"
},
"id": {
"type": "string"
},
"inbox_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"platform": {
"type": "string"
},
"require_admission": {
"type": "boolean"
},
"retain_content": {
"type": "boolean"
},
"setup_required": {
"type": "boolean"
},
"status": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"email": {
"properties": {
"address": {
"type": "string"
},
"connection_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"hook_id": {
"type": "string"
},
"rules": {
"properties": {
"automatic_reply": {
"type": "boolean"
},
"mode": {
"type": "string"
},
"rules": {
"items": {
"properties": {
"body_keywords": {
"items": {
"type": "string"
},
"type": "array"
},
"domains": {
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"type": "string"
},
"senders": {
"items": {
"type": "string"
},
"type": "array"
},
"subject_keywords": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"rules_version": {
"type": "integer"
},
"source_id": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}POST /api/public/v1/webhooks/{hook_id}/emailPrepare an Agent email channel
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Agent ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"connection": {
"properties": {
"binding_version": {
"type": "integer"
},
"bound_hook_id": {
"type": "string"
},
"bound_hook_status": {
"type": "string"
},
"bound_hook_title": {
"type": "string"
},
"created_at": {
"type": "string"
},
"email_address": {
"type": "string"
},
"email_hook_id": {
"type": "string"
},
"id": {
"type": "string"
},
"inbox_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"platform": {
"type": "string"
},
"require_admission": {
"type": "boolean"
},
"retain_content": {
"type": "boolean"
},
"setup_required": {
"type": "boolean"
},
"status": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"email": {
"properties": {
"address": {
"type": "string"
},
"connection_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"hook_id": {
"type": "string"
},
"rules": {
"properties": {
"automatic_reply": {
"type": "boolean"
},
"mode": {
"type": "string"
},
"rules": {
"items": {
"properties": {
"body_keywords": {
"items": {
"type": "string"
},
"type": "array"
},
"domains": {
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"type": "string"
},
"senders": {
"items": {
"type": "string"
},
"type": "array"
},
"subject_keywords": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"rules_version": {
"type": "integer"
},
"source_id": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PATCH /api/public/v1/webhooks/{hook_id}/emailUpdate Agent email triggers
Request format: application/json; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Agent ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}body · body · Required
JSON
{
"description": "Rules and expected version",
"in": "body",
"name": "body",
"required": true,
"schema": {
"properties": {
"rules": {
"properties": {
"automatic_reply": {
"type": "boolean"
},
"mode": {
"type": "string"
},
"rules": {
"items": {
"properties": {
"body_keywords": {
"items": {
"type": "string"
},
"type": "array"
},
"domains": {
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"type": "string"
},
"senders": {
"items": {
"type": "string"
},
"type": "array"
},
"subject_keywords": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"rules_version": {
"type": "integer"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"connection": {
"properties": {
"binding_version": {
"type": "integer"
},
"bound_hook_id": {
"type": "string"
},
"bound_hook_status": {
"type": "string"
},
"bound_hook_title": {
"type": "string"
},
"created_at": {
"type": "string"
},
"email_address": {
"type": "string"
},
"email_hook_id": {
"type": "string"
},
"id": {
"type": "string"
},
"inbox_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"platform": {
"type": "string"
},
"require_admission": {
"type": "boolean"
},
"retain_content": {
"type": "boolean"
},
"setup_required": {
"type": "boolean"
},
"status": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"email": {
"properties": {
"address": {
"type": "string"
},
"connection_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"hook_id": {
"type": "string"
},
"rules": {
"properties": {
"automatic_reply": {
"type": "boolean"
},
"mode": {
"type": "string"
},
"rules": {
"items": {
"properties": {
"body_keywords": {
"items": {
"type": "string"
},
"type": "array"
},
"domains": {
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"type": "string"
},
"senders": {
"items": {
"type": "string"
},
"type": "array"
},
"subject_keywords": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"rules_version": {
"type": "integer"
},
"source_id": {
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}GET /api/public/v1/webhooks/{hook_id}/email/messagesList Agent email messages
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Agent ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}before · query · Optional
JSON
{
"description": "Message cursor",
"in": "query",
"name": "before",
"type": "integer"
}Responses
GET /api/public/v1/webhooks/{hook_id}/email/messages/{message_id}Read an Agent email message
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Agent ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}message_id · path · Required
JSON
{
"description": "Retained email ID",
"in": "path",
"name": "message_id",
"required": true,
"type": "integer"
}Responses
POST /api/public/v1/webhooks/{hook_id}/email/previewPreview email trigger matching
Request format: application/json; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Agent ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}body · body · Required
JSON
{
"description": "Retained message and proposed rules",
"in": "body",
"name": "body",
"required": true,
"schema": {
"properties": {
"message_id": {
"type": "integer"
},
"rules": {
"properties": {
"automatic_reply": {
"type": "boolean"
},
"mode": {
"type": "string"
},
"rules": {
"items": {
"properties": {
"body_keywords": {
"items": {
"type": "string"
},
"type": "array"
},
"domains": {
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"type": "string"
},
"senders": {
"items": {
"type": "string"
},
"type": "array"
},
"subject_keywords": {
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"reason": {
"type": "string"
},
"rule_id": {
"type": "string"
},
"wake": {
"type": "boolean"
}
},
"type": "object"
}POST /api/public/v1/webhooks/{hook_id}/invokeRun or continue a saved AIP Agent
action=created starts a session; prompted continues or stops it. Poll the session events endpoint for completion. A 202 response means accepted, not completed.
Request format: application/json; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Owned Agent Hook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Agent invocation",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"action": {
"enum": [
"created",
"prompted"
],
"type": "string"
},
"payload": {
"properties": {
"after_event_id": {
"type": "integer"
},
"context": {},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"model_config": {
"additionalProperties": {},
"type": "object"
},
"prompt": {
"type": "string"
},
"request_id": {
"type": "string"
},
"session_id": {
"type": "string"
},
"signal": {
"type": "string"
},
"system_prompt": {
"type": "string"
}
},
"type": "object"
}
},
"required": [
"action",
"payload"
],
"type": "object"
}
}Responses
202 Accepted
JSON
{
"properties": {
"after_event_id": {
"type": "integer"
},
"event_url": {
"type": "string"
},
"request_id": {
"type": "string"
},
"run_id": {
"type": "string"
},
"session_id": {
"type": "string"
}
},
"type": "object"
}PATCH /api/public/v1/webhooks/{hook_id}/memoryUpdate only the owned webhook's Memory settings
Request format: application/json; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Webhook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Memory settings; shared writes require webhook or all reads",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"hook": {
"properties": {
"communication_knowledge_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"created_at": {
"type": "string"
},
"created_by": {
"properties": {
"account_id": {
"type": "string"
},
"api_key_id": {
"type": "string"
},
"api_key_name": {
"type": "string"
},
"email": {
"type": "string"
},
"profile_id": {
"type": "string"
}
},
"type": "object"
},
"crm_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"description": {
"type": "string"
},
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"hook_id": {
"example": "hook_123",
"type": "string"
},
"knowledge_base_list": {
"items": {
"type": "string"
},
"type": "array"
},
"memory": {
"properties": {
"read_scope": {
"enum": [
"self",
"webhook",
"all"
],
"example": "self",
"type": "string"
},
"write_scope": {
"enum": [
"self",
"shared"
],
"example": "self",
"type": "string"
}
},
"type": "object"
},
"model": {
"type": "string"
},
"model_source": {
"type": "string"
},
"policies": {
"items": {
"type": "string"
},
"type": "array"
},
"reasoning_effort": {
"type": "string"
},
"runtime_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"sandbox_mode": {
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"secrets": {
"items": {
"properties": {
"name": {
"example": "CRM_TOKEN",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"selected_skills": {
"items": {
"properties": {
"enabled": {
"type": "boolean"
},
"skill_id": {
"example": "usr_123",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"status": {
"type": "string"
},
"system_prompt": {
"type": "string"
},
"title": {
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"output_tokens": {
"type": "integer"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"policy_options": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}400 Bad Request
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}404 Not Found
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}GET /api/public/v1/webhooks/{hook_id}/sessions/{session_id}/eventsRead an AIP Agent session's events
Poll with the returned next_after cursor until run.completed, run.failed or run.interrupted. Match the requested request_id. Reads remain scoped to the key's Profile and selected Agent.
Request format: No request body format specified; Response format: application/json.
Parameters
hook_id · path · Required
JSON
{
"description": "Owned Agent Hook ID",
"in": "path",
"name": "hook_id",
"required": true,
"type": "string"
}session_id · path · Required
JSON
{
"description": "Session ID returned by invoke",
"in": "path",
"name": "session_id",
"required": true,
"type": "string"
}after · query · Optional
JSON
{
"description": "Last consumed event sequence",
"in": "query",
"name": "after",
"type": "integer"
}limit · query · Optional
JSON
{
"description": "Page size (max 200)",
"in": "query",
"name": "limit",
"type": "integer"
}Responses
200 OK
JSON
{
"properties": {
"events": {
"items": {
"discriminator": "type",
"properties": {
"created_at": {
"example": "2026-08-16T12:00:00Z",
"format": "date-time",
"type": "string"
},
"data": {
"allOf": [
{
"properties": {
"attempt": {
"minimum": 1,
"type": "integer"
},
"attempts": {
"minimum": 1,
"type": "integer"
},
"channel": {
"enum": [
"stdout",
"stderr",
"progress"
],
"type": "string"
},
"code": {
"type": "string"
},
"context_window": {
"minimum": 0,
"type": "integer"
},
"cost": {},
"delta": {
"type": "string"
},
"duration_ms": {
"minimum": 0,
"type": "integer"
},
"error": {
"type": "string"
},
"exit_code": {
"type": "integer"
},
"files": {
"items": {
"type": "string"
},
"type": "array"
},
"final_message_id": {
"type": "string"
},
"finish_reason": {
"type": "string"
},
"input": {},
"is_error": {
"type": "boolean"
},
"kind": {
"type": "string"
},
"last": {
"properties": {
"cache_read_tokens": {
"minimum": 0,
"type": "integer"
},
"cache_write_tokens": {
"minimum": 0,
"type": "integer"
},
"input_tokens": {
"minimum": 0,
"type": "integer"
},
"output_tokens": {
"minimum": 0,
"type": "integer"
},
"reasoning_tokens": {
"minimum": 0,
"type": "integer"
},
"total_tokens": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"cache_read_tokens",
"cache_write_tokens",
"input_tokens",
"output_tokens",
"reasoning_tokens",
"total_tokens"
],
"type": "object"
},
"message": {
"type": "string"
},
"message_id": {
"type": "string"
},
"model": {
"type": "string"
},
"model_config": {
"properties": {
"model": {
"type": "string"
},
"model_source": {
"enum": [
"hast",
"codex_account"
],
"type": "string"
},
"reasoning_effort": {
"type": "string"
}
},
"type": "object"
},
"model_source": {
"type": "string"
},
"modified_at": {
"format": "date-time",
"type": "string"
},
"name": {
"type": "string"
},
"operation": {
"enum": [
"update",
"delete"
],
"type": "string"
},
"options": {
"items": {},
"type": "array"
},
"output": {},
"parent_tool_call_id": {
"type": "string"
},
"path": {
"type": "string"
},
"plan_id": {
"type": "string"
},
"prompt": {
"type": "string"
},
"reason": {
"type": "string"
},
"reasoning_id": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"role": {
"enum": [
"user",
"assistant",
"system"
],
"type": "string"
},
"scope": {
"type": "string"
},
"size_bytes": {
"minimum": 0,
"type": "integer"
},
"status": {
"enum": [
"starting",
"ready",
"failed",
"released",
"succeeded",
"interrupted"
],
"type": "string"
},
"steps": {
"items": {
"properties": {
"status": {
"enum": [
"pending",
"in_progress",
"completed"
],
"example": "in_progress",
"type": "string"
},
"step": {
"type": "string"
}
},
"required": [
"status",
"step"
],
"type": "object"
},
"type": "array"
},
"text": {
"type": "string"
},
"tokens_after": {
"minimum": 0,
"type": "integer"
},
"tokens_before": {
"minimum": 0,
"type": "integer"
},
"tool_call_id": {
"type": "string"
},
"total": {
"properties": {
"cache_read_tokens": {
"minimum": 0,
"type": "integer"
},
"cache_write_tokens": {
"minimum": 0,
"type": "integer"
},
"input_tokens": {
"minimum": 0,
"type": "integer"
},
"output_tokens": {
"minimum": 0,
"type": "integer"
},
"reasoning_tokens": {
"minimum": 0,
"type": "integer"
},
"total_tokens": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"cache_read_tokens",
"cache_write_tokens",
"input_tokens",
"output_tokens",
"reasoning_tokens",
"total_tokens"
],
"type": "object"
},
"turn_type": {
"type": "string"
}
},
"type": "object"
}
],
"description": "Data is the HAST-owned payload union; Type selects its required shape as\ndefined in docs/reference/task-agent-event-v2.md."
},
"engine": {
"enum": [
"codex_cli",
"pi_agent_cli"
],
"example": "codex_cli",
"type": "string"
},
"event_id": {
"example": "evt_123",
"type": "string"
},
"replayable": {
"example": true,
"type": "boolean"
},
"run_id": {
"example": "run_123",
"type": "string"
},
"schema_version": {
"enum": [
2
],
"example": 2,
"type": "integer"
},
"sequence": {
"description": "Sequence is a positive durable order, or null for volatile events.",
"example": 42,
"minimum": 1,
"type": "integer",
"x-nullable": true
},
"session_id": {
"example": "session_123",
"type": "string"
},
"source": {
"enum": [
"runtime",
"backplane",
"workspace"
],
"example": "runtime",
"type": "string"
},
"task_id": {
"example": "task_123",
"type": "string"
},
"type": {
"enum": [
"runtime.status",
"run.queued",
"run.started",
"run.retrying",
"run.completed",
"run.failed",
"run.interrupted",
"message.started",
"message.delta",
"message.completed",
"reasoning.started",
"reasoning.delta",
"reasoning.completed",
"tool.started",
"tool.updated",
"tool.completed",
"plan.updated",
"plan.completed",
"usage.updated",
"file.changed",
"input.requested",
"context.compacted",
"warning",
"error"
],
"example": "message.completed",
"type": "string"
}
},
"required": [
"created_at",
"data",
"engine",
"event_id",
"replayable",
"schema_version",
"sequence",
"source",
"task_id",
"type"
],
"type": "object"
},
"type": "array"
},
"has_more": {
"example": true,
"type": "boolean"
},
"next_after": {
"example": 42,
"format": "int64",
"type": "integer",
"x-nullable": true
}
},
"type": "object"
}Schedules
GET /api/public/v1/schedulesList Task Agent schedules
Request format: No request body format specified; Response format: application/json.
Parameters
limit · query · Optional
JSON
{
"description": "Schedule page size",
"in": "query",
"name": "limit",
"type": "integer"
}Responses
200 OK
JSON
{
"properties": {
"schedules": {
"items": {
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"cron_spec": {
"type": "string"
},
"id": {
"type": "string"
},
"last_run_at": {
"type": "string"
},
"last_task_id": {
"type": "string"
},
"mode": {
"type": "string"
},
"next_run_at": {
"type": "string"
},
"prompt": {
"type": "string"
},
"status": {
"type": "string"
},
"timezone": {
"type": "string"
},
"title": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}POST /api/public/v1/schedulesCreate Task Agent schedule
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Schedule request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"cron_spec": {
"example": "0 15 * * 1",
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"mode": {
"example": "direct_execute",
"type": "string"
},
"next_run_at": {
"example": "2026-09-15T01:00:00Z",
"type": "string"
},
"prompt": {
"example": "Summarize the workspace.",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"timezone": {
"example": "Asia/Shanghai",
"type": "string"
},
"title": {
"example": "Weekly workspace report",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"schedule": {
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"cron_spec": {
"type": "string"
},
"id": {
"type": "string"
},
"last_run_at": {
"type": "string"
},
"last_task_id": {
"type": "string"
},
"mode": {
"type": "string"
},
"next_run_at": {
"type": "string"
},
"prompt": {
"type": "string"
},
"status": {
"type": "string"
},
"timezone": {
"type": "string"
},
"title": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}GET /api/public/v1/schedules/{scheduleID}Get Task Agent schedule
Request format: No request body format specified; Response format: application/json.
Parameters
scheduleID · path · Required
JSON
{
"description": "Schedule ID",
"in": "path",
"name": "scheduleID",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"schedule": {
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"cron_spec": {
"type": "string"
},
"id": {
"type": "string"
},
"last_run_at": {
"type": "string"
},
"last_task_id": {
"type": "string"
},
"mode": {
"type": "string"
},
"next_run_at": {
"type": "string"
},
"prompt": {
"type": "string"
},
"status": {
"type": "string"
},
"timezone": {
"type": "string"
},
"title": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PUT /api/public/v1/schedules/{scheduleID}Update Task Agent schedule
Request format: application/json; Response format: application/json.
Parameters
scheduleID · path · Required
JSON
{
"description": "Schedule ID",
"in": "path",
"name": "scheduleID",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Schedule request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"cron_spec": {
"example": "0 15 * * 1",
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"mode": {
"example": "direct_execute",
"type": "string"
},
"next_run_at": {
"example": "2026-09-15T01:00:00Z",
"type": "string"
},
"prompt": {
"example": "Summarize the workspace.",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"timezone": {
"example": "Asia/Shanghai",
"type": "string"
},
"title": {
"example": "Weekly workspace report",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"schedule": {
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"cron_spec": {
"type": "string"
},
"id": {
"type": "string"
},
"last_run_at": {
"type": "string"
},
"last_task_id": {
"type": "string"
},
"mode": {
"type": "string"
},
"next_run_at": {
"type": "string"
},
"prompt": {
"type": "string"
},
"status": {
"type": "string"
},
"timezone": {
"type": "string"
},
"title": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PATCH /api/public/v1/schedules/{scheduleID}Update Task Agent schedule
Request format: application/json; Response format: application/json.
Parameters
scheduleID · path · Required
JSON
{
"description": "Schedule ID",
"in": "path",
"name": "scheduleID",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Schedule request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"cron_spec": {
"example": "0 15 * * 1",
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"mode": {
"example": "direct_execute",
"type": "string"
},
"next_run_at": {
"example": "2026-09-15T01:00:00Z",
"type": "string"
},
"prompt": {
"example": "Summarize the workspace.",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"timezone": {
"example": "Asia/Shanghai",
"type": "string"
},
"title": {
"example": "Weekly workspace report",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"schedule": {
"properties": {
"config": {
"additionalProperties": {},
"type": "object"
},
"cron_spec": {
"type": "string"
},
"id": {
"type": "string"
},
"last_run_at": {
"type": "string"
},
"last_task_id": {
"type": "string"
},
"mode": {
"type": "string"
},
"next_run_at": {
"type": "string"
},
"prompt": {
"type": "string"
},
"status": {
"type": "string"
},
"timezone": {
"type": "string"
},
"title": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}DELETE /api/public/v1/schedules/{scheduleID}Delete Task Agent schedule
Request format: No request body format specified; Response format: application/json.
Parameters
scheduleID · path · Required
JSON
{
"description": "Schedule ID",
"in": "path",
"name": "scheduleID",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"ok": {
"example": true,
"type": "boolean"
}
},
"type": "object"
}GET /api/public/v1/schedules/{scheduleID}/runsList Task Agent schedule runs
Request format: No request body format specified; Response format: application/json.
Parameters
scheduleID · path · Required
JSON
{
"description": "Schedule ID",
"in": "path",
"name": "scheduleID",
"required": true,
"type": "string"
}limit · query · Optional
JSON
{
"description": "Run page size",
"in": "query",
"name": "limit",
"type": "integer"
}Responses
200 OK
JSON
{
"properties": {
"runs": {
"items": {
"properties": {
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"run_at": {
"type": "string"
},
"schedule_id": {
"type": "string"
},
"status": {
"type": "string"
},
"task_id": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Knowledge bases
GET /api/public/v1/knowledge-basesList public Task Agent Knowledge Bases
Request format: No request body format specified; Response format: application/json.
Parameters
page · query · Optional
JSON
{
"description": "Page number, default 1",
"in": "query",
"name": "page",
"type": "integer"
}page_size · query · Optional
JSON
{
"description": "Page size, default 20 and max 100",
"in": "query",
"name": "page_size",
"type": "integer"
}Responses
200 OK
JSON
{
"properties": {
"knowledge_bases": {
"items": {
"properties": {
"cloudflare_instance_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"cloudflare_mcp_url": {
"example": "https://hast-kb-product-docs.search.ai.cloudflare.com/mcp",
"type": "string"
},
"cloudflare_public_endpoint_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"created_at": {
"type": "string"
},
"description": {
"type": "string"
},
"error_message": {
"type": "string"
},
"id": {
"example": "kb_123",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "Product docs",
"type": "string"
},
"source_content_type": {
"example": "text/markdown",
"type": "string"
},
"source_filename": {
"example": "docs.md",
"type": "string"
},
"source_type": {
"example": "url",
"type": "string"
},
"source_uri": {
"example": "https://example.com/docs.md",
"type": "string"
},
"status": {
"example": "indexed",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"pagination": {
"properties": {
"has_more": {
"example": false,
"type": "boolean"
},
"limit": {
"example": 20,
"type": "integer"
},
"offset": {
"example": 0,
"type": "integer"
},
"page": {
"example": 1,
"type": "integer"
},
"page_size": {
"example": 20,
"type": "integer"
},
"total": {
"example": 1,
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}POST /api/public/v1/knowledge-basesCreate a public Task Agent Knowledge Base
Creates a URL Knowledge Base with JSON or a file Knowledge Base with multipart/form-data. Indexing continues asynchronously.
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "URL Knowledge Base request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"description": {
"example": "Public product documentation",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "Product docs",
"type": "string"
},
"source_type": {
"example": "url",
"type": "string"
},
"url": {
"example": "https://example.com/docs.md",
"type": "string"
}
},
"type": "object"
}
}Responses
201 Created
JSON
{
"properties": {
"knowledge_base": {
"properties": {
"cloudflare_instance_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"cloudflare_mcp_url": {
"example": "https://hast-kb-product-docs.search.ai.cloudflare.com/mcp",
"type": "string"
},
"cloudflare_public_endpoint_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"created_at": {
"type": "string"
},
"description": {
"type": "string"
},
"error_message": {
"type": "string"
},
"id": {
"example": "kb_123",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "Product docs",
"type": "string"
},
"source_content_type": {
"example": "text/markdown",
"type": "string"
},
"source_filename": {
"example": "docs.md",
"type": "string"
},
"source_type": {
"example": "url",
"type": "string"
},
"source_uri": {
"example": "https://example.com/docs.md",
"type": "string"
},
"status": {
"example": "indexed",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}400 Bad Request
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}GET /api/public/v1/knowledge-bases/{id}Read a public Task Agent Knowledge Base
Request format: No request body format specified; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Knowledge Base ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"knowledge_base": {
"properties": {
"cloudflare_instance_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"cloudflare_mcp_url": {
"example": "https://hast-kb-product-docs.search.ai.cloudflare.com/mcp",
"type": "string"
},
"cloudflare_public_endpoint_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"created_at": {
"type": "string"
},
"description": {
"type": "string"
},
"error_message": {
"type": "string"
},
"id": {
"example": "kb_123",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "Product docs",
"type": "string"
},
"source_content_type": {
"example": "text/markdown",
"type": "string"
},
"source_filename": {
"example": "docs.md",
"type": "string"
},
"source_type": {
"example": "url",
"type": "string"
},
"source_uri": {
"example": "https://example.com/docs.md",
"type": "string"
},
"status": {
"example": "indexed",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}404 Not Found
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}PUT /api/public/v1/knowledge-bases/{id}Update a public Task Agent Knowledge Base
Request format: application/json; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Knowledge Base ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Knowledge Base update request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"description": {
"example": "Updated description",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "Updated product docs",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"knowledge_base": {
"properties": {
"cloudflare_instance_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"cloudflare_mcp_url": {
"example": "https://hast-kb-product-docs.search.ai.cloudflare.com/mcp",
"type": "string"
},
"cloudflare_public_endpoint_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"created_at": {
"type": "string"
},
"description": {
"type": "string"
},
"error_message": {
"type": "string"
},
"id": {
"example": "kb_123",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "Product docs",
"type": "string"
},
"source_content_type": {
"example": "text/markdown",
"type": "string"
},
"source_filename": {
"example": "docs.md",
"type": "string"
},
"source_type": {
"example": "url",
"type": "string"
},
"source_uri": {
"example": "https://example.com/docs.md",
"type": "string"
},
"status": {
"example": "indexed",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}404 Not Found
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}PATCH /api/public/v1/knowledge-bases/{id}Update a public Task Agent Knowledge Base
Request format: application/json; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Knowledge Base ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Knowledge Base update request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"description": {
"example": "Updated description",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "Updated product docs",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"knowledge_base": {
"properties": {
"cloudflare_instance_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"cloudflare_mcp_url": {
"example": "https://hast-kb-product-docs.search.ai.cloudflare.com/mcp",
"type": "string"
},
"cloudflare_public_endpoint_id": {
"example": "hast-kb-product-docs",
"type": "string"
},
"created_at": {
"type": "string"
},
"description": {
"type": "string"
},
"error_message": {
"type": "string"
},
"id": {
"example": "kb_123",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "Product docs",
"type": "string"
},
"source_content_type": {
"example": "text/markdown",
"type": "string"
},
"source_filename": {
"example": "docs.md",
"type": "string"
},
"source_type": {
"example": "url",
"type": "string"
},
"source_uri": {
"example": "https://example.com/docs.md",
"type": "string"
},
"status": {
"example": "indexed",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}404 Not Found
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}DELETE /api/public/v1/knowledge-bases/{id}Delete a public Task Agent Knowledge Base
Knowledge deletion is disabled to preserve imported originals. This compatibility endpoint returns HTTP 409.
Request format: No request body format specified; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Knowledge Base ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}Responses
409 Conflict
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}CRM
GET /api/public/v1/business-resourcesList CRM and customer communication knowledge bases
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/business-resources/communication-knowledgeCreate a customer communication knowledge base
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Create a customer communication knowledge base request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"name": {
"type": "string"
},
"request_id": {
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/business-resources/crmCreate an optional Twenty workspace
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Create an optional Twenty workspace request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"name": {
"type": "string"
},
"request_id": {
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}GET /api/public/v1/business-resources/{resource_id}Browse CRM records or communication knowledge source documents
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}object · query · Optional
JSON
{
"description": "CRM object (default people); use CRM schema for supported objects",
"in": "query",
"name": "object",
"type": "string"
}cursor · query · Optional
JSON
{
"description": "CRM next-page cursor",
"in": "query",
"name": "cursor",
"type": "string"
}query · query · Optional
JSON
{
"description": "Communication knowledge search (maximum 2000 bytes); omit to browse sources",
"in": "query",
"name": "query",
"type": "string"
}before · query · Optional
JSON
{
"description": "Communication document pagination cursor",
"in": "query",
"name": "before",
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}DELETE /api/public/v1/business-resources/{resource_id}Delete an unused channel resource configuration
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/business-resources/{resource_id}/crm/attachments/uploadUpload a CRM attachment
Request format: application/json; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
GET /api/public/v1/business-resources/{resource_id}/crm/schemaRead CRM business objects and field schema
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}GET /api/public/v1/business-resources/{resource_id}/crm/{object}Search CRM records
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}object · path · Required
JSON
{
"description": "object",
"in": "path",
"name": "object",
"required": true,
"type": "string"
}query · query · Optional
JSON
{
"description": "Search (maximum 300 bytes, no quotes or line breaks)",
"in": "query",
"name": "query",
"type": "string"
}cursor · query · Optional
JSON
{
"description": "Provider cursor returned by the previous page",
"in": "query",
"name": "cursor",
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/business-resources/{resource_id}/crm/{object}Create a CRM record
Discover objects and writable fields using the CRM schema endpoint before writing. Read back on uncertain errors before retrying.
Request format: application/json; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}object · path · Required
JSON
{
"description": "object",
"in": "path",
"name": "object",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Create a CRM record request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"request_id": {
"description": "Stable UUID required on create. Reuse it only for the identical create request.",
"type": "string"
},
"updated_at": {
"description": "Required on update; use updatedAt from the last record readback.",
"type": "string"
},
"values": {
"additionalProperties": {},
"description": "Only writable fields from GET /business-resources/{resource_id}/crm/schema.",
"type": "object"
}
},
"required": [
"values"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}GET /api/public/v1/business-resources/{resource_id}/crm/{object}/{record_id}Read CRM record details
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}object · path · Required
JSON
{
"description": "object",
"in": "path",
"name": "object",
"required": true,
"type": "string"
}record_id · path · Required
JSON
{
"description": "record_id",
"in": "path",
"name": "record_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}PATCH /api/public/v1/business-resources/{resource_id}/crm/{object}/{record_id}Update a CRM record
Discover objects and writable fields using the CRM schema endpoint before writing. Read back on uncertain errors before retrying.
Request format: application/json; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}object · path · Required
JSON
{
"description": "object",
"in": "path",
"name": "object",
"required": true,
"type": "string"
}record_id · path · Required
JSON
{
"description": "record_id",
"in": "path",
"name": "record_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Update a CRM record request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"request_id": {
"description": "Stable UUID required on create. Reuse it only for the identical create request.",
"type": "string"
},
"updated_at": {
"description": "Required on update; use updatedAt from the last record readback.",
"type": "string"
},
"values": {
"additionalProperties": {},
"description": "Only writable fields from GET /business-resources/{resource_id}/crm/schema.",
"type": "object"
}
},
"required": [
"values"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}DELETE /api/public/v1/business-resources/{resource_id}/crm/{object}/{record_id}Delete a CRM record
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}object · path · Required
JSON
{
"description": "object",
"in": "path",
"name": "object",
"required": true,
"type": "string"
}record_id · path · Required
JSON
{
"description": "record_id",
"in": "path",
"name": "record_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}GET /api/public/v1/business-resources/{resource_id}/crm/{object}/{record_id}/files/{field}/{file_id}Download a file attached to a CRM record
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}object · path · Required
JSON
{
"description": "object",
"in": "path",
"name": "object",
"required": true,
"type": "string"
}record_id · path · Required
JSON
{
"description": "record_id",
"in": "path",
"name": "record_id",
"required": true,
"type": "string"
}field · path · Required
JSON
{
"description": "field",
"in": "path",
"name": "field",
"required": true,
"type": "string"
}file_id · path · Required
JSON
{
"description": "file_id",
"in": "path",
"name": "file_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}GET /api/public/v1/business-resources/{resource_id}/crm/{object}/{record_id}/relations/{field}Browse related CRM records
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}object · path · Required
JSON
{
"description": "object",
"in": "path",
"name": "object",
"required": true,
"type": "string"
}record_id · path · Required
JSON
{
"description": "record_id",
"in": "path",
"name": "record_id",
"required": true,
"type": "string"
}field · path · Required
JSON
{
"description": "field",
"in": "path",
"name": "field",
"required": true,
"type": "string"
}cursor · query · Optional
JSON
{
"description": "Provider cursor returned by the previous page",
"in": "query",
"name": "cursor",
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}GET /api/public/v1/business-resources/{resource_id}/membersList CRM member identities for owner and assignee fields
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "Owned CRM resource ID",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}cursor · query · Optional
JSON
{
"description": "Next cursor from the previous member page",
"in": "query",
"name": "cursor",
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"has_more": {
"type": "boolean"
},
"members": {
"items": {
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string"
},
"id": {
"type": "string"
},
"last_name": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"next_cursor": {
"type": "string"
}
},
"type": "object"
}POST /api/public/v1/business-resources/{resource_id}/membersCreate or reuse a CRM member without retaining a password
Uses the selected managed workspace's existing registration flow. No invitation is sent. Generated passwords are discarded. Does not reset accounts outside this CRM; provider email-verification settings still apply.
Request format: application/json; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "Owned platform-managed CRM resource ID",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Actual email and name; never a password",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
}
},
"required": [
"email",
"first_name"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"email": {
"type": "string"
},
"first_name": {
"type": "string"
},
"id": {
"type": "string"
},
"last_name": {
"type": "string"
}
},
"type": "object"
}POST /api/public/v1/business-resources/{resource_id}/provisionRetry an incomplete CRM provisioning operation
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "resource_id",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}Memory projects
GET /api/public/v1/chat_memory_projectsList user chat memory projects
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
POST /api/public/v1/chat_memory_projectsCreate a user chat memory project
Request format: No request body format specified; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Request body",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"customer_connection_id": {
"type": "string"
},
"customer_id": {
"type": "integer"
},
"name": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
}Responses
GET /api/public/v1/chat_memory_projects/writesList user chat memory indexing operations
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
Prompt
POST /api/public/v1/promptsSubmit a public Task Agent prompt
Creates a normal conversational Task Agent session when session_id is omitted, or appends a turn to an existing session. request_id is idempotent.
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Public prompt request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"dynamic_tools": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"files": {
"items": {
"type": "string"
},
"type": "array"
},
"model": {
"example": "hast/auto",
"type": "string"
},
"prompt": {
"example": "Summarize the release notes.",
"type": "string"
},
"reasoning_effort": {
"example": "medium",
"type": "string"
},
"request_id": {
"example": "client-turn-1",
"type": "string"
},
"secret_bindings": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
},
"session_id": {
"example": "sess_abc123",
"type": "string"
},
"skill_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"system_prompt": {
"type": "string"
}
},
"type": "object"
}
}Responses
202 Accepted
JSON
{
"properties": {
"request_id": {
"example": "client-turn-1",
"type": "string"
},
"session_id": {
"example": "sess_abc123",
"type": "string"
},
"status": {
"example": "dispatch_pending",
"type": "string"
}
},
"type": "object"
}401 Unauthorized
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}409 Conflict
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}413 Request Entity Too Large
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}Sessions and events
GET /api/public/v1/sessionsList public Task Agent sessions
Request format: No request body format specified; Response format: application/json.
Parameters
limit · query · Optional
JSON
{
"description": "Page size (1-100, default 50)",
"in": "query",
"name": "limit",
"type": "integer"
}cursor · query · Optional
JSON
{
"description": "Opaque cursor returned by the previous page",
"in": "query",
"name": "cursor",
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": "string"
},
"sessions": {
"items": {
"properties": {
"event_cursor": {
"type": "integer"
},
"mode": {
"type": "string"
},
"runtime_provider": {
"type": "string"
},
"session_id": {
"example": "sess_abc123",
"type": "string"
},
"status": {
"example": "running",
"type": "string"
},
"task_origin": {
"example": "session",
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"model": {
"type": "string"
},
"output_tokens": {
"type": "integer"
},
"pricing": {
"properties": {
"cache_read_usd_per_token": {
"type": "string"
},
"cache_write_usd_per_token": {
"type": "string"
},
"input_usd_per_token": {
"type": "string"
},
"output_usd_per_token": {
"type": "string"
}
},
"type": "object"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}GET /api/public/v1/sessions/{id}Read a public Task Agent session
Request format: No request body format specified; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Session ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"session": {
"properties": {
"event_cursor": {
"type": "integer"
},
"mode": {
"type": "string"
},
"runtime_provider": {
"type": "string"
},
"session_id": {
"example": "sess_abc123",
"type": "string"
},
"status": {
"example": "running",
"type": "string"
},
"task_origin": {
"example": "session",
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"model": {
"type": "string"
},
"output_tokens": {
"type": "integer"
},
"pricing": {
"properties": {
"cache_read_usd_per_token": {
"type": "string"
},
"cache_write_usd_per_token": {
"type": "string"
},
"input_usd_per_token": {
"type": "string"
},
"output_usd_per_token": {
"type": "string"
}
},
"type": "object"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}DELETE /api/public/v1/sessions/{id}Delete a public Task Agent session
Request format: No request body format specified; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Session ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"task": {
"properties": {
"client_id": {
"example": "client-main-user-123",
"type": "string"
},
"config": {
"additionalProperties": {},
"type": "object"
},
"created_at": {
"type": "string"
},
"event_cursor": {
"example": 42,
"type": "integer"
},
"id": {
"example": "task-agent-123",
"type": "string"
},
"mode": {
"example": "agent_run",
"type": "string"
},
"profile_id": {
"example": "user_123",
"type": "string"
},
"prompt": {
"type": "string"
},
"runtime_provider": {
"example": "cubesandbox",
"type": "string"
},
"sandbox_id": {
"example": "sandbox-main-user-123",
"type": "string"
},
"sandbox_scope": {
"example": "main",
"type": "string"
},
"status": {
"example": "needs_input",
"type": "string"
},
"task_origin": {
"example": "session",
"type": "string"
},
"title": {
"example": "Release validation",
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"model": {
"type": "string"
},
"output_tokens": {
"type": "integer"
},
"pricing": {
"properties": {
"cache_read_usd_per_token": {
"type": "string"
},
"cache_write_usd_per_token": {
"type": "string"
},
"input_usd_per_token": {
"type": "string"
},
"output_usd_per_token": {
"type": "string"
}
},
"type": "object"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
},
"workspace_object_prefix": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}POST /api/public/v1/sessions/{id}/cancelCancel a public Task Agent session
Request format: No request body format specified; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Session ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"task": {
"properties": {
"client_id": {
"example": "client-main-user-123",
"type": "string"
},
"config": {
"additionalProperties": {},
"type": "object"
},
"created_at": {
"type": "string"
},
"event_cursor": {
"example": 42,
"type": "integer"
},
"id": {
"example": "task-agent-123",
"type": "string"
},
"mode": {
"example": "agent_run",
"type": "string"
},
"profile_id": {
"example": "user_123",
"type": "string"
},
"prompt": {
"type": "string"
},
"runtime_provider": {
"example": "cubesandbox",
"type": "string"
},
"sandbox_id": {
"example": "sandbox-main-user-123",
"type": "string"
},
"sandbox_scope": {
"example": "main",
"type": "string"
},
"status": {
"example": "needs_input",
"type": "string"
},
"task_origin": {
"example": "session",
"type": "string"
},
"title": {
"example": "Release validation",
"type": "string"
},
"token_usage": {
"properties": {
"cache_read_tokens": {
"type": "integer"
},
"cache_write_tokens": {
"type": "integer"
},
"cost_status": {
"type": "string"
},
"estimated_cost_usd": {
"type": "number"
},
"input_tokens": {
"type": "integer"
},
"model": {
"type": "string"
},
"output_tokens": {
"type": "integer"
},
"pricing": {
"properties": {
"cache_read_usd_per_token": {
"type": "string"
},
"cache_write_usd_per_token": {
"type": "string"
},
"input_usd_per_token": {
"type": "string"
},
"output_usd_per_token": {
"type": "string"
}
},
"type": "object"
},
"reasoning_tokens": {
"type": "integer"
},
"reported_sessions": {
"type": "integer"
},
"total_tokens": {
"type": "integer"
},
"unpriced_tokens": {
"type": "integer"
},
"unreported_sessions": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"updated_at": {
"type": "string"
},
"workspace_object_prefix": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}GET /api/public/v1/sessions/{id}/eventsList public Task Agent Event v2 events
Request format: No request body format specified; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Session ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}after · query · Optional
JSON
{
"description": "Return persisted events after this sequence",
"in": "query",
"name": "after",
"type": "integer"
}limit · query · Optional
JSON
{
"description": "Event page size, maximum 200",
"in": "query",
"name": "limit",
"type": "integer"
}Responses
200 OK
JSON
{
"properties": {
"events": {
"items": {
"discriminator": "type",
"properties": {
"created_at": {
"example": "2026-08-16T12:00:00Z",
"format": "date-time",
"type": "string"
},
"data": {
"allOf": [
{
"properties": {
"attempt": {
"minimum": 1,
"type": "integer"
},
"attempts": {
"minimum": 1,
"type": "integer"
},
"channel": {
"enum": [
"stdout",
"stderr",
"progress"
],
"type": "string"
},
"code": {
"type": "string"
},
"context_window": {
"minimum": 0,
"type": "integer"
},
"cost": {},
"delta": {
"type": "string"
},
"duration_ms": {
"minimum": 0,
"type": "integer"
},
"error": {
"type": "string"
},
"exit_code": {
"type": "integer"
},
"files": {
"items": {
"type": "string"
},
"type": "array"
},
"final_message_id": {
"type": "string"
},
"finish_reason": {
"type": "string"
},
"input": {},
"is_error": {
"type": "boolean"
},
"kind": {
"type": "string"
},
"last": {
"properties": {
"cache_read_tokens": {
"minimum": 0,
"type": "integer"
},
"cache_write_tokens": {
"minimum": 0,
"type": "integer"
},
"input_tokens": {
"minimum": 0,
"type": "integer"
},
"output_tokens": {
"minimum": 0,
"type": "integer"
},
"reasoning_tokens": {
"minimum": 0,
"type": "integer"
},
"total_tokens": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"cache_read_tokens",
"cache_write_tokens",
"input_tokens",
"output_tokens",
"reasoning_tokens",
"total_tokens"
],
"type": "object"
},
"message": {
"type": "string"
},
"message_id": {
"type": "string"
},
"model": {
"type": "string"
},
"model_config": {
"properties": {
"model": {
"type": "string"
},
"model_source": {
"enum": [
"hast",
"codex_account"
],
"type": "string"
},
"reasoning_effort": {
"type": "string"
}
},
"type": "object"
},
"model_source": {
"type": "string"
},
"modified_at": {
"format": "date-time",
"type": "string"
},
"name": {
"type": "string"
},
"operation": {
"enum": [
"update",
"delete"
],
"type": "string"
},
"options": {
"items": {},
"type": "array"
},
"output": {},
"parent_tool_call_id": {
"type": "string"
},
"path": {
"type": "string"
},
"plan_id": {
"type": "string"
},
"prompt": {
"type": "string"
},
"reason": {
"type": "string"
},
"reasoning_id": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"role": {
"enum": [
"user",
"assistant",
"system"
],
"type": "string"
},
"scope": {
"type": "string"
},
"size_bytes": {
"minimum": 0,
"type": "integer"
},
"status": {
"enum": [
"starting",
"ready",
"failed",
"released",
"succeeded",
"interrupted"
],
"type": "string"
},
"steps": {
"items": {
"properties": {
"status": {
"enum": [
"pending",
"in_progress",
"completed"
],
"example": "in_progress",
"type": "string"
},
"step": {
"type": "string"
}
},
"required": [
"status",
"step"
],
"type": "object"
},
"type": "array"
},
"text": {
"type": "string"
},
"tokens_after": {
"minimum": 0,
"type": "integer"
},
"tokens_before": {
"minimum": 0,
"type": "integer"
},
"tool_call_id": {
"type": "string"
},
"total": {
"properties": {
"cache_read_tokens": {
"minimum": 0,
"type": "integer"
},
"cache_write_tokens": {
"minimum": 0,
"type": "integer"
},
"input_tokens": {
"minimum": 0,
"type": "integer"
},
"output_tokens": {
"minimum": 0,
"type": "integer"
},
"reasoning_tokens": {
"minimum": 0,
"type": "integer"
},
"total_tokens": {
"minimum": 0,
"type": "integer"
}
},
"required": [
"cache_read_tokens",
"cache_write_tokens",
"input_tokens",
"output_tokens",
"reasoning_tokens",
"total_tokens"
],
"type": "object"
},
"turn_type": {
"type": "string"
}
},
"type": "object"
}
],
"description": "Data is the HAST-owned payload union; Type selects its required shape as\ndefined in docs/reference/task-agent-event-v2.md."
},
"engine": {
"enum": [
"codex_cli",
"pi_agent_cli"
],
"example": "codex_cli",
"type": "string"
},
"event_id": {
"example": "evt_123",
"type": "string"
},
"replayable": {
"example": true,
"type": "boolean"
},
"run_id": {
"example": "run_123",
"type": "string"
},
"schema_version": {
"enum": [
2
],
"example": 2,
"type": "integer"
},
"sequence": {
"description": "Sequence is a positive durable order, or null for volatile events.",
"example": 42,
"minimum": 1,
"type": "integer",
"x-nullable": true
},
"session_id": {
"example": "session_123",
"type": "string"
},
"source": {
"enum": [
"runtime",
"backplane",
"workspace"
],
"example": "runtime",
"type": "string"
},
"task_id": {
"example": "task_123",
"type": "string"
},
"type": {
"enum": [
"runtime.status",
"run.queued",
"run.started",
"run.retrying",
"run.completed",
"run.failed",
"run.interrupted",
"message.started",
"message.delta",
"message.completed",
"reasoning.started",
"reasoning.delta",
"reasoning.completed",
"tool.started",
"tool.updated",
"tool.completed",
"plan.updated",
"plan.completed",
"usage.updated",
"file.changed",
"input.requested",
"context.compacted",
"warning",
"error"
],
"example": "message.completed",
"type": "string"
}
},
"required": [
"created_at",
"data",
"engine",
"event_id",
"replayable",
"schema_version",
"sequence",
"source",
"task_id",
"type"
],
"type": "object"
},
"type": "array"
},
"has_more": {
"example": true,
"type": "boolean"
},
"next_after": {
"example": 42,
"format": "int64",
"type": "integer",
"x-nullable": true
}
},
"type": "object"
}GET /api/public/v1/sessions/{id}/events/streamStream public Task Agent events
Event v2 SSE supports after and Last-Event-ID replay.
Request format: No request body format specified; Response format: text/event-stream.
Parameters
id · path · Required
JSON
{
"description": "Session ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}after · query · Optional
JSON
{
"description": "Return persisted events after this sequence",
"in": "query",
"name": "after",
"type": "integer"
}Responses
200 SSE stream
JSON
{
"type": "string"
}POST /api/public/v1/sessions/{id}/interruptInterrupt a public Task Agent turn
Request format: No request body format specified; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Session ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"request_id": {
"example": "task-agent-turn-1710000000000000000",
"type": "string"
},
"status": {
"example": "queued",
"type": "string"
}
},
"type": "object"
}202 Accepted
JSON
{
"properties": {
"request_id": {
"example": "task-agent-turn-1710000000000000000",
"type": "string"
},
"status": {
"example": "queued",
"type": "string"
}
},
"type": "object"
}Skills
GET /api/public/v1/skillsList public Task Agent skills
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"properties": {
"skills": {
"items": {
"properties": {
"capability_id": {
"type": "string"
},
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"hash": {
"example": "sha256:abc123",
"type": "string"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}POST /api/public/v1/skillsCreate a public Task Agent skill
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Skill request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"example": "E2E Summary",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"expected_checksum_sha256": {
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source_type": {
"example": "upload",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"skill": {
"properties": {
"capability_id": {
"type": "string"
},
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"hash": {
"example": "sha256:abc123",
"type": "string"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}GET /api/public/v1/skills/{skillID}Read, update, or delete a public Task Agent skill
Request format: application/json; Response format: application/json.
Parameters
skillID · path · Required
JSON
{
"description": "Skill ID",
"in": "path",
"name": "skillID",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Skill request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"example": "E2E Summary",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"expected_checksum_sha256": {
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source_type": {
"example": "upload",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"skill": {
"properties": {
"capability_id": {
"type": "string"
},
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"hash": {
"example": "sha256:abc123",
"type": "string"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PUT /api/public/v1/skills/{skillID}Read, update, or delete a public Task Agent skill
Request format: application/json; Response format: application/json.
Parameters
skillID · path · Required
JSON
{
"description": "Skill ID",
"in": "path",
"name": "skillID",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Skill request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"example": "E2E Summary",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"expected_checksum_sha256": {
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source_type": {
"example": "upload",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"skill": {
"properties": {
"capability_id": {
"type": "string"
},
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"hash": {
"example": "sha256:abc123",
"type": "string"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PATCH /api/public/v1/skills/{skillID}Read, update, or delete a public Task Agent skill
Request format: application/json; Response format: application/json.
Parameters
skillID · path · Required
JSON
{
"description": "Skill ID",
"in": "path",
"name": "skillID",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Skill request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"example": "E2E Summary",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"expected_checksum_sha256": {
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source_type": {
"example": "upload",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"skill": {
"properties": {
"capability_id": {
"type": "string"
},
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"hash": {
"example": "sha256:abc123",
"type": "string"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}DELETE /api/public/v1/skills/{skillID}Read, update, or delete a public Task Agent skill
Request format: application/json; Response format: application/json.
Parameters
skillID · path · Required
JSON
{
"description": "Skill ID",
"in": "path",
"name": "skillID",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Skill request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"example": "E2E Summary",
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"expected_checksum_sha256": {
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source_type": {
"example": "upload",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"skill": {
"properties": {
"capability_id": {
"type": "string"
},
"description": {
"type": "string"
},
"directory_name": {
"example": "e2e-summary",
"type": "string"
},
"display_name": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"entrypoint_path": {
"example": "SKILL.md",
"type": "string"
},
"files": {
"items": {
"properties": {
"content": {
"type": "string"
},
"path": {
"example": "SKILL.md",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"hash": {
"example": "sha256:abc123",
"type": "string"
},
"skill_id": {
"example": "e2e-summary",
"type": "string"
},
"source": {
"example": "user",
"type": "string"
},
"status": {
"example": "active",
"type": "string"
},
"url": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Channels
GET /api/public/v1/channelsList user channel connections
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
POST /api/public/v1/channelsConnect a verified existing Chatwoot message inbox
Request format: No request body format specified; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Request body",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"inbox_id": {
"type": "integer"
},
"name": {
"type": "string"
},
"require_admission": {
"type": "boolean"
}
},
"required": [
"inbox_id",
"name"
],
"type": "object"
}
}Responses
POST /api/public/v1/channels/accountInitialize a user channel account
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
GET /api/public/v1/channels/agentsList Agents available for channel assignment
Request format: No request body format specified; Response format: application/json.
Parameters
page · query · Optional
JSON
{
"description": "Page number",
"in": "query",
"name": "page",
"type": "integer"
}page_size · query · Optional
JSON
{
"description": "Page size, maximum 100",
"in": "query",
"name": "page_size",
"type": "integer"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/channels/authorizations/{provider}Begin channel authorization
Request format: No request body format specified; Response format: application/json.
Parameters
provider · path · Required
JSON
{
"description": "provider",
"in": "path",
"name": "provider",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/channels/authorizations/{provider}/completeComplete channel authorization
Request format: application/json; Response format: application/json.
Parameters
provider · path · Required
JSON
{
"description": "provider",
"in": "path",
"name": "provider",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Complete channel authorization request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"code": {
"type": "string"
},
"require_admission": {
"type": "boolean"
},
"state": {
"type": "string"
}
},
"required": [
"code",
"state"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/channels/deletions/{id}/retryRetry channel cleanup
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
202 Accepted
JSON
{
"additionalProperties": {
"type": "string"
},
"type": "object"
}POST /api/public/v1/channels/facebookConnect a Facebook page
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Connect a Facebook page request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"page_id": {
"type": "string"
},
"require_admission": {
"type": "boolean"
},
"token": {
"type": "string"
}
},
"required": [
"page_id",
"token"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/channels/facebook/pagesList authorized Facebook pages
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "List authorized Facebook pages request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"token": {
"type": "string"
}
},
"required": [
"token"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}GET /api/public/v1/channels/inboxesList available Chatwoot message inboxes
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
GET /api/public/v1/channels/resourcesList channel resources and operations
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
POST /api/public/v1/channels/resourcesRegister an independently bindable channel resource
Request format: application/json; Response format: application/json.
Parameters
body · body · Required
JSON
{
"description": "Resource reference",
"in": "body",
"name": "body",
"required": true,
"schema": {
"properties": {
"base_url": {
"type": "string"
},
"created_at": {
"type": "string"
},
"credential_expires_at": {
"type": "string"
},
"id": {
"type": "string"
},
"kind": {
"enum": [
"hast_memory",
"cloudflare",
"knowledge_source",
"knowledge_collection",
"hindsight",
"twenty",
"tool",
"schedule"
],
"type": "string",
"x-enum-varnames": [
"ChannelResourceMemory",
"ChannelResourceKnowledge",
"ChannelResourceSource",
"ChannelResourceCollection",
"ChannelResourceFacts",
"ChannelResourceCRM",
"ChannelResourceTool",
"ChannelResourceSchedule"
]
},
"managed": {
"type": "boolean"
},
"name": {
"type": "string"
},
"reference_id": {
"type": "string"
},
"scope_type": {
"type": "string"
},
"secret_id": {
"type": "string"
},
"status": {
"type": "string"
}
},
"type": "object"
}
}Responses
POST /api/public/v1/channels/resources/crmCreate an optional Twenty workspace
Request format: application/json; Response format: application/json.
Parameters
body · body · Required
JSON
{
"description": "CRM name and stable request ID",
"in": "body",
"name": "body",
"required": true,
"schema": {
"properties": {
"name": {
"type": "string"
},
"request_id": {
"type": "string"
}
},
"type": "object"
}
}Responses
DELETE /api/public/v1/channels/resources/{resource_id}Delete an unused channel resource configuration
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "Resource ID",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}Responses
POST /api/public/v1/channels/resources/{resource_id}/provisionRetry an incomplete CRM provisioning operation
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "CRM resource ID",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}Responses
PUT /api/public/v1/channels/resources/{resource_id}/statusDisable or reverify a CRM resource
Request format: application/json; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "CRM resource ID",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Request body",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"status": {
"type": "string"
}
},
"required": [
"status"
],
"type": "object"
}
}Responses
POST /api/public/v1/channels/resources/{resource_id}/verifyVerify a Twenty resource credential and workspace
Request format: No request body format specified; Response format: application/json.
Parameters
resource_id · path · Required
JSON
{
"description": "CRM resource ID",
"in": "path",
"name": "resource_id",
"required": true,
"type": "string"
}Responses
GET /api/public/v1/channels/schedule_sourcesList verified Webhook Schedule destinations
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
GET /api/public/v1/channels/sendsList user channel sends and provider statuses
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
GET /api/public/v1/channels/setupRead channel setup configuration
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/channels/setupCreate a message channel
Slack accepts optional slack_trigger_rules with require_mention, auto_reply_channel_ids and auto_reply_sender_ids. Omit it for mention-required defaults. Channel and sender exceptions are OR conditions; obtain actual IDs from the authorized Slack workspace.
Request format: No request body format specified; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Request body",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"account_id": {
"type": "string"
},
"account_sid": {
"type": "string"
},
"api_key": {
"type": "string"
},
"api_secret": {
"type": "string"
},
"application_id": {
"type": "string"
},
"auth_token": {
"type": "string"
},
"bot_token": {
"type": "string"
},
"callback_token": {
"type": "string"
},
"corp_id": {
"type": "string"
},
"corp_secret": {
"type": "string"
},
"email": {
"type": "string"
},
"encoding_aes_key": {
"type": "string"
},
"imap_address": {
"type": "string"
},
"imap_login": {
"type": "string"
},
"imap_password": {
"type": "string"
},
"line_channel_id": {
"type": "string"
},
"line_channel_secret": {
"type": "string"
},
"line_channel_token": {
"type": "string"
},
"medium": {
"type": "string"
},
"name": {
"type": "string"
},
"open_kfid": {
"type": "string"
},
"phone_number": {
"type": "string"
},
"platform": {
"type": "string"
},
"require_admission": {
"type": "boolean"
},
"signing_secret": {
"type": "string"
},
"slack_trigger_rules": {
"properties": {
"auto_reply_channel_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"auto_reply_sender_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"require_mention": {
"type": "boolean"
}
},
"required": [
"require_mention"
],
"type": "object"
},
"smtp_address": {
"type": "string"
},
"smtp_login": {
"type": "string"
},
"smtp_password": {
"type": "string"
},
"telegram_trigger_rules": {
"properties": {
"group_rules": {
"items": {
"properties": {
"chat_id": {
"type": "string"
},
"mode": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"website_url": {
"type": "string"
}
},
"type": "object"
}
}Responses
POST /api/public/v1/channels/whatsappCreate an official WhatsApp Cloud connection
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Create an official WhatsApp Cloud connection request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"app_secret_id": {
"type": "string"
},
"app_secret_name": {
"type": "string"
},
"app_secret_value": {
"type": "string"
},
"business_account_id": {
"type": "string"
},
"name": {
"type": "string"
},
"phone_number": {
"type": "string"
},
"phone_number_id": {
"type": "string"
},
"require_admission": {
"type": "boolean"
},
"token_secret_id": {
"type": "string"
},
"token_secret_name": {
"type": "string"
},
"token_secret_value": {
"type": "string"
}
},
"required": [
"business_account_id",
"name",
"phone_number",
"phone_number_id"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}DELETE /api/public/v1/channels/{connection_id}Disconnect a user channel
Request format: No request body format specified; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "Connection ID",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}Responses
PUT /api/public/v1/channels/{connection_id}/bindingRelease a legacy channel association
Request format: application/json; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "Channel connection ID",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}body · body · Required
JSON
{
"description": "Expected Webhook ID and binding version; target must be empty to release the association",
"in": "body",
"name": "body",
"required": true,
"schema": {
"properties": {
"expected_binding_version": {
"type": "integer"
},
"expected_hook_id": {
"type": "string"
},
"require_admission": {
"type": "boolean"
},
"target_hook_id": {
"type": "string"
}
},
"type": "object"
}
}Responses
GET /api/public/v1/channels/{connection_id}/deletion_previewPreview retained Knowledge affected by channel deletion
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"properties": {
"attachment_count": {
"type": "integer"
},
"bases": {
"items": {
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"record_count": {
"type": "integer"
},
"source_count": {
"type": "integer"
}
},
"type": "object"
}GET /api/public/v1/channels/{connection_id}/installationRead channel installation information
WeChat installation includes wechat_trusted_ips, the configured public egress IP list. An empty array means the deployment has not configured it; other platforms omit this field. Slack installation includes slack_trigger_rules and the callback URL. Use the returned rules to preserve existing exceptions when updating a Slack channel.
Request format: No request body format specified; Response format: See response definitions.
Parameters
No parameters declared in the specification.
Responses
POST /api/public/v1/channels/{connection_id}/reconnectReconnect a disconnected channel
Verify the provider inbox before resuming synchronization. Existing history remains associated with this connection. Automatic replies stay off until an Agent is selected again.
Request format: No request body format specified; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "Connection ID",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}Responses
DELETE /api/public/v1/channels/{connection_id}/removeDelete a channel with optional retained Knowledge cleanup
Request format: No request body format specified; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "Connection ID",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}purge_knowledge · query · Optional
JSON
{
"description": "Delete retained originals and derived knowledge in all affected bases",
"in": "query",
"name": "purge_knowledge",
"type": "boolean"
}Responses
202 Accepted
JSON
{
"properties": {
"deletion": {
"properties": {
"affected_base_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"completed": {
"type": "integer"
},
"connection_id": {
"type": "string"
},
"created_at": {
"type": "string"
},
"error": {
"type": "string"
},
"finished_at": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"purge_knowledge": {
"type": "boolean"
},
"stage": {
"type": "string"
},
"state": {
"type": "string"
},
"total": {
"type": "integer"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PATCH /api/public/v1/channels/{connection_id}/slackSet Slack mention requirements and automatic reply exceptions
Replace the complete Slack trigger rules. Mentions, exempt channel IDs and exempt user or bot IDs independently trigger replies. Both ID arrays support multiple values (up to 100 unique IDs each). Direct messages trigger normally and own-bot echoes are ignored. Requires an owned Slack channel; read /channels/{connection_id}/installation before editing and after saving.
Request format: application/json; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "Channel ID",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Complete Slack trigger rules",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"auto_reply_channel_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"auto_reply_sender_ids": {
"items": {
"type": "string"
},
"type": "array"
},
"require_mention": {
"type": "boolean"
}
},
"required": [
"require_mention"
],
"type": "object"
}
}Responses
PATCH /api/public/v1/channels/{connection_id}/telegramSet Telegram group Agent triggers
Replace all group rules. Unlisted groups sync knowledge only. Modes: sync_only, mention (mention or reply to the Bot), all. Private chats trigger normally; Agent configuration and member admission are checked independently.
Request format: application/json; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "Channel ID",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Complete Telegram group rules",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"group_rules": {
"items": {
"properties": {
"chat_id": {
"type": "string"
},
"mode": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}Responses
PATCH /api/public/v1/channels/{connection_id}/wechat-kfComplete WeChat customer service setup
Request format: application/json; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "connection_id",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Complete WeChat customer service setup request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"corp_secret": {
"type": "string"
},
"open_kfid": {
"type": "string"
}
},
"required": [
"corp_secret",
"open_kfid"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}POST /api/public/v1/channels/{connection_id}/wechat-kf/accountsDiscover WeChat customer service accounts without saving credentials
Requires channels:write on a Profile key. Returns account names, IDs and management eligibility for an owned WeChat channel. Does not save the Secret or change bindings. Select an account with manage_privilege=true, then PATCH the WeChat setup with corp_secret and open_kfid.
Request format: application/json; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "Owned WeChat channel connection ID",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Application Secret; never include in prompts or logs",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"corp_secret": {
"maxLength": 4096,
"type": "string"
}
},
"required": [
"corp_secret"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"accounts": {
"items": {
"properties": {
"manage_privilege": {
"type": "boolean"
},
"name": {
"type": "string"
},
"open_kfid": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}400 wechat_credentials_invalid
JSON
{
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
}
},
"type": "object"
}401 Missing or invalid API key
JSON
{
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
}
},
"type": "object"
}403 Requires a Profile key with channels:write
JSON
{
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
}
},
"type": "object"
}404 WeChat channel not found
JSON
{
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
}
},
"type": "object"
}409 Channel account unavailable
JSON
{
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
}
},
"type": "object"
}422 wechat_credentials_invalid, wechat_permission_denied, wechat_ip_not_allowed or wechat_accounts_unavailable
JSON
{
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
}
},
"type": "object"
}502 wechat_accounts_unavailable
JSON
{
"properties": {
"code": {
"type": "string"
},
"error": {
"type": "string"
}
},
"type": "object"
}POST /api/public/v1/channels/{connection_id}/wechat-kf/domain-verificationUpload a WeCom domain verification file
Request format: application/json; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "connection_id",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Upload a WeCom domain verification file request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"content": {
"type": "string"
},
"filename": {
"type": "string"
}
},
"required": [
"content",
"filename"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}PATCH /api/public/v1/channels/{connection_id}/whatsappReauthorize an official WhatsApp Cloud connection
Request format: application/json; Response format: application/json.
Parameters
connection_id · path · Required
JSON
{
"description": "connection_id",
"in": "path",
"name": "connection_id",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Reauthorize an official WhatsApp Cloud connection request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"app_secret_id": {
"type": "string"
},
"app_secret_name": {
"type": "string"
},
"app_secret_value": {
"type": "string"
},
"business_account_id": {
"type": "string"
},
"phone_number_id": {
"type": "string"
},
"token_secret_id": {
"type": "string"
},
"token_secret_name": {
"type": "string"
},
"token_secret_value": {
"type": "string"
}
},
"required": [
"business_account_id",
"phone_number_id"
],
"type": "object"
}
}Responses
200 OK
JSON
{
"additionalProperties": true,
"type": "object"
}Memory
GET /api/public/v1/memoriesList public Task Agent memories
Request format: No request body format specified; Response format: application/json.
Parameters
scope_type · query · Optional
JSON
{
"description": "Filter memory category",
"enum": [
"task_agent",
"webhook"
],
"in": "query",
"name": "scope_type",
"type": "string"
}scope_id · query · Optional
JSON
{
"description": "Webhook ID; empty selects shared, omitted selects all in the category",
"in": "query",
"name": "scope_id",
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"memories": {
"items": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}POST /api/public/v1/memoriesCreate a public Task Agent memory
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Memory request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"content": {
"example": "Prefer concise validation notes.",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "project-preferences",
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"memory": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}GET /api/public/v1/memories/by-id/{memoryID}Read a memory by ID within the authenticated user
Request format: No request body format specified; Response format: application/json.
Parameters
memoryID · path · Required
JSON
{
"description": "Memory ID",
"in": "path",
"name": "memoryID",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"memory": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PUT /api/public/v1/memories/by-id/{memoryID}Update a memory by ID, optionally moving its scope
Request format: application/json; Response format: application/json.
Parameters
memoryID · path · Required
JSON
{
"description": "Memory ID",
"in": "path",
"name": "memoryID",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Memory update",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"content": {
"example": "Prefer concise validation notes.",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "project-preferences",
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"memory": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}404 Not Found
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}PATCH /api/public/v1/memories/by-id/{memoryID}Update a memory by ID, optionally moving its scope
Request format: application/json; Response format: application/json.
Parameters
memoryID · path · Required
JSON
{
"description": "Memory ID",
"in": "path",
"name": "memoryID",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Memory update",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"content": {
"example": "Prefer concise validation notes.",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "project-preferences",
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"memory": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}404 Not Found
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}DELETE /api/public/v1/memories/by-id/{memoryID}Delete a memory by ID within the authenticated user
Request format: No request body format specified; Response format: application/json.
Parameters
memoryID · path · Required
JSON
{
"description": "Memory ID",
"in": "path",
"name": "memoryID",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"ok": {
"example": true,
"type": "boolean"
}
},
"type": "object"
}GET /api/public/v1/memories/{name}Read, update, or delete a public Task Agent memory
Request format: application/json; Response format: application/json.
Parameters
name · path · Required
JSON
{
"description": "Memory name",
"in": "path",
"name": "name",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Memory request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"content": {
"example": "Prefer concise validation notes.",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "project-preferences",
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"memory": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PUT /api/public/v1/memories/{name}Read, update, or delete a public Task Agent memory
Request format: application/json; Response format: application/json.
Parameters
name · path · Required
JSON
{
"description": "Memory name",
"in": "path",
"name": "name",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Memory request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"content": {
"example": "Prefer concise validation notes.",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "project-preferences",
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"memory": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PATCH /api/public/v1/memories/{name}Read, update, or delete a public Task Agent memory
Request format: application/json; Response format: application/json.
Parameters
name · path · Required
JSON
{
"description": "Memory name",
"in": "path",
"name": "name",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Memory request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"content": {
"example": "Prefer concise validation notes.",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "project-preferences",
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"memory": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}DELETE /api/public/v1/memories/{name}Read, update, or delete a public Task Agent memory
Request format: application/json; Response format: application/json.
Parameters
name · path · Required
JSON
{
"description": "Memory name",
"in": "path",
"name": "name",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Memory request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"content": {
"example": "Prefer concise validation notes.",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"example": "project-preferences",
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"memory": {
"properties": {
"content": {
"type": "string"
},
"created_at": {
"type": "string"
},
"id": {
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"name": {
"type": "string"
},
"scope_id": {
"example": "",
"type": "string"
},
"scope_type": {
"enum": [
"task_agent",
"webhook"
],
"example": "task_agent",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Files
GET /api/public/v1/filesList, download, or delete public workspace files
Request format: No request body format specified; Response format: application/json.
Parameters
session_id · query · Optional
JSON
{
"description": "Session ID",
"in": "query",
"name": "session_id",
"type": "string"
}path · query · Optional
JSON
{
"description": "Workspace directory path",
"in": "query",
"name": "path",
"type": "string"
}scope · query · Optional
JSON
{
"description": "Workspace scope",
"in": "query",
"name": "scope",
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"properties": {
"file_id": {
"example": "opaque-file-id",
"type": "string"
},
"id": {
"example": "opaque-file-id",
"type": "string"
},
"name": {
"example": "report.csv",
"type": "string"
},
"path": {
"example": "uploads/upload-id/report.csv",
"type": "string"
},
"relative_path": {
"example": "uploads/upload-id/report.csv",
"type": "string"
},
"session_id": {
"type": "string"
},
"size_bytes": {
"example": 1024,
"type": "integer"
},
"type": {
"example": "file",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"next_cursor": {
"type": "string"
}
},
"type": "object"
}POST /api/public/v1/filesUpload a public Task Agent file
Request format: No request body format specified; Response format: application/json.
Parameters
file · formData · Required
JSON
{
"description": "File",
"in": "formData",
"name": "file",
"required": true,
"type": "file"
}Responses
201 Created
JSON
{
"properties": {
"file": {
"properties": {
"file_id": {
"example": "opaque-file-id",
"type": "string"
},
"id": {
"example": "opaque-file-id",
"type": "string"
},
"name": {
"example": "report.csv",
"type": "string"
},
"path": {
"example": "uploads/upload-id/report.csv",
"type": "string"
},
"relative_path": {
"example": "uploads/upload-id/report.csv",
"type": "string"
},
"session_id": {
"type": "string"
},
"size_bytes": {
"example": 1024,
"type": "integer"
},
"type": {
"example": "file",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}GET /api/public/v1/files.zipDownload a public workspace ZIP
Request format: No request body format specified; Response format: application/zip.
Parameters
session_id · query · Optional
JSON
{
"description": "Session ID",
"in": "query",
"name": "session_id",
"type": "string"
}scope · query · Optional
JSON
{
"description": "Workspace scope",
"in": "query",
"name": "scope",
"type": "string"
}Responses
200 Workspace ZIP
JSON
{
"type": "file"
}GET /api/public/v1/files/{relativePath}Download or delete a public workspace file
Request format: No request body format specified; Response format: application/octet-stream.
Parameters
relativePath · path · Required
JSON
{
"description": "Workspace relative path",
"in": "path",
"name": "relativePath",
"required": true,
"type": "string"
}session_id · query · Optional
JSON
{
"description": "Session ID",
"in": "query",
"name": "session_id",
"type": "string"
}file_id · query · Required
JSON
{
"description": "Opaque file ID",
"in": "query",
"name": "file_id",
"required": true,
"type": "string"
}scope · query · Optional
JSON
{
"description": "Workspace scope",
"in": "query",
"name": "scope",
"type": "string"
}Responses
200 Workspace file
JSON
{
"type": "file"
}DELETE /api/public/v1/files/{relativePath}Download or delete a public workspace file
Request format: No request body format specified; Response format: application/octet-stream.
Parameters
relativePath · path · Required
JSON
{
"description": "Workspace relative path",
"in": "path",
"name": "relativePath",
"required": true,
"type": "string"
}session_id · query · Optional
JSON
{
"description": "Session ID",
"in": "query",
"name": "session_id",
"type": "string"
}file_id · query · Required
JSON
{
"description": "Opaque file ID",
"in": "query",
"name": "file_id",
"required": true,
"type": "string"
}scope · query · Optional
JSON
{
"description": "Workspace scope",
"in": "query",
"name": "scope",
"type": "string"
}Responses
200 Workspace file
JSON
{
"type": "file"
}Connectors
GET /api/public/v1/connectors/accountsList public connector accounts
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"properties": {
"connector_accounts": {
"items": {
"additionalProperties": {},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}GET /api/public/v1/connectors/accounts/{id}Read, update, or delete a public connector account
Request format: application/json; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Connector account ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Connector account request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"external_account_ref": {
"example": "connected-account-id",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"provider": {
"example": "github",
"type": "string"
},
"status": {
"example": "connected",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"connector_account": {
"additionalProperties": {},
"type": "object"
}
},
"type": "object"
}PUT /api/public/v1/connectors/accounts/{id}Read, update, or delete a public connector account
Request format: application/json; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Connector account ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Connector account request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"external_account_ref": {
"example": "connected-account-id",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"provider": {
"example": "github",
"type": "string"
},
"status": {
"example": "connected",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"connector_account": {
"additionalProperties": {},
"type": "object"
}
},
"type": "object"
}PATCH /api/public/v1/connectors/accounts/{id}Read, update, or delete a public connector account
Request format: application/json; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Connector account ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Connector account request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"external_account_ref": {
"example": "connected-account-id",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"provider": {
"example": "github",
"type": "string"
},
"status": {
"example": "connected",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"connector_account": {
"additionalProperties": {},
"type": "object"
}
},
"type": "object"
}DELETE /api/public/v1/connectors/accounts/{id}Read, update, or delete a public connector account
Request format: application/json; Response format: application/json.
Parameters
id · path · Required
JSON
{
"description": "Connector account ID",
"in": "path",
"name": "id",
"required": true,
"type": "string"
}request · body · Optional
JSON
{
"description": "Connector account request",
"in": "body",
"name": "request",
"schema": {
"properties": {
"external_account_ref": {
"example": "connected-account-id",
"type": "string"
},
"metadata": {
"additionalProperties": {},
"type": "object"
},
"provider": {
"example": "github",
"type": "string"
},
"status": {
"example": "connected",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"connector_account": {
"additionalProperties": {},
"type": "object"
}
},
"type": "object"
}GET /api/public/v1/connectors/catalogList public connector catalog
Request format: No request body format specified; Response format: application/json.
Parameters
search · query · Optional
JSON
{
"description": "Search toolkits",
"in": "query",
"name": "search",
"type": "string"
}cursor · query · Optional
JSON
{
"description": "Next cursor",
"in": "query",
"name": "cursor",
"type": "string"
}limit · query · Optional
JSON
{
"description": "Page size, maximum 100",
"in": "query",
"name": "limit",
"type": "integer"
}Responses
200 OK
JSON
{
"properties": {
"agent_id": {
"type": "string"
},
"connection_scope": {
"type": "string"
},
"connectors": {
"items": {
"properties": {
"account_label": {
"type": "string"
},
"description": {
"type": "string"
},
"label": {
"example": "GitHub",
"type": "string"
},
"logo": {
"type": "string"
},
"provider": {
"example": "github",
"type": "string"
},
"runtime_provider": {
"example": "composio",
"type": "string"
},
"start_url": {
"type": "string"
},
"status": {
"example": "connected",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"has_more": {
"type": "boolean"
},
"limit": {
"example": 20,
"type": "integer"
},
"next_cursor": {
"type": "string"
},
"profile_id": {
"type": "string"
},
"search": {
"example": "github",
"type": "string"
}
},
"type": "object"
}GET /api/public/v1/connectors/statusList public connector status
Request format: No request body format specified; Response format: application/json.
Parameters
search · query · Optional
JSON
{
"description": "Search connector catalog",
"in": "query",
"name": "search",
"type": "string"
}cursor · query · Optional
JSON
{
"description": "Next cursor",
"in": "query",
"name": "cursor",
"type": "string"
}limit · query · Optional
JSON
{
"description": "Page size, maximum 100",
"in": "query",
"name": "limit",
"type": "integer"
}Responses
200 OK
JSON
{
"properties": {
"agent_id": {
"type": "string"
},
"connection_scope": {
"type": "string"
},
"connectors": {
"items": {
"properties": {
"account_label": {
"type": "string"
},
"description": {
"type": "string"
},
"label": {
"example": "GitHub",
"type": "string"
},
"logo": {
"type": "string"
},
"provider": {
"example": "github",
"type": "string"
},
"runtime_provider": {
"example": "composio",
"type": "string"
},
"start_url": {
"type": "string"
},
"status": {
"example": "connected",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"has_more": {
"type": "boolean"
},
"limit": {
"example": 20,
"type": "integer"
},
"next_cursor": {
"type": "string"
},
"profile_id": {
"type": "string"
},
"search": {
"example": "github",
"type": "string"
}
},
"type": "object"
}POST /api/public/v1/connectors/{provider}/oauth/authorizeStart public connector OAuth authorization
Request format: application/json; Response format: application/json.
Parameters
provider · path · Required
JSON
{
"description": "Connector provider",
"in": "path",
"name": "provider",
"required": true,
"type": "string"
}Responses
200 OK
JSON
{
"properties": {
"auth_url": {
"type": "string"
},
"connected_account_id": {
"type": "string"
}
},
"type": "object"
}Secrets
GET /api/public/v1/secretsList User Secrets
Lists owned User Secret metadata. Secret values are write-only and are never returned.
Request format: No request body format specified; Response format: application/json.
Parameters
No parameters declared in the specification.
Responses
200 OK
JSON
{
"properties": {
"secrets": {
"items": {
"properties": {
"created_at": {
"type": "string"
},
"id": {
"example": "sec_123",
"type": "string"
},
"name": {
"example": "kubeconfig",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}POST /api/public/v1/secretsCreate a User Secret
Creates a write-only User Secret. The response returns metadata only.
Request format: application/json; Response format: application/json.
Parameters
request · body · Required
JSON
{
"description": "Secret request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"name": {
"example": "kubeconfig",
"type": "string"
},
"value": {
"example": "write-only",
"type": "string"
}
},
"type": "object"
}
}Responses
201 Created
JSON
{
"properties": {
"secret": {
"properties": {
"created_at": {
"type": "string"
},
"id": {
"example": "sec_123",
"type": "string"
},
"name": {
"example": "kubeconfig",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}PATCH /api/public/v1/secrets/{secretID}Update a User Secret value
Replaces the write-only Secret value. The response returns metadata only.
Request format: application/json; Response format: application/json.
Parameters
secretID · path · Required
JSON
{
"description": "Secret ID",
"in": "path",
"name": "secretID",
"required": true,
"type": "string"
}request · body · Required
JSON
{
"description": "Secret request",
"in": "body",
"name": "request",
"required": true,
"schema": {
"properties": {
"value": {
"example": "write-only",
"type": "string"
}
},
"type": "object"
}
}Responses
200 OK
JSON
{
"properties": {
"secret": {
"properties": {
"created_at": {
"type": "string"
},
"id": {
"example": "sec_123",
"type": "string"
},
"name": {
"example": "kubeconfig",
"type": "string"
},
"updated_at": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}404 Not Found
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}DELETE /api/public/v1/secrets/{secretID}Delete a User Secret
Request format: No request body format specified; Response format: application/json.
Parameters
secretID · path · Required
JSON
{
"description": "Secret ID",
"in": "path",
"name": "secretID",
"required": true,
"type": "string"
}Responses
204 No Content
404 Not Found
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}409 Conflict
JSON
{
"properties": {
"code": {
"description": "Code is the business status code (0 = success; see pkg/utils/errors.go).",
"example": 0,
"type": "integer"
},
"message": {
"description": "Message is a human-readable status or error description.",
"example": "ok",
"type": "string"
}
},
"type": "object"
}Discover WeChat customer service accounts
After creating a WeChat channel draft and completing WeCom authorization, call POST /api/public/v1/channels/{connection_id}/wechat-kf/accounts with a Profile API key granting channels:write. Write includes read. Single-Agent conversation keys cannot use this endpoint.
Request body (replace the Secret placeholder only through protected client arguments, never prompts or logs):
{"corp_secret":"<APPLICATION_SECRET>"}Successful response (200):
{"accounts":[{"open_kfid":"wk-example","name":"Customer support","manage_privilege":true}]}Select by name from accounts with manage_privilege: true. One manageable account may be preselected; several require a user choice. An empty list is valid. Discovery does not save the Secret or change bindings. Confirm setup with PATCH /api/public/v1/channels/{connection_id}/wechat-kf, sending the same corp_secret and selected open_kfid; the server rechecks management permission.
For 400/422 wechat_credentials_invalid, check the application Secret and company ID. For 422 wechat_permission_denied, authorize the application for customer-service APIs. For 422 wechat_ip_not_allowed, configure trusted outbound IPs. Retry 422/502 wechat_accounts_unavailable. Check API-key authentication/scopes for 401/403, channel ownership for 404, and channel account initialization for 409.