Orchex API Reference

Complete API reference for Orchex — the AI-native task orchestrator.

Overview

Orchex provides three primary integration surfaces:

1. MCP Tools — Execute orchestrations via Model Context Protocol
2. Cloud API — RESTful HTTP API for cloud-hosted orchestrations
3. Stream Definitions — Define multi-step workflows with YAML manifests

MCP Tools

Orchex exposes orchestration capabilities through the Model Context Protocol, enabling AI assistants to execute complex multi-step tasks.

Available Tools

`orchex_execute`

Execute a task orchestration with AI-powered planning and execution.

Parameters:

• task (string, required) — Natural language description of the task
• files (array, optional) — File paths to include in context
• dryRun (boolean, optional) — Preview plan without executing (default: false)
• maxSteps (number, optional) — Maximum orchestration steps (default: 10)

Returns:

• status — Execution status (success, failed, cancelled)
• result — Task execution results and artifacts
• steps — Array of executed steps with details
• metrics — Performance and token usage metrics

Example:

const result = await orchex_execute({
  task: "Add user authentication to the API",
  files: ["src/server.ts", "src/routes/"],
  maxSteps: 15
});

`orchex_status`

Check the status of a running orchestration.

Parameters:

• executionId (string, required) — Execution ID from orchex_execute

Returns:

• status — Current execution status
• progress — Completed steps / total steps
• currentStep — Description of current operation
• elapsed — Execution time in milliseconds

`orchex_cancel`

Cancel a running orchestration.

Parameters:

• executionId (string, required) — Execution ID to cancel

Returns:

• cancelled — Boolean indicating success
• finalState — State snapshot at cancellation

MCP Server Configuration

Installation:

{
  "mcpServers": {
    "orchex": {
      "command": "npx",
      "args": ["-y", "@wundam/orchex"]
    }
  }
}

Documentation: MCP Integration Guide

Cloud API

The Orchex Cloud API provides HTTP endpoints for executing orchestrations, managing teams, and tracking usage.

Base URL: https://api.orchex.dev/v1

Authentication: Bearer token in Authorization header

Authorization: Bearer orchex_sk_...

Endpoints

Execute Orchestration

POST /executions

Start a new orchestration execution.

Request Body:

{
  "task": "Implement feature X",
  "context": {
    "files": ["src/app.ts"],
    "environment": "production"
  },
  "options": {
    "dryRun": false,
    "maxSteps": 10,
    "timeout": 300000
  }
}

Response:

{
  "id": "exec_1234567890",
  "status": "running",
  "createdAt": "2026-02-05T10:00:00Z",
  "statusUrl": "/executions/exec_1234567890"
}

Get Execution Status

GET /executions/:id

Response:

{
  "id": "exec_1234567890",
  "status": "completed",
  "progress": {
    "current": 8,
    "total": 8
  },
  "result": {
    "success": true,
    "artifacts": [...],
    "summary": "Feature implemented successfully"
  },
  "metrics": {
    "duration": 45000,
    "tokensUsed": 12500
  }
}

List Executions

GET /executions?limit=50&status=completed

Query Parameters:

• limit — Results per page (default: 50, max: 100)
• status — Filter by status (running, completed, failed)
• before — Cursor for pagination

Cancel Execution

POST /executions/:id/cancel

Team Management

GET /teams/:id
PATCH /teams/:id
GET /teams/:id/members
POST /teams/:id/members
DELETE /teams/:id/members/:userId

Usage & Billing

GET /usage/current
GET /usage/history?month=2026-02
GET /billing/subscription
POST /billing/subscription

Documentation: Cloud API Reference

Stream Definitions

Streams are YAML manifests that define multi-step orchestration workflows. They enable version-controlled, repeatable task execution.

Manifest Structure

name: feature-name
version: 1.0.0
description: Human-readable description

streams:
  stream-id:
    description: What this stream does
    plan: |
      Step-by-step plan for AI to follow
      Can reference files, patterns, best practices
    
    context:
      files:
        - src/relevant/*.ts
        - docs/related.md
      depth: moderate  # minimal | moderate | comprehensive
    
    commands:
      - command: test
        critical: true
      - command: lint
        critical: false
    
    constraints:
      maxSteps: 15
      timeout: 300000
      requireTests: true

Manifest Fields

Top Level

• name (string, required) — Unique manifest identifier
• version (string, required) — Semantic version
• description (string, required) — Manifest purpose
• streams (object, required) — Stream definitions

Stream Definition

• description (string, required) — Stream purpose
• plan (string, required) — Execution instructions for AI
• context (object, optional) — Context configuration
  • files (array) — File patterns to include
  • depth (string) — Context depth level
• commands (array, optional) — Validation commands
  • command (string) — Command to execute
  • critical (boolean) — Fail on command failure
• constraints (object, optional) — Execution limits
  • maxSteps (number) — Maximum orchestration steps
  • timeout (number) — Timeout in milliseconds
  • requireTests (boolean) — Require test validation

Context Patterns

File Patterns:

• Glob patterns: src/**/*.ts, tests/*.test.ts
• Directories: src/features/auth/
• Specific files: package.json, README.md

Depth Levels:

• minimal — Only specified files (~5-10 files)
• moderate — Files + immediate dependencies (~20-30 files)
• comprehensive — Full project context (~50+ files)

Command Execution

Commands run in project root with inherited environment:

commands:
  - command: npm test
    critical: true        # Fail orchestration on error
  - command: npm run lint
    critical: false       # Log error but continue
  - command: npm run build
    critical: true

Example Manifests

See complete examples:

• Hello World — Simple single-stream example
• Add Feature — Multi-stream feature development
• Fix Bug — Bug fix workflow with testing

Documentation: Stream Manifest Guide

SDK & Libraries

Node.js SDK

import { OrchexClient } from '@wundam/orchex';

const client = new OrchexClient({
  apiKey: process.env.ORCHEX_API_KEY
});

const execution = await client.execute({
  task: 'Refactor authentication module',
  files: ['src/auth/'],
  options: { maxSteps: 12 }
});

await execution.wait();
console.log(execution.result);

CLI

# Execute a manifest
orchex exec manifest.yaml stream-id

# Execute a task directly
orchex run "Fix the login bug"

# Check execution status
orchex status exec_1234567890

# Start MCP server
orchex mcp

Documentation: CLI Reference

Rate Limits & Quotas

Cloud API Limits

See orchex.dev/pricing for current rate limits and quotas by tier.

Error Codes

• 429 — Rate limit exceeded
• 402 — Payment required (quota exceeded)
• 401 — Invalid API key
• 403 — Insufficient permissions
• 500 — Server error

Documentation: Rate Limits & Errors

Webhooks

Receive real-time notifications for execution events.

Event Types:

• execution.started
• execution.step_completed
• execution.completed
• execution.failed
• execution.cancelled

Payload:

{
  "event": "execution.completed",
  "timestamp": "2026-02-05T10:05:00Z",
  "data": {
    "executionId": "exec_1234567890",
    "status": "completed",
    "result": {...}
  }
}

Documentation: Webhooks Guide

Additional Resources

• Getting Started Guide — Quick start tutorial
• MCP Integration — Model Context Protocol details
• Cloud API Reference — Complete REST API docs
• Stream Manifests — Manifest format specification
• CLI Reference — Command-line interface
• Authentication — API keys and OAuth
• Webhooks — Event notifications
• Errors & Troubleshooting — Error codes and solutions

Support

• Documentation: orchex.dev/docs
• Website: orchex.dev
• Support: support@orchex.dev

Last updated: February 2026 • Orchex v1.0.0-rc.1