API DOCUMENTATION

API Documentation

Complete technical reference for integrating Arko via API Keys

Introducción

La API de Arko es REST puro con streaming NDJSON: sin SDK obligatorio, un curl basta. Los agentes, chats, mensajes y powers viven bajo /v3/; el perfil, las keys, las memorias y el Builder bajo /v2/.

Base URL: https://arko.arcaelas.com

POST, PUT y PATCH exigen Content-Type: application/json (si no, 415). Todos los ejemplos de esta página son ejecutables: pega tu API Key arriba y usa "Probar este endpoint" en cada bloque.

Autenticación

Toda petición autenticada lleva Authorization: Bearer <token>. Hay dos tokens: el JWT de Firebase (la sesión del navegador: recibe todos los scopes, incluido _jwt_only) y las API Keys sk-… creadas en /v2/keys, que solo reciben sus scopes asignados.

Header de autorización

curl https://arko.arcaelas.com/v3/agents \
  -H "Authorization: Bearer sk-..."

Scope	Autoriza
agents:read	Listar y consultar agentes
agents:write	Crear, editar y eliminar agentes; hablar con el Builder
chats:read	Listar y consultar chats y mensajes
chats:write	Enviar mensajes, editar y eliminar chats
powers:read	Listar y consultar powers
powers:write	Crear, editar y eliminar powers
memories:read	Listar y consultar memorias
memories:write	Crear, editar y eliminar memorias
keys:read	Listar y consultar API Keys
keys:delete	Eliminar API Keys
_jwt_only	Operaciones exclusivas del JWT de Firebase (perfil, keys, suscripción)

API Key expirada → 401 ERR_KEY_EXPIRED; sin token o inválido → 401 ERR_NO_TOKEN; API Key en endpoint solo-JWT → 403 ERR_INSUFFICIENT_SCOPE.

Envelope de respuesta

Todas las respuestas JSON comparten el mismo envelope. En producción, los errores 5xx y los mensajes técnicos se enmascaran.

Éxito

{ "success": true, "data": { … } }

// Listas paginadas
{ "success": true, "data": { "rows": [ … ], "count": 42, "offset": 0, "limit": 100 } }

Error

{
  "success": false,
  "message": "NOT_FOUND",
  "cause": { "code": "ERR_NOT_FOUND", "id": "<uuid>" }
}

Los endpoints en streaming responden application/x-ndjson: un evento JSON por línea, sin envelope.

Paginación

Parámetro	Default	Descripción
offset	0	Elementos a saltar.
limit	100	Máximo de elementos (max 100).
order	DESC	Más reciente primero. Excepción: los mensajes de chat y del wizard ordenan ASC (cronología).
search	—	Filtro parcial case-insensitive (max 200 chars).

Errores

Status	Código	Descripción
400	ERR_VALIDATION	Body o parámetros inválidos
400	ERR_INVALID_JSON	JSON malformado en el body
401	ERR_NO_TOKEN	Token ausente o inválido
401	ERR_KEY_EXPIRED	API Key expirada
403	ERR_INSUFFICIENT_SCOPE	La API Key no tiene el scope requerido (o el endpoint es _jwt_only)
403	ERR_FORBIDDEN	Acción no permitida (ej. API Key en un endpoint solo-JWT)
403	ERR_QUOTA_EXCEEDED	Cuota del plan superada (mensajes, memorias, imágenes)
403	ERR_CAPACITY_LIMIT	Límite de recursos de la cuenta alcanzado
404	ERR_NOT_FOUND	Recurso inexistente o de otro usuario
409	ERR_ALREADY_SUBSCRIBED	Suscripción ya activa
409	ERR_NOT_SUBSCRIBED	No hay suscripción que cancelar o reanudar
415	ERR_INVALID_CONTENT_TYPE	POST/PUT/PATCH exigen Content-Type: application/json
429	ERR_THROTTLED	Demasiadas peticiones en la ventana (contacto)
500	—	Error interno (mensaje enmascarado en producción)

