En resumen
- Agentes, chats y contactos.Cree, lea, actualice y elimine agentes, y lea conversaciones, mensajes y contactos.
- Claves con solo lo que necesitan.Claves secretas para sus servidores, claves restringidas limitadas a los permisos que marque.
- OpenAPI 3.1 incluido.Una descripción legible por máquinas se sirve en directo, generada a partir de las mismas reglas que comprueba la API.
- Seguro para reintentar.Envíe una Idempotency-Key y una escritura reintentada devuelve el primer resultado en lugar de ejecutarse dos veces.
Una API permite que su propio software hable directamente con OneType. Las agencias configuran agentes para sus clientes desde un script, los equipos de producto llevan las conversaciones a sus propios informes y los equipos de operaciones mantienen los ajustes de los agentes en código. La API REST le da los mismos datos y reglas que el panel, por HTTPS sencillo.
Lo que puede hacer
- Agentes: listar, crear, leer, actualizar y eliminar, incluidas instrucciones, modelo, dominios permitidos y preguntas sugeridas.
- Conversaciones: listarlas por agente, estado o fecha de inicio, leer una y leer sus mensajes.
- Contactos: listar y leer a las personas que ha conocido su agente.
- Chat: abrir una conversación y recibir la respuesta del agente, en JSON o en streaming.
- Descargar la descripción OpenAPI 3.1 en /v1/openapi.json.
Cada mensaje indica si lo escribió una IA o su equipo. Las listas usan cursores, de 1 a 100 elementos por página, y se mantienen estables mientras llegan elementos nuevos. Una actualización puede llevar la revisión que usted leyó, de modo que un cambio hecho por otra persona entre medias se rechaza en lugar de sobrescribirse.
Claves de API con permisos
Los propietarios y administradores crean claves en “Developer”, “API keys”. Una clave secreta puede hacer lo que puede hacer un administrador del workspace, salvo gestionar claves y las acciones exclusivas de propietarios. Una clave restringida tiene solo los permisos que usted marca, nunca más que los suyos. Use una clave restringida por integración o script, para que cada una pueda hacer solo su trabajo.
Una clave se muestra una sola vez y se guarda como hash. La lista muestra los últimos caracteres de cada clave y cuándo se usó por última vez. Revoque una clave y la siguiente solicitud con ella falla. Las claves pertenecen a un workspace y nunca pueden leer los datos de otro.
Pensada para integraciones reales
Todo error tiene la misma forma, con un código estable, un mensaje, detalles de campo cuando proceden y un id de solicitud. Envíe Idempotency-Key en una escritura y el primer resultado se conserva durante 24 horas, así que un reintento tras un tiempo de espera agotado nunca crea un segundo agente ni una segunda respuesta.
Cada clave puede hacer 100 solicitudes y hasta 20 mensajes de chat cada 10 segundos. Las cabeceras RateLimit muestran cuánto queda, y un 429 indica cuánto esperar. Los límites son los mismos en todos los planes de pago. Las solicitudes con una clave incorrecta se limitan por dirección de red.
Lo que la API aún no cubre
Las fuentes de conocimiento, el uso, los webhooks y las integraciones se gestionan en el panel, no a través de la API. Los contactos son de solo lectura. Las claves son solo para servidores: aún no hay clave de navegador. Hoy no hay un SDK publicado en npm, así que use HTTPS sencillo o genere un cliente a partir del archivo OpenAPI.
El archivo OpenAPI se genera a partir de los mismos esquemas que usa la API para comprobar las solicitudes, así que nunca se desvía de lo que acepta el servidor. La API solo cambia añadiendo cosas: campos nuevos, endpoints nuevos y tipos de evento nuevos, de modo que el código que ignora los campos desconocidos sigue funcionando.