Illustrative client reference — authentication pending confirmation. Irfan Pasha has not yet confirmed the authentication scheme. The URLs, OAuth 2.0/OIDC design, scope names, token lifetime, payloads, and monitoring settings are proposed documentation details rather than a verified production contract. Reserved
.exampleaddresses are placeholders, and every token and clip record below is invented. Confirm the production base URL and authentication before integrating.
Document control
| Item | Value |
|---|---|
| Archive | Kadamba Footage Archive, Mysuru |
| Owner | Vasanthi Iyer |
| Intended readers | Nine cataloguing and rights staff; approved outside clients |
| Authentication reviewer | Irfan Pasha — confirmation pending |
| API version | Proposed v1
|
| Status | Published illustrative reference; not yet a production contract |
| Short overview | Catalogue API and Health Checks |
Kadamba reports 48,000 clips and 1,120 hours of digitised footage. These are collection totals, not export quotas or a promise that every item can be licensed.
1. Addresses and conventions
Proposed addresses:
- API:
https://api.kadamba-footage-archive.example - Token service:
https://auth.kadamba-footage-archive.example - Catalogue resources:
/v1
Conventions:
- Bodies are JSON unless stated otherwise.
-
clip_idis a stable archive identifier, such asKFA-000138. - Dates use
YYYY-MM-DD; timestamps use ISO 8601 in UTC. - Durations are whole seconds.
- A record version helps prevent two people from silently overwriting each other's changes.
- An empty rights array means nothing has been approved in that category, not "everything".
- A
nullrights date means not recorded or not decided, not perpetual permission.
2. Authentication and access — pending Irfan's confirmation
2.1 Roles and scopes
A scope is a permission attached to a token. It separates reading from changing records.
| Scope | What it permits | Proposed holder |
|---|---|---|
catalogue.read |
Search and read clip metadata | Staff and approved clients |
catalogue.write |
Change cataloguing metadata | Cataloguing staff |
rights.read |
Read rights information | Rights staff; clients only for approved public fields |
rights.write |
Replace rights information | Rights staff |
health.read |
Read detailed readiness information | Operations and monitoring identity |
Proposed role bundles:
-
Cataloguing staff:
catalogue.read catalogue.write rights.read -
Rights staff:
catalogue.read rights.read rights.write -
Outside client:
catalogue.read; optional, filteredrights.read -
Monitor:
health.readonly
2.2 Proposed client flow: OAuth 2.0 Client Credentials
This is a server-to-server flow, not a person typing a password into a browser.
- Each client receives a unique
client_idandclient_secret. - The client's backend exchanges them for a short-lived access token.
- The backend sends that token with API requests.
- When the token expires, the backend requests a new one; this flow does not need a refresh token.
Illustrative token request:
POST /oauth/token
Host: auth.kadamba-footage-archive.example
Authorization: Basic BASE64_OF_CLIENT_ID_AND_CLIENT_SECRET
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&scope=catalogue.read
Illustrative response:
{
"access_token": "EXAMPLE_ONLY_NOT_A_REAL_TOKEN",
"token_type": "Bearer",
"expires_in": 900,
"scope": "catalogue.read"
}
expires_in: 900 means 15 minutes and is proposed, not confirmed. Bearer means the API expects the token in an authorization header. A real bearer token must be protected like a password.
2.3 Proposed staff flow: OpenID Connect with PKCE
- A staff member starts sign-in through the archive application.
- The application sends them to the identity provider.
- After sign-in, the application receives a one-time authorization code.
- It exchanges that code and a PKCE verifier for tokens. PKCE protects the exchange.
- The application uses the access token for the staff member's permitted API calls.
Passwords and client secrets must never appear in catalogue requests, browser code, support tickets, screenshots, or bookmarks.
2.4 Calling a protected endpoint
GET /v1/clips/KFA-000138
Host: api.kadamba-footage-archive.example
Authorization: Bearer EXAMPLE_ACCESS_TOKEN
Accept: application/json
- 401 Unauthorized: the token is missing, malformed, expired, or invalid. Authenticate again once; do not loop retries.
- 403 Forbidden: authentication worked, but the token lacks the required scope. Request access instead of retrying repeatedly.
-
429 Too Many Requests: the caller exceeded an agreed limit. Respect
Retry-Afterif supplied.
Token storage, rotation, revocation, expiry, rate limits, and the exact credential transport remain pending confirmation.
3. Common errors
Successful reads and the illustrated updates return 200 OK. Proposed error envelope:
{
"error": {
"code": "validation_failed",
"message": "One or more fields need attention.",
"fields": {
"duration_seconds": "Must be a positive integer."
}
},
"request_id": "req_example_01"
}
request_id is a support reference, not a credential.
| HTTP status | Proposed meaning | Caller action |
|---|---|---|
400 |
Request could not be parsed | Fix JSON, parameters, or date formats |
401 |
Authentication missing or invalid | Authenticate again once |
403 |
Caller lacks permission | Check scopes or access approval |
404 |
No visible clip matches the ID | Check the ID; do not assume deletion |
409 |
Record changed since it was read | Re-read, compare, and retry deliberately |
422 |
Readable fields fail validation | Correct the named fields |
429 |
Request budget exhausted | Back off and respect Retry-After
|
503 |
Service or dependency unavailable | Retry later with bounded backoff |
4. Endpoint reference
4.1 Search clips
GET /v1/clips
Scope: catalogue.read
Purpose: Find clips and page through summary records. Search results are discovery aids, not permission to use footage.
| Parameter | Required | Meaning |
|---|---|---|
q |
No | Words matched against title, subjects, and description |
page |
No | One-based result page; proposed default 1
|
per_page |
No | Results per page; proposed default 25, maximum 100
|
subject |
No | Exact subject filter, repeatable |
rights_status |
No | Workflow filter; it does not grant a licence |
digitised |
No |
true or false; digital availability does not imply clearance |
from_date, to_date
|
No | Inclusive recording-date bounds |
sort |
No | Proposed: relevance, date_asc, date_desc, title_asc
|
Example:
GET /v1/clips?q=monsoon&subject=Mysuru&page=1&per_page=2
Authorization: Bearer EXAMPLE_ACCESS_TOKEN
Illustrative response:
{
"data": [
{
"clip_id": "KFA-000138",
"title": "Mysuru market after monsoon rain",
"date": "1987-06-14",
"duration_seconds": 92,
"source_format": "16mm film",
"digitised": true,
"subjects": ["Mysuru", "markets", "monsoon"],
"rights_status": "review_required"
}
],
"page": 1,
"per_page": 2,
"total": 1
}
total counts records matching the filter, not total archive holdings. No matches returns 200, data: [], and total: 0.
4.2 Read one clip
GET /v1/clips/{clip_id}
Scope: catalogue.read
Purpose: Retrieve the client-visible cataloguing record for one clip. Replace {clip_id} with the actual ID and omit the braces.
{
"clip_id": "KFA-000138",
"title": "Mysuru market after monsoon rain",
"date": "1987-06-14",
"duration_seconds": 92,
"source_format": "16mm film",
"digitised": true,
"preservation_format": "FFV1/MKV",
"access_format": "H.264/MP4",
"subjects": ["Mysuru", "markets", "monsoon"],
"rights_status": "review_required",
"catalogue_record_version": 17,
"updated_at": "2026-11-18T20:38:44Z"
}
-
source_formatdescribes the original carrier. -
preservation_formatdescribes the preservation file, not necessarily a client download. -
access_formatdescribes a viewing proxy, not redistribution permission. - Retain
catalogue_record_versionbefore making an update. - The rights endpoint is the proposed source of truth if this summary's
rights_statusis stale.
4.3 Update cataloguing metadata
PATCH /v1/clips/{clip_id}
Scope: catalogue.write
Purpose: Change only supplied cataloguing fields. Omitted fields stay unchanged.
Staff rules:
- Send the
catalogue_record_versionlast read. - Do not change
rights_statushere; use the rights workflow. - Treat
clip_id, creation history, and system timestamps as read-only. - On
409, re-read and review the other person's changes before retrying.
PATCH /v1/clips/KFA-000138
Authorization: Bearer EXAMPLE_STAFF_TOKEN
Content-Type: application/json
{
"title": "Mysuru market after monsoon rain, 1987",
"subjects": ["Mysuru", "markets", "monsoon", "street trading"],
"catalogue_record_version": 17
}
Illustrative response:
{
"clip_id": "KFA-000138",
"updated": true,
"catalogue_record_version": 18,
"updated_at": "2026-11-19T09:30:00Z"
}
4.4 Read a clip's rights record
GET /v1/clips/{clip_id}/rights
Scope: rights.read
Purpose: Explain what has and has not been reviewed for possible use. This is not a signed licence or legal advice.
Proposed visibility rule: staff may receive operational review fields; outside clients receive only an approved public subset. Client responses must omit private donor details, legal analysis, personal contact data, and internal notes.
Illustrative staff-safe response:
{
"clip_id": "KFA-000138",
"status": "review_required",
"client_licensing": "not_available_until_cleared",
"credit": "Kadamba Footage Archive; donor credit pending",
"territories": [],
"licence_start_on": null,
"licence_end_on": null,
"allowed_media": [],
"allowed_edits": [],
"public_notes": "Not available for client licensing while review is pending.",
"donor_restrictions": "Donor credit wording requires review.",
"third_party_components": ["Background music"],
"consent_status": "not_assessed",
"music_status": "unresolved",
"review_owner": "rights-team",
"last_reviewed_at": null,
"rights_record_version": 9
}
Rights fields in plain terms:
| Field | Meaning | Proposed visibility |
|---|---|---|
status |
Position in the rights review workflow | Staff and clients |
client_licensing |
Whether the archive can currently consider a client licence | Staff and clients |
credit |
Required attribution wording, when applicable; not proof of permission | Staff and clients |
territories |
Places covered; [] means none confirmed |
Staff and clients |
licence_start_on |
First covered date, if decided | Staff and clients |
licence_end_on |
Last covered date; null is not perpetual |
Staff and clients |
allowed_media |
Approved channels; [] means none approved |
Staff and clients |
allowed_edits |
Permitted changes; [] means none approved |
Staff and clients |
public_notes |
Short note approved for client display | Staff and clients |
donor_restrictions |
Conditions from a donation or deposit agreement | Staff only unless cleared |
third_party_components |
Music, stills, performances, or other material needing separate checks | Staff only |
consent_status |
Whether releases or consents have been assessed; not a legal conclusion | Staff only |
music_status |
State of composition, recording, and synchronisation checks | Staff only |
review_owner |
Team responsible for the next review step | Staff only by default |
last_reviewed_at |
When the current state was assessed | Staff and clients if approved |
rights_record_version |
Version used to prevent conflicting rights updates | Staff only |
Proposed statuses:
| Status | Plain-English meaning |
|---|---|
review_required |
Assessment is unfinished; do not offer for licensing |
counsel_review |
A legal or specialist question remains open |
cleared_subset |
Only specifically recorded material, uses, or excerpts are cleared |
cleared |
Review is complete for the stated scope, not an unlimited licence or public-domain claim |
blocked |
Do not offer the clip for the requested use |
Read status together with territories, dates, media, edits, credit, and the final licence. One field never tells the whole story.
4.5 Replace a rights record
PUT /v1/clips/{clip_id}/rights
Scope: rights.write
Purpose: Replace the mutable rights record as a complete unit. Omitted mutable fields may be cleared or defaulted.
Rules for rights staff:
- Send the complete intended record and last-read
rights_record_version. - Confirm every empty array and
null. - Never place confidential legal analysis in
public_notes. - A rights update does not itself issue a client licence.
PUT /v1/clips/KFA-000138/rights
Authorization: Bearer EXAMPLE_RIGHTS_STAFF_TOKEN
Content-Type: application/json
{
"status": "counsel_review",
"client_licensing": "not_available_until_cleared",
"credit": "Kadamba Footage Archive; donor credit pending",
"territories": [],
"licence_start_on": null,
"licence_end_on": null,
"allowed_media": [],
"allowed_edits": [],
"public_notes": "Music and donor-credit wording are under review.",
"donor_restrictions": "Donor credit wording requires review.",
"third_party_components": ["Background music"],
"consent_status": "not_assessed",
"music_status": "counsel_review",
"review_owner": "rights-team",
"last_reviewed_at": "2026-11-19T09:30:00Z",
"rights_record_version": 9
}
Illustrative response:
{
"clip_id": "KFA-000138",
"updated": true,
"status": "counsel_review",
"rights_record_version": 10
}
Whether this should remain full-replacement PUT or become a partial PATCH is still a technical-review question.
4.6 Liveness
GET /health/live
Proposed access: public to the monitoring network or restricted by network policy; confirmation pending
Purpose: Show whether the API process is running, without proving every dependency works.
{"status":"ok"}
A failed process may return 503 or not respond. Responses must not contain stack traces, secrets, internal hostnames, client data, or detailed diagnostics.
4.7 Readiness
GET /health/ready
Proposed scope: health.read, or an equivalent private network rule
Purpose: Show whether the service is ready for catalogue traffic.
Healthy response:
{
"status": "ok",
"checks": {
"catalogue_index": "ok",
"metadata_store": "ok",
"preview_storage": "ok"
}
}
Illustrative 503 response:
{
"status": "not_ready",
"checks": {
"catalogue_index": "ok",
"metadata_store": "ok",
"preview_storage": "unavailable"
}
}
catalogue_index supports search, metadata_store holds records, and preview_storage holds access proxies. These illustrative names must not expose sensitive infrastructure in a public response.
5. Proposed UptimeRobot mapping
Use read-only requests only. Never run PATCH or PUT as an uptime check.
-
Kadamba | Catalogue Search | HTTPS + SSL—/v1/clips?q=monsoon&per_page=1 -
Kadamba | Clip Metadata | HTTPS + SSL—/v1/clips/KFA-000138 -
Kadamba | Rights Lookup | HTTPS + SSL—/v1/clips/KFA-000138/rights -
Kadamba | API Liveness | HTTPS + SSL—/health/live -
Kadamba | API Readiness | HTTPS + SSL—/health/ready
Proposed convention: five-minute interval, 30-second timeout, SSL validation, HTTP 200, and a small response keyword where reliable. If authentication is required, use a dedicated read-only monitoring identity. Store its secret in protected monitoring configuration, never in the URL, monitor name, or this document.
6. Outstanding technical confirmation
Publication of this reference does not mean the following items are approved:
- Irfan's confirmation of the actual authentication scheme and client onboarding.
- Production API and token-service hostnames.
- Scope names, role bundles, token lifetime, refresh behaviour, revocation, and rotation.
- The exact client-visible rights field list.
- Public, token-protected, or network-restricted access to health endpoints.
- Pagination defaults, sort values, rate limits, error payloads, and
Retry-Afterbehaviour. - Record-version semantics and
PUTversusPATCHfor rights updates. - Verification of every example and error path against the implemented service.
- Replacement of invented fixtures with approved documentation examples.
- A dated documentation update after these details are confirmed.
Until then, use this guide to understand the proposed API model and rights vocabulary—not as proof of a live endpoint, permission, or licence.
Top comments (0)