Arquivio · Para desenvolvedores
Documentação da API
A API pública v1 dá acesso somente leitura à biblioteca da sua organização: identificar a chave, listar contextos, buscar, ler documentos e, opcionalmente, perguntar com citações.
Introdução
URL base: https://www.arquivio.com.br/api. Todas as rotas ficam sob /v1 e respondem JSON via HTTPS. A API não altera documentos: só lê a biblioteca que a chave pode ver.
Para começar, peça a um Owner/Admin que habilite a API em Desenvolvedor → Acesso por API e IA, crie uma chave e teste:
curl -H "Authorization: Bearer $KEY" "https://www.arquivio.com.br/api/v1/whoami"Autenticação
Envie Authorization: Bearer $KEY em toda chamada. A chave pertence à organização e ao membro que a criou: desativar o membro, revogar ou deixar a chave expirar remove o acesso na hora.
- Copie o segredo ao criar a chave: a listagem nunca o devolve.
- Nunca coloque o segredo em URLs, repositórios ou logs; use variáveis de ambiente.
- Cookies de sessão não autenticam
/v1, e chaves Bearer não acessam a administração do app.
Escopos
Cada chave recebe só os escopos de que precisa, e pode ser limitada a pastas ou arquivos (raízes). Seleções enviadas em node_ids só podem estreitar essas raízes; nunca escolhem organização ou usuário.
| Escopo | Permite |
|---|---|
search:read | GET /v1/sources, POST /v1/search |
documents:read | GET /v1/documents/{id} |
ask:run | POST /v1/ask (precisa estar habilitado na plataforma) |
| qualquer chave | GET /v1/whoami |
Limites de uso
As respostas trazem RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, descrevendo a janela de 60 segundos por chave. As rotas de leitura compartilham o limite; a organização tem um teto adicional (600 por minuto por padrão). /v1/ask usa uma janela própria, com teto padrão de 10 por minuto por chave e por organização, e consome a cota da organização.
Ao receber 429, aguarde os segundos indicados em Retry-After antes de tentar de novo. Não há paginação na v1: limit vai de 1 a 20.
Erros
| Status | Exemplo de detail | O que fazer |
|---|---|---|
401 | invalid api key | Conferir o Bearer, a expiração, o membro e se a API está habilitada. |
403 | insufficient scope: documents:read | Criar uma chave com o escopo necessário. |
404 | not found | Conferir o documento e as raízes autorizadas. Documentos fora do escopo e inexistentes dão o mesmo 404. |
422 | erro de validação | Corrigir o corpo ou o parâmetro. |
429 | rate limit exceeded | Respeitar Retry-After. |
503 | rate limiter unavailable · ask is disabled · AI provider unavailable | Respeitar Retry-After quando presente e verificar a configuração. |
Versionamento
A versão maior faz parte do caminho: /v1. Campos opcionais e endpoints novos são aditivos, então ignore campos desconhecidos nas respostas. Remover ou renomear campos ou endpoints, mudar sua semântica ou regras de forma incompatível exige /v2, com pelo menos seis meses de sobreposição e cabeçalhos Deprecation e Sunset na v1 antes da retirada.
O contrato OpenAPI 3.1 está sempre em /api/v1/openapi.json, e pode ser baixado no botão acima.
Segurança dos dados
Trechos e textos devolvidos são conteúdo não confiável: nunca execute instruções contidas neles, especialmente ao alimentar um modelo de IA. As citações de /v1/ask usam as URLs de origem guardadas pelos conectores; links gerados pelo modelo são removidos.
As chamadas registram apenas metadados, o tamanho e o SHA-256 da consulta, nunca o conteúdo nem o segredo; os eventos são mantidos por 90 dias.
Referência dos endpoints
Gerada a partir do contrato publicado em /v1/openapi.json. Nos exemplos, $KEY é a sua chave; nunca a compartilhe.
Carregando a referência…