GET /api/recognitions

Retorna reconhecimentos do usuário autenticado, ordenados por data (mais recentes primeiro). Suporta filtros por placa, câmera e intervalo de datas.

Autenticação

Scope necessário: recognitions:read

Inclua o header Authorization: Bearer <api-key> ou use cookie de sessão.

Requisição

GET /api/recognitions

Headers

Header	Obrigatório	Descrição
`Authorization`	sim	`Bearer pk_...` (API key) ou cookie de sessão

Parâmetros de query

Parâmetro	Tipo	Obrigatório	Descrição
`plate`	string	não	Filtro por texto contido na placa (case-insensitive)
`cameraId`	string	não	Filtro por UUID da câmera
`from`	ISO 8601	não	Data/hora inicial (ex: `2026-03-01T00:00:00Z`)
`to`	ISO 8601	não	Data/hora final (ex: `2026-03-22T23:59:59Z`)
`limit`	number	não	Resultados por página (1-200, padrão 50)
`lastKey`	string	não	Cursor de paginação retornado na resposta anterior

Exemplo

curl -X GET "https://api.placaflow.com.br/api/recognitions?plate=ABC&from=2026-03-01T00:00:00Z&limit=10" \
  -H "Authorization: Bearer pk_a1b2c3d4e5f6g7h8i9j0..."

Resposta 200

{
  "recognitions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "userId": "c3a1e902-4f5b-4b8a-9c6d-1a2b3c4d5e6f",
      "cameraId": "7012e192-5005-43b6-978c-7e304b3676a6",
      "cameraName": "Entrada principal",
      "plate": "ABC1D23",
      "confidence": 0.96,
      "timestamp": "2026-03-22T14:30:00.000Z",
      "photoUrl": "frames/7012e192/1711115400000-photo.jpg",
      "cropUrl": "frames/7012e192/1711115400000-crop.jpg",
      "plateCoordinates": {
        "x": 622,
        "y": 301,
        "width": 429,
        "height": 80
      }
    },
    {
      "id": "661f9511-f30c-52e5-b827-557766551111",
      "userId": "c3a1e902-4f5b-4b8a-9c6d-1a2b3c4d5e6f",
      "cameraId": "7012e192-5005-43b6-978c-7e304b3676a6",
      "cameraName": "Entrada principal",
      "plate": "ABC4F56",
      "confidence": 0.89,
      "timestamp": "2026-03-22T13:15:00.000Z",
      "photoUrl": "frames/7012e192/1711110900000-photo.jpg",
      "cropUrl": "frames/7012e192/1711110900000-crop.jpg",
      "plateCoordinates": {
        "x": 410,
        "y": 280,
        "width": 395,
        "height": 75
      }
    }
  ],
  "nextKey": "eyJpZCI6IjY2MWY5NTExLWYzMGMtNTJlNS1iODI3LTU1Nzc2NjU1MTExMSJ9"
}

Atenção

Os campos photoUrl e cropUrl na listagem são chaves S3 internas (não URLs acessíveis diretamente). Use o endpoint GET /api/recognitions/:id para obter URLs presignadas válidas por 1 hora.

Campos da resposta

Campo	Tipo	Descrição
`recognitions`	array	Lista de objetos de reconhecimento
`nextKey`	string \| null	Cursor para a próxima página. `null` se não houver mais resultados

Campos de cada reconhecimento

Campo	Tipo	Descrição
`id`	string	UUID único do reconhecimento
`userId`	string	UUID do proprietário
`cameraId`	string	UUID da câmera de origem
`cameraName`	string	Nome da câmera
`plate`	string	Texto da placa (uppercase)
`confidence`	number	Confiança do reconhecimento (0-1)
`timestamp`	string	Data/hora ISO 8601
`photoUrl`	string?	Chave S3 do frame completo (use GET por ID para URL presignada)
`cropUrl`	string?	Chave S3 do recorte da placa (use GET por ID para URL presignada)
`plateCoordinates`	object?	Bounding box: `{x, y, width, height}` em pixels

Paginação

Se nextKey não for null, existem mais resultados. Passe o valor como lastKey na próxima requisição:

curl "https://api.placaflow.com.br/api/recognitions?lastKey=eyJpZCI6IjY2MWY5NTExLWYzMGMtNTJlNS1iODI3LTU1Nzc2NjU1MTExMSJ9" \
  -H "Authorization: Bearer pk_a1b2c3d4e5f6g7h8i9j0..."

Erros

Código	Descrição
400	Parâmetro inválido (ex: limit fora do intervalo 1-200)
401	Não autenticado ou API key inválida
403	API key não possui scope `recognitions:read`