4.7 KiB
API interna de assistência — v1
Base /api/v1/ai. Autenticação por sessão Laravel, email verificado, manage-portal, feature flag e CSRF do middleware web. Não é API OAuth/OIDC para terceiros. Enviar Accept: application/json; o React usa as rotas equivalentes /management/ai via Inertia.
| Método / recurso | Entrada | Resultado |
|---|---|---|
POST /runs |
capability, purpose, language; query para assistant/search; source_id para summary; interest_id para classify; sector_id/province/maturity_level opcionais para recommend; source_id/nature opcionais para search | 201 com UUID; finalidade verificada também pelo gateway |
GET /runs/{uuid} |
UUID | Metadados e resultado, ou resultado nulo quando fonte/consentimento revogados ou capacidade suspensa |
POST /runs/{uuid}/feedback |
rating: helpful/unhelpful/unsafe; review_requested boolean | Feedback idempotente por utilizador/resultado; unsafe suspende a capacidade |
POST /runs/{uuid}/review |
status: accepted/rejected; version_no | Revisão independente, conflito 409 em versão antiga; nenhum envio externo |
POST /documents |
Multipart file texto simples, authorised=true | 201 document_id canónico; não torna a fonte pesquisável |
POST /sources |
document_id, title, language pt/en, nature, source_url HTTPS, source_owner, evidence_reference, source_date, valid_until, authorised=true | Fonte pendente e fragmentos indexados, ainda inelegíveis |
POST /sources/{uuid}/review |
status: approved/revoked; expected_status | Confirmação por outra pessoa para aprovar; conflito se estado mudou |
POST /controls/{capability} |
suspended boolean | Suspensão imediata no armazenamento partilhado; fora do limite de consultas, mantendo autorização/CSRF |
Capacidades: assistant, search, recommend, classify, quality, sla, summary. Finalidades: investment_information para pesquisa/recomendação/excertos; interest_triage para triagem; data_quality e execution_monitoring para monitores.
Limite das consultas e alterações comuns: 20 pedidos/minuto por identidade de throttling Laravel. Erros: 401/redirect para sessão ausente conforme Accept; 403 autorização, 404 desactivação/ID inválido, 409 conflito, 422 validação/consentimento/fonte, 429 limite, 503 suspensão. Sem streaming, tools de modelos, chamadas directas do React a inferência ou contrato externo de sincronização.
Resultados de pesquisa são limitados a cinco fragmentos; pré-visualização a três; oportunidades a dez; monitores têm limites explícitos por regra. Listagens administrativas mostram até 50 fontes, 100 documentos e 20 execuções; paginação completa fica pendente. A interface identifica que resultados não são exaustivos.