Límites y planes

Cada plan define capacidades; excederlas devuelve 403 con ERR_QUOTA_EXCEEDED o ERR_CAPACITY_LIMIT según la ruta. El uso real se consulta en GET /v2/capacities.

Capacidad	Free	Pro
agents	20	20
messages_per_chat	20	150
memories	120	120
powers	50	50
parameters	10	10
agent_powers	5	5
images_per_chat	1	10
images_per_day	5	∞
images_per_month	∞	100

Autenticación

Registro y perfil del usuario autenticado. El registro y la gestión del perfil son exclusivos del JWT de Firebase.

POST/v2/authSolo JWT

Registrar usuario

Registra al usuario en la plataforma desde su JWT de Firebase. Idempotente: si ya existe, devuelve el existente (también 201).

Bootstrap para usuario nuevo: crea el Power get-time y el Agent arko (memory: true) vinculados.
API Keys no pueden registrar (403 ERR_FORBIDDEN); JWT inválido → 401 ERR_INVALID_TOKEN.

bash

curl -X POST https://arko.arcaelas.com/v2/auth \
  -H "Authorization: Bearer sk-..."

Respuesta (201)

{
  "success": true,
  "data": {
    "id": "9f2c4b1a-…",
    "fid": "firebase-uid",
    "name": "Miguel",
    "email": "m@x.com",
    "photo": "https://…",
    "anonymous": false,
    "created_at": "2026-07-01T00:00:00.000Z",
    "updated_at": "2026-07-01T00:00:00.000Z"
  }
}

GET/v2/auth

Perfil actual

Perfil completo del token en uso: identidad de Firebase más plan, scopes y capacidades activas.

kid es el id de la API Key usada (vacío con JWT). scopes: todos con JWT, los asignados con sk-.

bash

curl https://arko.arcaelas.com/v2/auth \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "id": "9f2c4b1a-…",
    "fid": "firebase-uid",
    "kid": "",
    "name": "Miguel",
    "email": "m@x.com",
    "photo": "https://…",
    "anonymous": false,
    "scopes": ["agents:read", "…", "_jwt_only"],
    "plan": "free",
    "plan_expires_at": "",
    "canceled": false,
    "capacities": [{ "name": "memories", "count": 120 }],
    "created_at": "…",
    "updated_at": "…"
  }
}

PUT/v2/authSolo JWT

Actualizar perfil

Actualiza name (sin HTML, max 100) y/o photo (URL http/https pública, max 2000). Escribe en Firebase y devuelve el perfil actualizado.

Parámetro	En	Tipo	Descripción
name	body	string	Nombre visible (max 100).
photo	body	string	URL pública http/https (hosts privados/loopback bloqueados).

bash

curl -X PUT https://arko.arcaelas.com/v2/auth \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Miguel G","photo":"https://cdn.example.com/me.png"}'

Respuesta (200)

{ "success": true, "data": { "…perfil con name/photo actualizados…" } }

DELETE/v2/authSolo JWT

Eliminar cuenta

Elimina la cuenta con cascada completa: usuario (DynamoDB + Firebase), keys, memorias, wizard, powers, agentes, chats, mensajes y tool calls. Irreversible.

bash

curl -X DELETE https://arko.arcaelas.com/v2/auth \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": null }

Planes y capacidades

Capacidades del plan activo con su uso real.

GET/v2/capacitiesSolo JWT

Capacidades y uso

Capacidades del plan con uso real. used es null en las capacidades por chat o por entidad (no tienen uso global).

bash

curl https://arko.arcaelas.com/v2/capacities \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "plan": "free",
    "plan_expires_at": "",
    "canceled": false,
    "capacities": [
      { "name": "memories", "cap": 120, "used": 3 },
      { "name": "messages_per_chat", "cap": 20, "used": null }
    ]
  }
}

Suscripción

Alta, cancelación y sincronización de la suscripción Pro ($4.99/mes vía Stripe).

