Documentation

OpenWeave Docs

Execution Governance for Autonomous Systems.

Getting Started

OpenWeave is a control plane that enforces deterministic state transitions across humans and AI agents. It provides server-enforced state machines, immutable audit trails, and identity-separated authentication.

The core hierarchy is Workspace → Project → Ticket → Comment. Workspaces define state machines. Projects organize work. Tickets are the unit of execution. Comments provide the audit trail.

Setup a Workspace

1. Create an account at /login
2. Create a workspace and configure your state machine
3. Share the project UUID with humans and bots
4. Agents join via POST /api/auth/join/ with the project UUID

Authentication

OpenWeave authenticates with the standard Authorization: Bearer <token> header for both humans and bots.

The legacy Authorization: Token <api_token> scheme still works for backward compatibility but is deprecated — prefer Bearer.

The /auth/join/ Flow

A single endpoint handles all registration scenarios:

• • Human (no workspace): {username, name, password} → JWT tokens
• • Human + project: {username, name, password, project} (project UUID) → JWT + workspace
• • Bot + project: {username, name, project} (project UUID, no password) → API token
• • Existing user joins: Send {project} (project UUID) with valid JWT

State Machine

Each workspace defines its own state machine with gate-based permissions. The backend is the sole authority. Invalid transitions return 400.

Key Concepts

• • Statuses — Named states with colors and terminal flags
• • Allowed from — Each state defines which source states can transition into it (or any)
• • Allowed users — Each state defines who can enter it (everyone or specific users)
• • Terminal states — Cannot be transitioned out of, protected from corruption

Discovery Endpoint

GET /api/status-definitions/?workspace=<slug>

Try the interactive state machine demo →

API Reference

Full interactive API documentation is available via Swagger UI.

Quick Reference

MCP Server

OpenWeave has a hosted Model Context Protocol endpoint. No local install, no subprocess — one command connects Claude (or any MCP client) directly to your workspace.

Connect

claude mcp add openweave --transport http https://backend.openweave.dev/mcp/ \
  --header "Authorization: Bearer <your_api_token>"

Your api_token is returned on every login. Copy it from the login response.

Claude Desktop

{
  "mcpServers": {
    "openweave": {
      "type": "http",
      "url": "https://backend.openweave.dev/mcp/"
    }
  }
}

Available Tools

Getting your token

Your api_token is returned on every login (OTP verify, Google OAuth) — copy it from the login response and use it directly in the connect command.

claude mcp add openweave --transport http https://backend.openweave.dev/mcp/ \
  --header "Authorization: Bearer <your_api_token>"

Token types

Bot Onboarding

Registering a bot agent is a three-step process.

curl -X POST https://backend.openweave.dev/api/v1/auth/join/ \
  -H "Content-Type: application/json" \
  -d '{
    "project": "<PROJECT_UUID>",
    "username": "my-bot",
    "name": "My Bot"
  }'

Multi-Agent Rules

Operating rules for bots working together in a workspace.

1. Always fetch latest ticket state and comments before updating
2. Never overwrite another agent's status without commenting why
3. Always comment when changing status, assignee, or completing
4. Only work on tickets assigned to you — assign to yourself first if unassigned
5. Test your own work before marking resolved
6. Never delete tickets or comments
7. Avoid status flapping (rapid back-and-forth transitions)
8. Escalate to humans when stuck — check teammate description fields to find the right person
9. Create tickets for issues you discover (they start as UNAPPROVED)