Recording API SANDBOX OverviewGuideAPI referencePortal

Sandbox base URL: https://apibox.pdleye.com/api/v1. See the overview for test courts.

Recording API v1 (draft)

Status: Draft v0. Subject to change. This document describes the planned partner API so that integrations can be prepared in advance. The endpoints are not live yet. Field names, error codes and status values are intended to be stable; items marked TBD will be fixed before launch. Breaking changes before launch will be announced to partners who received this draft.

This guide comes with a machine-readable OpenAPI 3.1 spec, api-v1.openapi.yaml, provided as a separate file alongside it. You can use it to generate a client.

Overview

The API lets your system order a video recording of a session on a court, for a given time range, and get back a link to the session page (full video and highlights) when it is ready.

You only work with:

Typical flow:

  1. A session ends on a court.
  2. You call POST /orders with the court key and the session's start and end time.
  3. You poll GET /orders/{order_id} (or receive a webhook) until the status is ready.
  4. You show the share_page_url to your user.

Base URL

https://api.pdleye.com/api/v1

The API is not live yet; this URL starts working at launch. TBD: a sandbox URL for testing.

All requests and responses use JSON (Content-Type: application/json) over HTTPS.

Authentication

Every request must include your API key:

Authorization: Bearer <key_id>.<secret>

Issuing, rotating and revoking keys is described in Key management.

A missing, invalid, revoked or expired key returns 401 unauthorized.

Courts

During onboarding we agree on a court key for each of your courts, for example riverside-court-3. Court keys are strings up to 64 characters (A-Z a-z 0-9 . _ -), unique within your account. You can list them with GET /courts.

A court key that is unknown or not assigned to your account returns 404 court_not_found.

Time format

Interval rules

Rule Value
start must be before end —
Minimum length 15 minutes (TBD)
Maximum length 180 minutes (TBD)
end must be in the past Recordings are made from the court's archive after the session ends.
How far back you can order TBD (limited by on-site archive retention, expect a few days)

Ordering a session that is still in progress, or a future one, returns 422 interval_in_future. Support for booking future sessions may be added later.

Endpoints

GET /courts

Lists the court keys available to your account.

GET /api/v1/courts
Authorization: Bearer key_abc123.s3cr3t
{
  "courts": [
    { "court_key": "riverside-court-3", "name": "Court 3" },
    { "court_key": "riverside-court-4", "name": "Court 4" }
  ]
}

POST /orders

Orders a recording for a court and time range.

Field Type Required Description
court_key string yes Your court key.
start string (RFC 3339) yes Session start.
end string (RFC 3339) yes Session end.
client_order_id string, ≤ 64 chars no, recommended Your own id for this order. Makes the request safe to retry (see Idempotency).
POST /api/v1/orders
Authorization: Bearer key_abc123.s3cr3t
Content-Type: application/json

{
  "court_key": "riverside-court-3",
  "start": "2026-11-03T18:00:00+01:00",
  "end": "2026-11-03T19:30:00+01:00",
  "client_order_id": "booking-88213"
}

Response 202 Accepted (new order) or 200 OK (same order returned again, see Idempotency):

{
  "order_id": "ord_5f0c2a9e7d8b4c1aa3e4b6d2f9a01c37",
  "client_order_id": "booking-88213",
  "court_key": "riverside-court-3",
  "start": "2026-11-03T17:00:00Z",
  "end": "2026-11-03T18:30:00Z",
  "status": "queued",
  "share_page_url": null,
  "error": null,
  "created_at": "2026-11-03T18:31:05Z",
  "updated_at": "2026-11-03T18:31:05Z"
}

GET /orders/{order_id}

Returns the current state of an order. Only orders created with your account are visible; any other id returns 404 order_not_found.

GET /api/v1/orders/ord_5f0c2a9e7d8b4c1aa3e4b6d2f9a01c37
Authorization: Bearer key_abc123.s3cr3t
{
  "order_id": "ord_5f0c2a9e7d8b4c1aa3e4b6d2f9a01c37",
  "client_order_id": "booking-88213",
  "court_key": "riverside-court-3",
  "start": "2026-11-03T17:00:00Z",
  "end": "2026-11-03T18:30:00Z",
  "status": "ready",
  "share_page_url": "https://session.pdleye.com/Xk3v9QmZ1pTq7wLr.html",
  "error": null,
  "created_at": "2026-11-03T18:31:05Z",
  "updated_at": "2026-11-03T18:52:40Z"
}

Order status

Status Meaning
queued Accepted, waiting for processing.
processing Video is being retrieved and processed.
ready Done. share_page_url is set.
failed Could not be produced. error explains why. Final.

Statuses only move forward: queued → processing → ready or failed.

Notes on ready:

Failure codes in error.code for failed orders:

Code Meaning
no_footage No video exists for this court and time range.
court_unavailable The court's camera could not be reached long enough to retrieve the video.
processing_failed Internal processing error. You may create a new order with a new client_order_id.

court_unavailable appears in two places with related meanings. As a 503 response to POST /orders, it means the order was not created and you can retry the request later. As error.code on a failed order, it means the order was accepted but the video could not be retrieved; that order is final.

