<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Sukriti Vohra</title>
    <description>The latest articles on DEV Community by Sukriti Vohra (@sukriti_vohra_7fcfb5fd185).</description>
    <link>https://dev.to/sukriti_vohra_7fcfb5fd185</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4247814%2Fcb66ea87-132a-4a03-b80d-702d605529dc.png</url>
      <title>DEV Community: Sukriti Vohra</title>
      <link>https://dev.to/sukriti_vohra_7fcfb5fd185</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/sukriti_vohra_7fcfb5fd185"/>
    <language>en</language>
    <item>
      <title>Kadamba Footage Archive Catalogue API: Client Reference</title>
      <dc:creator>Sukriti Vohra</dc:creator>
      <pubDate>Wed, 18 Nov 2026 21:07:58 +0000</pubDate>
      <link>https://dev.to/sukriti_vohra_7fcfb5fd185/kadamba-footage-archive-catalogue-api-client-reference-3m4a</link>
      <guid>https://dev.to/sukriti_vohra_7fcfb5fd185/kadamba-footage-archive-catalogue-api-client-reference-3m4a</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Illustrative client reference — authentication pending confirmation.&lt;/strong&gt; 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 &lt;code&gt;.example&lt;/code&gt; addresses are placeholders, and every token and clip record below is invented. Confirm the production base URL and authentication before integrating.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Document control
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Item&lt;/th&gt;
&lt;th&gt;Value&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Archive&lt;/td&gt;
&lt;td&gt;Kadamba Footage Archive, Mysuru&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Owner&lt;/td&gt;
&lt;td&gt;Vasanthi Iyer&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Intended readers&lt;/td&gt;
&lt;td&gt;Nine cataloguing and rights staff; approved outside clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Authentication reviewer&lt;/td&gt;
&lt;td&gt;Irfan Pasha — confirmation pending&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;API version&lt;/td&gt;
&lt;td&gt;Proposed &lt;code&gt;v1&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Status&lt;/td&gt;
&lt;td&gt;Published illustrative reference; not yet a production contract&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Short overview&lt;/td&gt;
&lt;td&gt;&lt;a href="https://dev.to/sukriti_vohra_7fcfb5fd185/kadamba-footage-archive-catalogue-api-and-health-checks-bbf"&gt;Catalogue API and Health Checks&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Kadamba reports &lt;strong&gt;48,000 clips&lt;/strong&gt; and &lt;strong&gt;1,120 hours of digitised footage&lt;/strong&gt;. These are collection totals, not export quotas or a promise that every item can be licensed.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Addresses and conventions
&lt;/h2&gt;

&lt;p&gt;Proposed addresses:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;API: &lt;code&gt;https://api.kadamba-footage-archive.example&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Token service: &lt;code&gt;https://auth.kadamba-footage-archive.example&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Catalogue resources: &lt;code&gt;/v1&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Conventions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Bodies are JSON unless stated otherwise.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;clip_id&lt;/code&gt; is a stable archive identifier, such as &lt;code&gt;KFA-000138&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Dates use &lt;code&gt;YYYY-MM-DD&lt;/code&gt;; timestamps use ISO 8601 in UTC.&lt;/li&gt;
&lt;li&gt;Durations are whole seconds.&lt;/li&gt;
&lt;li&gt;A record version helps prevent two people from silently overwriting each other's changes.&lt;/li&gt;
&lt;li&gt;An empty rights array means &lt;strong&gt;nothing has been approved in that category&lt;/strong&gt;, not "everything".&lt;/li&gt;
&lt;li&gt;A &lt;code&gt;null&lt;/code&gt; rights date means &lt;strong&gt;not recorded or not decided&lt;/strong&gt;, not perpetual permission.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  2. Authentication and access — pending Irfan's confirmation
&lt;/h2&gt;

&lt;h3&gt;
  
  
  2.1 Roles and scopes
&lt;/h3&gt;

&lt;p&gt;A scope is a permission attached to a token. It separates reading from changing records.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Scope&lt;/th&gt;
&lt;th&gt;What it permits&lt;/th&gt;
&lt;th&gt;Proposed holder&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;catalogue.read&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Search and read clip metadata&lt;/td&gt;
&lt;td&gt;Staff and approved clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;catalogue.write&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Change cataloguing metadata&lt;/td&gt;
&lt;td&gt;Cataloguing staff&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;rights.read&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Read rights information&lt;/td&gt;
&lt;td&gt;Rights staff; clients only for approved public fields&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;rights.write&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Replace rights information&lt;/td&gt;
&lt;td&gt;Rights staff&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;health.read&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Read detailed readiness information&lt;/td&gt;
&lt;td&gt;Operations and monitoring identity&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Proposed role bundles:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Cataloguing staff:&lt;/strong&gt; &lt;code&gt;catalogue.read catalogue.write rights.read&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Rights staff:&lt;/strong&gt; &lt;code&gt;catalogue.read rights.read rights.write&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Outside client:&lt;/strong&gt; &lt;code&gt;catalogue.read&lt;/code&gt;; optional, filtered &lt;code&gt;rights.read&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Monitor:&lt;/strong&gt; &lt;code&gt;health.read&lt;/code&gt; only&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  2.2 Proposed client flow: OAuth 2.0 Client Credentials
&lt;/h3&gt;

