Skip to content

API Design

Overview

The system exposes RESTful APIs for CRUD operations and WebSocket connections for real-time communication. Each agent service provides its own API endpoints, with the API Gateway handling routing based on URL patterns.

API Gateway Routes

The API Gateway routes requests to services based on path prefixes:

  • /api/projects/* → Project Agent Service
  • /api/agents/project/* → Project Agent chat endpoints
  • /api/agents/image/* → Image Generation Agent
  • /api/agents/video/* → Video Generation Agent
  • /api/agents/text/* → Text Generation Agent
  • /ws/* → WebSocket connections

REST API Specifications

Project Agent Service

Chat Endpoints

POST /api/agents/project/{project_id}/chat

Request:
{
    "message": "Create an activity for character generation",
    "user_id": "uuid"
}

Response:
{
    "response": "I'll create a character generation activity for you...",
    "actions_taken": [
        {
            "type": "activity_created",
            "activity_id": "uuid",
            "title": "Character Generation"
        }
    ]
}

Project Management

GET /api/projects/{project_id}

Response:
{
    "id": "uuid",
    "title": "My Video Project",
    "description": "A story about...",
    "created_at": "2024-01-01T00:00:00Z",
    "activities": [
        {
            "id": "uuid",
            "title": "Character Generation",
            "task_type": "image_generation",
            "position": 0
        }
    ]
}

POST /api/projects

Request:
{
    "title": "New Project",
    "description": "Project description"
}

Response:
{
    "id": "uuid",
    "title": "New Project",
    "description": "Project description",
    "created_at": "2024-01-01T00:00:00Z"
}

Specialized Agent Services

Chat Endpoints

POST /api/agents/{agent_type}/{card_id}/chat

Request:
{
    "message": "Change the model to DALL-E 3",
    "user_id": "uuid"
}

Response:
{
    "response": "I've updated the model to DALL-E 3...",
    "parameter_updates": {
        "model": "dall-e-3"
    }
}

Job Completion Callback

POST /api/agents/{agent_type}/{card_id}/job-completion

Request:
{
    "job_id": "uuid",
    "status": "completed",
    "result_url": "https://storage.example.com/result.png"
}

Response:
{
    "status": "processed"
}

Job Queue Service

POST /api/jobs

Request:
{
    "card_id": "uuid",
    "params": {
        "model": "stable-diffusion-xl",
        "prompt": "A heroic warrior",
        "resolution": "1024x1024"
    }
}

Response:
{
    "job_id": "uuid",
    "status": "queued",
    "created_at": "2024-01-01T00:00:00Z"
}

GET /api/jobs/{job_id}

Response:
{
    "id": "uuid",
    "card_id": "uuid",
    "status": "completed",
    "result_url": "https://storage.example.com/result.png",
    "created_at": "2024-01-01T00:00:00Z",
    "completed_at": "2024-01-01T00:05:00Z"
}

WebSocket Protocol

Connection Establishment

// Client connects with authentication
const ws = new WebSocket('wss://api.example.com/ws/project/{project_id}?token={jwt_token}');

Message Types

Client to Server

Chat Message

{
    "type": "chat_message",
    "agent_type": "project_agent",
    "context_id": "project_uuid",
    "message": "User's message",
    "user_id": "uuid"
}

Subscribe to Updates

{
    "type": "subscribe",
    "channels": ["job_updates", "agent_responses"],
    "context_id": "card_uuid"
}

Server to Client

Agent Response

{
    "type": "agent_response",
    "agent_type": "image_generation_agent",
    "context_id": "card_uuid",
    "message": "Agent's response",
    "timestamp": "2024-01-01T00:00:00Z"
}

Job Status Update

{
    "type": "job_update",
    "job_id": "uuid",
    "card_id": "uuid",
    "status": "processing",
    "progress": 45,
    "timestamp": "2024-01-01T00:00:00Z"
}

Job Completion

{
    "type": "job_completed",
    "job_id": "uuid",
    "card_id": "uuid",
    "status": "completed",
    "result_url": "https://storage.example.com/result.png",
    "timestamp": "2024-01-01T00:00:00Z"
}

MCP Server / ToolNode Interface

The MCP Server provides a unified interface for agents to retrieve context and perform operations.

Context Retrieval

GET /mcp/project-memory/{project_id}

Response:
{
    "project": {
        "id": "uuid",
        "title": "Project Title",
        "description": "Description"
    },
    "activities": [...],
    "task_cards": [...],
    "approved_assets": [...],
    "recent_jobs": [...]
}

GET /mcp/card-memory/{card_id}

Response:
{
    "card": {
        "id": "uuid",
        "title": "Card Title",
        "generation_params": {...}
    },
    "activity": {
        "task_type": "image_generation"
    },
    "jobs": [...],
    "assets": [...]
}

Model Discovery

GET /mcp/models/{task_type}

Response:
{
    "models": [
        {
            "id": "stable-diffusion-xl",
            "name": "Stable Diffusion XL",
            "capabilities": "High-quality realistic and artistic images",
            "parameters": {
                "resolutions": ["1024x1024", "1152x896"],
                "max_guidance_scale": 20
            }
        }
    ]
}

Operations

POST /mcp/activities

Request:
{
    "project_id": "uuid",
    "title": "Activity Title",
    "description": "Description",
    "task_type": "image_generation"
}

Response:
{
    "id": "uuid",
    "project_id": "uuid",
    "title": "Activity Title",
    "task_type": "image_generation",
    "position": 0
}

POST /mcp/task-cards

Request:
{
    "activity_id": "uuid",
    "title": "Task Card Title",
    "description": "Description"
}

Response:
{
    "id": "uuid",
    "activity_id": "uuid",
    "title": "Task Card Title",
    "generation_params": {}
}

PUT /mcp/task-cards/{card_id}/generation-params

Request:
{
    "model": "dall-e-3",
    "resolution": "1024x1024",
    "prompt": "Updated prompt"
}

Response:
{
    "card_id": "uuid",
    "generation_params": {
        "model": "dall-e-3",
        "resolution": "1024x1024",
        "prompt": "Updated prompt"
    }
}

Error Handling

All APIs follow a consistent error response format:

{
    "error": {
        "code": "RESOURCE_NOT_FOUND",
        "message": "Project not found",
        "details": {
            "project_id": "uuid"
        }
    },
    "timestamp": "2024-01-01T00:00:00Z"
}

Standard Error Codes

  • VALIDATION_ERROR - Invalid request parameters
  • RESOURCE_NOT_FOUND - Requested resource doesn't exist
  • UNAUTHORIZED - Authentication required
  • FORBIDDEN - Insufficient permissions
  • CONFLICT - Resource state conflict
  • INTERNAL_ERROR - Server error

Authentication & Authorization

JWT Token Structure

{
    "user_id": "uuid",
    "email": "user@example.com",
    "exp": 1234567890,
    "iat": 1234567890
}

Required Headers

Authorization: Bearer <jwt_token>
Content-Type: application/json
X-Request-ID: <unique_request_id>

Rate Limiting

Rate limits are enforced at the API Gateway level:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1234567890

Versioning

API versioning is handled through URL paths:

  • Current version: /api/v1/*
  • Future versions: /api/v2/*

Deprecation notices are provided via headers:

Sunset: Sat, 31 Dec 2024 23:59:59 GMT
Deprecation: true
Link: <https://api.example.com/api/v2/docs>; rel="successor-version"

OpenAPI Specification

Each service provides OpenAPI documentation at:

  • /api/docs - Interactive Swagger UI
  • /api/openapi.json - OpenAPI specification

Example OpenAPI snippet:

openapi: 3.0.0
info:
  title: Digital Product Creation API
  version: 1.0.0
paths:
  /api/agents/project/{project_id}/chat:
    post:
      summary: Send message to project agent
      parameters:
        - name: project_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                user_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Agent response
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: string
                  actions_taken:
                    type: array