Referencia API

Documentacion completa del API REST para el API de gestion de OpenClaws.

Autenticacion

Todas las solicitudes al API requieren un encabezado X-API-Key:

header

X-API-Key: your-api-key-here

URL Base

https://api.openclaws.mx

Endpoints

Metodo	Ruta	Descripcion
POST	/api/v1/users	Crear un nuevo usuario
GET	/api/v1/users	Listar todos los usuarios
GET	/api/v1/users/{user}	Obtener detalles del usuario + agentes
DELETE	/api/v1/users/{user}	Eliminar usuario (cascada)
PUT	/api/v1/users/{user}/tier	Cambiar nivel/plan del usuario
POST	/api/v1/users/{user}/agents	Agregar agente(s) al usuario
GET	/api/v1/users/{user}/agents	Listar agentes del usuario
GET	/api/v1/users/{user}/agents/{agent}	Obtener detalles del agente
DELETE	/api/v1/users/{user}/agents/{agent}	Eliminar un agente
POST	/api/v1/users/{user}/agents/{agent}/rotate-key	Rotar clave API del agente
GET	/api/v1/users/{user}/agents/{agent}/connect	Obtener URL del gateway + token
POST	/api/v1/users/{user}/agents/{agent}/chat	Proxy de chat (reenviar al gateway)
GET	/healthz	Verificacion de salud

Crear Usuario

Aprovisiona un namespace de Nomad, cuota de recursos y volumen CSI.

POST /api/v1/users

{
  "name": "alice",
  "tier": "plan-3"
}

Response 201

{
  "user": {
    "name": "alice",
    "tier": "plan-3",
    "namespace": "oc-alice",
    "agents": []
  }
}

Agregar Agente(s)

Crea secretos por agente en Vault y reconstruye el contenedor del usuario. La anthropic_api_key es requerida al agregar el primer agente.

POST /api/v1/users/{user}/agents

{
  "agents": [
    { "name": "manager" },
    { "name": "researcher" }
  ],
  "anthropic_api_key": "sk-ant-api03-..."
}

Response 201

{
  "agents": [
    {
      "name": "manager",
      "api_key": "a1b2c3d4...",
      "default": true
    },
    {
      "name": "researcher",
      "api_key": "e5f6g7h8...",
      "default": false
    }
  ]
}

Obtener Usuario

GET /api/v1/users/{user}

Response 200:
{
  "user": {
    "name": "alice",
    "tier": "plan-3",
    "namespace": "oc-alice",
    "agents": ["manager", "researcher"],
    "quota": {
      "cpu_mhz": 1024,
      "memory_mb": 2048
    }
  }
}

Cambiar Nivel

PUT /api/v1/users/{user}/tier

{
  "tier": "plan-4"
}

Actualiza la cuota de recursos y los limites de agentes. Los agentes existentes se preservan. Si el nuevo nivel tiene un limite de agentes menor que la cantidad actual, la solicitud falla.

Proxy de Chat

Reenvia mensajes de chat al gateway de OpenClaw del usuario. Utilizado por el frontend ya que no puede acceder a IPs internas del VPC directamente.

POST /api/v1/users/{user}/agents/{agent}/chat

{
  "message": "Hello, what can you help me with?"
}

Response 200

{
  "message": "I can help you with research, writing, and analysis...",
  "agent": "manager"
}

Internamente envia una solicitud compatible con OpenAI con model: "openclaw:{agent}" y un timeout de 120s para respuestas lentas del LLM.

Obtener Informacion de Conexion

Devuelve la URL del gateway y el token de autenticacion para acceso directo.

GET /api/v1/users/{user}/agents/{agent}/connect

Response 200:
{
  "gateway_url": "http://10.128.0.5:18789",
  "token": "gw-token-...",
  "agent": "manager"
}

Rotar Clave API

POST /api/v1/users/{user}/agents/{agent}/rotate-key

Response 200:
{
  "agent": "manager",
  "api_key": "new-key-..."
}

Genera una nueva clave API hexadecimal de 64 caracteres y actualiza Vault. La clave anterior se invalida inmediatamente.

Eliminar Usuario (Cascada)

Detiene el job de Nomad, elimina todos los secretos de Vault, remueve las intenciones de Consul, elimina el volumen CSI, la cuota y el namespace.

DELETE /api/v1/users/{user}

Response 204 (No Content)