POST/v2/servicesSolo JWT

Suscribirse a Pro

Crea un Stripe Checkout para el plan Pro. Si ya es Pro con cancelación programada, reanuda la suscripción en vez de crear checkout.

Ya suscrito y activo → 409 ERR_ALREADY_SUBSCRIBED; nada que reanudar → 409 ERR_NOT_SUBSCRIBED.

Parámetro	En	Tipo	Descripción
plan *	body	"pro"	Único plan contratable por API.

bash

curl -X POST https://arko.arcaelas.com/v2/services \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"plan":"pro"}'

Respuesta (200)

{ "success": true, "data": { "url": "https://checkout.stripe.com/…" } }

// Reanudación
{ "success": true, "data": { "resumed": true } }

DELETE/v2/servicesSolo JWT

Cancelar suscripción

Cancela la suscripción Pro al final del período (reversible, sin reembolso; sigue Pro hasta vencer).

Sin suscripción activa → 409 ERR_NOT_SUBSCRIBED.

bash

curl -X DELETE https://arko.arcaelas.com/v2/services \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": { "canceled": true } }

POST/v2/services/webhookPúblico

Webhook de Stripe

Autentica por firma stripe-signature (no Bearer). Sincroniza el alta, la renovación y la cancelación de la suscripción. Responde JSON plano de Stripe, sin envelope.

bash

curl -X POST https://arko.arcaelas.com/v2/services/webhook

Respuesta (200)

{ "received": true }

API Keys

Credenciales sk- para acceso programático. Gestión exclusiva del JWT: una API Key no puede gestionar keys.

GET/v2/keysSolo JWT

Listar keys

API Keys del usuario. El sha va truncado a 10 chars + "…" — el valor completo solo se ve en la creación y en el detalle.

Parámetro	En	Tipo	Descripción
offset	query	integer	Elementos a saltar (default 0).
limit	query	integer	Máximo de elementos (default 100, max 100).
order	query	string	Dirección: DESC (default, más reciente primero) o ASC.
search	query	string	Filtro parcial case-insensitive (max 200 chars).

bash

curl https://arko.arcaelas.com/v2/keys \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "rows": [{
      "id": "…",
      "name": "CI",
      "sha": "sk-a1b2c3...",
      "scopes": ["agents:read"],
      "expired_at": "",
      "created_at": "…",
      "updated_at": "…"
    }],
    "count": 1,
    "offset": 0,
    "limit": 100
  }
}

POST/v2/keysSolo JWT

Crear key

Crea una API Key y devuelve el sha completo — única oportunidad razonable de copiarlo.

Parámetro	En	Tipo	Descripción
name *	body	string	Nombre de la key (max 100).
scopes	body	string[]	Del catálogo agents\|powers\|chats\|memories:(read\|write), keys:read, keys:delete. Se deduplican.
expired_at	body	string	ISO 8601 futura; vacío = no expira.

bash

curl -X POST https://arko.arcaelas.com/v2/keys \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"name":"CI","scopes":["agents:read","chats:write"],"expired_at":"2027-01-01T00:00:00Z"}'

Respuesta (201)

{
  "success": true,
  "data": {
    "id": "…",
    "name": "CI",
    "sha": "sk-<64 hex>",
    "scopes": ["agents:read", "chats:write"],
    "expired_at": "2027-01-01T00:00:00.000Z",
    "created_at": "…",
    "updated_at": "…"
  }
}

GET/v2/keys/{id}Solo JWT

Detalle de key

Detalle con el sha completo. Key ajena o inexistente → 404 ERR_NOT_FOUND.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl https://arko.arcaelas.com/v2/keys/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": { "id": "…", "name": "CI", "sha": "sk-<64 hex>", "scopes": ["agents:read"], "expired_at": "", "created_at": "…", "updated_at": "…" } }

PUT/v2/keys/{id}Solo JWT

Editar key

