Open API Documentation

Connect TjAgentForge to your own systems and AI clients: the Open REST API (read + controlled writes) and an MCP server. Both share the same keys, the same execution path, and the same audit trail.

1. Authentication

Create a key on the console's "API Keys" page and send it in the Authorization header. Only a fingerprint is stored (irreversible); the plaintext is shown once at creation, and revocation takes effect immediately.

Authorization: Bearer tjaf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes: read (read-only) / write (controlled writes) / admin (manage this tenant's keys). allow_high_risk is a separate switch, not a scope.

2. REST calls

Read endpoint (requires the read scope):

curl -s https://tjagentforge.com/api/open/v1/projects \
  -H "Authorization: Bearer $TJAF_KEY"

Write endpoint (requires the write scope):

curl -s -X POST "https://tjagentforge.com/api/open/v1/tunings/$TUNING_ID/apply" \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Every response uses the {code, message, data} envelope; code=0 means success.

3. Controlled writes: the Open API never raises the automation level

At the default level a write is not executed immediately — the API returns needs_confirmation with a confirm_url, and it runs only after the key's owner approves it in the console. It executes directly only when the tenant is on full_auto. Irreversible high-risk actions are always rejected.

{
  "code": 0,
  "message": "ok",
  "data": {
    "status": "needs_confirmation",
    "action_id": "…",
    "confirm_url": "https://tjagentforge.com/dashboard/chat?s=…",
    "expires_at": "2026-01-01T00:15:00Z"
  }
}

4. MCP integration

MCP is a single Streamable HTTP endpoint speaking JSON-RPC 2.0, usable by any MCP-capable client (same API key authentication as REST).

Handshake and tool listing:

curl -s https://tjagentforge.com/api/open/mcp \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}'

# 列出可用工具（按密钥作用域过滤）
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Calling a tool (write tools also return needs_confirmation):

curl -s https://tjagentforge.com/api/open/mcp \
  -H "Authorization: Bearer $TJAF_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"project.list","arguments":{}}}'

5. Error codes

40103 — invalid or revoked key
40302 — insufficient scope
40303 — allow_high_risk required; or the action is irreversible and therefore rejected
42901 — rate limit or task quota exhausted (see message)

6. Machine-readable contract

The OpenAPI description can be imported into Postman or a client generator (a valid key is required):

curl -s https://tjagentforge.com/api/open/v1/openapi.json \
  -H "Authorization: Bearer $TJAF_KEY"