openapi.yaml

openapi: 3.1.0
info:
  title: HTMLTrust Directory API
  description: |
    Reference implementation of the HTMLTrust trust directory API. Provides endpoints
    for author management, content signing and verification, claims, and a federated
    trust directory with reputation tracking. The canonical v1 directory paths
    use RFC 9421 authentication for writes, negotiate the HTMLTrust JSON media
    types (with application/json as a compatibility representation), and use
    standard Cache-Control, ETag, and Vary headers on public reads.
  version: 1.0.0
  contact:
    name: HTMLTrust
    url: https://github.com/HTMLTrust/htmltrust-server-reference
    email: jason@jason-grey.com
  license:
    name: PolyForm Noncommercial License 1.0.0
    url: https://polyformproject.org/licenses/noncommercial/1.0.0/

servers:
  - url: /
    description: Same origin as the API document

tags:
  - name: Authors
    description: Operations related to author management and key pairs
  - name: Content
    description: Operations for signing and verifying content
  - name: Claims
    description: Operations for managing claim types and assertions
  - name: Directory
    description: Operations for the Network of Trust directory services
  - name: Keys
    description: Draft HTMLTrust key document lookup
  - name: Signers
    description: Draft signer reputation lookup
  - name: Endorsements
    description: |
      Operations for storing and retrieving third-party endorsements per
      HTMLTrust spec §2.5. Endorsements are standalone signed JSON blobs
      that attest a third party's opinion about a specific content hash.
      The directory is a passive store; verification is performed locally
      by the client.

security:
  - {} # No default security

