API Overview

About the API

The Compozy REST API serves as the central management interface for the workflow orchestration engine, providing powerful capabilities for building and managing AI-powered automation systems.

RESTful Design

Standard HTTP methods, status codes, and consistent JSON communication patterns

OpenAPI Specification

Complete Swagger documentation with interactive testing and code generation

Orchestration

Create, execute, and monitor complex AI agent workflows with sophisticated task coordination and state management

Manage Resources

Configure agents, tasks, tools, and schedules programmatically with full CRUD operations and validation

Monitor Operations

Access real-time execution status, comprehensive metrics, and detailed health information for production environments

Integrate Systems

Connect external applications and services seamlessly to Compozy workflows with standardized interfaces

API Categories

Workflows

Manage workflow definitions and executions. Create, start, pause, resume, and cancel AI-powered workflows with complex orchestration patterns.

Tasks

Access task configurations within workflows. Retrieve task definitions, parameters, and execution requirements for workflow components.

Agents

Discover and configure AI agents. Access agent definitions, LLM configurations, instructions, and available actions for workflow execution.

Tools

Manage external tool integrations. Retrieve tool definitions, schemas, and configurations for extending agent capabilities.

Schedules

Control scheduled workflow executions. Manage cron-based schedules, enable/disable recurring workflows, and configure timing parameters.

Memory

Manage persistent agent memory. Store, retrieve, and manage conversation context, agent state, and workflow memory across executions.

Operations

Monitor system health and metrics. Access Prometheus metrics, health checks, and operational data for production monitoring.

Getting Started

Configure Base URL

Set up your API client with the correct Compozy endpoint. All API endpoints are available at:

http://<your-compozy-instance>/api/v0

Authentication Setup

Configure secure access for API requests

Most endpoints require authentication. Include your API key in requests:

Authorization: Bearer your_api_key_here

Make Your First Request

Test the API with a simple workflow execution

# Execute a workflow
curl -X POST http://localhost:5001/api/v0/workflows/my-workflow/executions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{
    "input": {
      "message": "Hello, world!"
    }
  }'

Monitor Execution

Track workflow progress and retrieve results

Check execution status and retrieve outputs:

# Get execution status
curl -X GET http://localhost:5001/api/v0/executions/workflows/{execution_id} \
  -H "Authorization: Bearer your_api_key"

# Get execution outputs (when completed)
curl -X GET http://localhost:5001/api/v0/executions/workflows/{execution_id}/outputs \
  -H "Authorization: Bearer your_api_key"

Response Format Standards

Standard Success Response:

{
  "data": {
    "exec_id": "exec_01234567-89ab-cdef-0123-456789abcdef",
    "workflow_id": "my-workflow",
    "status": "running",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": "Workflow execution started successfully"
}

Authentication & Security

API Key Authentication
Use Bearer tokens in the Authorization header for secure API access
Role-Based Access
Different endpoints require different permission levels (read, write, admin)
Rate Limiting
Built-in rate limiting to prevent abuse and ensure fair resource usage
Request Validation
All inputs validated against JSON schemas before processing