Actualiza name y/o scopes (reemplaza el set completo).

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.
name	body	string	Nuevo nombre (max 100).
scopes	body	string[]	Set completo de scopes (reemplaza).

bash

curl -X PUT https://arko.arcaelas.com/v2/keys/<id> \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"scopes":["agents:read"]}'

Respuesta (200)

{ "success": true, "data": { "id": "…", "name": "CI", "sha": "sk-<64 hex>", "scopes": ["agents:read"], "expired_at": "", "created_at": "…", "updated_at": "…" } }

DELETE/v2/keys/{id}Solo JWT

Eliminar key

Hard delete: la key deja de funcionar de inmediato.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl -X DELETE https://arko.arcaelas.com/v2/keys/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": null }

Agentes

Asistentes configurables con memoria, web, imágenes y powers vinculados.

GET/v3/agentsagents:read

Listar agentes

Agentes del usuario. search filtra por nombre; content va truncado a 300 chars (completo en el detalle).

Parámetro	En	Tipo	Descripción
offset	query	integer	Elementos a saltar (default 0).
limit	query	integer	Máximo de elementos (default 100, max 100).
order	query	string	Dirección: DESC (default, más reciente primero) o ASC.
search	query	string	Filtro parcial case-insensitive (max 200 chars).

bash

curl https://arko.arcaelas.com/v3/agents \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "rows": [{
      "id": "550e8400-…",
      "name": "support_bot",
      "content": "You help users…",
      "memory": true,
      "web": false,
      "images": false,
      "created_at": "…",
      "updated_at": "…"
    }],
    "count": 1,
    "offset": 0,
    "limit": 100
  }
}

POST/v3/agentsagents:write

Crear agente

Crea un agente. Los powers ajenos o inexistentes se ignoran en silencio.

Capacidades agents (20) y agent_powers (5) → 403 ERR_CAPACITY_LIMIT.

Parámetro	En	Tipo	Descripción
name *	body	string	Nombre del agente (max 200).
content	body	string	System prompt (max 5000).
memory	body	boolean	Memoria persistente. Solo con JWT; con API Key se fuerza a false.
web	body	boolean	Búsqueda web. Solo con JWT.
images	body	boolean	Generación de imágenes. Solo con JWT.
powers	body	string[]	IDs de powers a vincular (max 20).

bash

curl -X POST https://arko.arcaelas.com/v3/agents \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"name":"support_bot","content":"You help users","memory":true,"powers":[]}'

Respuesta (201)

{
  "success": true,
  "data": {
    "id": "550e8400-…",
    "name": "support_bot",
    "content": "You help users",
    "memory": true,
    "web": false,
    "images": false,
    "created_at": "…",
    "updated_at": "…"
  }
}

GET/v3/agents/{id}agents:read

Detalle de agente

Detalle con sus powers expandidos (webhook + parameters). Ajeno o inexistente → 404 ERR_NOT_FOUND.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl https://arko.arcaelas.com/v3/agents/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "id": "550e8400-…",
    "name": "support_bot",
    "content": "…",
    "memory": true,
    "web": false,
    "images": false,
    "powers": [{
      "id": "…",
      "name": "slack",
      "content": "Send msgs",
      "webhook": { "url": "https://…", "header": {} },
      "parameters": [{ "id": "…", "name": "channel", "content": "Slack channel", "value": "", "required": true }],
      "created_at": "…",
      "updated_at": "…"
    }],
    "created_at": "…",
    "updated_at": "…"
  }
}

PUT/v3/agents/{id}agents:write

Actualizar agente

Actualización parcial. powers (si viene) reemplaza el set completo vía diff: desvincula los ausentes y vincula los nuevos.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.
name	body	string	Nuevo nombre.
content	body	string	Nuevo system prompt (max 5000).
memory	body	boolean	Solo con JWT.
web	body	boolean	Solo con JWT.
images	body	boolean	Solo con JWT.
powers	body	string[]	Set completo de IDs (reemplaza vía diff).

bash

