API Reference

Base URL

https://api.yocaso.dev

Request Format

All endpoints are accessed through the KrakenD API gateway using REST-style paths:

POST /api/v1/<domain>/<service>/<method>
Content-Type: application/json

For example:

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/send-message \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "conv_abc",
    "user_message": {
      "role": "ROLE_USER",
      "content": [{ "type": "CONTENT_PART_TYPE_TEXT", "content": "Hello" }]
    }
  }'

Request and response bodies use protojson encoding (JSON representation of Protocol Buffer messages).

Authentication

Every request must include one of:

Method	Header	Use Case
Secret key	X-API-Key: sk_...	Backend-to-backend
Publishable key + JWT	X-API-Key: pk_... + Authorization: Bearer <jwt>	Client apps
JWT only	Authorization: Bearer <jwt>	Dashboard

User impersonation

Header	Required	Description
X-On-Behalf-Of: <user-id>	Required when a backend secret key (sk_*) acts on behalf of a specific user, including on create-thread	Scope users:impersonate must be granted to the key

See Authentication for details or the API Key Integration Guide for scopes, rate limits, and code examples.

API Services

API	Base Path	RPCs	Description
LLM APIs	/api/v1/llm/gateway/	31	Threads, messages, MCP tools, memories, voice sessions (in progress)
Storage APIs	/api/v1/storage/gateway/	15	Per-user file storage, upload/download URLs
Authentication APIs	/api/v1/api-keys/	7	API key lifecycle management
Notification APIs	/api/v1/notifications/	49	Push, inbox, preferences, send, topics, subscribers, workflows, providers
Scheduler APIs	/api/v1/scheduler/	10	Scheduled jobs — cron, one-shot, and recurring-interval schedules; execution history

Total: 112 RPCs across 5 services.