&lt;p&gt;This is a server-to-server flow, not a person typing a password into a browser.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Each client receives a unique &lt;code&gt;client_id&lt;/code&gt; and &lt;code&gt;client_secret&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The client's backend exchanges them for a short-lived access token.&lt;/li&gt;
&lt;li&gt;The backend sends that token with API requests.&lt;/li&gt;
&lt;li&gt;When the token expires, the backend requests a new one; this flow does not need a refresh token.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Illustrative token request:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight http"&gt;&lt;code&gt;&lt;span class="no"&gt;POST&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;oauth&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;token&lt;/span&gt;
&lt;span class="nc"&gt;Host&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;auth&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;kadamba&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;footage&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;archive&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;
&lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Basic&lt;/span&gt; &lt;span class="no"&gt;BASE64_OF_CLIENT_ID_AND_CLIENT_SECRET&lt;/span&gt;
&lt;span class="nc"&gt;Content&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;application&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;x&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;www&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;form&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;urlencoded&lt;/span&gt;

&lt;span class="na"&gt;grant_type&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;client_credentials&lt;/span&gt;&lt;span class="o"&gt;&amp;amp;&lt;/span&gt;&lt;span class="n"&gt;scope&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;catalogue&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;read&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Illustrative response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"access_token"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"EXAMPLE_ONLY_NOT_A_REAL_TOKEN"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"token_type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Bearer"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"expires_in"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;900&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"scope"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"catalogue.read"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;expires_in: 900&lt;/code&gt; means 15 minutes and is &lt;strong&gt;proposed, not confirmed&lt;/strong&gt;. &lt;code&gt;Bearer&lt;/code&gt; means the API expects the token in an authorization header. A real bearer token must be protected like a password.&lt;/p&gt;

&lt;h3&gt;
  
  
  2.3 Proposed staff flow: OpenID Connect with PKCE
&lt;/h3&gt;

&lt;ol&gt;
&lt;li&gt;A staff member starts sign-in through the archive application.&lt;/li&gt;
&lt;li&gt;The application sends them to the identity provider.&lt;/li&gt;
&lt;li&gt;After sign-in, the application receives a one-time authorization code.&lt;/li&gt;
&lt;li&gt;It exchanges that code and a PKCE verifier for tokens. PKCE protects the exchange.&lt;/li&gt;
&lt;li&gt;The application uses the access token for the staff member's permitted API calls.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Passwords and client secrets must never appear in catalogue requests, browser code, support tickets, screenshots, or bookmarks.&lt;/p&gt;

&lt;h3&gt;
  
  
  2.4 Calling a protected endpoint
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight http"&gt;&lt;code&gt;&lt;span class="no"&gt;GET&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;v1&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;clips&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="no"&gt;KFA&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;000138&lt;/span&gt;
&lt;span class="nc"&gt;Host&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;api&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;kadamba&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;footage&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;archive&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;example&lt;/span&gt;
&lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Bearer&lt;/span&gt; &lt;span class="no"&gt;EXAMPLE_ACCESS_TOKEN&lt;/span&gt;
&lt;span class="nc"&gt;Accept&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;application&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;json&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;401 Unauthorized:&lt;/strong&gt; the token is missing, malformed, expired, or invalid. Authenticate again once; do not loop retries.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;403 Forbidden:&lt;/strong&gt; authentication worked, but the token lacks the required scope. Request access instead of retrying repeatedly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;429 Too Many Requests:&lt;/strong&gt; the caller exceeded an agreed limit. Respect &lt;code&gt;Retry-After&lt;/code&gt; if supplied.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Token storage, rotation, revocation, expiry, rate limits, and the exact credential transport remain pending confirmation.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Common errors
&lt;/h2&gt;

&lt;p&gt;Successful reads and the illustrated updates return &lt;code&gt;200 OK&lt;/code&gt;. Proposed error envelope:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"error"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"code"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"validation_failed"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"message"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"One or more fields need attention."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"fields"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"duration_seconds"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Must be a positive integer."&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"request_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"req_example_01"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;request_id&lt;/code&gt; is a support reference, not a credential.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;HTTP status&lt;/th&gt;
&lt;th&gt;Proposed meaning&lt;/th&gt;
&lt;th&gt;Caller action&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;400&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Request could not be parsed&lt;/td&gt;
&lt;td&gt;Fix JSON, parameters, or date formats&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;401&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Authentication missing or invalid&lt;/td&gt;
&lt;td&gt;Authenticate again once&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;403&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Caller lacks permission&lt;/td&gt;
&lt;td&gt;Check scopes or access approval&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;404&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No visible clip matches the ID&lt;/td&gt;
&lt;td&gt;Check the ID; do not assume deletion&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;409&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Record changed since it was read&lt;/td&gt;
&lt;td&gt;Re-read, compare, and retry deliberately&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;422&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Readable fields fail validation&lt;/td&gt;
&lt;td&gt;Correct the named fields&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;429&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Request budget exhausted&lt;/td&gt;
&lt;td&gt;Back off and respect &lt;code&gt;Retry-After&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;503&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Service or dependency unavailable&lt;/td&gt;
&lt;td&gt;Retry later with bounded backoff&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  4. Endpoint reference
&lt;/h2&gt;