curl -X PUT https://arko.arcaelas.com/v3/agents/<id> \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"name":"soporte_v2","web":true}'

Respuesta (200)

{ "success": true, "data": { "id": "550e8400-…", "name": "soporte_v2", "web": true, "…": "…" } }

DELETE/v3/agents/{id}agents:write

Eliminar agente

Elimina el agente con cascada: sus chats, mensajes, tool calls y vínculos agent_power.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl -X DELETE https://arko.arcaelas.com/v3/agents/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": null }

Chats

Conversaciones con agentes. Se crean automáticamente al enviar un mensaje con aid — no hay endpoint de creación directa.

GET/v3/chatschats:read

Listar chats

Chats del usuario ordenados por actividad reciente (updated_at). content es el último mensaje visible truncado a 150 chars.

Parámetro	En	Tipo	Descripción
offset	query	integer	Elementos a saltar (default 0).
limit	query	integer	Máximo de elementos (default 100, max 100).
order	query	string	Dirección: DESC (default, más reciente primero) o ASC.
search	query	string	Filtro parcial case-insensitive (max 200 chars).
archived	query	boolean	Filtra por estado de archivo.

bash

curl https://arko.arcaelas.com/v3/chats \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "rows": [{
      "id": "c1a2b3d4-…",
      "name": "Ideas de marca",
      "content": "Aroma Norte, Café Vereda…",
      "archived": false,
      "agent": { "id": "…", "name": "arko" },
      "created_at": "…",
      "updated_at": "…"
    }],
    "count": 1,
    "offset": 0,
    "limit": 100
  }
}

GET/v3/chats/{id}chats:read

Detalle de chat

Mismo shape que la lista. Ajeno o inexistente → 404 ERR_NOT_FOUND.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl https://arko.arcaelas.com/v3/chats/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": { "id": "c1a2b3d4-…", "name": "Ideas de marca", "content": "…", "archived": false, "agent": { "id": "…", "name": "arko" }, "created_at": "…", "updated_at": "…" } }

PUT/v3/chats/{id}chats:write

Renombrar o archivar

Renombra (name 1–200) y/o archiva/desarchiva (archived).

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.
name	body	string	Nuevo nombre (1–200).
archived	body	boolean	Estado de archivo.

bash

curl -X PUT https://arko.arcaelas.com/v3/chats/<id> \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'

Respuesta (200)

{ "success": true, "data": { "id": "c1a2b3d4-…", "name": "Ideas de marca", "archived": true, "…": "…" } }

DELETE/v3/chats/{id}chats:write

Eliminar chat

Elimina el chat con cascada de mensajes y tool calls.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl -X DELETE https://arko.arcaelas.com/v3/chats/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": null }

GET/v3/chats/{id}/messageschats:read

Mensajes del chat

Mensajes visibles: solo user/assistant con contenido no vacío (los tool se excluyen). Orden por created_at, default ASC (cronología).

A diferencia del resto de listas, aquí el orden por defecto es ASC.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.
offset	query	integer	Elementos a saltar (default 0).
limit	query	integer	Máximo de elementos (default 100, max 100).
order	query	string	Dirección: DESC (default, más reciente primero) o ASC.
search	query	string	Filtro parcial case-insensitive (max 200 chars).

bash

curl https://arko.arcaelas.com/v3/chats/<id>/messages \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "rows": [{
      "id": "…",
      "role": "user",
      "content": "Hola",
      "type": "text",
      "created_at": "…",
      "updated_at": "…"
    }],
    "count": 2,
    "offset": 0,
    "limit": 100
  }
}

Mensajes

El endpoint central: envía un mensaje a un agente y recibe la respuesta en streaming NDJSON o como JSON completo.

POST/v3/messageschats:write

Enviar mensaje

Envía un mensaje. cid usa un chat existente; aid crea chat nuevo (cid tiene prioridad). El mensaje del usuario se persiste ANTES de llamar a la IA: no se pierde si el stream falla.

