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:
- your API key;
- your court keys: identifiers you choose for your courts, agreed with us during onboarding;
- order ids returned by the API (and optionally your own order ids).
Typical flow:
- A session ends on a court.
- You call
POST /orderswith the court key and the session's start and end time. - You poll
GET /orders/{order_id}(or receive a webhook) until the status isready. - You show the
share_page_urlto 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>
- The key is a long-lived API key, not a session token. There is no refresh flow; you replace it only when rotating it or if it leaks.
- We issue your first key during onboarding. Store it on your server only; never put it in a browser or mobile app.
- A key gives access only to the courts assigned to your account.
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
- All timestamps are RFC 3339 with an explicit offset:
2026-11-03T18:00:00+01:00or2026-11-03T17:00:00Z. Timestamps without an offset are rejected. - Responses always use UTC (
Z). - Precision is seconds; fractions are ignored.
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:
- The API returns the session page only, not direct links to video files. The full video and highlights are on that page.
share_page_urlis a public, unguessable link. Anyone who has it can watch the session, so share it only with the players of that session.- The page may keep improving after
ready(for example, extra highlights or analysis are added). The URL does not change. - Typical time from order to
ready: TBD (expect minutes to tens of minutes, depending on session length and load). - Link lifetime: TBD.
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}" }
}
- Event types:
order.ready,order.failed. - Signature:
v1is the hex HMAC-SHA256 of"{t}.{raw request body}"using your webhook secret (issued separately from the API key). Verify it with a constant-time comparison and reject requests wheretis more than 5 minutes old. - The header can contain more than one
v1value (t=...,v1=...,v1=...) while the webhook secret is being rotated. Accept the request if anyv1matches. See Webhook secret rotation. - Respond with any
2xxwithin 10 seconds. Otherwise we retry with backoff for up to 24 hours. - Deliveries can repeat or arrive out of order. Deduplicate by
event_idand treat the order object as the current state.
Idempotency
Send a client_order_id with every order. Then:
- Repeating
POST /orderswith the sameclient_order_idand the samecourt_key,startandendreturns the existing order with200 OK. No second recording is made, so network retries are safe. - Reusing a
client_order_idwith different parameters returns409 idempotency_conflict.
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)
- Ask us for a new key.
- We issue a second key. Both keys work during an overlap window of 14 days.
- Deploy the new key everywhere you use the API.
- 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
/keysendpoints are planned and may not be available at launch.
- Call
POST /keyswith your current key. The response contains the new key's secret, shown once. - Deploy the new key.
- Check
GET /keys: when the old key'slast_used_atstops moving, callDELETE /keys/{key_id}for it.
Rules:
POST /keysreturns409 key_limit_reachedif two keys are already active. Revoke one first.DELETE /keys/{key_id}cannot revoke the key making the request if it is your only active key (409 last_active_key).- Every key creation and revocation is emailed to your technical contact. If you didn't make the change, contact us immediately.
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
- The version is in the path (
/api/v1). Within v1 we only make additive changes: new endpoints, new optional request fields, new response fields, new error codes, new webhook event types. Ignore fields you don't recognise. - Breaking changes go into a new version, with advance notice.
Changelog
- Draft v0 (2026-10-20): first draft for partner review. Includes key management: up to two active keys, rotation with a 14-day overlap, planned self-service
/keysendpoints, webhook secret rotation with dual signatures.