Em resumo
- Agentes, chats e contatos.Crie, leia, atualize e exclua agentes, e leia conversas, mensagens e contatos.
- Chaves só com o que precisam.Chaves secretas para seus servidores, chaves restritas limitadas às permissões que você marcar.
- OpenAPI 3.1 incluído.Uma descrição legível por máquina é servida ao vivo, gerada a partir das mesmas regras que a API verifica.
- Seguro para repetir.Envie um Idempotency-Key e uma escrita repetida devolve o primeiro resultado em vez de rodar duas vezes.
Uma API permite que seu próprio software converse diretamente com a OneType. Agências configuram agentes para clientes a partir de um script, equipes de produto levam conversas para seus próprios relatórios e equipes de operações mantêm as configurações dos agentes em código. A API REST dá os mesmos dados e regras do painel, por HTTPS simples.
O que você pode fazer
- Agentes: liste, crie, leia, atualize e exclua, incluindo instruções, modelo, domínios permitidos e perguntas sugeridas.
- Conversas: liste por agente, status ou data de início, leia uma e leia as mensagens dela.
- Contatos: liste e leia as pessoas que seu agente conheceu.
- Chat: abra uma conversa e receba a resposta do agente, em JSON ou em streaming.
- Baixe a descrição OpenAPI 3.1 em /v1/openapi.json.
Cada mensagem informa se foi escrita pela IA ou pela sua equipe. As listas usam cursores, de 1 a 100 itens por página, e permanecem estáveis enquanto novos itens chegam. Uma atualização pode levar a revisão que você leu, de modo que uma mudança feita por alguém nesse meio-tempo é recusada em vez de sobrescrita.
Chaves de API com escopos
Proprietários e administradores criam chaves em “Developer”, “API keys”. Uma chave secreta pode fazer o que um administrador do workspace pode, exceto gerenciar chaves e ações exclusivas de proprietários. Uma chave restrita tem apenas as permissões que você marcar, nunca mais do que as suas. Use uma chave restrita por integração ou script, para que cada uma faça apenas o seu trabalho.
Uma chave é mostrada uma vez e guardada em formato hash. A lista mostra os últimos caracteres de cada chave e quando foi usada pela última vez. Revogue uma chave e a próxima solicitação com ela falha. As chaves pertencem a um workspace e nunca podem ler os dados de outro.
Feita para integrações reais
Todo erro tem o mesmo formato, com um código estável, uma mensagem, detalhes de campo quando aplicáveis e um id de solicitação. Envie Idempotency-Key em uma escrita e o primeiro resultado é mantido por 24 horas, de modo que uma nova tentativa após um timeout nunca cria um segundo agente ou uma segunda resposta.
Cada chave pode fazer 100 solicitações e até 20 mensagens de chat a cada 10 segundos. Os cabeçalhos RateLimit mostram quanto resta, e um 429 informa quanto esperar. Os limites são os mesmos em todo plano pago. Solicitações com uma chave errada são limitadas por endereço de rede.
O que a API ainda não cobre
Fontes de conhecimento, uso, webhooks e integrações são gerenciados no painel, não pela API. Os contatos são somente leitura. As chaves são apenas para servidores: ainda não há chave para navegador. Hoje não há SDK publicado no npm, então use HTTPS simples ou gere um cliente a partir do arquivo OpenAPI.
O arquivo OpenAPI é gerado a partir dos mesmos esquemas que a API usa para verificar solicitações, então nunca se desvia do que o servidor aceita. A API só muda acrescentando coisas: novos campos, novos endpoints e novos tipos de evento, de modo que um código que ignora campos desconhecidos continua funcionando.