Tools internos según flags del agente: fecha/hora siempre; memorias si memory; búsqueda web si web; generación de imágenes si images; más sus powers vinculados.
Cuota messages_per_chat cuenta solo mensajes user del chat → 403 ERR_QUOTA_EXCEEDED.
Con stream: false, los id y timestamps de messages en la respuesta son sintéticos (los persistidos difieren).
El evento tool va ofuscado ("{}"), salvo image_generate que emite { type: "image", url } con la URL real.

Parámetro	En	Tipo	Descripción
content *	body	string	Texto del mensaje.
cid	body	uuid	Chat existente (prioridad sobre aid).
aid	body	uuid	Agente: crea un chat nuevo si no hay cid.
stream	body	boolean	NDJSON en vivo (default true). false = JSON completo.

bash

curl -X POST -N https://arko.arcaelas.com/v3/messages \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"content":"Hola","aid":"550e8400-…","stream":true}'

Respuesta (201) · NDJSON

{ "type": "chat", "id": "c1a2…", "name": "Hola", "agent": { "id": "550e…", "name": "arko" } }
{ "type": "message", "id": "…", "role": "user", "content": "Hola" }
{ "type": "message_start", "id": "…" }
{ "type": "delta", "content": "Hola, ¿en qué" }
{ "type": "tool_call", "id": "call_…", "name": "web_search", "arguments": "{}" }
{ "type": "tool", "id": "call_…", "name": "web_search", "content": "{}" }
{ "type": "image", "id": "call_…", "url": "https://…" }
{ "type": "message_end", "id": "…" }
{ "type": "done", "messages": [ … ] }

Powers

Webhooks que la IA puede invocar como herramientas: cualquier API REST al servicio del agente.

GET/v3/powerspowers:read

Listar powers

Powers del usuario. content truncado a 300; la lista incluye url y method pero no header ni parameters (eso está en el detalle).

Parámetro	En	Tipo	Descripción
offset	query	integer	Elementos a saltar (default 0).
limit	query	integer	Máximo de elementos (default 100, max 100).
order	query	string	Dirección: DESC (default, más reciente primero) o ASC.
search	query	string	Filtro parcial case-insensitive (max 200 chars).

bash

curl https://arko.arcaelas.com/v3/powers \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "rows": [{
      "id": "…",
      "name": "slack",
      "content": "Send msgs…",
      "url": "https://hooks.slack.com/…",
      "method": "POST",
      "created_at": "…",
      "updated_at": "…"
    }],
    "count": 1,
    "offset": 0,
    "limit": 100
  }
}

POST/v3/powerspowers:write

Crear power

Registra un webhook como herramienta. content es la descripción con la que la IA decide cuándo invocarlo.

Capacidades powers (50) y parameters (10) → 403 ERR_CAPACITY_LIMIT.

Parámetro	En	Tipo	Descripción
name *	body	string	Nombre del power (max 200).
content	body	string	Descripción para la IA (max 500).
url *	body	string	URL https pública (validada segura).
method	body	string	GET\|POST\|PUT\|DELETE\|PATCH (default GET).
x_header_key	body	string	Nombre del header de auth del webhook.
x_header_value	body	string	Valor del header de auth.
parameters	body	object[]	{ name, content, value?, required? } — max 50 por petición.

bash

curl -X POST https://arko.arcaelas.com/v3/powers \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"name":"slack","content":"Send messages to Slack","url":"https://hooks.slack.com/services/T00/B00/xxxx","method":"POST","parameters":[{"name":"text","content":"Message content","required":true}]}'

Respuesta (201)

{
  "success": true,
  "data": {
    "id": "…",
    "name": "slack",
    "content": "Send messages to Slack",
    "webhook": { "url": "https://hooks.slack.com/…", "method": "POST", "header": {} },
    "parameters": [{ "id": "…", "name": "text", "content": "Message content", "value": "", "required": true }],
    "created_at": "…",
    "updated_at": "…"
  }
}

GET/v3/powers/{id}powers:read

