API Reference
40+ REST endpoints covering authentication, agent management, AI features, billing, and system health. All endpoints return JSON and require Bearer token authentication in production.
Authentication
The API provides two authentication paths: a Bearer token for programmatic access, and a session cookie for the dashboard. In production, API requests require a Bearer token set via the API_TOKEN environment variable:
Authorization: Bearer your-api-token- Bearer token — required on all endpoints in production, set via
API_TOKEN /api/health— exempt from authentication, so uptime checks work without a token- Dashboard sessions — use a session cookie set during login instead of a Bearer token
Rate Limits
| Scope | Limit | Window |
|---|---|---|
| General API | 120 requests | 1 minute |
| Heavy operations | 10 requests | 1 minute |
Heavy rate limiting applies to these endpoints:
clone-urlmedia/produceleads/scrapebatchgrok/querybrowser/execute3d/scenesvibe-design/projects
System
Server health check. Returns uptime, memory usage, version, and environment.
Authentication Endpoints
Authenticate a user. Sets a session cookie and returns a token.
// Request body
{ "email": "[email protected]", "password": "..." }
// Response
{ "token": "session-token", "plan": "pro" }Get current session info. Returns email and subscription plan.
Invalidate the current session and clear the cookie.
Agents & Skills
List all available agents with metadata (name, model, tier, description).
List all available skills with descriptions and input schemas.
Send a task to the Orchestrator for intelligent routing and execution.
Design System
Get the current DESIGN.md content with reasoning and token layers.
Clone a brand's design system from a URL. Heavy rate limited.
// Request body
{ "url": "https://example.com" }
// Response
{ "design": { "reasoning": {...}, "tokens": {...} } }Export the design system as DESIGN.md, CSS variables, JSON tokens, or Tailwind config.
Media & 3D
Start a media production job (video, image, audio). Heavy rate limited.
Generate a Blender 3D scene from a text prompt. Heavy rate limited.
Create a new Vibe Design Studio project. Heavy rate limited.
Monetization
Start a lead scraping job for a target industry. Heavy rate limited.
Submit a batch content generation job. Heavy rate limited.
// Request body
{
"type": "blog|social|product|email|seo",
"prompt": "Topic or instructions",
"count": 10 // max: 100
}AI Queries
Send a real-time query to Grok (grok-4.5) for live data. Heavy rate limited.
Execute a headless browser task. Heavy rate limited.
Branding
Returns this instance's branding (company name, tagline, logo, colors). Public, no auth required.
Update this instance's branding — theme your own self-hosted dashboard with your company name, logo, and colors. Admin only.
Knowledge Graph
List all knowledge graph entries with metadata.
Add a new entry to the knowledge graph.
Error Responses
All endpoints return standard error objects:
{
"error": "Description of what went wrong"
}| Status | Meaning |
|---|---|
400 | Bad Request — Missing or invalid parameters |
401 | Unauthorized — Missing or invalid API token |
403 | Forbidden — Valid token but insufficient permissions |
404 | Not Found — Resource does not exist |
429 | Too Many Requests — Rate limit exceeded |
500 | Server Error — Unexpected failure |
Frequently Asked Questions
Does the AI OS API require authentication?
Yes. In production, API requests require a Bearer token set via the API_TOKEN environment variable, sent as an Authorization: Bearer header. The /api/health endpoint is exempt, and dashboard access uses session cookies set during login instead of a token.
What are the API rate limits?
General API requests are limited to 120 per minute. Heavy operations — clone-url, media/produce, leads/scrape, batch, grok/query, browser/execute, 3d/scenes, and vibe-design/projects — are limited to 10 per minute.
What happens when the rate limit is exceeded?
The API returns a 429 Too Many Requests status with a standard error object describing what went wrong.
What does an API error response look like?
Every endpoint returns a JSON object with an error field describing the problem, alongside a standard HTTP status code — 400 for bad requests, 401 for missing or invalid tokens, 403 for insufficient permissions, 404 for missing resources, 429 for rate limiting, and 500 for server errors.
How many REST endpoints does the API expose?
The AI OS API offers 40+ REST endpoints covering authentication, agent and skill management, the design system, media and 3D generation, monetization, AI queries, tenant branding, and the knowledge graph. All endpoints return JSON.
Can I submit a batch content generation job through the API?
Yes. POST /api/batch accepts a type (blog, social, product, email, or seo), a prompt, and a count of up to 100 items, and is heavy rate limited.