Referencia completa de la API HTTP para el runtime de JamJet: workflows, ejecuciones, agentes, auditoría e inquilinos.

Referencia de la API REST

El runtime de JamJet expone una API REST en http://localhost:7700 por defecto. Todas las solicitudes y respuestas utilizan JSON.

Autenticación

Los endpoints protegidos requieren un token Bearer:

Authorization: Bearer <token>

Los tokens se crean mediante la CLI o la API del operador. El runtime almacena solo el hash — el texto plano se devuelve una sola vez en el momento de la creación.

Roles

Rol	Lectura	Escritura	Admin
`operator`	sí	sí	sí
`developer`	sí	sí	no
`reviewer`	sí	no	no
`viewer`	sí	no	no

Las operaciones de escritura (POST, PUT, DELETE) requieren developer u operator. La gestión de tenants requiere operator.

Estado del sistema

`GET /health`

No requiere autenticación.

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

Workflows

`POST /workflows`

Registra una definición de workflow (IR compilada).

Solicitud:

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

Respuesta 201 Created:

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

consejo: La mayoría de los usuarios no llaman a este endpoint directamente. jamjet run workflow.yaml compila y envía la IR automáticamente.

Ejecuciones

`POST /executions`

Inicia una nueva ejecución de workflow.

Solicitud:

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

workflow_version es opcional — por defecto usa la última versión registrada.

Respuesta 201 Created:

{
  "execution_id": "exec_a1b2c3d4"
}

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

`GET /executions`

Lista las ejecuciones con filtrado opcional.

Parámetros de consulta:

Parámetro	Tipo	Predeterminado	Descripción
`status`	string	—	Filtrar: `running`, `paused`, `completed`, `failed`, `cancelled`
`limit`	int	50	Máximo de resultados
`offset`	int	0	Desplazamiento de paginación

Respuesta:

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

Obtiene una ejecución individual con su estado completo.

Respuesta:

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

Equivalente en CLI: jamjet inspect exec_a1b2c3d4

`GET /executions/:id/events`

Obtiene la línea de tiempo de eventos de una ejecución.

Respuesta:

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

Tipos de eventos: WorkflowStarted, NodeScheduled, NodeCompleted, ApprovalReceived, ExternalEventReceived, ToolCallCompleted, WorkflowCancelled

Equivalente en CLI: jamjet events exec_a1b2c3d4

`POST /executions/:id/cancel`

Cancela una ejecución en curso.

Respuesta:

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

`POST /executions/:id/approve`

Envía una decisión de aprobación para un nodo con intervención humana.

Solicitud:

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

Solo decision es obligatorio. Valores válidos: "approved", "rejected".

Respuesta:

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

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

Inyecta un evento externo para reactivar una ejecución pausada.

Solicitud:

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

Respuesta:

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

Agentes

`POST /agents`

Registra un agente con su Agent Card.

Solicitud:

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

Respuesta 201 Created:

{
  "agent_id": "research-agent"
}

`GET /agents`

Lista agentes con filtrado opcional.

Parámetros de consulta:

Parámetro	Tipo	Descripción
`status`	string	`registered`, `active`, `paused`, `deactivated`
`skill`	string	Filtrar por nombre de habilidad
`protocol`	string	`mcp`, `a2a`, `anp`

Equivalente CLI: jamjet agents list

`GET /agents/:id`

Obtiene los detalles completos del agente incluyendo el Agent Card.

Equivalente CLI: jamjet agents inspect <agent_id>

`POST /agents/discover`

Descubre un agente remoto por URL. Obtiene /.well-known/agent.json y registra el agente.

Solicitud:

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

Respuesta 201 Created: objeto de agente completo.

Equivalente CLI: jamjet agents discover <url>

`POST /agents/:id/activate`

Activa un agente registrado.

Respuesta:

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

`POST /agents/:id/deactivate`

Desactiva un agente.

`POST /agents/:id/heartbeat`

Heartbeat de verificación de actividad del agente.

Respuesta:

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

Registro de auditoría

`GET /audit`

Consulta el registro de auditoría inmutable.

Parámetros de consulta:

Parámetro	Tipo	Predeterminado	Descripción
`execution_id`	string	—	Filtrar por ejecución
`actor_id`	string	—	Filtrar por actor/usuario
`event_type`	string	—	Filtrar por tipo de operación
`limit`	int	50	Máximo de resultados (máx. 200)
`offset`	int	0	Desplazamiento para paginación

Respuesta:

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

La gestión de tenants requiere el rol operator.

`POST /tenants`

Crea un nuevo tenant.

Solicitud:

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

Respuesta 201 Created:

{
  "tenant_id": "acme"
}

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

Todos los campos son opcionales.

Estado	Significado	Ejemplo
`400`	Solicitud incorrecta	`{ "error": "bad request: ir.workflow_id is required" }`
`401`	No autorizado	`{ "error": "invalid or expired token" }`
`403`	Prohibido	`{ "error": "insufficient role — developer or operator required" }`
`404`	No encontrado	`{ "error": "not found: execution exec_abc123" }`
`500`	Error interno	`{ "error": "internal error: ..." }`

Configuración

Variable de entorno	Predeterminado	Descripción
`JAMJET_BIND`	`127.0.0.1`	Dirección de enlace
`JAMJET_PORT`	`7700`	Puerto HTTP
`JAMJET_PUBLIC_URL`	`http://{bind}:{port}`	URL pública para federación
`DATABASE_URL`	`.jamjet/runtime.db`	Cadena de conexión SQLite o PostgreSQL
`JAMJET_TOKEN`	—	Token de API predeterminado (para clientes)
`RUST_LOG`	`info`	Nivel de registro

Mapeo de CLI a API

Comando CLI	Endpoint de API
`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`

nota: jamjet dev inicia el servidor del runtime localmente. jamjet validate y jamjet eval run son operaciones del lado del cliente que no llaman a la API.

Referencia de la API REST

Referencia de la API REST

Autenticación

Roles

Estado del sistema

`GET /health`

Workflows

`POST /workflows`

Ejecuciones

`POST /executions`

`GET /executions`

`GET /executions/:id`

`GET /executions/:id/events`

`POST /executions/:id/cancel`

`POST /executions/:id/approve`

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

Agentes

`POST /agents`

`GET /agents`

`GET /agents/:id`

`POST /agents/discover`

`POST /agents/:id/activate`

`POST /agents/:id/deactivate`

`POST /agents/:id/heartbeat`

Registro de auditoría

`GET /audit`

Tenants

`POST /tenants`

`GET /tenants`

`GET /tenants/:id`

`PUT /tenants/:id`

Workers

`GET /workers`

Federación

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

Respuestas de error

Configuración

Mapeo de CLI a API

On this page