API Reference

This document provides REST API endpoints for managing and triggering Xema Workflows.

Authentication
Base URL
Common Response Format
Workflow Management
Workflow Execution
Artifact Management
Template APIs
Error Handling

Authentication

All API requests require authentication:

bash

1curl -H "Authorization: Bearer $XEMA_TOKEN" https://workflow-engine-api.xema.dev/workflows/...

Token Management

Generate API tokens in the dashboard:

Settings → API Tokens → Generate Token

Rate Limiting

Free tier: 100 requests/minute
Pro tier: 1000 requests/minute
Enterprise: Custom limits

Rate limit headers:

text

1X-RateLimit-Limit: 1000
2X-RateLimit-Remaining: 999
3X-RateLimit-Reset: 1234567890

Base URL

https://workflow-engine-api.xema.dev

All endpoints are relative to this base URL.

Common Response Format

Success Response

json

1{
2  "success": true,
3  "data": {
4    "id": "resource_id",
5    "name": "resource_name"
6  },
7  "metadata": {
8    "timestamp": "2026-04-27T14:30:00Z",
9    "version": "1.0"
10  }
11}

Error Response

json

1{
2  "success": false,
3  "error": {
4    "code": "INVALID_INPUT",
5    "message": "The provided input is invalid",
6    "details": {
7      "field": "inputs.project_name",
8      "reason": "Required field missing"
9    }
10  }
11}

Pagination

List endpoints support pagination:

bash

1GET /workflows?page=1&limit=20

Response:

json

1{
2  "data": [...],
3  "pagination": {
4    "page": 1,
5    "limit": 20,
6    "total": 150,
7    "pages": 8
8  }
9}

Workflow Management

Get Workflow

Retrieve workflow details:

GET /workflows/{workflowId}

Parameters:

workflowId (path, required) — Workflow ID

Response:

json

1{
2  "data": {
3    "id": "wf_abc123",
4    "name": "my-workflow",
5    "projectId": "proj_123",
6    "version": "1.0.0",
7    "status": "active",
8    "createdAt": "2026-04-27T10:00:00Z",
9    "updatedAt": "2026-04-27T14:30:00Z",
10    "triggers": ["workflow_dispatch", "schedule"],
11    "jobCount": 5
12  }
13}

List Workflows

List all workflows in a project:

GET /projects/{projectId}/workflows

Parameters:

projectId (path, required) — Project ID
page (query, optional) — Page number (default: 1)
limit (query, optional) — Items per page (default: 20)
status (query, optional) — Filter by status (active, archived)

Response:

json

1{
2  "data": [
3    {
4      "id": "wf_abc123",
5      "name": "requirements-analysis",
6      "version": "1.0.0",
7      "status": "active",
8      "triggers": ["workflow_dispatch"],
9      "lastRun": "2026-04-27T14:00:00Z"
10    }
11  ],
12  "pagination": { ... }
13}

Create Workflow

Create a new workflow:

POST /projects/{projectId}/workflows

Body:

json

1{
2  "name": "my-workflow",
3  "description": "My first workflow",
4  "content": "apiVersion: xema.dev/workflow/v1alpha1\nkind: Workflow\n..."
5}

Response:

json

1{
2  "data": {
3    "id": "wf_abc123",
4    "name": "my-workflow",
5    "version": "1.0.0",
6    "createdAt": "2026-04-27T14:30:00Z"
7  }
8}

Update Workflow

Update an existing workflow:

PUT /workflows/{workflowId}

Body:

json

1{
2  "description": "Updated description",
3  "content": "apiVersion: xema.dev/workflow/v1alpha1\nkind: Workflow\n..."
4}

Response:

json

1{
2  "data": {
3    "id": "wf_abc123",
4    "version": "1.0.1",
5    "updatedAt": "2026-04-27T14:35:00Z"
6  }
7}

Delete Workflow

Delete a workflow:

DELETE /workflows/{workflowId}

Response:

json

1{
2  "data": {
3    "id": "wf_abc123",
4    "deleted": true
5  }
6}

Workflow Execution

Dispatch Workflow

Trigger a workflow manually:

POST /workflows/{workflowId}/dispatch

Body:

json

1{
2  "inputs": {
3    "project_name": "Acme Portal",
4    "scope": "full",
5    "budget": 500000
6  }
7}

Response:

json

1{
2  "data": {
3    "runId": "run_abc123",
4    "workflowId": "wf_abc123",
5    "status": "pending",
6    "createdAt": "2026-04-27T14:30:00Z"
7  }
8}

Get Run Status

Get the status of a workflow run:

GET /workflows/runs/{runId}

Response:

json