&lt;h3&gt;
  
  
  4.1 Search clips
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;GET /v1/clips&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Scope:&lt;/strong&gt; &lt;code&gt;catalogue.read&lt;/code&gt;&lt;br&gt;&lt;br&gt;
&lt;strong&gt;Purpose:&lt;/strong&gt; Find clips and page through summary records. Search results are discovery aids, not permission to use footage.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Parameter&lt;/th&gt;
&lt;th&gt;Required&lt;/th&gt;
&lt;th&gt;Meaning&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;q&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Words matched against title, subjects, and description&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;page&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;One-based result page; proposed default &lt;code&gt;1&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;per_page&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Results per page; proposed default &lt;code&gt;25&lt;/code&gt;, maximum &lt;code&gt;100&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;subject&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Exact subject filter, repeatable&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;rights_status&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Workflow filter; it does not grant a licence&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;digitised&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;true&lt;/code&gt; or &lt;code&gt;false&lt;/code&gt;; digital availability does not imply clearance&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;from_date&lt;/code&gt;, &lt;code&gt;to_date&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Inclusive recording-date bounds&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sort&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Proposed: &lt;code&gt;relevance&lt;/code&gt;, &lt;code&gt;date_asc&lt;/code&gt;, &lt;code&gt;date_desc&lt;/code&gt;, &lt;code&gt;title_asc&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight http"&gt;&lt;code&gt;&lt;span class="na"&gt;GET /v1/clips?q&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;monsoon&lt;/span&gt;&lt;span class="o"&gt;&amp;amp;&lt;/span&gt;&lt;span class="n"&gt;subject&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="nc"&gt;Mysuru&lt;/span&gt;&lt;span class="o"&gt;&amp;amp;&lt;/span&gt;&lt;span class="n"&gt;page&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="o"&gt;&amp;amp;&lt;/span&gt;&lt;span class="n"&gt;per_page&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;
&lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Bearer&lt;/span&gt; &lt;span class="no"&gt;EXAMPLE_ACCESS_TOKEN&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Illustrative response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"data"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"title"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Mysuru market after monsoon rain"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"date"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1987-06-14"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"duration_seconds"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;92&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"source_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"16mm film"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"digitised"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"subjects"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Mysuru"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"markets"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"monsoon"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"rights_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"review_required"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"page"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"per_page"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"total"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;total&lt;/code&gt; counts records matching the filter, not total archive holdings. No matches returns &lt;code&gt;200&lt;/code&gt;, &lt;code&gt;data: []&lt;/code&gt;, and &lt;code&gt;total: 0&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  4.2 Read one clip
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;GET /v1/clips/{clip_id}&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Scope:&lt;/strong&gt; &lt;code&gt;catalogue.read&lt;/code&gt;&lt;br&gt;&lt;br&gt;
&lt;strong&gt;Purpose:&lt;/strong&gt; Retrieve the client-visible cataloguing record for one clip. Replace &lt;code&gt;{clip_id}&lt;/code&gt; with the actual ID and omit the braces.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"title"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Mysuru market after monsoon rain"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"date"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1987-06-14"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"duration_seconds"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;92&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"source_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"16mm film"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"digitised"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"preservation_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"FFV1/MKV"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"access_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"H.264/MP4"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"subjects"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Mysuru"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"markets"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"monsoon"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"rights_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"review_required"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"catalogue_record_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;17&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"updated_at"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-11-18T20:38:44Z"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;source_format&lt;/code&gt; describes the original carrier.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;preservation_format&lt;/code&gt; describes the preservation file, not necessarily a client download.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;access_format&lt;/code&gt; describes a viewing proxy, not redistribution permission.&lt;/li&gt;
&lt;li&gt;Retain &lt;code&gt;catalogue_record_version&lt;/code&gt; before making an update.&lt;/li&gt;
&lt;li&gt;The rights endpoint is the proposed source of truth if this summary's &lt;code&gt;rights_status&lt;/code&gt; is stale.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  4.3 Update cataloguing metadata
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;PATCH /v1/clips/{clip_id}&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Scope:&lt;/strong&gt; &lt;code&gt;catalogue.write&lt;/code&gt;&lt;br&gt;&lt;br&gt;
&lt;strong&gt;Purpose:&lt;/strong&gt; Change only supplied cataloguing fields. Omitted fields stay unchanged.&lt;/p&gt;

