JamJet

REST API Reference

Complete HTTP API reference for the JamJet runtime — workflows, executions, agents, audit, and tenants.

REST API Reference

The JamJet runtime exposes a REST API on http://localhost:7700 by default. All requests and responses use JSON.

Authentication

Protected endpoints require a Bearer token:

Authorization: Bearer <token>

Tokens are created via the CLI or the operator API. The runtime stores only the hash — the plaintext is returned once at creation time.

Roles

RoleReadWriteAdmin
operatoryesyesyes
developeryesyesno
revieweryesnono
vieweryesnono

Write operations (POST, PUT, DELETE) require developer or operator. Tenant management requires operator.

Health

GET /health

No authentication required.

{ "status": "ok", "version": "0.1.1" }

Workflows

POST /workflows

Register a workflow definition (compiled IR).

Request:

{
  "ir": {
    "workflow_id": "research-agent",
    "version": "0.1.0",
    "state_schema": { ... },
    "nodes": { ... },
    "edges": [ ... ]
  }
}

Response 201 Created:

{
  "workflow_id": "research-agent",
  "version": "0.1.0"
}

tip: Most users do not call this endpoint directly. jamjet run workflow.yaml compiles and submits the IR automatically.

Executions

POST /executions

Start a new workflow execution.

Request:

{
  "workflow_id": "research-agent",
  "workflow_version": "0.1.0",
  "input": {
    "query": "Latest AI agent frameworks?"
  }
}

workflow_version is optional — defaults to the latest registered version.

Response 201 Created:

{
  "execution_id": "exec_a1b2c3d4"
}

CLI equivalent: jamjet run workflow.yaml --input '{"query": "..."}'

GET /executions

List executions with optional filtering.

Query parameters:

ParameterTypeDefaultDescription
statusstring—Filter: running, paused, completed, failed, cancelled
limitint50Max results
offsetint0Pagination offset

Response:

{
  "executions": [
    {
      "execution_id": "exec_a1b2c3d4",
      "workflow_id": "research-agent",
      "status": "completed",
      "created_at": "2026-03-12T10:00:00Z",
      "completed_at": "2026-03-12T10:00:04Z"
    }
  ]
}

GET /executions/:id

Get a single execution with full state.

Response:

{
  "execution_id": "exec_a1b2c3d4",
  "workflow_id": "research-agent",
  "status": "completed",
  "state": {
    "query": "Latest AI agent frameworks?",
    "answer": "..."
  },
  "steps_executed": 3,
  "created_at": "2026-03-12T10:00:00Z",
  "completed_at": "2026-03-12T10:00:04Z"
}

CLI equivalent: jamjet inspect exec_a1b2c3d4

GET /executions/:id/events

Get the event timeline for an execution.

Response:

{
  "events": [
    {
      "sequence": 1,
      "kind": "WorkflowStarted",
      "node_id": null,
      "created_at": "2026-03-12T10:00:00.000Z"
    },
    {
      "sequence": 2,
      "kind": "NodeCompleted",
      "node_id": "search",
      "created_at": "2026-03-12T10:00:00.200Z"
    },
    {
      "sequence": 3,
      "kind": "NodeCompleted",
      "node_id": "synthesize",
      "created_at": "2026-03-12T10:00:02.040Z"
    }
  ]
}

Event kinds: WorkflowStarted, NodeScheduled, NodeCompleted, ApprovalReceived, ExternalEventReceived, ToolCallCompleted, WorkflowCancelled

CLI equivalent: jamjet events exec_a1b2c3d4

POST /executions/:id/cancel

Cancel a running execution.

Response:

{
  "execution_id": "exec_a1b2c3d4",
  "status": "cancelled"
}

POST /executions/:id/approve

Send an approval decision for a human-in-the-loop node.

Request:

{
  "decision": "approved",
  "node_id": "manager-review",
  "user_id": "user-42",
  "comment": "Looks good, proceed.",
  "state_patch": {
    "priority": "high"
  }
}

Only decision is required. Valid values: "approved", "rejected".

Response:

{
  "execution_id": "exec_a1b2c3d4",
  "accepted": true
}

POST /executions/:id/external-event

Inject an external event to wake a paused execution.

Request:

{
  "correlation_key": "payment-received",
  "payload": {
    "amount": 500,
    "currency": "USD"
  }
}

Response:

{
  "execution_id": "exec_a1b2c3d4",
  "accepted": true
}

Agents

POST /agents

Register an agent with its Agent Card.

Request:

{
  "id": "research-agent",
  "uri": "http://localhost:7701",
  "name": "Research Agent",
  "description": "Searches the web and synthesizes reports.",
  "version": "0.1.0",
  "capabilities": {
    "skills": [
      {
        "name": "research",
        "description": "Deep research on any topic",
        "input_schema": { "type": "object", "properties": { "query": { "type": "string" } } },
        "output_schema": { "type": "object", "properties": { "report": { "type": "string" } } }
      }
    ],
    "protocols": ["a2a"],
    "tools_provided": ["web_search"],
    "tools_consumed": []
  },
  "autonomy": "guided",
  "auth": { "type": "bearer_token" }
}

