Saltar al contenido
Qomni

Agents

Crea un agente, dale voz y ponlo a atender: REST para las llamadas y un WebSocket para hablar con él en tiempo real desde tu app.

URL base
https://api.qomni.ai/agents/v1
Clave
sk_agents_test_…
curl https://api.qomni.ai/agents/v1/calls \
  -H "Authorization: Bearer sk_agents_test_…"

Novedades

Errores

La forma de todo error de la API de Qomni, cada campo que trae y qué hacer con cada código y estado HTTP.

Todo error de la API de Qomni tiene la misma forma, definida una sola vez en contracts/shared/v1/components.yaml#/components/schemas/Error. Decide por code, muestra message y guarda request_id.

Códigos

Estado code Qué hacer
401 api_key_missing Falta el header Authorization. Envía Authorization: Bearer <key>.
401 api_key_malformed La clave no tiene la forma sk_… o su checksum no cuadra. Cópiala de nuevo.
401 api_key_invalid La clave no existe o fue revocada. Crea otra.
401 api_key_wrong_product La clave es de otro producto. Usa una clave de Agents.
403 product_not_active El workspace no tiene Agents activo. Actívalo en Ajustes.
404 not_found La ruta o el recurso no existen.
404 host_moved El host es la dirección antigua de un producto (agents.qomni.ai), que ya no sirve páginas. Usa https://app.qomni.ai/{workspace}/{producto}.
404 api_host_moved El host es la dirección antigua de la API (agents-api.qomni.ai). No redirige: message trae la URL base nueva, https://api.qomni.ai/agents/v1. Cambia la URL base de tu cliente.
404 unknown_api El primer segmento de la ruta en api.qomni.ai no nombra ninguna API. Empieza la ruta por el producto y la versión (/agents/v1/…).
405 method_not_allowed La ruta existe, pero no con ese método.
410 product_host_moved Enviaste un POST, PUT, PATCH o DELETE a la dirección antigua de un producto (agents.qomni.ai). Esas direcciones sólo redirigen un GET o HEAD a app.qomni.ai/{workspace}/{producto}; envía la petición ahí. La API no pasa por esas direcciones: vive en https://api.qomni.ai/agents/v1.
421 wrong_cell La clave es de otra celda. No ocurre con una clave creada por el workspace.
422 validation_failed Un campo falta o no es válido. Corrige los campos de fields. Los campos desconocidos también se rechazan.
429 rate_limited Superaste el límite. Espera los segundos de Retry-After y reintenta. Ver Límites de uso.
503 origin_unavailable La celda no respondió. No se hizo nada: reintenta con backoff. Ver Idempotencia.

Cada operación de la referencia lista además los códigos propios de esa operación, por ejemplo demo_unavailable al abrir una sesión del demo.

Forma

{
  "error": {
    "code": "api_key_wrong_product",
    "message": "This key is for another product.",
    "request_id": "req_01m40n2ansfhj861etnav19mbp"
  }
}
Campo Tipo Descripción
code string, obligatorio Estable. Es el valor con el que decide tu código.
message string, obligatorio Para personas. Puede cambiar en cualquier momento: nunca compares contra él.
request_id string, obligatorio Identifica la petición. Inclúyelo cuando escribas a soporte.
fields objeto Sólo en validation_failed: los mensajes de cada campo, por nombre.

En el WebSocket de Agents, un error es un mensaje de tipo error con el mismo objeto { code, message } dentro.

En tu código

Lee code y guarda request_id. Por ejemplo, al crear una llamada sin destino la API responde 422 con el detalle de cada campo en fields:

422 Unprocessable Contentjson
{
  "error": {
    "code": "validation_failed",
    "message": "The to field is required.",
    "request_id": "req_52abfa8dd5144eee89f62f0c653310e5",
    "fields": {
      "to": ["The to field is required."]
    }
  }
}
Navegación del sitio

Nuevo

2 de 7 pasos hechosSigue: la plataforma en producción

Qomni está en beta privada

La API y la app todavía no están abiertas. Mira qué está hecho, qué falta y cómo se abre, paso a paso hasta el primer cliente.

Escribe para buscar…

↑↓ moverte↵ abrirEsc para cerrar