Illustrative proposed reference — not a verified production contract. Prepared for Vasanthi Iyer and the nine cataloguing and rights staff at Kadamba Footage Archive, Mysuru, and for outside clients. Kadamba reports 48,000 clips and 1,120 hours of digitised footage. No OpenAPI document or Kadamba UptimeRobot export was available, so the hostnames, routes, sample records, monitor names, and access rules below are realistic placeholders. The reserved
.exampleaddresses are not live services. Replace them and obtain technical sign-off before client integration.
Catalogue and rights endpoints
Proposed API base: https://api.kadamba-footage-archive.example/v1
Use JSON, stable clip IDs, and ISO 8601 dates. per_page controls page size; q searches title, subject, and description text.
| Method and path | Plain-English purpose | Proposed audience |
|---|---|---|
GET /v1/clips |
Search and page through the catalogue | Staff and clients |
GET /v1/clips/{clip_id} |
Read one clip's technical and descriptive metadata | Staff and clients |
PATCH /v1/clips/{clip_id} |
Change selected cataloguing fields | Cataloguing staff |
GET /v1/clips/{clip_id}/rights |
Read clearance and licensing status | Staff; client visibility TBD |
PUT /v1/clips/{clip_id}/rights |
Replace a rights record | Rights staff |
GET /health/live |
Answer whether the API process is alive | Monitoring |
GET /health/ready |
Answer whether required dependencies are ready | Monitoring and operations |
Search the catalogue
GET /v1/clips?q=monsoon&page=1&per_page=2
Illustrative 200 OK response:
{
"data": [
{
"clip_id": "KFA-000138",
"title": "Mysuru market after monsoon rain",
"date": "1987-06-14",
"duration_seconds": 92,
"source_format": "16mm film",
"rights_status": "review_required"
},
{
"clip_id": "KFA-001204",
"title": "Kaveri flood-response newsreel",
"date": "1992-08-03",
"duration_seconds": 148,
"source_format": "U-matic",
"rights_status": "cleared_subset"
}
],
"page": 1,
"per_page": 2,
"total": 2
}
Read one clip
GET /v1/clips/KFA-000138
{
"clip_id": "KFA-000138",
"title": "Mysuru market after monsoon rain",
"date": "1987-06-14",
"duration_seconds": 92,
"digitised": true,
"preservation_format": "FFV1/MKV",
"access_format": "H.264/MP4",
"subjects": ["Mysuru", "markets", "monsoon"],
"rights_status": "review_required"
}
A successful catalogue update could return:
{"clip_id":"KFA-000138","updated":true,"catalogue_record_version":17}
Read or update rights
GET /v1/clips/KFA-000138/rights
{
"clip_id": "KFA-000138",
"status": "review_required",
"client_licensing": "not_available_until_cleared",
"credit": "Kadamba Footage Archive; donor credit pending",
"territories": [],
"review_owner": "rights-team"
}
A successful rights update could return:
{"clip_id":"KFA-000138","updated":true,"rights_record_version":9,"status":"review_required"}
A rights status is a workflow signal, not a licence. Clients should wait for written licensing confirmation.
Server health endpoints
GET /health/live should be cheap and should not depend on every downstream service:
{"status":"ok"}
GET /health/ready can report whether the service is ready to accept catalogue traffic:
{
"status": "ok",
"checks": {
"catalogue_index": "ok",
"metadata_store": "ok",
"preview_storage": "ok"
}
}
Keep stack traces, secrets, internal hostnames, and client details out of health responses.
UptimeRobot check names
These are proposed display names, not a claim that the monitors currently exist. Suggested settings are HTTPS with SSL validation, a five-minute interval, and a 30-second timeout. Check for HTTP 200 and, where practical, a small response keyword. Do not run destructive PATCH or PUT requests as uptime checks.
-
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
Monitoring service: UptimeRobot.
Authentication: confirm with Irfan Pasha
Before treating this as integration documentation, Irfan Pasha should confirm:
- the actual scheme and header—API key, Bearer token, OAuth 2.0, or another method;
- staff, rights-staff, and client scopes, including whether clients may see rights summaries;
- whether readiness and detailed health results must be private;
- credential issuance, expiry, rotation, revocation, rate limits, and the real
401/403payloads; - whether monitors need credentials and how those secrets are stored.
Never put real credentials in query strings, sample JSON, screenshots, monitor names, this article, or bookmarks. All examples here are credential-free placeholders.
Top comments (0)