Detalle de power

Detalle con webhook { url, method, header } y parameters completos.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl https://arko.arcaelas.com/v3/powers/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": { "id": "…", "name": "slack", "content": "…", "webhook": { "url": "https://…", "method": "POST", "header": { "Authorization": "Bearer xxx" } }, "parameters": [], "created_at": "…", "updated_at": "…" } }

PUT/v3/powers/{id}powers:write

Actualizar power

Actualización parcial + gestión de parámetros en la misma llamada: item con id → actualiza; con id y name: null → elimina; sin id → crea.

Valida la capacidad parameters sobre el conteo final (existentes − borrados + creados).

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.
name	body	string	Nuevo nombre.
content	body	string	Nueva descripción (max 500).
url	body	string	Nueva URL (validada segura).
method	body	string	Nuevo método HTTP.
parameters	body	object[]	Mixto crear/editar/borrar en una sola petición.

bash

curl -X PUT https://arko.arcaelas.com/v3/powers/<id> \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"method":"PUT","parameters":[{"name":"text","required":true}]}'

Respuesta (200)

{ "success": true, "data": { "…power completo con webhook y parameters actualizados…" } }

DELETE/v3/powers/{id}powers:write

Eliminar power

Elimina el power con cascada: sus parameters y sus vínculos con agentes (los agentes permanecen).

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl -X DELETE https://arko.arcaelas.com/v3/powers/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": null }

Memorias

Información persistente del usuario que los agentes con memoria consultan y guardan.

GET/v2/memoriesmemories:read

Listar memorias

Memorias del usuario. search filtra por contenido; content truncado a 300 chars (completo en el detalle).

Parámetro	En	Tipo	Descripción
offset	query	integer	Elementos a saltar (default 0).
limit	query	integer	Máximo de elementos (default 100, max 100).
order	query	string	Dirección: DESC (default, más reciente primero) o ASC.
search	query	string	Filtro parcial case-insensitive (max 200 chars).

bash

curl https://arko.arcaelas.com/v2/memories \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "rows": [{
      "id": "…",
      "content": "Le gusta el café…",
      "created_at": "…",
      "updated_at": "…"
    }],
    "count": 1,
    "offset": 0,
    "limit": 100
  }
}

POST/v2/memoriesmemories:write

Crear memoria

Crea una memoria (content sanitizado, max 500).

Capacidad memories (120) → 403 ERR_QUOTA_EXCEEDED.

Parámetro	En	Tipo	Descripción
content *	body	string	Contenido (max 500).

bash

curl -X POST https://arko.arcaelas.com/v2/memories \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"content":"Prefiere respuestas cortas"}'

Respuesta (201)

{ "success": true, "data": { "id": "…", "content": "Prefiere respuestas cortas", "created_at": "…", "updated_at": "…" } }

GET/v2/memories/{id}memories:read

Detalle de memoria

Contenido completo. Ajena o inexistente → 404 ERR_NOT_FOUND.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl https://arko.arcaelas.com/v2/memories/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": { "id": "…", "content": "…", "created_at": "…", "updated_at": "…" } }

PUT/v2/memories/{id}memories:write

Editar memoria

Actualiza el contenido (max 500).

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.
content *	body	string	Nuevo contenido (max 500).

bash

curl -X PUT https://arko.arcaelas.com/v2/memories/<id> \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"content":"Prefiere respuestas muy cortas"}'

Respuesta (200)

{ "success": true, "data": { "id": "…", "content": "Prefiere respuestas muy cortas", "created_at": "…", "updated_at": "…" } }

DELETE/v2/memories/{id}memories:write

Eliminar memoria

Hard delete.

Parámetro	En	Tipo	Descripción
id *	path	uuid	Identificador del recurso.

bash

curl -X DELETE https://arko.arcaelas.com/v2/memories/<id> \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": null }

Wizard (Builder)

El asistente conversacional que crea y edita agentes y powers bajo confirmación explícita. Un solo hilo por usuario.

