Reference

API Reference

Complete reference for Contd.ai REST API, gRPC services, and SDKs.

Authentication

All API requests require authentication via one of:

•JWT Token: For user sessions (obtained via login)
•API Key: For programmatic access (created per organization)

headers

# Using JWT Token
Authorization: Bearer <jwt_token>

# Using API Key
X-API-Key: ctd_your_api_key_here

Base URL

https://api.contd.ai/v1

Workflow Endpoints

POST/workflows

Request Body

{
  "name": "my_workflow",
  "version": "1.0.0",
  "definition": {
    "steps": [
      { "id": "step1", "type": "llm", "config": {...} },
      { "id": "step2", "type": "script", "config": {...} }
    ]
  }
}

Response

{
  "id": "wf_abc123",
  "name": "my_workflow",
  "version": "1.0.0",
  "created_at": "2026-01-28T10:00:00Z"
}

POST/workflows/:workflow_id/trigger

Trigger a workflow execution.

Request Body

{
  "input": {
    "message": "Hello, world!",
    "user_id": "usr_123"
  }
}

Response

{
  "run_id": "run_xyz789",
  "workflow_id": "wf_abc123",
  "status": "running",
  "started_at": "2026-01-28T10:00:00Z"
}

GET/workflows/:workflow_id/runs/:run_id

Get workflow run status and details.

Response

{
  "run_id": "run_xyz789",
  "workflow_id": "wf_abc123",
  "status": "completed",
  "started_at": "2026-01-28T10:00:00Z",
  "completed_at": "2026-01-28T10:02:15Z",
  "steps": [
    { "id": "step1", "status": "completed", "duration_ms": 1200 },
    { "id": "step2", "status": "completed", "duration_ms": 800 }
  ],
  "output": { "result": "Success!" }
}

SDK Examples

Python SDK

example.py

from contd import Client, workflow, step

client = Client(api_key="ctd_your_api_key")

@workflow
async def my_workflow(ctx):
    result = await ctx.run(process_data, ctx.input)
    return await ctx.run(generate_output, result)

# Register and trigger
client.register(my_workflow)
run = await client.trigger("my_workflow", {"data": "input"})

# Wait for completion
result = await client.wait_for_completion(run.id)
print(result.output)

TypeScript SDK

example.ts

import { Client, workflow, step } from '@contd/sdk';

const client = new Client({ apiKey: 'ctd_your_api_key' });

const myWorkflow = workflow('my_workflow', async (ctx) => {
  const result = await ctx.run(processData, ctx.input);
  return await ctx.run(generateOutput, result);
});

// Register and trigger
client.register(myWorkflow);
const run = await client.trigger('my_workflow', { data: 'input' });

// Wait for completion
const result = await client.waitForCompletion(run.id);
console.log(result.output);

Error Codes

Code	Description
400	Bad Request - Invalid input
401	Unauthorized - Invalid or missing credentials
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limits

Plan	Requests/min	Concurrent Workflows
Free	60	5
Pro	600	50
Enterprise	Unlimited	Unlimited