components:
  securitySchemes:
    HttpSignatureInput:
      type: apiKey
      in: header
      name: Signature-Input
      description: |
        RFC 9421 signature metadata. Send this header together with the
        `Signature` header represented by `HttpMessageSignature`.
    HttpMessageSignature:
      type: apiKey
      in: header
      name: Signature
      description: |
        RFC 9421 HTTP Message Signature, the scheme draft §9.8 REQUIRES for
        POST endpoints: "POST endpoints MUST be authenticated using HTTP
        Message Signatures [RFC9421] with a key that the directory can resolve
        via Section 8."

        The request carries `Signature-Input` and `Signature` header fields.
        For the canonical v1 POST endpoints, `sig1` MUST cover exactly these
        components in this order: `@method`, `@target-uri`, `host`, `date`,
        and `content-digest` (RFC 9530). The
        `keyid` signature parameter is resolved per draft §8 (DID, HTTPS key
        document, or a directory `/keys/{id}` reference) and the signature is
        verified against that key, so the authenticated identity is the key
        itself rather than a shared secret.

        Example:

          Signature-Input: sig1=("@method" "@target-uri" "host" "date" \
            "content-digest");created=1770000000;keyid="https://directory.example/keys/k-abc123";alg="ed25519"
          Signature: sig1=:BASE64_ED25519_SIGNATURE:

        Failed verification returns 401 with a
        `WWW-Authenticate: Signature realm="htmltrust-directory"` challenge
        and an `application/problem+json` body.

    AuthorApiKey:
      type: apiKey
      in: header
      name: X-AUTHOR-API-KEY
      description: |
        Supplementary scheme. API key linked to a specific author, used by the
        directory's own convenience signing endpoint. It is a bearer secret,
        not a resolvable identity, and is refused when NODE_ENV=production
        unless HTMLTRUST_ALLOW_API_KEY_AUTH=1 is set.

    GeneralApiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: |
        Supplementary demo/admin scheme for submission endpoints. A shared
        secret proves nothing about who submitted a record, so it cannot carry
        the submitter identity the protocol depends on; prefer the paired
        HttpSignatureInput and HttpMessageSignature schemes. Refused when NODE_ENV=production unless
        HTMLTRUST_ALLOW_API_KEY_AUTH=1 is set.

    AdminApiKey:
      type: apiKey
      in: header
      name: X-ADMIN-API-KEY
      description: Admin-level API key for directory-operator operations

  schemas:
    Problem:
      type: object
      description: |
        RFC 9457 problem details, the error format draft §9.9 requires. Served
        as `application/problem+json`.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          description: URI identifying the problem type
        title:
          type: string
          description: Short human-readable summary of the problem type
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation specific to this occurrence
        contentHash:
          type: string
          description: Present on submission errors that concern a specific content hash
      example:
        type: "https://htmltrust.org/errors/signature-invalid"
        title: "Signature verification failed"
        status: 400
        detail: "The endorsement signature did not verify against the canonical JSON payload."

    Error:
      type: object
      description: |
        Legacy error envelope, still returned by endpoints outside the
        authentication, endorsement, and content paths. New code should expect
        `Problem`.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Additional error details
      example:
        code: "UNAUTHORIZED"
        message: "Invalid API key"

    Author:
      type: object
      required:
        - id
        - name
        - keyType
        - createdAt
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the author
        name:
          type: string
          description: Name of the author
        description:
          type: string
          description: Description of the author
        url:
          type: string
          format: uri
          description: URL associated with the author
        keyType:
          type: string
          enum: [HUMAN, AI, HUMAN_AI_MIX, ORGANIZATION]
          description: Type of the author key
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
      example:
        id: "123e4567-e89b-12d3-a456-426614174000"
        name: "John Doe"
        description: "Technology writer and researcher"
        url: "https://johndoe.example.com"
        keyType: "HUMAN"
        createdAt: "2023-01-01T12:00:00Z"
        updatedAt: "2023-01-01T12:00:00Z"

    PublicKey:
      type: object
      required:
        - id
        - authorId
        - key
        - algorithm
        - createdAt
      properties:
        id:
          type: string
          description: Opaque public identifier for the key document
          pattern: "^(k_[A-Za-z0-9_-]{20,64}|[0-9A-Fa-f]{24})$"
        authorId:
          type: string
          format: uuid
          description: ID of the author this key belongs to
        key:
          type: string
          description: Legacy public key in PEM format
        algorithm:
          type: string
          description: The cryptographic algorithm used
          enum: [RSA, ECDSA, ED25519, ed25519, ecdsa-p256, ecdsa-p384, rsa-pkcs1-sha256, rsa-pss-sha256]
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        expiresAt:
          type: string
          format: date-time
          description: Expiration timestamp (if applicable)
      example:
        id: "k_2Y7mB8xQ4nP6rT9vW3zA5cD7eF"
        authorId: "123e4567-e89b-12d3-a456-426614174000"
        key: "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----"
        algorithm: "RSA"
        createdAt: "2023-01-01T12:00:00Z"
        expiresAt: "2024-01-01T12:00:00Z"

    DirectoryDiscovery:
      type: object
      required: [directory, version, capabilities, supportedAlgorithms, supportedProfiles]
      properties:
        directory:
          type: string
          format: uri
        version:
          type: string
        capabilities:
          type: object
          required: [content, endorsements, keys, reputation]
          properties:
            content: { type: boolean }
            endorsements: { type: boolean }
            keys: { type: boolean }
            reputation: { type: boolean }
        supportedAlgorithms:
          type: object
          properties:
            signature:
              type: array
              items: { type: string }
            hash:
              type: array
              items: { type: string }
        supportedProfiles:
          type: array
          items: { type: string }

    KeyDocument:
      type: object
      required: [algorithm, publicKey, publicKeyEncoding]
      properties:
        kid:
          type: string
        algorithm:
          type: string
          enum: [ed25519, ecdsa-p256, ecdsa-p384, rsa-pss-sha256, rsa-pkcs1-sha256]
        publicKey:
          type: string
          description: Canonical unpadded standard Base64 SPKI DER public key bytes.
        publicKeyEncoding:
          enum: [spki-der]
          type: string
          description: Reference-server extension describing how publicKey was derived from the stored PEM.
        publicKeyPem:
          type: string
          description: Legacy PEM compatibility field.
        expires:
          type: string
          format: date-time
        revoked:
          type: boolean

    ContentRecord:
      type: object
      required: [contentHash, firstSeen, signers, endorsementCount]
      properties:
        contentHash:
          type: string
          description: Hash with algorithm prefix and canonical unpadded standard Base64 digest.
        firstSeen:
          type: string
          format: date-time
        signers:
          type: array
          items:
            type: object
            required: [profile, keyid, algorithm, signedAt, scope, location, signature]
            properties:
              profile:
                type: string
              keyid:
                type: string
              algorithm:
                type: string
              signedAt:
                type: string
                format: date-time
              scope:
                type: string
                enum: [url, origin]
              location:
                type: string
                format: uri
              signature:
                type: string
                description: Canonical unpadded standard Base64 signature.
        endorsementCount:
          type: integer

    ContentSubmission:
      type: object
      required: [profile, contentHash, keyid, algorithm, signedAt, scope, location, signature, sourceURL, claims]
      properties:
        profile:
          type: string
          enum: [htmltrust-signature-v1]
        contentHash:
          type: string
        keyid:
          type: string
        algorithm:
          type: string
          enum: [ed25519, ecdsa-p256, ecdsa-p384, rsa-pss-sha256, rsa-pkcs1-sha256]
        signedAt:
          type: string
          format: date-time
          pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
        scope:
          type: string
          enum: [url, origin]
        location:
          type: string
          format: uri
        signature:
          type: string
          description: Canonical unpadded standard Base64 signature.
        sourceURL:
          type: string
          format: uri
          pattern: "^[hH][tT][tT][pP][sS]://"
        claims:
          type: array
          items:
            type: object
            required: [name, content]
            additionalProperties: false
            properties:
              name: { type: string }
              content: { type: string }

    SignerReputation:
      type: object
      required: [keyid, score, asOf, components]
      properties:
        keyid:
          type: string
        score:
          type: number
          minimum: 0
          maximum: 1
        asOf:
          type: string
          format: date-time
        components:
          type: array
          items: { type: string }
        methodology:
          type: string
          format: uri

    Claim:
      type: object
      required:
        - id
        - name
        - description
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the claim type
        name:
          type: string
          description: Name of the claim type
        description:
          type: string
          description: Description of what this claim type represents
        possibleValues:
          type: array
          description: Possible values for this claim type (if applicable)
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
      example:
        id: "123e4567-e89b-12d3-a456-426614174002"
        name: "ContentType"
        description: "The type of content being signed"
        possibleValues: ["Article", "Image", "Video", "Audio", "Dataset"]
        createdAt: "2023-01-01T12:00:00Z"
        updatedAt: "2023-01-01T12:00:00Z"

    V1ContentSignature:
      type: object
      required:
        - profile
        - context
        - canonicalizationProfile
        - attributeProfile
        - urlProfile
        - contentHash
        - claimsHash
        - signedAt
        - scope
        - location
        - sourceURL
        - keyid
        - algorithm
        - signature
        - claims
      properties:
        profile:
          type: string
          enum: [htmltrust-signature-v1]
        context:
          type: string
          format: uri
        canonicalizationProfile:
          type: string
          enum: [htmltrust-c14n-v1]
        attributeProfile:
          type: string
          enum: [htmltrust-attrs-v1]
        urlProfile:
          type: string
          enum: [htmltrust-safe-url-v1]
        contentHash:
          type: string
          description: Hash of the canonical signed content
        claimsHash:
          type: string
          description: Directory-computed hash of the canonical v1 claims serialization
        signedAt:
          type: string
          description: Exact UTC timestamp in YYYY-MM-DDTHH:MM:SSZ form
          pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"
        scope:
          type: string
          enum: [url, origin]
        location:
          type: string
          format: uri
          description: URL or origin derived from sourceURL under scope
        sourceURL:
          type: string
          format: uri
          description: Final HTTPS occurrence URL
          pattern: "^[hH][tT][tT][pP][sS]://"
        keyid:
          type: string
          description: Exact directory key identifier bound into the JCS payload
        algorithm:
          type: string
          description: Canonical signature algorithm identifier
        signature:
          type: string
          description: Signature over the RFC 8785 JCS v1 signing payload
        claims:
          type: array
          items:
            type: object
            required: [name, content]
            additionalProperties: false
            properties:
              name: { type: string }
              content: { type: string }
        authorId:
          type: string
          description: Directory author that owns the signing key
        domain:
          type: string
          format: uri
          description: Occurrence origin retained for compatibility and indexing
        createdAt:
          type: string
          format: date-time

    ContentSignature:
      type: object
      required:
        - contentHash
        - claimsHash
        - signedAt
        - domain
        - authorId
        - keyid
        - algorithm
        - signature
        - claims
      properties:
        contentHash:
          type: string
          description: Hash of the normalized content using canonical unpadded standard Base64
        claimsHash:
          type: string
          description: Hash of all direct child meta claims using the same hash algorithm as contentHash
        signedAt:
          type: string
          description: UTC RFC3339 timestamp from the direct child signed-at claim
        domain:
          type: string
          description: Serialized Web origin associated with the content; bare hostnames are invalid
        authorId:
          type: string
          format: uuid
          description: ID of the author who signed the content
        keyid:
          type: string
          description: Resolvable identifier for the signing key
        algorithm:
          type: string
          description: Signature algorithm identifier from the registry
        signature:
          type: string
          description: Canonical unpadded standard Base64 signature over contentHash:claimsHash:domain:signedAt
        claims:
          type: object
          description: Claims about the content
          additionalProperties: true
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
      example:
        contentHash: "sha256:RAyBCvKTW5KNnGZSyXZYe+8V8DEEnUMRxjk5LSgCHo4"
        claimsHash: "sha256:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU"
        signedAt: "2026-05-01T10:30:00Z"
        domain: "https://example.com"
        authorId: "123e4567-e89b-12d3-a456-426614174000"
        keyid: "https://directory.example/keys/k_2Y7mB8xQ4nP6rT9vW3zA5cD7eF"
        algorithm: "ed25519"
        signature: "MEUCIQD7y5SxmQJ9f0lE9B0BwqIJKKdL5fZMNQOiPnKWUJfmrgIgEbHtPwDxM9xGbCZzW9k2R9jFxwJZQQlPfhgj+0YP7vQ="
        claims:
          ContentType: "Article"
          License: "CC-BY-4.0"
          AIAssistance: "Minimal"
        createdAt: "2023-01-01T12:00:00Z"

    KeyReputation:
      type: object
      required:
        - keyId
        - trustScore
        - verifiedSignatures
      properties:
        keyId:
          type: string
          description: Opaque public key id, or a legacy ObjectId accepted by the compatibility route
        trustScore:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Trust score between 0 and 1
        verifiedSignatures:
          type: integer
          description: Number of verified signatures using this key
        reports:
          type: integer
          description: Number of reports against this key
        lastUpdated:
          type: string
          format: date-time
          description: Last update timestamp
      example:
        keyId: "k_2Y7mB8xQ4nP6rT9vW3zA5cD7eF"
        trustScore: 0.95
        verifiedSignatures: 1250
        reports: 2
        lastUpdated: "2023-01-01T12:00:00Z"

    ContentOccurrence:
      type: object
      required:
        - url
        - domain
        - firstSeen
      properties:
        url:
          type: string
          format: uri
          description: URL where the content was found
        domain:
          type: string
          description: Domain where the content was found
        firstSeen:
          type: string
          format: date-time
          description: When the content was first seen at this location
        lastSeen:
          type: string
          format: date-time
          description: When the content was last seen at this location
        authorId:
          type: string
          format: uuid
          description: ID of the author who signed the content at this location (if any)
        signatureValid:
          type: boolean
          description: Whether the signature at this location is valid
      example:
        url: "https://example.com/article/123"
        domain: "example.com"
        firstSeen: "2023-01-01T12:00:00Z"
        lastSeen: "2023-01-02T12:00:00Z"
        authorId: "123e4567-e89b-12d3-a456-426614174000"
        signatureValid: true

    Endorsement:
      type: object
      description: |
        A standalone signed endorsement document per draft §10.1.

        The directory verifies the endorser's signature over
        JCS(document minus `signature`) before storing it (§9.7), and serves
        every submitted member without adding fields of its own. Section 10.1
        requires unrecognised members to be preserved and
        included in the signed payload, so an injected `_id`, `createdAt`, or
        `contentHash` alias would invalidate the endorser's signature for
        anyone who recomputes it. The server-assigned identifier is returned
        in the `Location` header of the 201 response instead.

        Additional members not listed here MAY be present and are preserved.
      required:
        - endorser
        - endorsement
        - algorithm
        - signature
        - timestamp
      properties:
        endorser:
          type: string
          description: Endorser keyid, resolvable per draft §8 (e.g. "did:web:publisher.org")
        endorsement:
          type: string
          description: Content hash being endorsed, including algorithm prefix
        signature:
          type: string
          description: Canonical unpadded standard Base64 signature over JCS(document with signature omitted)
        timestamp:
          type: string
          description: RFC 3339 UTC timestamp at which the endorsement was issued
        algorithm:
          type: string
          description: Signature algorithm identifier from draft §7.1
        claim:
          type: string
          description: Free-text human-readable rationale for the endorsement
        expires:
          type: string
          description: RFC 3339 UTC timestamp after which the endorsement is no longer valid
        revokedBy:
          type: string
          description: Content hash of the document that supersedes this one
        contentHash:
          type: string
          deprecated: true
          description: |
            Legacy alias for `endorsement`. Only present on documents stored
            before the directory began serving submissions verbatim; new
            submissions are served exactly as signed.
      example:
        endorser: "did:web:publisher.org"
        endorsement: "sha256:RAyBCvKTW5KNnGZSyXZYe+8V8DEEnUMRxjk5LSgCHo4"
        signature: "BASE64_SIG"
        timestamp: "2025-05-01T00:00:00Z"
        algorithm: "ed25519"