Response 201 Created:

{
  "agent_id": "research-agent"
}

GET /agents

List agents with optional filtering.

Query parameters:

ParameterTypeDescription
statusstringregistered, active, paused, deactivated
skillstringFilter by skill name
protocolstringmcp, a2a, anp

CLI equivalent: jamjet agents list

GET /agents/:id

Get full agent details including the Agent Card.

CLI equivalent: jamjet agents inspect <agent_id>

POST /agents/discover

Discover a remote agent by URL. Fetches /.well-known/agent.json and registers the agent.

Request:

{
  "url": "https://remote-agent.example.com"
}

Response 201 Created: full agent object.

CLI equivalent: jamjet agents discover <url>

POST /agents/:id/activate

Activate a registered agent.

Response:

{
  "agent_id": "research-agent",
  "status": "active"
}

POST /agents/:id/deactivate

Deactivate an agent.

POST /agents/:id/heartbeat

Agent liveness heartbeat.

Response:

{
  "agent_id": "research-agent",
  "ok": true
}

Audit log

GET /audit

Query the immutable audit log.

Query parameters:

ParameterTypeDefaultDescription
execution_idstring—Filter by execution
actor_idstring—Filter by actor/user
event_typestring—Filter by operation type
limitint50Max results (max 200)
offsetint0Pagination offset

Response:

{
  "items": [
    {
      "id": "audit_001",
      "execution_id": "exec_a1b2c3d4",
      "event_type": "node_completed",
      "actor_id": "agent:research-agent",
      "created_at": "2026-03-12T10:00:02Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Tenants

Tenant management requires operator role.

POST /tenants

Create a new tenant.

Request:

{
  "id": "acme",
  "name": "Acme Corp"
}

Response 201 Created:

{
  "tenant_id": "acme"
}

GET /tenants

List all tenants.

GET /tenants/:id

Get tenant details.

PUT /tenants/:id

Update tenant configuration.

Request:

{
  "name": "Acme Corporation",
  "status": "active",
  "policy": { ... },
  "limits": { ... }
}

All fields optional.

Workers

GET /workers

List active runtime workers.

Federation

GET /.well-known/did.json

W3C DID Document for A2A federation. No authentication required. Returns the runtime's decentralized identifier with service endpoints for active agents.

Error responses

All errors return JSON with an appropriate HTTP status code:

StatusMeaningExample
400Bad request{ "error": "bad request: ir.workflow_id is required" }
401Unauthorized{ "error": "invalid or expired token" }
403Forbidden{ "error": "insufficient role — developer or operator required" }
404Not found{ "error": "not found: execution exec_abc123" }
500Internal error{ "error": "internal error: ..." }

Configuration

Environment variableDefaultDescription
JAMJET_BIND127.0.0.1Bind address
JAMJET_PORT7700HTTP port
JAMJET_PUBLIC_URLhttp://{bind}:{port}Public URL for federation
DATABASE_URL.jamjet/runtime.dbSQLite or PostgreSQL connection string
JAMJET_TOKEN—Default API token (for clients)
RUST_LOGinfoLog level

CLI to API mapping

CLI commandAPI endpoint
jamjet run <wf> --input <json>POST /executions
jamjet inspect <exec_id>GET /executions/:id + GET /executions/:id/events
jamjet events <exec_id>GET /executions/:id/events
jamjet agents listGET /agents
jamjet agents inspect <id>GET /agents/:id
jamjet agents activate <id>POST /agents/:id/activate
jamjet agents deactivate <id>POST /agents/:id/deactivate
jamjet agents discover <url>POST /agents/discover

note: jamjet dev starts the runtime server locally. jamjet validate and jamjet eval run are client-side operations that do not call the API.

A2A Integration

Delegate to and serve other agents using the Agent-to-Agent protocol.

Framework Comparison

JamJet vs LangGraph vs CrewAI vs AutoGen — feature matrix across execution, durability, observability, eval, and scale.

On this page

REST API ReferenceAuthenticationRolesHealthGET /healthWorkflowsPOST /workflowsExecutionsPOST /executionsGET /executionsGET /executions/:idGET /executions/:id/eventsPOST /executions/:id/cancelPOST /executions/:id/approvePOST /executions/:id/external-eventAgentsPOST /agentsGET /agentsGET /agents/:idPOST /agents/discoverPOST /agents/:id/activatePOST /agents/:id/deactivatePOST /agents/:id/heartbeatAudit logGET /auditTenantsPOST /tenantsGET /tenantsGET /tenants/:idPUT /tenants/:idWorkersGET /workersFederationGET /.well-known/did.jsonError responsesConfigurationCLI to API mapping