Skip to main content

Capabilities Marketplace Pricing Blog Help Center Contact

The platform to build agents with memory, custom tools, and a REST API.

Product

Capabilities
Marketplace
Pricing
Changelog

Resources

Blog
Documentation
About

Support

FAQs
Support
Contact

Legal

Privacy
Terms
License
Security
Data deletion
Disclaimer
Do not sell my data

© 2026 Arko Studio. All rights reserved.

Centro de ayuda
API y claves

API y claves

Usa Arko desde tu propio software: API REST, autenticación con API keys y streaming.

¿Cómo creo una API Key?Desde API Keys, pulsa Nueva API Key y define: Nombre — para identificar dónde se usa (p. ej. "Producción API"). Fecha de expiración — opcional; la clave deja de funcionar después de esa fecha. Permisos (scopes) — los recursos a los que esta clave podrá acceder. Al crearla, Arko te muestra la clave completa una sola vez. Importante: copia y guarda la clave en un lugar seguro en ese momento. Por seguridad, las claves se almacenan cifradas y no se pueden volver a mostrar después de crearlas.¿Cómo me autentico con la API?Todas las solicitudes a la API requieren un token Bearer en el encabezado Authorization. Usa la API Key que generaste (empiezan por sk-): Si el token es inválido o expiró, la API responde 401. Si la clave no tiene permiso para el recurso, responde 403. Revisa cómo manejar los errores y cómo funcionan los scopes.¿Cómo funcionan los permisos (scopes) de una clave?Cada API key lleva una lista de scopes: los recursos que esa clave puede tocar (agentes, chats, mensajes, powers, memorias…). Al crearla marcas exactamente los que necesita. En cada solicitud, la API verifica que la clave tenga el scope del recurso; si no lo tiene, responde 403 aunque la clave sea válida. Buenas prácticas: Mínimo privilegio: una clave por integración, solo con los scopes que esa integración usa. Un dashboard de solo lectura no necesita permisos de escritura. Claves separadas para desarrollo y producción: si una se filtra, la revocas sin tumbar la otra. La lista completa de scopes disponibles está en la documentación.¿Cuál es la URL base de la API?La URL base es: Todas las rutas son relativas a esa base. Por ejemplo, para enviar un mensaje: Desde ahí trabajas con tus recursos de Arko —agentes, chats, mensajes y powers— de forma programática, usando la misma autenticación Bearer. Cada recurso expone operaciones de listado, creación, edición y eliminación; el detalle por endpoint está en la documentación.¿Cómo envío mi primer mensaje con curl?Con tu API key y el ID de un agente (aid), un solo comando basta: La respuesta llega en streaming NDJSON: una línea JSON por evento (el chat creado, cada fragmento de la respuesta, el cierre). Verás algo como: No necesitas ningún SDK: funciona igual con fetch, axios o el cliente HTTP de tu stack. La documentación incluye un playground para probarlo sin salir del navegador.¿La API soporta respuestas en streaming?Sí. El endpoint POST /v3/messages devuelve por defecto un stream NDJSON (stream=true): recibes los mensajes generados a medida que se producen, línea por línea. Si prefieres una única respuesta con todo el resultado, pasa stream=false y obtendrás un JSON con todos los mensajes generados de una vez. Tip: usa streaming para interfaces de chat donde quieras mostrar la respuesta mientras se escribe; usa stream=false para procesos por lotes.¿La API tiene límites de uso propios?La API comparte los límites de tu plan: los mensajes por chat, agentes, memorias y powers que consumes por API salen de la misma cuota que usas en la web. No hay una cuota separada "de API". Además existe un límite de tasa para proteger el servicio: si envías demasiadas solicitudes en poco tiempo recibirás 429. En ese caso: Aplica reintentos con espera creciente (backoff exponencial). Reparte cargas por lotes en el tiempo en lugar de ráfagas. Si tu volumen crece de forma sostenida, Pro o Max elevan las cuotas del plan.¿Qué errores puede devolver la API?Los errores siguen un formato consistente: un JSON con success: false, un message legible y un código de error, junto al código de estado HTTP. Los más comunes: 400 — datos inválidos en la solicitud (revisa el message: indica el campo). 401 — token inválido o expirado. 403 — permisos insuficientes para el recurso (scopes). 404 — el recurso no existe o no es tuyo. 429 — límite de tasa excedido (espera y reintenta). 500 — error interno del servidor. Tip: registra el message y el código de error en tus logs; están pensados para diagnosticar sin adivinar. Ante un 429, aplica reintentos con espera creciente (backoff).¿Cómo elimino o expiro una API Key?Puedes controlar el ciclo de vida de cada clave de dos formas: Fecha de expiración — al crearla defines cuándo deja de funcionar automáticamente. Ideal para claves temporales (una demo, un contratista). Eliminar API Key — la revocas de inmediato. Cuidado: eliminar una clave es irreversible. Las aplicaciones que la usen dejarán de funcionar en cuanto la borres. Ten a mano una clave de reemplazo antes de revocar una en producción: crea la nueva, despliega el cambio y elimina la vieja al final.

¿No está tu pregunta? Busca en el centro de ayuda.