# 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.