REST API Reference

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

{
  "runtime": { "version": "1.0.0", "state": "Online" },
  "postgres": { "state": "Online", "port": 5480 },
  "forge": { "state": "Offline", "port": null }
}

// Request
{
  "username": "alice",
  "password": "Str0ngPass!x",
  "email": "alice@example.com",    // optional
  "display_name": "Alice Martin"   // optional
}

// Response 201
{
  "user": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "username": "alice",
    "email": "alice@example.com",
    "display_name": "Alice Martin",
    "created_at": "2024-01-15T10:30:00+00:00"
  }
}

// Response 200
{ "authRequired": true }

// Request
{ "username": "alice", "password": "Str0ngPass!x" }

// Response 200
{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "expiresIn": 900,
  "user": {
    "id": "3fa85f64-...",
    "username": "alice",
    "email": "alice@example.com",
    "display_name": "Alice Martin",
    "created_at": "2024-01-15T10:30:00+00:00"
  }
}

// Request
{ "refreshToken": "eyJ..." }

// Response 200
{ "accessToken": "eyJ...", "expiresIn": 900 }

// Request
{ "refreshToken": "eyJ..." }

// Response 200
{ "message": "logged out" }

// Request body: AppManifest object
{
  "appId": "crm",
  "name": "My CRM",
  "version": "1.0.0",
  "dataContract": [...],
  "permissions": {...}
}

// Response 200
{
  "message": "app 'crm' installed"
}

{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "first_name": "Alice",
  "last_name": "Martin",
  "email": "alice@acme.com",
  "tags": ["vip", "enterprise"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

// Request
{
  "method": "sendWelcomeEmail",
  "params": { "contactId": "f47ac10b..." }
}

// Response 200 -- the handler's return value is returned directly
{ "sent": true }

// Error response
{ "error": "Failed to connect to SMTP server" }

{
  "app_id": "crm",
  "status": "running"
}

// Request
{
  "payload": { "type": "send_report", "userId": "..." }
}

// Response 201
{ "job_id": "a1b2c3d4-..." }

// Job object (from GET)
{
  "id": "a1b2c3d4-...",
  "app_id": "crm",
  "status": "completed",
  "payload": { "type": "send_report", "userId": "..." },
  "result": { "sent": true },
  "error": null,
  "attempts": 1
}

// POST /api/v1/apps/crm/secrets
// Request
{ "key": "OPENAI_API_KEY", "value": "sk-..." }
// Response
{ "message": "secret 'OPENAI_API_KEY' set" }

// GET /api/v1/apps/crm/secrets
// Response -- key names only, never values
["OPENAI_API_KEY", "STRIPE_SECRET_KEY", "SMTP_PASSWORD"]

// POST /api/v1/apps/crm/roles/assign
{ "userId": "3fa85f64-...", "role": "admin" }

// GET /api/v1/apps/crm/permissions
{
  "roles": ["admin"],
  "permissions": ["contacts.create", "contacts.read", "contacts.update", "contacts.delete", "deals.create", "deals.read", "deals.update", "deals.delete"]
}

# Query parameters
$ GET /api/v1/audit
  ?app_id=crm         # Filter by app (matches table_schema)
  &entity=contacts    # Filter by table name
  &limit=100          # Max results (default 100, max 1000)

[
  {
    "id": 1001,
    "table_schema": "crm",
    "table_name": "contacts",
    "record_id": "f47ac10b-...",
    "operation": "UPDATE",
    "old_record": { "email": "alice@old.com" },
    "new_record": { "email": "alice@acme.com" },
    "changed_at": "2024-01-15T10:30:00Z"
  }
]

{ "error": "human-readable error message" }