&lt;p&gt;Staff rules:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Send the &lt;code&gt;catalogue_record_version&lt;/code&gt; last read.&lt;/li&gt;
&lt;li&gt;Do not change &lt;code&gt;rights_status&lt;/code&gt; here; use the rights workflow.&lt;/li&gt;
&lt;li&gt;Treat &lt;code&gt;clip_id&lt;/code&gt;, creation history, and system timestamps as read-only.&lt;/li&gt;
&lt;li&gt;On &lt;code&gt;409&lt;/code&gt;, re-read and review the other person's changes before retrying.
&lt;/li&gt;
&lt;/ul&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight http"&gt;&lt;code&gt;&lt;span class="no"&gt;PATCH&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;v1&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;clips&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="no"&gt;KFA&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;000138&lt;/span&gt;
&lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Bearer&lt;/span&gt; &lt;span class="no"&gt;EXAMPLE_STAFF_TOKEN&lt;/span&gt;
&lt;span class="nc"&gt;Content&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;application&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;json&lt;/span&gt;

&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="s2"&gt;"title"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Mysuru market after monsoon rain, 1987"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"subjects"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Mysuru"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"markets"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"monsoon"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"street trading"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"catalogue_record_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;17&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;Illustrative response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"updated"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"catalogue_record_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;18&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"updated_at"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-11-19T09:30:00Z"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  4.4 Read a clip's rights record
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;GET /v1/clips/{clip_id}/rights&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Scope:&lt;/strong&gt; &lt;code&gt;rights.read&lt;/code&gt;&lt;br&gt;&lt;br&gt;
&lt;strong&gt;Purpose:&lt;/strong&gt; Explain what has and has not been reviewed for possible use. This is not a signed licence or legal advice.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;Illustrative staff-safe response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"review_required"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"client_licensing"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"not_available_until_cleared"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"credit"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Kadamba Footage Archive; donor credit pending"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"territories"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"licence_start_on"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"licence_end_on"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"allowed_media"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"allowed_edits"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"public_notes"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Not available for client licensing while review is pending."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"donor_restrictions"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Donor credit wording requires review."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"third_party_components"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Background music"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"consent_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"not_assessed"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"music_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"unresolved"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"review_owner"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"rights-team"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"last_reviewed_at"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"rights_record_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;9&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Rights fields in plain terms:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Field&lt;/th&gt;
&lt;th&gt;Meaning&lt;/th&gt;
&lt;th&gt;Proposed visibility&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;status&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Position in the rights review workflow&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;client_licensing&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Whether the archive can currently consider a client licence&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;credit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Required attribution wording, when applicable; not proof of permission&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;territories&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Places covered; &lt;code&gt;[]&lt;/code&gt; means none confirmed&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;licence_start_on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;First covered date, if decided&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;licence_end_on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Last covered date; &lt;code&gt;null&lt;/code&gt; is not perpetual&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;allowed_media&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Approved channels; &lt;code&gt;[]&lt;/code&gt; means none approved&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;allowed_edits&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Permitted changes; &lt;code&gt;[]&lt;/code&gt; means none approved&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;public_notes&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Short note approved for client display&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;donor_restrictions&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Conditions from a donation or deposit agreement&lt;/td&gt;
&lt;td&gt;Staff only unless cleared&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;third_party_components&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Music, stills, performances, or other material needing separate checks&lt;/td&gt;
&lt;td&gt;Staff only&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;consent_status&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Whether releases or consents have been assessed; not a legal conclusion&lt;/td&gt;
&lt;td&gt;Staff only&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;music_status&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;State of composition, recording, and synchronisation checks&lt;/td&gt;
&lt;td&gt;Staff only&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;review_owner&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Team responsible for the next review step&lt;/td&gt;
&lt;td&gt;Staff only by default&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;last_reviewed_at&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;When the current state was assessed&lt;/td&gt;
&lt;td&gt;Staff and clients if approved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;rights_record_version&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Version used to prevent conflicting rights updates&lt;/td&gt;
&lt;td&gt;Staff only&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Proposed statuses:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Status&lt;/th&gt;
&lt;th&gt;Plain-English meaning&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;review_required&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Assessment is unfinished; do not offer for licensing&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;counsel_review&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A legal or specialist question remains open&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cleared_subset&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Only specifically recorded material, uses, or excerpts are cleared&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cleared&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Review is complete for the stated scope, not an unlimited licence or public-domain claim&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;blocked&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Do not offer the clip for the requested use&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Read &lt;code&gt;status&lt;/code&gt; together with territories, dates, media, edits, credit, and the final licence. One field never tells the whole story.&lt;/p&gt;

&lt;h3&gt;
  
  
  4.5 Replace a rights record
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;PUT /v1/clips/{clip_id}/rights&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Scope:&lt;/strong&gt; &lt;code&gt;rights.write&lt;/code&gt;&lt;br&gt;&lt;br&gt;
&lt;strong&gt;Purpose:&lt;/strong&gt; Replace the mutable rights record as a complete unit. Omitted mutable fields may be cleared or defaulted.&lt;/p&gt;

&lt;p&gt;Rules for rights staff:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Send the complete intended record and last-read &lt;code&gt;rights_record_version&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Confirm every empty array and &lt;code&gt;null&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Never place confidential legal analysis in &lt;code&gt;public_notes&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A rights update does not itself issue a client licence.
&lt;/li&gt;
&lt;/ul&gt;
&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight http"&gt;&lt;code&gt;&lt;span class="no"&gt;PUT&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;v1&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;clips&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="no"&gt;KFA&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="mi"&gt;000138&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;rights&lt;/span&gt;
&lt;span class="nc"&gt;Authorization&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nc"&gt;Bearer&lt;/span&gt; &lt;span class="no"&gt;EXAMPLE_RIGHTS_STAFF_TOKEN&lt;/span&gt;
&lt;span class="nc"&gt;Content&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="nc"&gt;Type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;application&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;json&lt;/span&gt;

