FastClaw Upstream App Integration API

This is the integration contract for upstream applications that want to use FastClaw as their Agent runtime.

Use this document when building a SaaS, bot, marketplace, or workflow product that owns its own users but delegates agent execution, tools, memory, usage metering, quota checks, and optional channels to FastClaw.

Which Interface To Use

Need	Interface	Notes
End-user chat with an agent	`/v1/chat/completions`	OpenAI-compatible, plus FastClaw extensions. This is the primary upstream app API.
List callable agents for an API key	`GET /v1/agents`	Respects API-key scope.
Provision one upstream end-user	`POST /v1/users`	Optional. Chat can lazy-provision via `user` or `X-Fastclaw-End-User`.
Query usage / token spend	`GET /v1/usage`	For upstream billing dashboards.
Set paid-plan limits	`/v1/quota`	For subscription and entitlement enforcement.
Admin/dashboard automation	`/api/*` or `fastclaw ...` CLI	Cookie/admin oriented, broader surface, not the minimal upstream app contract.
Coding-agent live preview runtime	`docs/coding-agent-runtime.md`	Project/runtime endpoints are documented separately.

For a normal upstream product, start with /v1/*. Do not build against dashboard internals unless the product is also administering FastClaw.

Authentication

Use an API key:

Authorization: Bearer fcak_...

API key types:

Type	Intended use
`admin`	Platform automation. Can operate broadly. Keep server-side only.
`user`	App backend acting as one FastClaw owner account. Can use that owner's agents.
`agent`	App backend scoped to explicit agent IDs. Recommended for single-agent integrations.

Do not expose FastClaw API keys in browsers or mobile apps. The upstream app backend should call FastClaw and map its own auth/session model to FastClaw user or X-Fastclaw-End-User.

Identity Model

FastClaw has its own user_id because memory, sessions, usage, quotas, and per-user preferences need a stable isolation key.

For upstream apps, there are two supported patterns:

Explicit provisioning:

POST /v1/users
Authorization: Bearer fcak_...
Content-Type: application/json

{
  "external_id": "upstream-user-123",
  "display_name": "Alice"
}

Response:

{
  "user_id": "u_...",
  "external_id": "upstream-user-123"
}

Lazy provisioning on chat:

Pass either:
- body field: "user": "upstream-user-123"
- header: X-Fastclaw-End-User: upstream-user-123
FastClaw will create or reuse the app-user row for that API key.

Use the upstream user's stable internal ID, not email or display name. That keeps identity stable if the user changes their profile.

Chat API

`POST /v1/chat/completions`

OpenAI-compatible endpoint with FastClaw extensions.

Required:

messages: array with at least one user message

Agent selection:

Preferred: body field agent_id
Alternative: X-Fastclaw-Agent-ID header
If omitted, FastClaw resolves the default accessible agent for the caller

Session selection:

Header: X-Fastclaw-Session-Key
If omitted, FastClaw creates an API session key for that turn

Request:

POST /v1/chat/completions
Authorization: Bearer fcak_...
Content-Type: application/json
X-Fastclaw-Session-Key: chat-upstream-user-123-default

{
  "agent_id": "agt_...",
  "model": "ignored-by-fastclaw-agent-config",
  "stream": true,
  "user": "upstream-user-123",
  "messages": [
    { "role": "user", "content": "帮我总结今天的订单异常" }
  ],
  "params": {
    "tenant_id": "tenant_1",
    "locale": "zh-CN"
  }
}

FastClaw extensions:

Field	Type	Purpose
`agent_id`	string	Agent to call. Body wins over header.
`user`	string	Upstream end-user ID. Body wins over `X-Fastclaw-End-User`.
`params`	object	Per-turn structured context shown to the agent. Not persisted.
`images`	string[]	Image URLs/data URLs shown to vision models and materialized into workspace.
`imageUrls`	string[]	Alias for `images`.
`attachments`	array	General files materialized into workspace. Use for PDFs, docs, zips, etc.

Attachment shape:

{
  "attachments": [
    {
      "url": "https://example.com/report.pdf",
      "name": "report.pdf"
    }
  ]
}

Streaming responses follow OpenAI SSE shape:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"..."},"index":0}]}

data: [DONE]

Non-streaming responses follow OpenAI response shape:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "agent",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Session Key Guidance

Choose a deterministic session key from your product model:

<app-name>:<upstream-user-id>:<conversation-id>

Do not reuse one session key for unrelated conversations. Session keys control chat history, memory extraction context, and usage grouping.

Agents

`GET /v1/agents`

Lists only agents accessible to the API key.

GET /v1/agents
Authorization: Bearer fcak_...

Response:

{
  "agents": [
    {
      "id": "agt_...",
      "name": "agt_...",
      "model": "openai/gpt-4.1-mini"
    }
  ]
}

For provisioning agents, cloning templates, installing skills, or configuring providers, use dashboard /api/* endpoints or the fastclaw CLI. Those are operator/admin workflows, not the minimal end-user chat API.

Usage And Quotas

`GET /v1/usage`

Returns token usage for the authenticated FastClaw user, or for a specific app-user when user_id is provided.

Query params:

Param	Required	Notes
`days`	no	Default `30`, max `90`.
`user_id`	no	FastClaw user ID returned by `/v1/users`.

GET /v1/usage?user_id=u_...&days=30
Authorization: Bearer fcak_...

Response:

{
  "userId": "u_...",
  "days": 30,
  "daily": [
    {
      "day": "2026-06-26",
      "agentId": "agt_...",
      "model": "gpt-4.1-mini",
      "inputTokens": 100,
      "outputTokens": 50,
      "cacheReadTokens": 0,
      "cacheCreationTokens": 0,
      "requestCount": 1
    }
  ],
  "totals": {
    "inputTokens": 100,
    "outputTokens": 50,
    "cacheReadTokens": 0,
    "cacheCreationTokens": 0,
    "requestCount": 1
  }
}

`PUT /v1/quota`

Sets paid-plan limits for a FastClaw user.

PUT /v1/quota
Authorization: Bearer fcak_...
Content-Type: application/json

{
  "user_id": "u_...",
  "monthly_token_limit": 5000000,
  "monthly_request_limit": 10000,
  "reset_day": 1
}

Limits of 0 mean no limit for that dimension. reset_day must be 1..28; invalid values are normalized to 1.

`GET /v1/quota`

GET /v1/quota?user_id=u_...
Authorization: Bearer fcak_...

Returns the configured quota and, when usage metering is enabled, current status.

`DELETE /v1/quota`

DELETE /v1/quota?user_id=u_...
Authorization: Bearer fcak_...

Removes explicit quota and reverts the user to unlimited FastClaw-side quota.

Recommended Upstream Flow

Operator creates/configures an agent in FastClaw.
Operator creates an agent API key scoped to that agent.
Upstream backend stores the API key server-side.
When a product user starts:
- call POST /v1/users, or use lazy provisioning via chat user
- store the returned user_id if you need usage/quota lookups
For each conversation:
- send POST /v1/chat/completions
- set agent_id
- set a deterministic X-Fastclaw-Session-Key
- set user to the upstream stable user ID
On subscription changes:
- call PUT /v1/quota
For billing dashboards:
- call GET /v1/usage

Error Shape

FastClaw returns JSON errors compatible with OpenAI-style clients:

{
  "error": {
    "message": "agent not found",
    "type": "not_found_error"
  }
}

Common statuses:

Status	Meaning
`400`	Bad request body, missing messages, missing user_id, etc.
`401`	Missing/invalid API key.
`404`	Agent not found or not accessible by this API key.
`429`	Rate limited or quota exceeded.
`503`	Usage/quota subsystem not configured for that endpoint.

What To Give An Agent

When asking an AI coding agent to integrate an upstream app with FastClaw, give it:

This document.
The FastClaw base URL.
API key type and scope.
Agent ID.
Your upstream user ID field.
Your conversation/session ID field.
Whether you need usage/quota billing integration.

If the agent supports Skills, install or load:

skills/fastclaw-api-integration/SKILL.md

That skill is the short operational version of this API contract.

Navigation Menu

Uh oh!

FastClaw Upstream App Integration API

Which Interface To Use

Authentication

Identity Model

Chat API

`POST /v1/chat/completions`

Session Key Guidance

Agents

`GET /v1/agents`

Usage And Quotas

`GET /v1/usage`

`PUT /v1/quota`

`GET /v1/quota`

`DELETE /v1/quota`

Recommended Upstream Flow

Error Shape

What To Give An Agent

Uh oh!

FilesExpand file tree

upstream-api.md

Latest commit

History

upstream-api.md

File metadata and controls

FastClaw Upstream App Integration API

Which Interface To Use

Authentication

Identity Model

Chat API

POST /v1/chat/completions

Session Key Guidance

Agents

GET /v1/agents

Usage And Quotas

GET /v1/usage

PUT /v1/quota

GET /v1/quota

DELETE /v1/quota

Recommended Upstream Flow

Error Shape

What To Give An Agent

`POST /v1/chat/completions`

`GET /v1/agents`

`GET /v1/usage`

`PUT /v1/quota`

`GET /v1/quota`

`DELETE /v1/quota`