The Arkloop API is a RESTful HTTP API with a base path of /v1.

Base URL

Environment	URL
Local Development (Direct)	`http://127.0.0.1:19001`
Local Development (via Gateway)	`http://127.0.0.1:19000`

Authentication

All protected endpoints require a Bearer Token in the request header:

Authorization: Bearer <access_token>

Tokens are obtained via POST /v1/auth/login. After expiration, use the Refresh Token to obtain a new token (POST /v1/auth/refresh). After login, the Refresh Token is stored in an HttpOnly cookie by the server; the front-end refreshes the Access Token by calling the refresh endpoint.

API Key authentication is also supported for some endpoints:

Authorization: Bearer al_...

Error Response Format

{
  "error": "error.code",
  "message": "human-readable description",
  "trace_id": "...",
  "details": {}
}

Common error codes:

HTTP Status Code	Error Code	Description
400	`validation.error`	Request parameter validation failed
401	`auth.unauthorized`	Unauthorized or invalid token
403	`auth.forbidden`	Insufficient permissions
404	`not_found`	Resource not found
409	`conflict`	Resource conflict (e.g., duplicate creation)
422	`validation.error`	Request body parsing failed
429	`rate_limit`	Request frequency limit exceeded
500	`internal_error`	Internal server error

Pagination

List endpoints that support pagination use cursor-based pagination:

GET /v1/threads?limit=20&before=<cursor>

SSE (Server-Sent Events)

Run execution progress is pushed via SSE events. For details, see Run Execution Endpoints.

Endpoint Index

Auth & Account

Auth — Login, registration, token refresh, email verification
Me — Personal info, usage, credits, invitation codes
API Keys — Programmatic access keys

Core Resources

Threads — session management
Messages — message reading and writing
Runs — Agent Loop execution
Projects — session grouping

Accounts

Accounts — personal and workspace accounts, memberships

Configuration

LLM Providers — provider accounts, model lists, and selector prefixes
MCP Configs — MCP server configuration
Tool Providers — tool backend and credential configuration
ASR Credentials — speech recognition credentials

Billing & Entitlements

Credits & Usage — credit management and usage statistics
Subscriptions & Plans — subscriptions and plans
Entitlements — entitlement coverage
API Keys — API key management

Notifications & Webhooks

Notifications — in-app notifications
Webhooks — event delivery

Admin

Admin Overview — summary of platform management endpoints
Audit Logs — operation auditing
IP Rules — access control
Feature Flags — feature toggles

System

Health Check — /healthz /readyz

API Overview