&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="s2"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"counsel_review"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"client_licensing"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"not_available_until_cleared"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"credit"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Kadamba Footage Archive; donor credit pending"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"territories"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"licence_start_on"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"licence_end_on"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;null&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"allowed_media"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"allowed_edits"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"public_notes"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Music and donor-credit wording are under review."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"donor_restrictions"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Donor credit wording requires review."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"third_party_components"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Background music"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"consent_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"not_assessed"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"music_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"counsel_review"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"review_owner"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"rights-team"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"last_reviewed_at"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"2026-11-19T09:30:00Z"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="s2"&gt;"rights_record_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;9&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;Illustrative response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"updated"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"counsel_review"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"rights_record_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Whether this should remain full-replacement &lt;code&gt;PUT&lt;/code&gt; or become a partial &lt;code&gt;PATCH&lt;/code&gt; is still a technical-review question.&lt;/p&gt;

&lt;h3&gt;
  
  
  4.6 Liveness
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;GET /health/live&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Proposed access:&lt;/strong&gt; public to the monitoring network or restricted by network policy; confirmation pending&lt;br&gt;&lt;br&gt;
&lt;strong&gt;Purpose:&lt;/strong&gt; Show whether the API process is running, without proving every dependency works.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A failed process may return &lt;code&gt;503&lt;/code&gt; or not respond. Responses must not contain stack traces, secrets, internal hostnames, client data, or detailed diagnostics.&lt;/p&gt;

&lt;h3&gt;
  
  
  4.7 Readiness
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;GET /health/ready&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Proposed scope:&lt;/strong&gt; &lt;code&gt;health.read&lt;/code&gt;, or an equivalent private network rule&lt;br&gt;&lt;br&gt;
&lt;strong&gt;Purpose:&lt;/strong&gt; Show whether the service is ready for catalogue traffic.&lt;/p&gt;

&lt;p&gt;Healthy response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"checks"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"catalogue_index"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"metadata_store"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"preview_storage"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Illustrative &lt;code&gt;503&lt;/code&gt; response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"not_ready"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"checks"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"catalogue_index"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"metadata_store"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"preview_storage"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"unavailable"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;catalogue_index&lt;/code&gt; supports search, &lt;code&gt;metadata_store&lt;/code&gt; holds records, and &lt;code&gt;preview_storage&lt;/code&gt; holds access proxies. These illustrative names must not expose sensitive infrastructure in a public response.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Proposed UptimeRobot mapping
&lt;/h2&gt;

&lt;p&gt;Use read-only requests only. Never run &lt;code&gt;PATCH&lt;/code&gt; or &lt;code&gt;PUT&lt;/code&gt; as an uptime check.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | Catalogue Search | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/v1/clips?q=monsoon&amp;amp;per_page=1&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | Clip Metadata | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/v1/clips/KFA-000138&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | Rights Lookup | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/v1/clips/KFA-000138/rights&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | API Liveness | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/health/live&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | API Readiness | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/health/ready&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  6. Outstanding technical confirmation
&lt;/h2&gt;

&lt;p&gt;Publication of this reference does &lt;strong&gt;not&lt;/strong&gt; mean the following items are approved:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Irfan's confirmation of the actual authentication scheme and client onboarding.&lt;/li&gt;
&lt;li&gt;Production API and token-service hostnames.&lt;/li&gt;
&lt;li&gt;Scope names, role bundles, token lifetime, refresh behaviour, revocation, and rotation.&lt;/li&gt;
&lt;li&gt;The exact client-visible rights field list.&lt;/li&gt;
&lt;li&gt;Public, token-protected, or network-restricted access to health endpoints.&lt;/li&gt;
&lt;li&gt;Pagination defaults, sort values, rate limits, error payloads, and &lt;code&gt;Retry-After&lt;/code&gt; behaviour.&lt;/li&gt;
&lt;li&gt;Record-version semantics and &lt;code&gt;PUT&lt;/code&gt; versus &lt;code&gt;PATCH&lt;/code&gt; for rights updates.&lt;/li&gt;
&lt;li&gt;Verification of every example and error path against the implemented service.&lt;/li&gt;
&lt;li&gt;Replacement of invented fixtures with approved documentation examples.&lt;/li&gt;
&lt;li&gt;A dated documentation update after these details are confirmed.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Until then, use this guide to understand the proposed API model and rights vocabulary—not as proof of a live endpoint, permission, or licence.&lt;/p&gt;

