Skip to main content
Conventions

API Overview

Manage cloud-hosted AI Agents through a RESTful JSON API — create Agents, configure environments, run sessions, and stream events. The API is in Beta. Some features may be adjusted in future releases.

Gateway URL

EnvironmentURL
Productionhttps://api.qoder.com.cn/api/v1/cloud

Versioning

The current API version is v1. All endpoints carry the version in the URL path (/v1/), so no separate version header is required.

Available APIs

ResourceDescriptionBase path
AgentsCreate, list, update, delete, and archive Agent instances/agents
EnvironmentsManage runtime environment configurations/environments
SessionsCreate Agent sessions and manage their lifecycle/sessions
EventsRead and stream session events/events
FilesUpload files and associate them with sessions/files
VaultsStore sensitive credentials securely/vaults
SkillsRegister and manage Agent skills/skills
Memory StoresPersist memory for Agent context/memory_stores
DeploymentsScheduled deployment automation/deployments
Forward TemplatesForward Agent template definitions, versioning, archiving, and cloning/api/v1/forward/templates
Forward IdentitiesCreate, enable, disable, delete Forward identities and query Agents/api/v1/forward/identities
Forward Identity ConfigsPer-identity template configuration and effective configuration queries/api/v1/forward/identities/{identity_id}/templates
Forward ChannelsForward channel and QR code session management/api/v1/forward/channels, /api/v1/forward/qr_sessions
Forward SessionsForward session lifecycle, events, and SSE streaming/api/v1/forward/sessions
Forward ResourcesRegister and list Forward external resources/api/v1/forward/resources
Forward SchedulesForward scheduled task and run record management/api/v1/forward/schedules, /api/v1/forward/schedule_runs

Request size limits

  • Maximum request body size: 4 MB.
  • Larger bodies are truncated on the server, which causes JSON parsing to fail. The API then returns a 400 invalid_request_error with the message: "Request body must be valid JSON."

Request headers

Every request must include the Authorization header. The Content-Type header is recommended but optional — the server auto-detects JSON: 
Authorization: Bearer $QODER_PAT
Content-Type: application/json

Beta status

  1. The API is broadly stable, but request signatures may see minor adjustments in future iterations.
  2. New features ship under new beta identifiers.
  3. In production, pin the API version and add compatibility handling.
  4. All current features work without an additional Beta header.

Quick connectivity check

# List Agents under the current account to verify authentication and connectivity
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_PAT"
A successful response looks like: 
{
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

Rate limiting

No application-level rate limits apply today. The gateway enforces global burst-traffic controls and DDoS protection, which may return 429 or 503 responses under heavy load. Retry 5xx and 429 responses with exponential backoff (1 s, 2 s, 4 s — up to three attempts).

What's next

  • Authentication — get and use a personal access token (PAT).
  • Errors — look up error codes and troubleshooting steps.
  • Pagination — paginate list endpoints.
Guides
Tutorials
API Reference