1{
2  "data": {
3    "runId": "run_abc123",
4    "workflowId": "wf_abc123",
5    "status": "running",
6    "progress": {
7      "jobsCompleted": 2,
8      "jobsTotal": 5,
9      "percentComplete": 40
10    },
11    "jobs": [
12      {
13        "jobId": "job_1",
14        "name": "analyze-requirements",
15        "status": "completed",
16        "startedAt": "2026-04-27T14:30:05Z",
17        "completedAt": "2026-04-27T14:32:10Z",
18        "duration": 125
19      },
20      {
21        "jobId": "job_2",
22        "name": "architecture-design",
23        "status": "running",
24        "startedAt": "2026-04-27T14:32:15Z"
25      }
26    ],
27    "startedAt": "2026-04-27T14:30:00Z"
28  }
29}

Get Job Output

Retrieve outputs from a completed job:

GET /workflows/runs/{runId}/jobs/{jobId}/outputs

Response:

json

1{
2  "data": {
3    "jobId": "job_1",
4    "status": "completed",
5    "outputs": {
6      "summary": "Requirements analysis complete",
7      "issues_found": 3,
8      "recommendations": ["Add API docs", "Improve error handling"]
9    }
10  }
11}

Get Run Logs

Retrieve execution logs:

GET /workflows/runs/{runId}/logs

Query Parameters:

jobId (optional) — Filter to specific job
level (optional) — Log level (info, warning, error)
limit (optional) — Max log lines (default: 100)

Response:

json

1{
2  "data": {
3    "logs": [
4      {
5        "timestamp": "2026-04-27T14:30:05Z",
6        "jobId": "job_1",
7        "level": "info",
8        "message": "Starting job: analyze-requirements"
9      },
10      {
11        "timestamp": "2026-04-27T14:30:10Z",
12        "jobId": "job_1",
13        "level": "info",
14        "message": "Processing 12 requirements..."
15      }
16    ]
17  }
18}

List Runs

List all runs for a workflow:

GET /workflows/{workflowId}/runs

Query Parameters:

status (optional) — Filter by status (pending, running, succeeded, failed)
page (optional) — Page number
limit (optional) — Items per page

Response:

json

1{
2  "data": [
3    {
4      "runId": "run_abc123",
5      "status": "succeeded",
6      "createdAt": "2026-04-27T14:30:00Z",
7      "completedAt": "2026-04-27T14:45:00Z",
8      "duration": 900
9    }
10  ],
11  "pagination": { ... }
12}

Cancel Run

Cancel a running workflow:

POST /workflows/runs/{runId}/cancel

Response:

json

1{
2  "data": {
3    "runId": "run_abc123",
4    "status": "cancelled",
5    "cancelledAt": "2026-04-27T14:35:00Z"
6  }
7}

Retry Run

Retry a failed workflow:

POST /workflows/runs/{runId}/retry

Body (optional):

json

1{
2  "inputs": {
3    "retry_strategy": "exponential"
4  }
5}

Response:

json

1{
2  "data": {
3    "newRunId": "run_def456",
4    "originalRunId": "run_abc123",
5    "status": "pending"
6  }
7}

Artifact Management

List Artifacts

List all artifacts from a run:

GET /workflows/runs/{runId}/artifacts

Query Parameters:

type (optional) — Filter by artifact type
page (optional) — Page number

Response:

json

1{
2  "data": [
3    {
4      "id": "art_abc123",
5      "type": "requirements_spec",
6      "version": 1,
7      "hash": "sha256:abc123...",
8      "size": 45632,
9      "createdAt": "2026-04-27T14:35:00Z",
10      "metadata": {
11        "phase": "requirements",
12        "project_id": "proj_123"
13      }
14    }
15  ]
16}

Get Artifact

Retrieve artifact details:

GET /artifacts/{artifactId}

Response:

json

1{
2  "data": {
3    "id": "art_abc123",
4    "type": "requirements_spec",
5    "version": 1,
6    "pointer": "s3://artifacts/art_abc123/v1",
7    "hash": "sha256:abc123...",
8    "size": 45632,
9    "createdAt": "2026-04-27T14:35:00Z",
10    "content": "# Requirements Specification\n..."
11  }
12}

Download Artifact

Download artifact content:

GET /artifacts/{artifactId}/download

Returns the artifact file (binary).

Get Artifact History

Get all versions of an artifact:

GET /artifacts/{artifactId}/versions

Response:

json

1{
2  "data": [
3    {
4      "version": 2,
5      "hash": "sha256:def456...",
6      "createdAt": "2026-04-27T14:40:00Z"
7    },
8    {
9      "version": 1,
10      "hash": "sha256:abc123...",
11      "createdAt": "2026-04-27T14:35:00Z"
12    }
13  ]
14}

Template APIs

List Templates

Get all available templates:

GET /templates

Query Parameters:

type (optional) — Filter by type (prompt, deliverable, session)
complexity (optional) — Filter by complexity (simple, complex, enterprise)
search (optional) — Search by name