</description>
      <category>api</category>
      <category>documentation</category>
      <category>reference</category>
      <category>archives</category>
    </item>
    <item>
      <title>Kadamba Footage Archive: Catalogue API and Health Checks</title>
      <dc:creator>Sukriti Vohra</dc:creator>
      <pubDate>Wed, 18 Nov 2026 20:37:56 +0000</pubDate>
      <link>https://dev.to/sukriti_vohra_7fcfb5fd185/kadamba-footage-archive-catalogue-api-and-health-checks-bbf</link>
      <guid>https://dev.to/sukriti_vohra_7fcfb5fd185/kadamba-footage-archive-catalogue-api-and-health-checks-bbf</guid>
      <description>&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Illustrative proposed reference — not a verified production contract.&lt;/strong&gt; Prepared for Vasanthi Iyer and the nine cataloguing and rights staff at Kadamba Footage Archive, Mysuru, and for outside clients. Kadamba reports &lt;strong&gt;48,000 clips&lt;/strong&gt; and &lt;strong&gt;1,120 hours of digitised footage&lt;/strong&gt;. 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 &lt;code&gt;.example&lt;/code&gt; addresses are not live services. Replace them and obtain technical sign-off before client integration.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;h2&gt;
  
  
  Catalogue and rights endpoints
&lt;/h2&gt;

&lt;p&gt;Proposed API base: &lt;code&gt;https://api.kadamba-footage-archive.example/v1&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;Use JSON, stable clip IDs, and ISO 8601 dates. &lt;code&gt;per_page&lt;/code&gt; controls page size; &lt;code&gt;q&lt;/code&gt; searches title, subject, and description text.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Method and path&lt;/th&gt;
&lt;th&gt;Plain-English purpose&lt;/th&gt;
&lt;th&gt;Proposed audience&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GET /v1/clips&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Search and page through the catalogue&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GET /v1/clips/{clip_id}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Read one clip's technical and descriptive metadata&lt;/td&gt;
&lt;td&gt;Staff and clients&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PATCH /v1/clips/{clip_id}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Change selected cataloguing fields&lt;/td&gt;
&lt;td&gt;Cataloguing staff&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GET /v1/clips/{clip_id}/rights&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Read clearance and licensing status&lt;/td&gt;
&lt;td&gt;Staff; client visibility TBD&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;PUT /v1/clips/{clip_id}/rights&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Replace a rights record&lt;/td&gt;
&lt;td&gt;Rights staff&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GET /health/live&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Answer whether the API process is alive&lt;/td&gt;
&lt;td&gt;Monitoring&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;GET /health/ready&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Answer whether required dependencies are ready&lt;/td&gt;
&lt;td&gt;Monitoring and operations&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h3&gt;
  
  
  Search the catalogue
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;GET /v1/clips?q=monsoon&amp;amp;page=1&amp;amp;per_page=2&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;Illustrative &lt;code&gt;200 OK&lt;/code&gt; response:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"data"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"title"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Mysuru market after monsoon rain"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"date"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1987-06-14"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"duration_seconds"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;92&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"source_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"16mm film"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"rights_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"review_required"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-001204"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"title"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Kaveri flood-response newsreel"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"date"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1992-08-03"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"duration_seconds"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;148&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"source_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"U-matic"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="nl"&gt;"rights_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"cleared_subset"&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"page"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"per_page"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"total"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Read one clip
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;GET /v1/clips/KFA-000138&lt;/code&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"title"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Mysuru market after monsoon rain"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"date"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1987-06-14"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"duration_seconds"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;92&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"digitised"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"preservation_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"FFV1/MKV"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"access_format"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"H.264/MP4"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"subjects"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Mysuru"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"markets"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"monsoon"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"rights_status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"review_required"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A successful catalogue update could return:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"updated"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"catalogue_record_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="mi"&gt;17&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Read or update rights
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;GET /v1/clips/KFA-000138/rights&lt;/code&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"review_required"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"client_licensing"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"not_available_until_cleared"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"credit"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Kadamba Footage Archive; donor credit pending"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"territories"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"review_owner"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"rights-team"&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A successful rights update could return:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nl"&gt;"clip_id"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s2"&gt;"KFA-000138"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"updated"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"rights_record_version"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="mi"&gt;9&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s2"&gt;"review_required"&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A rights status is a workflow signal, &lt;strong&gt;not a licence&lt;/strong&gt;. Clients should wait for written licensing confirmation.&lt;/p&gt;

&lt;h2&gt;
  
  
  Server health endpoints
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;GET /health/live&lt;/code&gt; should be cheap and should not depend on every downstream service:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;GET /health/ready&lt;/code&gt; can report whether the service is ready to accept catalogue traffic:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"checks"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"catalogue_index"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"metadata_store"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"preview_storage"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ok"&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Keep stack traces, secrets, internal hostnames, and client details out of health responses.&lt;/p&gt;

&lt;h2&gt;
  
  
  UptimeRobot check names
&lt;/h2&gt;

