API Reference

REST API reference for the YokeBot engine.

Overview

The YokeBot engine exposes a REST API for managing agents, tasks, chat, knowledge bases, and data tables. The dashboard uses this API under the hood, and you can call it directly for custom integrations.

Base URL

For YokeBot Cloud:

https://api.yokebot.com/api

For self-hosted instances, the default is:

http://localhost:3001/api

All endpoints below are relative to the base URL. For example, listing agents:

GET https://api.yokebot.com/api/agents

Authentication

The API supports two authentication methods:

1. JWT Tokens (Dashboard)

Supabase JWT tokens are used by the dashboard. Requires both Authorization and X-Team-Id headers.

curl -X GET https://api.yokebot.com/api/agents \
  -H "Authorization: Bearer YOUR_SUPABASE_ACCESS_TOKEN" \
  -H "X-Team-Id: YOUR_TEAM_ID" \
  -H "Content-Type: application/json"

2. API Keys (Programmatic Access)

API keys are ideal for CI/CD pipelines, scripts, Zapier integrations, and mobile apps. Create them in Settings > API Keys.

curl -X GET https://api.yokebot.com/api/agents \
  -H "Authorization: Bearer yk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json"

API keys embed the team context, so no X-Team-Id header is needed.

Scopes

API keys can be scoped to limit access. Available scopes:

Scope	Access
*	Full access (default)
agents:read / agents:write	Agent management
tasks:read / tasks:write	Task management
chat:read / chat:write	Team chat and task thread messages
data:read / data:write	Source of record (data tables)
files:read / files:write	Workspace files
kb:read / kb:write	Knowledge base documents

Agents

Method	Endpoint	Description
GET	/agents	List all agents in the current team.
POST	/agents	Create a new agent.
GET	/agents/:id	Get agent details.
PATCH	/agents/:id	Update an agent.
DELETE	/agents/:id	Delete an agent.
POST	/agents/:id/start	Start the agent (enable heartbeat scheduling).
POST	/agents/:id/stop	Stop the agent (pause heartbeat scheduling).

Tasks

Method	Endpoint	Description
GET	/tasks	List tasks with optional status filter.
POST	/tasks	Create a new task.
GET	/tasks/:id	Get task details and comments.
PATCH	/tasks/:id	Update task status or details.
POST	/tasks/:id/comments	Add a comment to a task.
POST	/tasks/:id/approve	Approve a pending task.
POST	/tasks/:id/reject	Reject a pending task with feedback.

Chat

Method	Endpoint	Description
GET	/chat/messages	Get messages in the team chat.
POST	/chat/messages	Send a message to the team chat.
GET	/tasks/:id/messages	Get messages in a task thread.
POST	/tasks/:id/messages	Send a message to a task thread.

Knowledge Base

Method	Endpoint	Description
GET	/knowledge-bases	List knowledge bases.
POST	/knowledge-bases	Create a knowledge base.
POST	/knowledge-bases/:id/documents	Upload a document (multipart/form-data).
GET	/knowledge-bases/:id/documents	List documents in a KB.
DELETE	/knowledge-bases/:id/documents/:docId	Delete a document.
POST	/knowledge-bases/:id/query	Semantic search query.

Data Tables

Method	Endpoint	Description
GET	/tables	List data tables.
POST	/tables	Create a table with column definitions.
GET	/tables/:id/rows	Query rows with filters.
POST	/tables/:id/rows	Insert rows.
PATCH	/tables/:id/rows	Update rows matching filters.
DELETE	/tables/:id/rows	Delete rows matching filters.

Error Responses

All error responses follow a standard format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent with id 'abc123' not found.",
    "status": 404
  }
}

Status Code	Meaning
400	Bad request — invalid parameters.
401	Unauthorized — missing or invalid token.
403	Forbidden — insufficient permissions.
404	Not found — resource does not exist.
429	Rate limited — too many requests.
500	Internal server error.

API Key Management

Method	Endpoint	Description
POST	/api-keys	Create a new API key (admin only, returns plaintext once).
GET	/api-keys	List API keys for the team (admin only, no secrets).
DELETE	/api-keys/:id	Permanently delete an API key (admin only).
POST	/api-keys/:id/revoke	Revoke an API key (soft delete, keeps audit trail).
POST	/api-keys/:id/regenerate	Revoke and recreate a key with same name/scopes.

Rate Limits

Dashboard (JWT) requests: 5,000 requests per 15 minutes.

API key requests use per-key limits based on subscription tier:

Tier	Standard Endpoints	Chat/LLM Endpoints
Free / No subscription	20/min	5/min
Starter Crew ($29/mo)	60/min	20/min
Growth Crew ($59/mo)	200/min	50/min
Power Crew ($149/mo)	600/min	100/min

Rate limit headers are included in every response:

RateLimit-Limit: 60
RateLimit-Remaining: 47
RateLimit-Reset: 30