{
  "openapi": "3.1.0",
  "info": {
    "title": "Madrid Film Calendar FDB Partner API",
    "version": "1.0.0",
    "description": "Bulk-first, read-only FDB partner snapshot contract with factual records and Madrid Film Calendar's cited research. CC BY applies only to rights Madrid Film Calendar owns or controls."
  },
  "servers": [{"url": "https://data.madridfilmcalendar.com"}],
  "paths": {
    "/v1/current.json": {
      "get": {
        "summary": "Resolve the current immutable catalog snapshot",
        "operationId": "getCurrentSnapshot",
        "security": [{"partnerBearer": []}],
        "responses": {
          "200": {
            "description": "Current snapshot pointer",
            "headers": {
              "ETag": {"schema": {"type": "string"}},
              "Cache-Control": {"schema": {"type": "string"}}
            },
            "content": {"application/json": {"schema": {"$ref": "./current.schema.json"}}}
          },
          "304": {"description": "The pointer has not changed"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"}
        }
      }
    },
    "/v1/snapshots/{snapshotVersion}/manifest.json": {
      "get": {
        "summary": "Fetch an immutable snapshot manifest",
        "operationId": "getSnapshotManifest",
        "security": [{"partnerBearer": []}],
        "parameters": [{"$ref": "#/components/parameters/SnapshotVersion"}],
        "responses": {
          "200": {
            "description": "Snapshot manifest with payload checksums",
            "content": {"application/json": {"schema": {"$ref": "./manifest.schema.json"}}}
          },
          "304": {"description": "The immutable manifest is already cached"},
          "404": {"description": "Unknown snapshot version"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"}
        }
      }
    },
    "/v1/snapshots/{snapshotVersion}/upcoming-films.ndjson.gz": {
      "get": {
        "summary": "Download films with their current and future Madrid screenings",
        "operationId": "downloadUpcomingFilmSnapshot",
        "description": "Valid credentials receive a short-lived signed R2 redirect. Clients must not forward the partner Authorization header to the cross-host signed URL.",
        "security": [{"partnerBearer": []}],
        "parameters": [{"$ref": "#/components/parameters/SnapshotVersion"}],
        "responses": {
          "307": {
            "description": "Temporary redirect to a signed R2 download URL that expires after 60 seconds",
            "headers": {
              "Location": {"schema": {"type": "string", "format": "uri"}},
              "Cache-Control": {"schema": {"type": "string"}}
            }
          },
          "404": {"description": "Unknown snapshot version"},
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {"$ref": "#/components/responses/Forbidden"}
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "partnerBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "mfc_partner_v1",
        "description": "A revocable machine credential created at https://www.madridfilmcalendar.com/partners. Send it only in the Authorization header."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The machine credential is missing, malformed, unknown, revoked, or compromised.",
        "headers": {
          "WWW-Authenticate": {"schema": {"type": "string"}}
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["error"],
              "properties": {"error": {"const": "invalid_credentials"}}
            }
          }
        }
      },
      "Forbidden": {
        "description": "The credential is valid but its partner account is suspended.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": ["error"],
              "properties": {"error": {"const": "account_suspended"}}
            }
          }
        }
      }
    },
    "parameters": {
      "SnapshotVersion": {
        "name": "snapshotVersion",
        "in": "path",
        "required": true,
        "schema": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"}
      }
    }
  }
}