paths:
  /.well-known/htmltrust:
    get:
      tags:
        - Directory
      summary: Discover trust directory capabilities
      operationId: discoverDirectory
      responses:
        "200":
          description: Directory discovery document
          headers:
            Cache-Control:
              schema: { type: string }
            ETag:
              schema: { type: string }
            Vary:
              schema: { type: string }
          content:
            application/htmltrust-directory+json:
              schema:
                $ref: "#/components/schemas/DirectoryDiscovery"
            application/json:
              schema:
                $ref: "#/components/schemas/DirectoryDiscovery"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /keys/{id}:
    get:
      tags:
        - Keys
      summary: Retrieve a draft HTMLTrust key document
      operationId: getKeyDocument
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            pattern: "^(k_[A-Za-z0-9_-]{20,64}|[0-9A-Fa-f]{24})$"
      responses:
        "200":
          description: Key document
          headers:
            Cache-Control:
              schema: { type: string }
            ETag:
              schema: { type: string }
            Vary:
              schema: { type: string }
          content:
            application/htmltrust-key+json:
              schema:
                $ref: "#/components/schemas/KeyDocument"
            application/json:
              schema:
                $ref: "#/components/schemas/KeyDocument"
        "404":
          description: Key not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "400":
          description: Invalid key identifier
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Directory could not read the key document
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /signers/{id}/reputation:
    get:
      tags:
        - Signers
      summary: Retrieve directory-computed signer reputation
      operationId: getSignerReputation
      parameters:
        - name: id
          in: path
          required: true
          description: Directory key id, author id, or percent-encoded keyid.
          schema:
            type: string
      responses:
        "200":
          description: Signer reputation
          headers:
            Cache-Control:
              schema: { type: string }
            ETag:
              schema: { type: string }
            Vary:
              schema: { type: string }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SignerReputation"
        "404":
          description: Signer not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "400":
          description: Invalid signer identifier
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Directory could not read signer reputation
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /content:
    post:
      tags:
        - Content
      summary: Submit a signed content occurrence for indexing
      description: |
        Canonical HTMLTrust v1 directory submission endpoint. The directory
        recomputes the claims hash from the complete `claims` array and
        re-verifies the v1 JCS signing payload. `location` must be derived
        from `sourceURL` according to `scope`; callers cannot submit a
        precomputed `claimsHash`.
      operationId: submitContent
      security:
        - HttpSignatureInput: []
          HttpMessageSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContentSubmission"
          application/htmltrust-content+json:
            schema:
              $ref: "#/components/schemas/ContentSubmission"
      responses:
        "201":
          description: Content record created
          headers:
            Cache-Control:
              schema: { type: string }
            Location:
              schema: { type: string }
          content:
            application/htmltrust-content+json:
              schema:
                $ref: "#/components/schemas/ContentRecord"
            application/json:
              schema:
                $ref: "#/components/schemas/ContentRecord"
        "400":
          description: Invalid submission
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Missing or invalid HTTP Message Signature
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "415":
          description: Request body media type is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Verified content could not be stored
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /content/{hash}:
    get:
      tags:
        - Content
      summary: Retrieve a draft content record by content hash
      operationId: getContentRecord
      parameters:
        - name: hash
          in: path
          required: true
          description: Percent-encoded content hash including algorithm prefix.
          schema:
            type: string
      responses:
        "200":
          description: Content record
          headers:
            Cache-Control:
              schema: { type: string }
            ETag:
              schema: { type: string }
            Vary:
              schema: { type: string }
          content:
            application/htmltrust-content+json:
              schema:
                $ref: "#/components/schemas/ContentRecord"
            application/json:
              schema:
                $ref: "#/components/schemas/ContentRecord"
        "404":
          description: Content not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "400":
          description: Invalid content hash
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Directory could not read the content record
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /content/{hash}/endorsements:
    get:
      tags:
        - Endorsements
      summary: List draft structured endorsements for a content hash
      operationId: listContentEndorsements
      parameters:
        - name: hash
          in: path
          required: true
          description: Percent-encoded content hash including algorithm prefix.
          schema:
            type: string
      responses:
        "200":
          description: Structured endorsement documents
          headers:
            Cache-Control:
              schema: { type: string }
            ETag:
              schema: { type: string }
            Vary:
              schema: { type: string }
          content:
            application/htmltrust-endorsement+json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Endorsement"
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Endorsement"
        "400":
          description: Invalid content hash
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Directory could not read endorsements
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /api/authors:
    post:
      tags:
        - Authors
      summary: Create a new author and key pair
      description: |
        Creates a new author profile. If `publicKey` is supplied, the
        directory registers that key and never holds the private half; the
        author signs its own content and submits it to POST /content.
        Otherwise the directory acts as the convenience registry of draft §9.6
        and generates the key pair itself, in which case the private key is
        stored and never exposed.
      operationId: createAuthor
      security:
        - GeneralApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - keyType
              properties:
                name:
                  type: string
                  description: Name of the author
                description:
                  type: string
                  description: Description of the author
                url:
                  type: string
                  format: uri
                  description: URL associated with the author
                keyType:
                  type: string
                  enum: [HUMAN, AI, HUMAN_AI_MIX, ORGANIZATION]
                  description: Type of the author key
                keyAlgorithm:
                  type: string
                  enum: [RSA, ECDSA, ED25519, ed25519, ecdsa-p256, ecdsa-p384, rsa-pkcs1-sha256, rsa-pss-sha256]
                  default: RSA
                  description: The cryptographic algorithm to use for the key pair
                publicKey:
                  type: string
                  description: |
                    Optional SPKI PEM public key the author already holds.
                    When present the directory stores no private key for this
                    author, so POST /content/sign is unavailable to it and the
                    author signs locally instead.
      responses:
        "201":
          description: Author created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  author:
                    $ref: "#/components/schemas/Author"
                  authorApiKey:
                    type: string
                    description: API key for author-specific operations (only returned once at creation)
        "400":
          description: Invalid input
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      tags:
        - Authors
      summary: List authors
      description: Returns a list of authors with optional filtering
      operationId: listAuthors
      security:
        - GeneralApiKey: []
      parameters:
        - name: name
          in: query
          description: Filter by author name
          schema:
            type: string
        - name: keyType
          in: query
          description: Filter by key type
          schema:
            type: string
            enum: [HUMAN, AI, HUMAN_AI_MIX, ORGANIZATION]
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: List of authors
          content:
            application/json:
              schema:
                type: object
                properties:
                  authors:
                    type: array
                    items:
                      $ref: "#/components/schemas/Author"
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      pages:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/authors/{authorId}:
    get:
      tags:
        - Authors
      summary: Get author details
      description: Returns details about a specific author
      operationId: getAuthor
      parameters:
        - name: authorId
          in: path
          required: true
          description: ID of the author
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Author details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Author"
        "404":
          description: Author not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      tags:
        - Authors
      summary: Update author details
      description: Updates details for a specific author
      operationId: updateAuthor
      security:
        - AuthorApiKey: []
      parameters:
        - name: authorId
          in: path
          required: true
          description: ID of the author
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the author
                description:
                  type: string
                  description: Description of the author
                url:
                  type: string
                  format: uri
                  description: URL associated with the author
      responses:
        "200":
          description: Author updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Author"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden - API key does not match author
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Author not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      tags:
        - Authors
      summary: Delete an author
      description: Deletes an author and associated keys
      operationId: deleteAuthor
      security:
        - AuthorApiKey: []
      parameters:
        - name: authorId
          in: path
          required: true
          description: ID of the author
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Author deleted successfully
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Forbidden - API key does not match author
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Author not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/authors/{authorId}/public-key:
    get:
      tags:
        - Authors
      summary: Get author's public key
      description: Returns the public key for a specific author
      operationId: getAuthorPublicKey
      parameters:
        - name: authorId
          in: path
          required: true
          description: ID of the author
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Author's public key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicKey"
        "404":
          description: Author or public key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/content/sign:
    post:
      tags:
        - Content
      summary: Sign content
      description: |
        Author-authenticated convenience signer for the frozen
        `htmltrust-signature-v1` profile. The directory selects the
        authenticated author's directory-held key, derives `location` from
        the final HTTPS `sourceURL` and `scope`, computes `claimsHash` from
        the strict v1 claims array, and signs the RFC 8785 JSON payload. The
        caller must not submit `claimsHash` or the legacy `domain` field.
      operationId: signContent
      security:
        - AuthorApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contentHash
                - sourceURL
                - scope
                - signedAt
                - claims
              properties:
                contentHash:
                  type: string
                  description: Hash of the normalized content using canonical unpadded standard Base64
                sourceURL:
                  type: string
                  format: uri
                  description: Final HTTPS response URL where the signed section will be published
                scope:
                  type: string
                  enum: [url, origin]
                  description: Location binding scope used to derive the signed location
                signedAt:
                  type: string
                  description: Exact UTC timestamp in YYYY-MM-DDTHH:MM:SSZ form, also present in claims
                claims:
                  type: array
                  description: Strict v1 claim records. Include exactly one signed-at record.
                  items:
                    type: object
                    required: [name, content]
                    additionalProperties: false
                    properties:
                      name: { type: string }
                      content: { type: string }
      responses:
        "201":
          description: Content signed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/V1ContentSignature"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: No active directory-held signing key exists for the author
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /api/content/verify:
    post:
      tags:
        - Content
      summary: Verify content signature (DEPRECATED)
      description: |
        DEPRECATED: cryptographic verification is a local operation per
        HTMLTrust spec §3.1. This endpoint is retained as a low-trust
        convenience and will be removed in a future major version. Clients
        MUST verify signatures locally (e.g. via SubtleCrypto). Responses
        include the `Deprecation: true` header per RFC 9745.
      deprecated: true
      operationId: verifyContent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contentHash
                - claimsHash
                - domain
                - signedAt
                - authorId
                - signature
              properties:
                contentHash:
                  type: string
                  description: Hash of the normalized content using canonical unpadded standard Base64
                claimsHash:
                  type: string
                  description: Hash of all direct child meta claims
                domain:
                  type: string
                  description: Serialized Web origin associated with the content; bare hostnames are invalid
                signedAt:
                  type: string
                  format: date-time
                authorId:
                  type: string
                  format: uuid
                  description: ID of the author who signed the content
                signature:
                  type: string
                  description: Cryptographic signature to verify
      responses:
        "200":
          description: Verification result
          content:
            application/json:
              schema:
                type: object
                required:
                  - valid
                properties:
                  valid:
                    type: boolean
                    description: Whether the signature is valid
                  author:
                    $ref: "#/components/schemas/Author"
                  claims:
                    type: object
                    description: Claims included in the signature
                    additionalProperties: true
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/claims:
    post:
      tags:
        - Claims
      summary: Create a new claim type
      description: Creates a new claim type definition
      operationId: createClaimType
      security:
        - AdminApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - description
              properties:
                name:
                  type: string
                  description: Name of the claim type
                description:
                  type: string
                  description: Description of what this claim type represents
                possibleValues:
                  type: array
                  description: Possible values for this claim type (if applicable)
                  items:
                    type: string
      responses:
        "201":
          description: Claim type created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claim"
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    get:
      tags:
        - Claims
      summary: List claim types
      description: Returns a list of claim types
      operationId: listClaimTypes
      parameters:
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: List of claim types
          content:
            application/json:
              schema:
                type: object
                properties:
                  claims:
                    type: array
                    items:
                      $ref: "#/components/schemas/Claim"
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      pages:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer
        "429":
          description: Request rate limit exceeded
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /api/claims/{claimId}:
    get:
      tags:
        - Claims
      summary: Get claim type details
      description: Returns details about a specific claim type
      operationId: getClaimType
      parameters:
        - name: claimId
          in: path
          required: true
          description: ID of the claim type
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Claim type details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Claim"
        "404":
          description: Claim type not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/directory/keys:
    get:
      tags:
        - Directory
      summary: Search public keys
      description: Searches for public keys in the directory
      operationId: searchPublicKeys
      parameters:
        - name: authorName
          in: query
          description: Filter by author name
          schema:
            type: string
        - name: keyType
          in: query
          description: Filter by key type
          schema:
            type: string
            enum: [HUMAN, AI, HUMAN_AI_MIX, ORGANIZATION]
        - name: domain
          in: query
          description: Filter by domain associated with the author
          schema:
            type: string
        - name: minTrustScore
          in: query
          description: Minimum trust score
          schema:
            type: number
            format: float
            minimum: 0
            maximum: 1
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: List of public keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/PublicKey"
                        - type: object
                          properties:
                            author:
                              $ref: "#/components/schemas/Author"
                            trustScore:
                              type: number
                              format: float
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      pages:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer
        "429":
          description: Request rate limit exceeded
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /api/directory/keys/{keyId}/reputation:
    get:
      tags:
        - Directory
      summary: Get key reputation
      description: Returns reputation information for a specific key
      operationId: getKeyReputation
      parameters:
        - name: keyId
          in: path
          required: true
          description: Opaque public key id, or a legacy ObjectId accepted by the compatibility route.
          schema:
            type: string
            pattern: "^(k_[A-Za-z0-9_-]{20,64}|[0-9A-Fa-f]{24})$"
      responses:
        "200":
          description: Key reputation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KeyReputation"
        "404":
          description: Key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/directory/keys/{keyId}/report:
    post:
      tags:
        - Directory
      summary: Report a key
      description: Reports a key for suspicious or malicious activity
      operationId: reportKey
      security:
        - GeneralApiKey: []
      parameters:
        - name: keyId
          in: path
          required: true
          description: Opaque public key id, or a legacy ObjectId accepted by the compatibility route.
          schema:
            type: string
            pattern: "^(k_[A-Za-z0-9_-]{20,64}|[0-9A-Fa-f]{24})$"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - reason
              properties:
                reason:
                  type: string
                  enum: [IMPERSONATION, MISINFORMATION, SPAM, OTHER]
                  description: Reason for reporting
                details:
                  type: string
                  description: Additional details about the report
                evidence:
                  type: string
                  format: uri
                  description: URL to evidence supporting the report
      responses:
        "201":
          description: Report submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  reportId:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum: [PENDING, UNDER_REVIEW, ACCEPTED, REJECTED]
                    default: PENDING
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Key not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/directory/content:
    get:
      tags:
        - Directory
      summary: Search signed content
      description: Searches for signed content in the directory
      operationId: searchSignedContent
      parameters:
        - name: contentHash
          in: query
          description: Filter by content hash
          schema:
            type: string
        - name: authorId
          in: query
          description: Filter by author ID
          schema:
            type: string
            format: uuid
        - name: domain
          in: query
          description: Filter by domain
          schema:
            type: string
        - name: claim
          in: query
          description: "Filter by claim (format: claimName:claimValue)"
          schema:
            type: string
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: List of signed content
          content:
            application/json:
              schema:
                type: object
                properties:
                  signatures:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/ContentSignature"
                        - type: object
                          properties:
                            author:
                              $ref: "#/components/schemas/Author"
                            occurrences:
                              type: integer
                              description: Number of occurrences of this content
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      pages:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer
        "429":
          description: Request rate limit exceeded
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /api/directory/content/{contentHash}/occurrences:
    get:
      tags:
        - Directory
      summary: Find content occurrences
      description: Returns occurrences of a specific content hash across domains
      operationId: findContentOccurrences
      parameters:
        - name: contentHash
          in: path
          required: true
          description: Hash of the content
          schema:
            type: string
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          description: Number of items per page
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        "200":
          description: List of content occurrences
          content:
            application/json:
              schema:
                type: object
                properties:
                  occurrences:
                    type: array
                    items:
                      $ref: "#/components/schemas/ContentOccurrence"
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      pages:
                        type: integer
                      page:
                        type: integer
                      limit:
                        type: integer
        "404":
          description: Content hash not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/directory/content/report:
    post:
      tags:
        - Directory
      summary: Report content misuse
      description: Reports content for misuse, theft, or other issues
      operationId: reportContentMisuse
      security:
        - GeneralApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contentHash
                - sourceUrl
                - targetUrl
                - reason
              properties:
                contentHash:
                  type: string
                  description: Hash of the content being reported
                sourceUrl:
                  type: string
                  format: uri
                  description: Original source URL of the content
                targetUrl:
                  type: string
                  format: uri
                  description: URL where the content is being misused
                reason:
                  type: string
                  enum:
                    [
                      COPYRIGHT_VIOLATION,
                      UNAUTHORIZED_USE,
                      IMPERSONATION,
                      OTHER,
                    ]
                  description: Reason for reporting
                details:
                  type: string
                  description: Additional details about the report
      responses:
        "201":
          description: Report submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  reportId:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum: [PENDING, UNDER_REVIEW, ACCEPTED, REJECTED]
                    default: PENDING
        "400":
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Content hash not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/endorsements:
    get:
      tags:
        - Endorsements
      summary: List endorsements for a content hash (compatibility)
      description: |
        Returns all endorsements on file for a given content hash. This
        legacy `/api` route is public and remains available for pre-v1
        clients. Clients MUST verify each endorsement locally.
      operationId: listEndorsementsCompatibility
      parameters:
        - name: content-hash
          in: query
          required: true
          description: The content hash to look up endorsements for (for example, `sha256:...`).
          schema:
            type: string
      responses:
        "200":
          description: Array of endorsements
          headers:
            Cache-Control:
              schema: { type: string }
            ETag:
              schema: { type: string }
            Vary:
              schema: { type: string }
          content:
            application/htmltrust-endorsement+json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Endorsement"
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Endorsement"
        "400":
          description: Invalid input
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Directory could not read endorsements
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
    post:
      tags:
        - Endorsements
      summary: Submit a signed endorsement for storage
      description: |
        Stores a structured endorsement document. The signed payload is the
        JSON canonicalization of the endorsement document with `signature`
        omitted. The compatibility route accepts either the RFC 9421
        signature or the legacy general API key scheme.
      operationId: createEndorsement
      security:
        - HttpSignatureInput: []
          HttpMessageSignature: []
        - GeneralApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Endorsement"
          application/htmltrust-endorsement+json:
            schema:
              $ref: "#/components/schemas/Endorsement"
      responses:
        "201":
          description: Endorsement stored
          headers:
            Cache-Control:
              schema: { type: string }
            Location:
              schema: { type: string }
          content:
            application/htmltrust-endorsement+json:
              schema:
                $ref: "#/components/schemas/Endorsement"
            application/json:
              schema:
                $ref: "#/components/schemas/Endorsement"
        "400":
          description: Invalid input
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "415":
          description: Request body media type is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Verified endorsement could not be stored
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /api/endorsements/{id}:
    delete:
      tags:
        - Endorsements
      summary: Delete an endorsement (compatibility)
      description: |
        Removes an endorsement from the legacy `/api` surface. The route
        accepts an RFC 9421 signature from the endorser or an administrator
        API key. The route's controller also checks that a signed caller is
        the endorser before deleting the record.
      operationId: deleteEndorsementCompatibility
      security:
        - HttpSignatureInput: []
          HttpMessageSignature: []
        - AdminApiKey: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Endorsement deleted
        "400":
          description: Invalid endorsement identifier or request
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "403":
          description: The authenticated key is not the endorser
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "404":
          description: Endorsement not found
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Directory could not delete the endorsement
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"

  /endorsements:
    post:
      tags:
        - Endorsements
      summary: Submit a signed endorsement for storage
      description: |
        Stores a structured endorsement document. The signed payload is the
        JSON canonicalization of the endorsement document with `signature`
        omitted. The canonical endpoint requires the exact RFC 9421 HTMLTrust
        v1 signature profile and has no API-key fallback.
      operationId: createCanonicalEndorsement
      security:
        - HttpSignatureInput: []
          HttpMessageSignature: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Endorsement"
          application/htmltrust-endorsement+json:
            schema:
              $ref: "#/components/schemas/Endorsement"
      responses:
        "201":
          description: Endorsement stored
          headers:
            Cache-Control:
              schema: { type: string }
            Location:
              schema: { type: string }
          content:
            application/htmltrust-endorsement+json:
              schema:
                $ref: "#/components/schemas/Endorsement"
            application/json:
              schema:
                $ref: "#/components/schemas/Endorsement"
        "400":
          description: Invalid input
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "401":
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "406":
          description: Requested representation is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "415":
          description: Request body media type is not supported
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"
        "500":
          description: Verified endorsement could not be stored
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/Problem"