{
  "openapi": "3.1.0",
  "info": {
    "title": "Shoalrun content REST API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "/content/v1"
    }
  ],
  "paths": {
    "/resources/{key}/representations/{format}": {
      "head": {
        "summary": "Read HTML or Markdown headers",
        "description": "Query parameters are single-valued; unknown or duplicate parameters are rejected. Publication and revision checks run before conditional ETag checks. No pagination, search, writes, authentication, or cross-origin policy is supplied by this reference adapter. HEAD returns the GET status and headers without a response body.",
        "operationId": "getContentRepresentationHead",
        "parameters": [
          {
            "$ref": "#/components/parameters/channel"
          },
          {
            "$ref": "#/components/parameters/version"
          },
          {
            "$ref": "#/components/parameters/language"
          },
          {
            "$ref": "#/components/parameters/revision"
          },
          {
            "$ref": "#/components/parameters/key"
          },
          {
            "$ref": "#/components/parameters/format"
          },
          {
            "$ref": "#/components/parameters/ifNoneMatch"
          }
        ],
        "responses": {
          "200": {
            "description": "The selected resource or inventory.",
            "headers": {
              "ETag": {
                "description": "Strong SHA-256 validator of the exact UTF-8 response bytes.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "Unpinned discovery uses no-cache. Revision-pinned success uses public, max-age=31536000, immutable. Errors use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "The validated selected response matches If-None-Match. No response body.",
            "headers": {
              "ETag": {
                "description": "Strong SHA-256 validator of the exact UTF-8 response bytes.",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "Unpinned discovery uses no-cache. Revision-pinned success uses public, max-age=31536000, immutable. Errors use no-store.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "invalid_request: missing, duplicate, unknown, or malformed query parameter.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            }
          },
          "404": {
            "description": "not_found: unknown publication, resource, or route.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed: only GET and HEAD are supported; Allow lists both.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              },
              "Allow": {
                "schema": {
                  "const": "GET, HEAD"
                }
              }
            }
          },
          "406": {
            "description": "unsupported_format: unsupported or unavailable representation format.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            }
          },
          "409": {
            "description": "stale_revision: revision unavailable, or source bytes no longer match the pinned snapshot.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            }
          },
          "500": {
            "description": "internal_error: the source could not complete the request.",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "no-store"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "channel": {
        "name": "channel",
        "in": "query",
        "required": true,
        "description": "Exact publication channel. No default or fallback.",
        "example": "production",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2048
        }
      },
      "format": {
        "name": "format",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "enum": [
            "html",
            "markdown"
          ]
        },
        "example": "markdown"
      },
      "ifNoneMatch": {
        "name": "If-None-Match",
        "in": "header",
        "required": false,
        "description": "An ETag, comma-separated ETags, or *. Weak comparison is supported for GET and HEAD.",
        "schema": {
          "type": "string"
        }
      },
      "key": {
        "name": "key",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/ResourceKey"
        },
        "example": "k_WyJwYWdlIiwiZ3VpZGUuYmlsbGluZyJd"
      },
      "language": {
        "name": "language",
        "in": "query",
        "required": true,
        "description": "Exact publication language. No default or fallback.",
        "example": "en",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2048
        }
      },
      "revision": {
        "name": "revision",
        "in": "query",
        "required": true,
        "description": "Exact revision returned by the list endpoint. A different revision returns 409; it never silently reads newer content.",
        "schema": {
          "$ref": "#/components/schemas/digest"
        },
        "example": "0770e6d70db51967fac8dcc7bb4ff5a5bff87378eb2e2bbb63dea93d090c82e8"
      },
      "version": {
        "name": "version",
        "in": "query",
        "required": true,
        "description": "Exact publication version. No default or fallback.",
        "example": "current",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2048
        }
      }
    },
    "schemas": {
      "digest": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$"
      },
      "ResourceKey": {
        "type": "string",
        "pattern": "^k_[A-Za-z0-9_-]+$",
        "description": "Opaque stable typed-reference key. Use the returned key. It is k_ followed by unpadded base64url of UTF-8 JSON for [\"page\",documentId], [\"section\",documentId,sectionId], or [\"snippet\",id]. Publication and revision are separate selectors."
      }
    }
  }
}