&lt;p&gt;These are &lt;strong&gt;proposed display names, not a claim that the monitors currently exist&lt;/strong&gt;. 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 &lt;code&gt;PATCH&lt;/code&gt; or &lt;code&gt;PUT&lt;/code&gt; requests as uptime checks.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | Catalogue Search | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/v1/clips?q=monsoon&amp;amp;per_page=1&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | Clip Metadata | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/v1/clips/KFA-000138&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | Rights Lookup | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/v1/clips/KFA-000138/rights&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | API Liveness | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/health/live&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;Kadamba | API Readiness | HTTPS + SSL&lt;/code&gt; — &lt;code&gt;/health/ready&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Monitoring service: &lt;a href="https://uptimerobot.com/" rel="noopener noreferrer"&gt;UptimeRobot&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Authentication: confirm with Irfan Pasha
&lt;/h2&gt;

&lt;p&gt;Before treating this as integration documentation, Irfan Pasha should confirm:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;the actual scheme and header—API key, Bearer token, OAuth 2.0, or another method;&lt;/li&gt;
&lt;li&gt;staff, rights-staff, and client scopes, including whether clients may see rights summaries;&lt;/li&gt;
&lt;li&gt;whether readiness and detailed health results must be private;&lt;/li&gt;
&lt;li&gt;credential issuance, expiry, rotation, revocation, rate limits, and the real &lt;code&gt;401&lt;/code&gt;/&lt;code&gt;403&lt;/code&gt; payloads;&lt;/li&gt;
&lt;li&gt;whether monitors need credentials and how those secrets are stored.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Never put real credentials in query strings, sample JSON, screenshots, monitor names, this article, or bookmarks. All examples here are credential-free placeholders.&lt;/p&gt;

</description>
      <category>api</category>
      <category>documentation</category>
      <category>monitoring</category>
      <category>archives</category>
    </item>
    <item>
      <title>How We Dashboard a Cinema Chain: Scheduling, Footfall and Concessions</title>
      <dc:creator>Sukriti Vohra</dc:creator>
      <pubDate>Wed, 18 Nov 2026 20:26:55 +0000</pubDate>
      <link>https://dev.to/sukriti_vohra_7fcfb5fd185/how-we-dashboard-a-cinema-chain-scheduling-footfall-and-concessions-1odn</link>
      <guid>https://dev.to/sukriti_vohra_7fcfb5fd185/how-we-dashboard-a-cinema-chain-scheduling-footfall-and-concessions-1odn</guid>
      <description>&lt;p&gt;&lt;em&gt;By Ananya Krishnan, Operations, CineVerse Theatres.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;CineVerse Theatres runs nine theatres and 12,400 seats in Hyderabad. Our dashboard problem is not producing more charts. It is getting a duty manager, film programmer, and concession lead to the same next action.&lt;/p&gt;

&lt;p&gt;We organise the operating view around three questions:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Scheduling:&lt;/strong&gt; which show or screen needs attention?&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Footfall:&lt;/strong&gt; when are arrivals building relative to showtime?&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Concessions:&lt;/strong&gt; are transaction rate and basket size moving differently?&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Start with grain, not visuals
&lt;/h2&gt;

&lt;p&gt;We keep three kinds of facts separate:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Fact table&lt;/th&gt;
&lt;th&gt;Grain&lt;/th&gt;
&lt;th&gt;Useful fields&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;show_fact&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;One row per scheduled show&lt;/td&gt;
&lt;td&gt;Theatre, screen, film, scheduled and actual start, sellable seats, admissions, estimated screen-clear time&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;entry_bucket_fact&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;One row per counter and 15-minute bucket&lt;/td&gt;
&lt;td&gt;Theatre, counter, bucket start, entries, source timestamp&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;pos_line_fact&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;One row per concession receipt line&lt;/td&gt;
&lt;td&gt;Transaction ID, sale time, item, quantity, net sales, refund/void status&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Shared dimensions—such as theatre, screen, film, business date, daypart, and item—make the views comparable.&lt;/p&gt;

&lt;p&gt;One trap is joining raw POS lines directly to shows and then summing admissions. Every receipt line can duplicate the show-level measures. We aggregate each fact separately before comparing them at a common theatre, business-date, and daypart grain.&lt;/p&gt;

&lt;h2&gt;
  
  
  Scheduling: seats belong to shows
&lt;/h2&gt;

&lt;p&gt;The chain’s 12,400 seats describe our scale; they are not the denominator for a day’s occupancy. Each show has its own sellable capacity after holds and closures.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;show occupancy   = ticket admissions / sellable seats for that show
late-start delay = actual start - scheduled start
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Alongside occupancy, the schedule view surfaces:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;scheduled versus actual starts;&lt;/li&gt;
&lt;li&gt;insufficient clear-and-clean turnaround buffers;&lt;/li&gt;
&lt;li&gt;the number of shows starting in the same lobby-arrival window;&lt;/li&gt;
&lt;li&gt;dark screens during review-worthy programming slots.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A chain-wide average is useful for a weekly review, but intervention usually happens at show or screen level. Film-scheduling research similarly treats film, screen, start time, per-show demand, and operating constraints together. An optimizer is not required for these first useful checks.&lt;/p&gt;

&lt;h2&gt;
  
  
  Footfall: entries are not admissions
&lt;/h2&gt;

&lt;p&gt;Door counters, ticket scans, and POS transactions answer different questions.&lt;/p&gt;