Response:

json

1{
2  "data": [
3    {
4      "key": "requirements-enterprise",
5      "name": "Enterprise Requirements Spec",
6      "type": "deliverable",
7      "complexity": "enterprise",
8      "description": "Comprehensive requirements for enterprise projects"
9    }
10  ]
11}

Get Template

Retrieve template details:

GET /templates/{templateKey}

Response:

json

1{
2  "data": {
3    "key": "requirements-enterprise",
4    "name": "Enterprise Requirements Spec",
5    "type": "deliverable",
6    "version": "2.1.0",
7    "complexity": "enterprise",
8    "content": "# {{projectName}} Requirements...",
9    "requiredFields": ["projectName", "functionalRequirements"],
10    "optionalFields": ["budget", "timeline"]
11  }
12}

Render Template

Render a template with context:

POST /templates/{templateKey}/render

Body:

json

1{
2  "context": {
3    "projectName": "Acme Portal",
4    "functionalRequirements": [
5      {
6        "id": "FR-1",
7        "title": "User Authentication",
8        "priority": "high"
9      }
10    ],
11    "budget": 500000,
12    "timeline": "6 months"
13  }
14}

Response:

json

1{
2  "data": {
3    "rendered": "# Acme Portal Requirements Specification\n\n## Functional Requirements\n...",
4    "warnings": []
5  }
6}

Error Handling

Common Error Codes

Code	HTTP	Meaning
`INVALID_INPUT`	400	Input validation failed
`NOT_FOUND`	404	Resource not found
`UNAUTHORIZED`	401	Invalid or missing token
`FORBIDDEN`	403	Insufficient permissions
`CONFLICT`	409	Resource conflict
`INTERNAL_ERROR`	500	Server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

Error Response

json

1{
2  "success": false,
3  "error": {
4    "code": "INVALID_INPUT",
5    "message": "Input validation failed",
6    "details": {
7      "field": "inputs.budget",
8      "reason": "Must be a positive number",
9      "value": -1000
10    }
11  }
12}

Retry Strategy

Implement exponential backoff for retries:

text

1Wait time = 2^attempt (capped at 60 seconds)
2Attempt 1: 2 seconds
3Attempt 2: 4 seconds
4Attempt 3: 8 seconds
5...

Examples

Example 1: Dispatch and Monitor Workflow

bash

1#!/bin/bash
2
3# Dispatch workflow
4RESPONSE=$(curl -s -X POST https://workflow-engine-api.xema.dev/workflows/wf_abc123/dispatch \
5  -H "Authorization: Bearer $XEMA_TOKEN" \
6  -H "Content-Type: application/json" \
7  -d '{
8    "inputs": {
9      "project_name": "Acme Portal",
10      "scope": "full"
11    }
12  }')
13
14RUN_ID=$(echo $RESPONSE | jq -r '.data.runId')
15echo "Workflow started: $RUN_ID"
16
17# Poll for completion
18while true; do
19  STATUS=$(curl -s https://workflow-engine-api.xema.dev/runs/$RUN_ID \
20    -H "Authorization: Bearer $XEMA_TOKEN" | jq -r '.data.status')
21  
22  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then
23    echo "Workflow $STATUS"
24    break
25  fi
26  
27  echo "Status: $STATUS"
28  sleep 10
29done
30
31# Get artifacts
32curl -s https://workflow-engine-api.xema.dev/runs/$RUN_ID/artifacts \
33  -H "Authorization: Bearer $XEMA_TOKEN" | jq '.data'

Example 2: Template Rendering

bash

1# Render a template
2curl -X POST https://deliverable-specs-api.xema.dev/deliverable-specs/requirements-enterprise/render \
3  -H "Authorization: Bearer $XEMA_TOKEN" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "context": {
7      "projectName": "Acme Portal",
8      "functionalRequirements": [
9        {
10          "id": "FR-1",
11          "title": "User Authentication",
12          "priority": "high"
13        }
14      ]
15    }
16  }' | jq '.data.rendered'

Last Updated: April 2026
API Version: 1.0

API Reference

Table of Contents

Authentication

Token Management

Rate Limiting

Base URL

Common Response Format

Success Response

Error Response

Pagination

Workflow Management

Get Workflow

List Workflows

Create Workflow

Update Workflow

Delete Workflow

Workflow Execution

Dispatch Workflow

Get Run Status

Get Job Output

Get Run Logs

List Runs

Cancel Run

Retry Run

Artifact Management

List Artifacts

Get Artifact

Download Artifact

Get Artifact History

Template APIs

List Templates

Get Template

Render Template

Error Handling

Common Error Codes

Error Response

Retry Strategy

Examples

Example 1: Dispatch and Monitor Workflow

Example 2: Template Rendering