Polling

Poll GET /orders/{order_id} no more often than every 30 seconds per order. Stop polling when the status is ready or failed. If you use webhooks, polling is only needed as a fallback.

Webhooks (planned)

Webhooks are planned and may not be available at launch. The format below is fixed so you can implement it now.

If you give us a webhook URL during onboarding, we send a POST when an order reaches ready or failed:

POST https://partner.example.com/hooks/recordings
Content-Type: application/json
X-Signature: t=1762194760,v1=5d41402abc4b2a76b9719d911017c592...

{
  "event_id": "evt_9b1d3c7a2e4f4a5b8c6d0e1f2a3b4c5d",
  "type": "order.ready",
  "created_at": "2026-11-03T18:52:40Z",
  "order": { "...": "same object as GET /orders/{order_id}" }
}

Idempotency

Send a client_order_id with every order. Then:

Without client_order_id, every request creates a new order.

Errors

All errors use one format:

{
  "error": {
    "code": "invalid_interval",
    "message": "start must be before end"
  }
}

Use code in your logic. message is for humans and may change.

HTTP code When
400 invalid_request Malformed JSON or missing or invalid field.
401 unauthorized Missing, invalid, revoked or expired API key.
404 court_not_found Unknown court key, or court not assigned to you.
404 order_not_found Unknown order id, or order belongs to another account.
404 key_not_found Unknown key id, or key belongs to another account (planned /keys).
409 idempotency_conflict client_order_id reused with different parameters.
409 key_limit_reached Two keys are already active (planned /keys).
409 last_active_key Cannot revoke your only active key with itself (planned /keys).
422 invalid_interval start is not before end, or a timestamp has no offset.
422 interval_too_short Shorter than the minimum length.
422 interval_too_long Longer than the maximum length.
422 interval_in_future end is in the future.
422 interval_too_old Older than the archive retention.
429 rate_limited Too many requests. See Retry-After.
503 court_unavailable The court cannot take orders right now; the order was not created. Retry later.
500 internal_error Unexpected error. Safe to retry with the same client_order_id.

Key management

Getting your first key

We create your first key during onboarding and send it through a one-time secret link or a shared password-manager entry, never by plain email. We store only a hash of the secret, so we cannot show it again; a lost secret means issuing a new key.

Active keys

Your account can have at most two active keys at a time. Two keys exist so you can rotate without downtime: both work while you switch over.

Keys do not expire by default. We recommend rotating at least once a year. If a key does have an expiry date (for example, an old key during rotation), we email your technical contact 7 days before it expires.

Rotation (at launch: through support)

  1. Ask us for a new key.
  2. We issue a second key. Both keys work during an overlap window of 14 days.
  3. Deploy the new key everywhere you use the API.
  4. Tell us when you're done. We check that the old key is no longer used and revoke it. If the window ends first, the old key expires on its own.

Rotation (planned: self-service)

The /keys endpoints are planned and may not be available at launch.

  1. Call POST /keys with your current key. The response contains the new key's secret, shown once.
  2. Deploy the new key.
  3. Check GET /keys: when the old key's last_used_at stops moving, call DELETE /keys/{key_id} for it.

Rules:

GET /keys

{
  "keys": [
    {
      "key_id": "key_abc123",
      "label": "production 2026",
      "created_at": "2026-11-01T09:00:00Z",
      "expires_at": null,
      "last_used_at": "2026-11-20T14:02:11Z",
      "is_current": false
    },
    {
      "key_id": "key_def456",
      "label": "production 2027",
      "created_at": "2026-11-20T13:55:00Z",
      "expires_at": null,
      "last_used_at": "2026-11-20T14:05:40Z",
      "is_current": true
    }
  ]
}

is_current marks the key used for this request. Secrets are never returned.

POST /keys

POST /api/v1/keys
Authorization: Bearer key_abc123.s3cr3t
Content-Type: application/json

{ "label": "production 2027" }

Response 201 Created:

{
  "key_id": "key_def456",
  "label": "production 2027",
  "created_at": "2026-11-20T13:55:00Z",
  "expires_at": null,
  "last_used_at": null,
  "is_current": false,
  "token": "key_def456.Zr8pQ2vX9mT4kL7nB1cW6yH3"
}

token is the full value for the Authorization: Bearer header. It is returned only here.

DELETE /keys/{key_id}

Revokes the key immediately. Returns 204 No Content. Requests with a revoked key get 401 unauthorized.

Leaked key

If a key may have leaked, contact us right away (or, once available, revoke it with DELETE /keys/{key_id} using your other key). A leaked key is revoked immediately, with no overlap window, and a new one is issued. We may also revoke a key ourselves if we detect misuse, and will contact you when we do.

Webhook secret rotation

The webhook secret is rotated through support in the same way, with a 14-day overlap. During the overlap we sign each webhook with both secrets, so X-Signature contains two v1 values. Accept the request if any of them matches one of your secrets. After the overlap only the new secret is used.

Rate limits

TBD before launch. Expect a per-key request limit and a limit on orders being processed at the same time. When a limit is hit, the API returns 429 with a Retry-After header in seconds.

Versioning

Changelog