From 80f8179f5e881310ffe9d3ac9a89e3e511cee06d Mon Sep 17 00:00:00 2001
From: Alex Firmani <jafirmani@gmail.com>
Date: Fri, 7 Aug 2026 08:16:13 -0700
Subject: [PATCH] Document the advertisement status endpoint in the OpenAPI
 schema

Add GET /sync/status/ad/{cid} alongside the existing publisher sync
status endpoints, with an AdStatus schema and a worked example.

The endpoint is live on cid.contact and in use by publishers, but was
the one sync status route missing from the schema. It returns only the
requested CID and an Indexed boolean; no phase data, timestamps, or
provider identity are stored per advertisement.

Indexed is true only when the advertisement was fully processed while
the indexer was configured to store its entries. Advertisements that
were skipped, are still in progress, failed, or have never been seen
report false, so a false result is not on its own evidence that the
advertisement was rejected.
---
 schemas/v1/openapi.yaml | 52 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/schemas/v1/openapi.yaml b/schemas/v1/openapi.yaml
index ee2de2e..0bfc586 100644
--- a/schemas/v1/openapi.yaml
+++ b/schemas/v1/openapi.yaml
@@ -164,6 +164,34 @@ paths:
           description: The given peer ID could not be decoded.
           content:
             text/plain: { }
+  /sync/status/ad/{cid}:
+    get:
+      description: Reports whether the content of a single advertisement is available from this indexer.
+      parameters:
+        - name: cid
+          in: path
+          description: The string representation of the advertisement CID.
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The advertisement status was determined.
+          content:
+            'application/json':
+              schema:
+                $ref: '#/components/schemas/AdStatus'
+              examples:
+                adStatus:
+                  $ref: '#/components/examples/AdStatusResponse'
+        '400':
+          description: The given CID could not be decoded.
+          content:
+            text/plain: { }
+        '500':
+          description: Failure occurred while processing the request.
+          content:
+            text/plain: { }
 components:
   schemas:
     FindResponse:
@@ -357,6 +385,23 @@ components:
           type: integer
           format: int64
           description: Total multihashes indexed; the sum of ChunkMultihashCount and HamtMultihashCount.
+    AdStatus:
+      type: object
+      description: |
+        Availability of a single advertisement's content from this indexer.
+        Timestamps and provider identity are not stored per advertisement and
+        are not returned.
+      properties:
+        Ad:
+          type: string
+          description: String CID of the requested advertisement.
+        Indexed:
+          type: boolean
+          description: |
+            True only when the advertisement was fully processed while the
+            indexer was configured to store its entries. Advertisements that
+            were skipped, are still in progress, failed, or have never been
+            seen report false.
   examples:
     NDJsonProviderRecords:
       summary: Streaming provider records response
@@ -526,6 +571,13 @@ components:
             ]
           }
         }
+    AdStatusResponse:
+      summary: Advertisement whose content is available from this indexer
+      value: |
+        {
+          "Ad": "baguqeerakziw4pilnfeydam57egdqe4qf4xo5nfljdnzzl3jutarmmimtsjq",
+          "Indexed": true
+        }
   parameters:
     Cascade:
       name: cascade