API pública

Endpoints do site institucional que não exigem autenticação.

GET /api/health

Estado do site. Verifica que o PHP executa e que a configuração da aplicação, que fica fora do docroot, é alcançável. Não consulta banco de dados e não revela informação de infraestrutura.

$ curl https://saitro.com/api/health

{"status":"ok","service":"saitro-website","time":"2026-08-03T21:30:00Z"}

Devolve 503 com "status":"error" quando a configuração está inalcançável. É mais útil que um arquivo estático de monitoração: pega falhas de permissão que deixariam o site de pé e a aplicação quebrada.

POST /api/a2a

Endpoint A2A (Agent2Agent), JSON-RPC 2.0 sobre HTTPS. Diferente dos demais: os outros entregam dados para serem lidos, este executa uma tarefa delegada por outro agente e devolve o resultado como artefato.

Descrito pelo Agent Card. Hoje expõe uma skill só, website-health. Público e sem autenticação, porque não toca em dado de cliente.

$ curl -X POST https://saitro.com/api/a2a \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":"1","method":"message/send",
         "params":{"message":{"role":"user","messageId":"m1",
                   "parts":[{"kind":"text","text":"is the website up?"}]}}}'

{"jsonrpc":"2.0","id":"1","result":{
  "id":"task-...","status":{"state":"completed",...},
  "artifacts":[{"name":"health","parts":[{"kind":"text","text":"{...}"}]}],
  "kind":"task"}}

A tarefa termina dentro da própria requisição, então o resultado já vem na resposta e não há o que consultar depois. Por isso tasks/get devolve -32001: é a verdade, não um stub fingindo estado. Sem streaming e sem push notifications.

O binding JSON-RPC mudou de estilo entre as versões da especificação. O Agent Card declara 0.3.0, que é o que os clientes implementam hoje, e os nomes da 1.0 (SendMessage, GetTask) são aceitos como alias.

Especificação

openapi.json — OpenAPI 3.1, cobrindo o health check. O A2A é JSON-RPC e se descreve pelo Agent Card, não por OpenAPI. O catálogo em /.well-known/api-catalog segue a RFC 9727 e lista os dois.

API da plataforma GSIM

Os demais endpoints sob /api/

Existem para uso do próprio site: formulário de contato, token CSRF, desafio ALTCHA e autenticação do portal. Dependem de sessão emitida pelas páginas e não são interface pública, portanto não estão documentados aqui nem na especificação.