HTTP API
Control plane REST API for headless chat — actors, conversations, messages, branches, and blobs on port 8090.
The control plane HTTP API provides headless chat without embedded agents. It runs on port 8090 by default (YOKE_CONTROL_PLANE_PORT).
Agent bootstrap routes (POST /agents, POST /agents/:agentId/join) live on the executor portal HTTP server, not the control plane. See Agent bootstrap.
Base URL
http://localhost:8090/v1/tenants/:tenant_idMulti-tenant: replace :tenant_id with your tenant slug (e.g. default).
Actors
POST /actors
GET /actors/:actor_idCreate chat identity (human, system, agent persona).
Conversations
POST /conversations
GET /conversations/:conversation_idParticipants
POST /conversations/:conversation_id/participants
POST /conversations/:conversation_id/participants/:participant_id/leave
GET /conversations/:conversation_id/participantsMessages
POST /conversations/:conversation_id/messages
GET /conversations/:conversation_id/messagesTranscript pagination
| Param | Description |
|---|---|
latest=true | Most recent N messages (default for chat UIs) |
limit | Page size (1–100, default 50) |
before | Message id cursor — older messages |
after | Message id cursor — newer messages |
branchId | Branch timeline (omit for main) |
Response includes:
{
"messages": [...],
"pagination": {
"hasMoreBefore": true,
"hasMoreAfter": false,
"oldestCursor": "...",
"newestCursor": "..."
}
}Branches
POST /conversations/:conversation_id/branches
GET /conversations/:conversation_id/branchesBlobs
POST /blobs
GET /blobs/:blob_id
GET /blobs/:blob_id/contentUpload raw bytes:
POST /v1/tenants/:tenant_id/blobs
Content-Type: image/png
Body: <bytes>Optional query: filename, width, height, durationMs.
Requires YOKE_STORAGE=s3 and YOKE_S3_BUCKET.
Schedules
POST /schedules
GET /schedules
DELETE /schedules/:keyKeyed delayed events — see Schedules.
Tenant ingress (agents)
Control plane can proxy agent bootstrap to executor:
POST /v1/tenants/:tenant_id/ingress/...SDK helper:
import { createAgentBootstrapHttpClient } from "@yoke/sdk";
const agents = createAgentBootstrapHttpClient({
baseUrl: `${controlPlaneUrl}/v1/tenants/${tenantId}/ingress`,
});SDK HTTP clients
import { createChatHttpClient, createAgentBootstrapHttpClient } from "@yoke/sdk";
const chat = createChatHttpClient({ baseUrl: controlPlaneUrl, tenantId });
const room = await chat.createRoom({ title: "support" });Health
Executor portal (separate port):
GET /health → ok
GET /metrics → Prometheus text format