API Reference

The /plate-reads endpoint is used to ingest ALPR data and is the primary public endpoint used to interact with external systems. This document outlines the expected request format and available fields.

Authentication

All requests require an API key sent in the header.

X-API-Key: your_api_key_here

Request Format

The API accepts JSON payloads with the following fields:

Field	Type	Required	Description
`ai_dump`	Object	No*	Object containing AI model predictions from CPAI *(preferred method).*
`memo`	String	No*	Comma-separated list of detections with confidence (DEPRECATED).
`plate_number`	String	No*	Direct plate number input (DEPRECATED).
`timestamp`	String	No	ISO 8601 timestamp of when the plate was detected. Defaults to current time if not provided.
`camera`	String	No	Name or identifier of the camera that captured the plate.
`Image`	String	No	Base64 encoded JPEG of the plate detection.
`ALERT_CLIP`	String	No	Blue Iris alert clip identifier.
`ALERT_PATH`	String	No	Blue Iris alert path.

*At least one of ai_dump, memo, or plate_number is required. memo is entirely deprecated. plate_number should only be used be non natively-supported AI systems.

Plate Information Methods

The API supports three different methods for providing plate information:

1. AI Dump Format

{
  "ai_dump": {
    "found": {
      "predictions": [
        {
          "plate": "ABC123",
          "confidence": 0.95,
          "x_min": 100,
          "y_min": 200,
          "x_max": 300,
          "y_max": 400,
          "valid_ocr_annotation": true,
          "ocr_annotation": "annotation_data",
          "plate_annotation": "plate_annotation_data"
        }
      ]
    }
  }
}

2. Memo Format

{
  "memo": "ABC123:0.95, person:0.87, car:0.99"
}

The system will extract license plates from the memo, filtering out non-plate objects.

3. Direct Plate Number

{
  "plate_number": "ABC123"
}

Response Format

Success Response (201 Created)

{
  "processed": [
    {
      "plate": "ABC123",
      "id": 42
    }
  ],
  "duplicates": [],
  "ignored": [],
  "message": "Processed 1 plates, 0 duplicates, 0 ignored"
}

Duplicate Response (409 Conflict)

{
  "processed": [],
  "duplicates": ["ABC123"],
  "ignored": [],
  "message": "Processed 0 plates, 1 duplicates, 0 ignored"
}

Error Response (400/401/500)

{
  "error": "Error message",
  "details": "Optional error details"
}

Notes

Plate numbers are automatically converted to uppercase
Duplicate detections (same plate at same timestamp) are automatically filtered
The system supports ignoring specific plates based on your configuration
Images are saved to disk if provided, with both full-size and thumbnail versions

API Reference

On this page