Medway Panorama — API (1.0.0)

Download OpenAPI specification:

API para integração com o Medway Panorama.

Autenticação

API Token (X-API-Token: <key>) — obrigatório em todos os endpoints. O token é gerado pelo Gestor no frontend.

Permissões

Endpoint	Requisito
`GET /institutions/`	Token válido (qualquer usuário)
`GET /data/`	Token válido (qualquer usuário)
`GET /summary/{uid}/results/`	Token válido + role Gestor + `?institution=<uid>`
`GET /student-summary/`	Token válido (qualquer usuário)
`GET /student-summary/{uid}/results/`	Token válido + role Gestor + `?institution=<uid>`

Fluxo típico

Descubra suas instituições em GET /api/v1/reports/api/institutions/.
Liste as consultas disponíveis em GET /api/v1/reports/api/data/ ou GET /api/v1/reports/api/student-summary/.
Consulte os resultados em GET /api/v1/reports/api/summary/{uid}/results/?institution=<uid>.

Institutions

Instituições acessíveis pelo token

Listar instituições

Retorna as instituições das quais o dono do token é membro ativo. Cada instituição inclui suas turmas (studentgroups), que podem ser usadas como filtro nos endpoints de resultados.

Authorizations:

APITokenAuth

Responses

Response samples

200
401

Content type

application/json

[{"uid": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
"name": "Faculdade Exemplo",
"display_name": "FEx",
"studentgroups": [{"uid": "c3d4e5f6-a1b2-7890-abcd-ef1234567890",
"name": "Turma A",
"display_name": "Turma A - 2026"
}
]
}
]

Report Queries

Consultas de relatório disponíveis

Listar consultas de relatório

Retorna todas as consultas de relatório ativas. Use o uid retornado para buscar resultados em /summary/{uid}/results/.

Authorizations:

APITokenAuth

Responses

Response samples

200
401

Content type

application/json

[{"uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Taxa de Aprovação"
}
]

Resultados de uma consulta de relatório

Retorna os resultados de uma consulta para a instituição informada.

Comportamento por cenário:

Sem ?student_group (padrão): retorna o resultado mais recente de cada turma ativa da instituição. Um item por turma.
Com ?student_group=<uid>: retorna o resultado mais recente para aquela turma específica. Array com um item ou [] se não houver resultado.
Com ?period_days=<n>: filtra os resultados pelo período (em dias). Pode ser combinado com ?student_group.

Atenção: este endpoint exige role Gestor e que o token pertença a um usuário membro ativo da instituição informada em ?institution.

Authorizations:

APITokenAuth

path Parameters

uid

required

string <uuid>

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

UID da consulta (obtido em GET /data/)

query Parameters

institution required	string <uuid> Example: institution=b1c2d3e4-f5a6-7890-abcd-ef1234567890 UID da instituição (obtido em `GET /institutions/`)
student_group	string <uuid> Example: student_group=c3d4e5f6-a1b2-7890-abcd-ef1234567890 UID da turma. Se informado, retorna o resultado mais recente apenas para essa turma (array com um item ou `[]`). Se omitido, retorna o mais recente por turma para toda a instituição.
period_days	integer Example: period_days=30 Filtra pelo período em dias. Pode ser combinado com `?student_group`.

Responses

Response samples

200
401
403
404

Content type

application/json

Example

Resultado encontrado

[{"uid": "9f8e7d6c-b1a2-4c3d-8e9f-012345678901",
"query_uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"query_name": "Taxa de Aprovação",
"student_group_uid": "c3d4e5f6-a1b2-7890-abcd-ef1234567890",
"student_group_name": "Turma A",
"rows": [{"indicador": "Aprovação",
"valor": 87.5
}
],
"period_days": 30
}
]

Student Queries

Consultas de alunos disponíveis

Listar consultas de alunos

Retorna todas as consultas de alunos ativas. Use o uid retornado para buscar resultados em /student-summary/{uid}/results/.

Authorizations:

APITokenAuth

Responses

Response samples

200
401

Content type

application/json

[{"uid": "x1y2z3w4-e5f6-7890-abcd-ef1234567890",
"name": "Desempenho por Aluno"
}
]

Resultados de uma consulta de alunos

Retorna os resultados de uma consulta de alunos para a instituição informada.

Comportamento por cenário:

Sem ?student_group (padrão): retorna o resultado mais recente de cada turma ativa da instituição. Um item por turma.
Com ?student_group=<uid>: retorna o resultado mais recente para aquela turma específica. Array com um item ou [] se não houver resultado.
Com ?period_days=<n>: filtra os resultados pelo período (em dias). Pode ser combinado com ?student_group.

Atenção: este endpoint exige role Gestor e que o token pertença a um usuário membro ativo da instituição informada em ?institution.

Authorizations:

APITokenAuth

path Parameters

uid

required

string <uuid>

Example: x1y2z3w4-e5f6-7890-abcd-ef1234567890

UID da consulta (obtido em GET /student-summary/)

query Parameters

institution required	string <uuid> Example: institution=b1c2d3e4-f5a6-7890-abcd-ef1234567890 UID da instituição (obtido em `GET /institutions/`)
student_group	string <uuid> Example: student_group=c3d4e5f6-a1b2-7890-abcd-ef1234567890 UID da turma. Se informado, retorna o resultado mais recente apenas para essa turma (array com um item ou `[]`). Se omitido, retorna o mais recente por turma para toda a instituição.
period_days	integer Example: period_days=30 Filtra pelo período em dias. Pode ser combinado com `?student_group`.

Responses

Response samples

200
401
403
404

Content type

application/json

Example

Resultado encontrado

[{"uid": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
"query_uid": "x1y2z3w4-e5f6-7890-abcd-ef1234567890",
"query_name": "Desempenho por Aluno",
"student_group_uid": "c3d4e5f6-a1b2-7890-abcd-ef1234567890",
"student_group_name": "Turma A",
"rows": [{"aluno": "João Silva",
"acertos": 72
}
],
"period_days": 30,
"executed_at": "2026-04-15T07:30:00Z"
}
]