&lt;p&gt;We plot entries in 15-minute buckets alongside ticket admissions and align them with upcoming showtimes. This helps distinguish a lobby arrival surge from a show that simply has low admissions.&lt;/p&gt;

&lt;p&gt;We deliberately do &lt;strong&gt;not&lt;/strong&gt; call &lt;code&gt;entries / admissions&lt;/code&gt; a conversion rate. Depending on the installation, counter events can include staff, re-entry, and people who do not attend a screening. Counter outages are shown as &lt;strong&gt;no data&lt;/strong&gt;, never as zero footfall.&lt;/p&gt;

&lt;p&gt;Aggregated counts are sufficient for this operating view. If a footfall source captures identifiable personal data, it needs a separate legal and privacy review; a dashboard is not a reason to collect more data.&lt;/p&gt;

&lt;h2&gt;
  
  
  Concessions: split spend into two drivers
&lt;/h2&gt;

&lt;p&gt;Total concession revenue rises with admissions, so revenue alone is hard to interpret. We use three measures over the same theatre and time window:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;transaction rate    = distinct concession transactions / ticket admissions
average receipt     = net concession sales / distinct concession transactions
spend per admission = net concession sales / ticket admissions
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With consistent scopes and denominators:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;spend per admission = transaction rate × average receipt
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;strong&gt;Illustrative example—not CineVerse data:&lt;/strong&gt; 100 admissions, 40 concession transactions, and ₹8,800 in net sales produce:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;a &lt;strong&gt;40% transaction rate&lt;/strong&gt;;&lt;/li&gt;
&lt;li&gt;a &lt;strong&gt;₹220 average receipt&lt;/strong&gt;;&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;₹88 spend per admission&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If transaction rate falls while average receipt holds, we investigate arrival bunching, queues, staffing, and stock availability before drawing conclusions about the menu or pricing. If one receipt serves a group, transaction rate is a proxy—not a measure of unique buyers.&lt;/p&gt;

&lt;p&gt;“Net sales” must have one documented meaning across theatres, including the treatment of taxes, refunds, and voids.&lt;/p&gt;

&lt;h2&gt;
  
  
  Make the dashboard actionable
&lt;/h2&gt;

&lt;p&gt;We reuse one dashboard with theatre, business-date, film, and daypart filters rather than maintaining separate copies for each location. Every panel displays the last successful source timestamp.&lt;/p&gt;

&lt;p&gt;Operational alerts focus on things someone can act on:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;stale or failed feeds;&lt;/li&gt;
&lt;li&gt;actual starts beyond the agreed late threshold;&lt;/li&gt;
&lt;li&gt;counter outages;&lt;/li&gt;
&lt;li&gt;arrival surges against the staffing plan;&lt;/li&gt;
&lt;li&gt;queue or stockout signals, where those are captured.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Low occupancy alone goes to programming review rather than automatically paging a duty manager.&lt;/p&gt;

&lt;p&gt;Refresh frequency follows the source. Refreshing a panel every 30 seconds does not improve a 15-minute extract. Business dates use the &lt;code&gt;Asia/Kolkata&lt;/code&gt; timezone and an explicit rule for post-midnight shows.&lt;/p&gt;

&lt;p&gt;Our basic rule is that every operational KPI needs an &lt;strong&gt;owner, grain, denominator, freshness expectation, and next action&lt;/strong&gt;. If a panel cannot tell someone what to check next, it probably belongs in an exploratory report rather than the operations dashboard.&lt;/p&gt;

&lt;h3&gt;
  
  
  Sources and further reading
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://web.williams.edu/Mathematics/sjmiller/public_html/math/papers/SilverScreenerPublishedJournalArticle_EliashbergEtAl.pdf" rel="noopener noreferrer"&gt;Demand-driven scheduling of movies in a multiplex — Eliashberg et al.&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://doi.org/10.1080/16522354.2020.1832745" rel="noopener noreferrer"&gt;Optimisation approaches and challenges of personnel deployment for movie exhibitors — Brühl and Eigler&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.independentcinemaoffice.org.uk/advice-support/how-to-start-a-cinema/the-economics-of-the-operation/" rel="noopener noreferrer"&gt;The economics of the operation — Independent Cinema Office&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://learn.microsoft.com/en-us/power-bi/guidance/star-schema" rel="noopener noreferrer"&gt;Understand star schema — Microsoft&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://grafana.com/docs/grafana/latest/visualizations/dashboards/build-dashboards/best-practices/" rel="noopener noreferrer"&gt;Grafana dashboard best practices&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;India’s &lt;a href="https://meity.gov.in/static/uploads/2024/06/2bf1f0e9f04e6fb4f8fef35e82c42aa5.pdf" rel="noopener noreferrer"&gt;Digital Personal Data Protection Act, 2023&lt;/a&gt; and the &lt;a href="https://www.pib.gov.in/PressNoteDetails.aspx?ModuleId=3&amp;amp;NoteId=156054" rel="noopener noreferrer"&gt;PIB summary of the DPDP Rules, 2025&lt;/a&gt;
&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>data</category>
      <category>analytics</category>
      <category>dashboards</category>
      <category>operations</category>
    </item>
  </channel>
</rss>
