API Reference

POST /api/auth/token
Content-Type: application/json
 
{
  "email": "user@example.com",
  "password": "password"
}

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Authorization: Bearer <token>

GET /api/conversations

{
  "conversations": [
    {
      "id": "uuid",
      "name": "My Build",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T11:45:00Z"
    }
  ]
}

GET /api/conversations/{id}

POST /api/conversations
Content-Type: application/json
 
{
  "name": "New Build Configuration"
}

DELETE /api/conversations/{id}

POST /api/chat
Content-Type: application/json
 
{
  "conversationId": "uuid",
  "message": "Create a Debian server with SSH and Docker"
}

{
  "messageId": "uuid",
  "response": "I'll create a Debian Bookworm server with...",
  "recipe": { ... }
}

GET /api/chat/stream?conversationId={id}&message={text}
Accept: text/event-stream

POST /api/builds
Content-Type: application/json
 
{
  "conversationId": "uuid"
}

{
  "buildId": "uuid",
  "status": "pending"
}

GET /api/builds/{id}

{
  "id": "uuid",
  "status": "building",
  "stage": "Config Agent",
  "progress": 45,
  "startedAt": "2025-01-15T10:30:00Z"
}

GET /api/streams/builds/{id}
Accept: text/event-stream

GET /api/builds/{id}/logs

GET /api/builds/{id}/download

GET /api/builds/{id}/tests

{
  "status": "passed",
  "tests": [
    {
      "description": "Boot verification",
      "status": "passed",
      "duration": 45.2
    },
    {
      "description": "Service check",
      "status": "passed",
      "assertions": [
        {
          "type": "service_running",
          "params": { "service": "ssh" },
          "result": "passed"
        }
      ]
    }
  ]
}

POST /api/builds/{id}/tests
Content-Type: application/json
 
{
  "assertions": [
    {
      "type": "http_responds",
      "params": { "url": "http://localhost/health" }
    }
  ]
}

GET /api/organizations

GET /api/organizations/{id}

POST /api/organizations
Content-Type: application/json
 
{
  "name": "My Company"
}

GET /api/organizations/{id}/members

POST /api/organizations/{id}/invites
Content-Type: application/json
 
{
  "email": "user@example.com",
  "role": "member"
}

GET /api/organizations/{orgId}/units

POST /api/organizations/{orgId}/units
Content-Type: application/json
 
{
  "name": "Engineering",
  "type": "business"
}

GET /api/units/{id}

GET /api/units/{unitId}/teams

POST /api/units/{unitId}/teams
Content-Type: application/json
 
{
  "name": "Platform Team"
}

GET /api/teams/{id}

POST /api/conversations/{id}/shares
Content-Type: application/json
 
{
  "targetType": "user",
  "targetId": "user-uuid",
  "permission": "edit"
}

GET /api/conversations/{id}/shares

DELETE /api/conversations/{id}/shares/{shareId}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

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

POST /api/webhooks
Content-Type: application/json
 
{
  "url": "https://example.com/webhook",
  "events": ["build.completed", "build.failed"]
}