Ajuda / API e programadores

API REST

Autenticação, permissões, limites, erros e os endpoints da API v1 (OpenAPI 3.1).

Autenticação

Crie uma chave em API e chaves, com apenas as permissões de que precisa. A chave (ak_…) é mostrada uma vez; guardamos apenas o seu hash. Envie-a no cabeçalho Authorization:

bash

curl https://www.zurianlab.com/api/v1/me \
  -H "Authorization: Bearer ak_..."

A especificação completa está em https://www.zurianlab.com/api/v1/openapi.json — pode dá-la a um assistente de IA (Claude, ChatGPT) junto com a chave para ele criar apps e cursos por si.

Permissões

Permissão	Permite
`apps:read`	Ler apps, produtos, aulas e membros
`apps:write`	Criar e editar apps (incl. design e definições)
`products:write`	Criar e editar produtos, módulos e aulas
`members:write`	Adicionar membros e dar/retirar acessos
`notifications:write`	Enviar notificações push
`ai:use`	Gerar cursos com a IA da organização

Endpoints principais

Método e caminho	Descrição
`GET /me`	Organização e permissões da chave
`GET /apps` · `POST /apps`	Listar e criar apps
`GET /apps/{id}` · `PATCH /apps/{id}`	Ler e editar uma app (marca, idioma, estado)
`POST /apps/{id}/products`	Criar um produto com módulos e aulas
`PATCH /products/{id}`	Editar; publicar notifica os alunos
`POST /products/{id}/lessons`	Acrescentar aulas
`POST /apps/{id}/members`	Adicionar aluno e dar acesso
`POST /apps/{id}/members/revoke`	Retirar acesso
`POST /apps/{id}/notifications`	Enviar notificação push
`POST /apps/{id}/generate`	Gerar um curso com a IA

Exemplo: dar acesso a um aluno

bash

curl -X POST https://www.zurianlab.com/api/v1/apps/APP_ID/members \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"ana@exemplo.pt","name":"Ana","product_ids":["PRODUCT_ID"]}'

Limites e erros

Até 300 pedidos por minuto por chave. Os erros devolvem JSON { "error": { "code", "message" } }:

Estado	Código	Quando
400	`invalid_json`	O corpo não é JSON válido
401	`unauthorized`	Chave em falta, inválida ou revogada
403	`forbidden` / `suspended`	Falta permissão, ou organização suspensa
402	`plan_limit`	O plano não permite (por exemplo, número de apps)
404	`not_found`	Recurso inexistente ou de outra organização
422	`invalid_request`	Validação falhou; `issues` indica os campos
429	`rate_limited`	Limite de pedidos excedido

Segurança

Nunca use a chave no navegador ou numa app pública. Revogue-a imediatamente se suspeitar de fuga; a coluna "último uso" ajuda a detetar chaves esquecidas.

SeguinteWebhooks de saída