Vollständige HTTP-API-Referenz für die JamJet-Runtime – Workflows, Ausführungen, Agents, Audit und Tenants.

REST API Referenz

Die JamJet Runtime stellt standardmäßig eine REST API unter http://localhost:7700 bereit. Alle Requests und Responses verwenden JSON.

Authentifizierung

Geschützte Endpoints erfordern ein Bearer Token:

Authorization: Bearer <token>

Tokens werden über die CLI oder die Operator API erstellt. Die Runtime speichert nur den Hash — der Klartext wird einmalig bei der Erstellung zurückgegeben.

Rollen

Rolle	Lesen	Schreiben	Admin
`operator`	ja	ja	ja
`developer`	ja	ja	nein
`reviewer`	ja	nein	nein
`viewer`	ja	nein	nein

Schreiboperationen (POST, PUT, DELETE) erfordern developer oder operator. Tenant-Verwaltung erfordert operator.

Health

`GET /health`

Keine Authentifizierung erforderlich.

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

Workflows

`POST /workflows`

Registriert eine Workflow-Definition (kompilierte 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"
}

Tipp: Die meisten Nutzer rufen diesen Endpoint nicht direkt auf. jamjet run workflow.yaml kompiliert und übermittelt die IR automatisch.

Executions

`POST /executions`

Startet eine neue Workflow-Ausführung.

Request:

{
  "workflow_id": "research-agent",
  "workflow_version": "0.1.0",
  "input": {
    "query": "Neueste AI Agent Frameworks?"
  }
}

workflow_version ist optional — verwendet standardmäßig die zuletzt registrierte Version.

Response 201 Created:

{
  "execution_id": "exec_a1b2c3d4"
}

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

`GET /executions`

Auflistung von Ausführungen mit optionaler Filterung.

Query-Parameter:

Parameter	Typ	Standard	Beschreibung
`status`	string	—	Filter: `running`, `paused`, `completed`, `failed`, `cancelled`
`limit`	int	50	Max. Ergebnisse
`offset`	int	0	Paginierungs-Offset

Antwort:

{
  "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`

Abruf einer einzelnen Ausführung mit vollständigem Zustand.

Antwort:

{
  "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-Äquivalent: jamjet inspect exec_a1b2c3d4

`GET /executions/:id/events`

Abruf der Event-Timeline einer Ausführung.

Antwort:

{
  "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-Arten: WorkflowStarted, NodeScheduled, NodeCompleted, ApprovalReceived, ExternalEventReceived, ToolCallCompleted, WorkflowCancelled

CLI-Äquivalent: jamjet events exec_a1b2c3d4

`POST /executions/:id/cancel`

Abbruch einer laufenden Ausführung.

Antwort:

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

`POST /executions/:id/approve`

Übermittlung einer Freigabe-Entscheidung für einen Human-in-the-Loop-Knoten.

Anfrage:

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

Nur decision ist erforderlich. Gültige Werte: "approved", "rejected".

Antwort:

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

`POST /executions/:id/external-event`

Injizieren Sie ein externes Ereignis, um eine pausierte Ausführung zu aktivieren.

Anfrage:

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

Antwort:

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

Agents

`POST /agents`

Registrieren Sie einen Agent mit seiner Agent Card.

Anfrage:

{
  "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" }
}

Antwort 201 Created:

{
  "agent_id": "research-agent"
}

`GET /agents`

Agents mit optionaler Filterung auflisten.

Query-Parameter:

Parameter	Typ	Beschreibung
`status`	string	`registered`, `active`, `paused`, `deactivated`
`skill`	string	Nach Skill-Name filtern
`protocol`	string	`mcp`, `a2a`, `anp`

CLI-Äquivalent: jamjet agents list

`GET /agents/:id`

Vollständige Agent-Details einschließlich der Agent Card abrufen.

CLI-Äquivalent: jamjet agents inspect <agent_id>

`POST /agents/discover`

Einen Remote-Agent per URL entdecken. Ruft /.well-known/agent.json ab und registriert den Agent.

Anfrage:

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

Antwort 201 Created: vollständiges Agent-Objekt.

CLI-Äquivalent: jamjet agents discover <url>

`POST /agents/:id/activate`

Einen registrierten Agent aktivieren.

Antwort:

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

`POST /agents/:id/deactivate`

Agent deaktivieren.

`POST /agents/:id/heartbeat`

Agent-Liveness-Heartbeat.

Antwort:

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

Audit-Log

`GET /audit`

Abfrage des unveränderlichen Audit-Logs.

Query-Parameter:

Parameter	Typ	Standard	Beschreibung
`execution_id`	string	—	Nach Ausführung filtern
`actor_id`	string	—	Nach Actor/User filtern
`event_type`	string	—	Nach Operationstyp filtern
`limit`	int	50	Max. Ergebnisse (max. 200)
`offset`	int	0	Paginierungs-Offset

Antwort:

{
  "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-Verwaltung erfordert die Rolle operator.

`POST /tenants`

Neuen Tenant erstellen.

Anfrage:

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

Antwort 201 Created:

{
  "tenant_id": "acme"
}

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

Alle Felder optional.

Status	Bedeutung	Beispiel
`400`	Ungültige Anfrage	`{ "error": "bad request: ir.workflow_id is required" }`
`401`	Nicht autorisiert	`{ "error": "invalid or expired token" }`
`403`	Verboten	`{ "error": "insufficient role — developer or operator required" }`
`404`	Nicht gefunden	`{ "error": "not found: execution exec_abc123" }`
`500`	Interner Fehler	`{ "error": "internal error: ..." }`

Konfiguration

Umgebungsvariable	Standard	Beschreibung
`JAMJET_BIND`	`127.0.0.1`	Bind-Adresse
`JAMJET_PORT`	`7700`	HTTP-Port
`JAMJET_PUBLIC_URL`	`http://{bind}:{port}`	Öffentliche URL für Federation
`DATABASE_URL`	`.jamjet/runtime.db`	SQLite- oder PostgreSQL-Verbindungsstring
`JAMJET_TOKEN`	—	Standard-API-Token (für Clients)
`RUST_LOG`	`info`	Log-Level

CLI zu API Mapping

CLI-Befehl	API-Endpunkt
`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 list`	`GET /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`

Hinweis: jamjet dev startet den Runtime-Server lokal. jamjet validate und jamjet eval run sind clientseitige Operationen, die die API nicht aufrufen.

REST-API-Referenz

REST API Referenz

Authentifizierung

Rollen

Health

`GET /health`

Workflows

`POST /workflows`

Executions

`POST /executions`

`GET /executions`

`GET /executions/:id`

`GET /executions/:id/events`

`POST /executions/:id/cancel`

`POST /executions/:id/approve`

`POST /executions/:id/external-event`

Agents

`POST /agents`

`GET /agents`

`GET /agents/:id`

`POST /agents/discover`

`POST /agents/:id/activate`

`POST /agents/:id/deactivate`

`POST /agents/:id/heartbeat`

Audit-Log

`GET /audit`

Tenants

`POST /tenants`

`GET /tenants`

`GET /tenants/:id`

`PUT /tenants/:id`

Workers

`GET /workers`

Federation

`GET /.well-known/did.json`

Fehlerantworten

Konfiguration

CLI zu API Mapping

On this page