POST/v2/wizard/messagesagents:write

Hablar con el Builder

Chat con el Builder. Respuesta SIEMPRE en stream NDJSON. Sus tools: list/create/update de agentes y powers, vínculos y memory_search.

El evento tool ofusca el contenido y agrega agent { id, name } cuando create_agent/update_agent tiene éxito.

Parámetro	En	Tipo	Descripción
content *	body	string	Mensaje para el Builder.

bash

curl -X POST -N https://arko.arcaelas.com/v2/wizard/messages \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"content":"crea un agente de soporte"}'

Respuesta (200) · NDJSON

{ "type": "message", "id": "…", "role": "user", "content": "crea un agente de soporte" }
{ "type": "message_start", "id": "…" }
{ "type": "delta", "content": "¿Nombre?" }
{ "type": "message_end", "id": "…" }
{ "type": "tool_call", "id": "…", "name": "create_agent", "arguments": "{}" }
{ "type": "tool", "id": "…", "name": "create_agent", "content": "{}", "agent": { "id": "…", "name": "support_bot" } }
{ "type": "done" }

GET/v2/wizard/messagesagents:read

Historial del Builder

Historial paginado, default ASC. Aquí los role: "tool" van con contenido completo y los tool_calls del assistant inline (sin ofuscar).

Parámetro	En	Tipo	Descripción
offset	query	integer	Elementos a saltar (default 0).
limit	query	integer	Máximo de elementos (default 100, max 100).
order	query	string	Dirección: DESC (default, más reciente primero) o ASC.
search	query	string	Filtro parcial case-insensitive (max 200 chars).

bash

curl https://arko.arcaelas.com/v2/wizard/messages \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{
  "success": true,
  "data": {
    "rows": [{
      "id": "…",
      "role": "assistant",
      "content": "Hecho.",
      "type": "text",
      "tool_call_id": "",
      "tool_calls": [{ "id": "…", "tcid": "call_…", "name": "create_agent", "arguments": "{\"name\":\"support_bot\"}" }],
      "created_at": "…",
      "updated_at": "…"
    }],
    "count": 12,
    "offset": 0,
    "limit": 100
  }
}

DELETE/v2/wizard/messagesagents:write

Vaciar conversación

Vacía la conversación del wizard (mensajes + tool calls).

bash

curl -X DELETE https://arko.arcaelas.com/v2/wizard/messages \
  -H "Authorization: Bearer sk-..."

Respuesta (200)

{ "success": true, "data": null }

Reportes

Moderación: reporta un mensaje de un chat.

POST/v2/reports

Reportar mensaje

Reporta un mensaje. reason: harmful | inaccurate | offensive | privacy | other. Envía email interno; fallo de envío → 500 ERR_REPORT_FAILED.

Parámetro	En	Tipo	Descripción
mid *	body	uuid	ID del mensaje reportado.
cid *	body	uuid	ID del chat.
reason *	body	string	harmful \| inaccurate \| offensive \| privacy \| other.
details	body	string	Detalle opcional (max 500).

bash

curl -X POST https://arko.arcaelas.com/v2/reports \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"mid":"<message-id>","cid":"<chat-id>","reason":"inaccurate","details":"Inventó cifras"}'

Respuesta (201)

{ "success": true, "data": { "reported": true } }

Contacto

Formulario público de contacto con throttle en memoria contra abuso.

POST/v2/contactPúblico

Enviar mensaje de contacto

Público (sin auth). Envía el mensaje a la bandeja de la plataforma. email max 254 con regex, message max 5000.

Throttle por IP: superar el límite por ventana → 429 ERR_THROTTLED.

Parámetro	En	Tipo	Descripción
email *	body	string	Correo de respuesta (max 254).
message *	body	string	Contenido del problema (max 5000).

bash

curl -X POST https://arko.arcaelas.com/v2/contact \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@x.com","message":"Hola…"}'

Respuesta (200)

{ "success": true, "data": { "sent": true } }