API Overview

Uranus provides a comprehensive REST API for all agent operations.

Base URL

https://your-domain.com/api

For local development:

http://localhost:8787/api

Authentication

Cloudflare Access

When Cloudflare Access is enabled, include the JWT:

curl https://your-domain.com/api/agents \
  -H "CF-Access-JWT-Assertion: <jwt-token>"

No Authentication

For public access or development:

curl https://your-domain.com/api/agents

Response Format

Success Response

{
  "data": { ... },
  "meta": {
    "total": 100,
    "limit": 50,
    "offset": 0
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  }
}

HTTP Status Codes

Code	Description
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
429	Rate Limited
500	Server Error

Common Patterns

List Resources

GET /api/agents/{id}/workflows?limit=50&offset=0

Query parameters:

• limit - Maximum results (default: 50)
• offset - Skip results (default: 0)
• search - Text search
• sort - Sort field
• order - asc/desc

Get Resource

GET /api/agents/{id}/workflows/{workflowId}

Create Resource

POST /api/agents/{id}/workflows
Content-Type: application/json

{
  "name": "New Workflow",
  "description": "..."
}

Update Resource

PUT /api/agents/{id}/workflows/{workflowId}
Content-Type: application/json

{
  "name": "Updated Name"
}

Delete Resource

DELETE /api/agents/{id}/workflows/{workflowId}

Rate Limiting

Rate limits apply per IP:

Endpoint	Limit
General	100/min
AI Chat	20/min
Browser	50/min
Bulk Operations	10/min

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702648800

Pagination

Offset-Based

GET /api/agents/{id}/contacts?limit=50&offset=100

Response includes meta:

{
  "data": [...],
  "meta": {
    "total": 500,
    "limit": 50,
    "offset": 100
  }
}

Cursor-Based

GET /api/agents/{id}/messages?cursor=abc123&limit=50

Response includes cursor:

{
  "data": [...],
  "meta": {
    "next_cursor": "def456",
    "has_more": true
  }
}

Filtering

Simple Filter

GET /api/agents/{id}/schedules?status=active

Multiple Values

GET /api/agents/{id}/contacts?tag=vip&tag=customer

Date Range

GET /api/agents/{id}/logs?from=2024-12-01&to=2024-12-31

Sorting

GET /api/agents/{id}/workflows?sort=created_at&order=desc

Multiple sorts:

GET /api/agents/{id}/contacts?sort=name,created_at&order=asc,desc

Search

GET /api/agents/{id}/contacts?search=john

Searches across relevant fields.

CORS

CORS is enabled for all origins:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Webhooks

Register webhooks for events:

POST /api/agents/{id}/webhooks
{
  "url": "https://your-server.com/webhook",
  "events": ["workflow.complete", "message.received"]
}

SDK

JavaScript/TypeScript

import { UranusClient } from '@uranus/sdk'

const client = new UranusClient({
  baseUrl: 'https://your-domain.com',
  apiKey: 'your-api-key'
})

const workflows = await client.workflows.list('agent-id')

Python

from uranus import UranusClient

client = UranusClient(
    base_url='https://your-domain.com',
    api_key='your-api-key'
)

workflows = client.workflows.list('agent-id')

API Reference

Category	Endpoints
Agents	Agent management
Workflows	Workflow CRUD and execution
Schedules	Task scheduling
Calendar	Calendar tasks
Chat	AI conversation
Browser	Browser automation
Contacts	Contact management
Sources	Data sources and RAG
MCP	MCP server integration
Gateways	Communication channels
Tools	Agent tools
Settings	Agent configuration
SQL	Database queries
Chat	Real-time communication (SSE + WebSocket)