FastClaw / APIs and integrations
Upstream API
FastClaw provides /v1/* API for upstream applications. The core is OpenAI-compatible chat completions, plus agents, users, usage, and quota.
API boundaries
docs/upstream-api.md clearly states that /v1/* is a stable interface for upstream applications; /api/* and CLI are more focused on operator/admin workflow.
| interface | Purpose |
|---|---|
| POST /v1/chat/completions | OpenAI-compatible dialogue, supports stream and non-stream |
| GET /v1/agents | List Agents accessible by the current key |
| POST /v1/users | Explicitly create or bind app_user |
| GET /v1/usage | Query usage |
| /v1/quota | Query or consume quota-related capabilities |
Certification
The upstream API uses Authorization: Bearer fcak_…. API key types include admin, user, and agent. The documentation emphasizes not exposing keys to browsers or mobile devices.
curl http://localhost:18953/v1/chat/completions \
-H "Authorization: Bearer fcak_xxx" \
-H "Content-Type: application/json" \
-d '{"agent_id":"agt_xxx","messages":[{"role":"user","content":"Hello"}]}'Chat extension fields
In addition to OpenAI messages/model/stream, FastClaw also supports agent_id, user, params, images, imageUrls, attachments, and headers such as X-Fastclaw-Session-Key and X-Fastclaw-End-User.
- agent_id: Select the Agent that handles the request.
- user or X-Fastclaw-End-User: Maps the end user in the upstream product.
- attachments: The server will materialize to /workspace and inject the path into the message.
- X-Fastclaw-Session-Key: Allows upstream applications to stably reuse the same session.