{
  "openapi": "3.1.0",
  "info": {
    "title": "Tokimi Timestamp PQ-v2",
    "version": "0.2.0",
    "description": "ML-DSA-87 signatures and SHA-512 across target digests, private commitments, Merkle nodes, signed-head preimages, archives and public key pins. Original files, digest and salt stay local. Operator clock; independent existence upper bounds unavailable. drand is not in this profile. Legacy v1 history is read-only. Read-only evidence endpoints for an optional Bitcoin block witness exist; the independent existence upper bound stays unavailable until the operator enables witnessing."
  },
  "servers": [
    {
      "url": "https://tokimi.space/api/timestamps/v1"
    }
  ],
  "paths": {
    "/pq/v2/health": {
      "get": {
        "summary": "API capability status",
        "responses": {
          "200": {
            "description": "API version and evidence boundary; not a guarantee that signing is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "independent_upper_bound": {
                      "enum": [
                        "unavailable",
                        "bitcoin_witness"
                      ],
                      "description": "bitcoin_witness while the operator has witnessing enabled, unavailable otherwise; GET /pq/v2/log/witness is the authoritative view. This describes the service. It verifies nothing about a receipt: a receiver checks evidence locally against a block header they obtained themselves."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/requests": {
      "post": {
        "summary": "Durably admit a commitment",
        "security": [
          {
            "TimestampKey": []
          }
        ],
        "description": "Stable admission gateway. Explicit commit/2 profile required. Save the 64-byte salt and Idempotency-Key locally before submission. A 202 is not signed inclusion; follow the Location header into the PQ-v2 read namespace. Legacy single-field/64-hex requests return 410 when authenticated with a v2 credential. No downgrade.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "profile",
                  "commitment"
                ],
                "properties": {
                  "commitment": {
                    "$ref": "#/components/schemas/Hex64"
                  },
                  "profile": {
                    "const": "tokimi-timestamp/commit/2"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Previously completed idempotent request; receipt is published",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Admission"
                }
              }
            }
          },
          "202": {
            "description": "Durable admission awaiting signed and archived inclusion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Admission"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "Same client/key was used with a different commitment"
          },
          "410": {
            "description": "Legacy profile retired; never retry by weakening the algorithm."
          },
          "413": {
            "description": "Body exceeds 1024 bytes"
          },
          "415": {
            "description": "application/json required"
          },
          "429": {
            "description": "Admission quota reached"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/pq/v2/requests/{id}": {
      "get": {
        "summary": "Retrieve the authenticated client's operation",
        "security": [
          {
            "TimestampKey": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Pending or complete",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Admission"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Unknown operation or different owner"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/pq/v2/receipts/{index}": {
      "get": {
        "summary": "Public receipt with stable original inclusion head",
        "parameters": [
          {
            "$ref": "#/components/parameters/Index"
          }
        ],
        "responses": {
          "200": {
            "description": "Signed inclusion receipt; no independent upper bound",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "404": {
            "description": "Not published"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/pq/v2/receipts/{index}/evidence": {
      "get": {
        "summary": "External evidence for a receipt",
        "description": "Optional, additive evidence object; the receipt and its bytes are unchanged. Head selection: let s be the receipt's original inclusion tree size; the smallest attested tree_size t >= s that has a bitcoin attestation, otherwise the smallest t >= s with a pending attestation, otherwise 404. Every attestation of the chosen head is returned, whatever its status. The API verifies nothing: check the object offline with verifyEvidence from /timestamp/verifier.mjs, with your own key pin and a block header you obtained yourself. A pending attestation establishes no upper bound. A response made only of bitcoin attestations may be cached (cache-control: public, max-age=3600); every other response is no-store. Query strings are rejected.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Index"
          }
        ],
        "responses": {
          "200": {
            "description": "Evidence object for the receipt's covering attested head",
            "headers": {
              "Cache-Control": {
                "description": "public, max-age=3600 when every attestation is bitcoin; otherwise no-store",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Evidence"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "description": "No attested head covers the receipt (witnessing disabled, nothing attested yet, or no such receipt)"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/pq/v2/log/keys": {
      "get": {
        "summary": "Advertised public key and log metadata",
        "description": "A key fetched here is not an independently selected receiver trust pin.",
        "responses": {
          "200": {
            "description": "Log identity, key, tree size and operator-clock boundary",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "independent_upper_bound": {
                      "enum": [
                        "unavailable",
                        "bitcoin_witness"
                      ],
                      "description": "bitcoin_witness while the operator has witnessing enabled, unavailable otherwise; GET /pq/v2/log/witness is the authoritative view. This describes the service. It verifies nothing about a receipt: a receiver checks evidence locally against a block header they obtained themselves."
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/pq/v2/log/sth": {
      "get": {
        "summary": "Latest published signed tree head",
        "responses": {
          "200": {
            "description": "Published head",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SignedTreeHead"
                }
              }
            }
          },
          "404": {
            "description": "No published head"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/pq/v2/log/sth/{size}": {
      "get": {
        "summary": "Historical published signed tree head",
        "parameters": [
          {
            "name": "size",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published head"
          },
          "404": {
            "description": "No published head at that size"
          }
        }
      }
    },
    "/pq/v2/log/entries": {
      "get": {
        "summary": "Public entries in [start,end), at most 100",
        "parameters": [
          {
            "name": "start",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published commitments and operator registration times; no private target/salt/owner mapping"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/pq/v2/log/proof/inclusion": {
      "get": {
        "summary": "SHA-512 tree inclusion path against an exact published prefix",
        "parameters": [
          {
            "name": "log_index",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "tree_size",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Path plus exact index and size; receiver supplies a valid matching root"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/pq/v2/log/proof/consistency": {
      "get": {
        "summary": "SHA-512 tree prefix consistency path",
        "parameters": [
          {
            "name": "first",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          },
          {
            "name": "second",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Consistency hashes; receiver verifies both matching roots"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          }
        }
      }
    },
    "/pq/v2/log/witness": {
      "get": {
        "summary": "Witnessing status",
        "description": "Public, read-only status of the optional OpenTimestamps witnessing. enabled is false until the operator turns witnessing on, and the independent existence upper bound is unavailable until then. It does not promise that any head will be attested or that any attestation will be confirmed in a Bitcoin block. Responses are no-store. Query strings are rejected.",
        "responses": {
          "200": {
            "description": "Witnessing configuration and progress",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WitnessStatus"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/pq/v2/log/witness/{tree_size}": {
      "get": {
        "summary": "Witness attestations for one published head",
        "description": "The attestations recorded for the published head of that tree size. A response made only of bitcoin attestations may be cached (cache-control: public, max-age=3600); every other response is no-store. Query strings are rejected.",
        "parameters": [
          {
            "name": "tree_size",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Attestations for that head",
            "headers": {
              "Cache-Control": {
                "description": "public, max-age=3600 when every attestation is bitcoin; otherwise no-store",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WitnessRecord"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "description": "That head has no attestation"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "TimestampKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Dedicated 64-byte CSPRNG bearer (86 canonical base64url chars), stored only as a SHA-512 digest on the API. Separate v2 credential; legacy tokens cannot create new records."
      }
    },
    "parameters": {
      "Index": {
        "name": "index",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid fixed-format input or range"
      },
      "Unauthorized": {
        "description": "Missing, expired, revoked or invalid timestamp credential"
      },
      "Unavailable": {
        "description": "Disabled, signing/archival failure, capacity, clock rollback or recovery required; preserve original request for retry"
      }
    },
    "schemas": {
      "Admission": {
        "type": "object",
        "required": [
          "request_id",
          "status"
        ],
        "properties": {
          "request_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "completed"
            ]
          },
          "receipt": {
            "$ref": "#/components/schemas/Receipt"
          }
        }
      },
      "SignedTreeHead": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "body",
          "signature",
          "public_key"
        ],
        "properties": {
          "body": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "schema",
              "log_id",
              "key_id",
              "key_epoch",
              "signature_algorithm",
              "hash_algorithm",
              "tree_size",
              "timestamp",
              "root_hash"
            ],
            "properties": {
              "schema": {
                "const": "tokimi-timestamp-sth/v2"
              },
              "log_id": {
                "const": "tokimi.space/timestamp/pq-2"
              },
              "key_id": {
                "type": "string",
                "pattern": "^sha512:[a-f0-9]{128}$"
              },
              "key_epoch": {
                "const": 1
              },
              "signature_algorithm": {
                "const": "ML-DSA-87"
              },
              "hash_algorithm": {
                "const": "SHA-512"
              },
              "tree_size": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991
              },
              "timestamp": {
                "type": "string",
                "format": "date-time"
              },
              "root_hash": {
                "$ref": "#/components/schemas/Hex64"
              }
            },
            "description": "Exact fixed-order transcript in spec-v2.md. Pure FIPS204 ML-DSA-87 with empty context, not HashML-DSA. Algorithm selection is not FIPS140 module validation."
          },
          "signature": {
            "type": "string",
            "minLength": 6170,
            "maxLength": 6170,
            "pattern": "^[A-Za-z0-9_-]+$"
          },
          "public_key": {
            "type": "string",
            "minLength": 3456,
            "maxLength": 3456,
            "pattern": "^[A-Za-z0-9_-]+$"
          }
        }
      },
      "Receipt": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "log_index",
          "entry",
          "inclusion_proof",
          "inclusion_sth",
          "external_evidence"
        ],
        "properties": {
          "schema": {
            "const": "tokimi-timestamp-receipt/v2"
          },
          "log_index": {
            "type": "integer",
            "minimum": 0
          },
          "entry": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "commitment",
              "registered_at"
            ],
            "properties": {
              "commitment": {
                "$ref": "#/components/schemas/Hex64"
              },
              "registered_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "inclusion_proof": {
            "type": "object",
            "required": [
              "tree_size",
              "hashes"
            ],
            "properties": {
              "tree_size": {
                "type": "integer",
                "minimum": 1
              },
              "hashes": {
                "type": "array",
                "maxItems": 64,
                "items": {
                  "$ref": "#/components/schemas/Hex64"
                }
              }
            }
          },
          "inclusion_sth": {
            "$ref": "#/components/schemas/SignedTreeHead"
          },
          "external_evidence": {
            "type": "array",
            "maxItems": 0
          }
        }
      },
      "Hex64": {
        "type": "string",
        "pattern": "^[a-f0-9]{128}$"
      },
      "WitnessStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "log_id",
          "enabled",
          "interval_ms",
          "calendars",
          "latest_attested_tree_size",
          "latest_bitcoin_tree_size",
          "pending"
        ],
        "properties": {
          "schema": {
            "const": "tokimi-timestamp-witness-status/v2"
          },
          "log_id": {
            "const": "tokimi.space/timestamp/pq-2"
          },
          "enabled": {
            "type": "boolean"
          },
          "interval_ms": {
            "type": "integer",
            "minimum": 60000,
            "maximum": 86400000,
            "description": "Minimum time between two submissions of a new head"
          },
          "calendars": {
            "type": "array",
            "maxItems": 8,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^https://[a-z0-9.-]+$"
            },
            "description": "Allowlisted OpenTimestamps calendar origins; the log contacts no other host"
          },
          "latest_attested_tree_size": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "latest_bitcoin_tree_size": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "pending": {
            "type": "integer",
            "minimum": 0,
            "description": "Attestations still waiting for a Bitcoin block"
          }
        }
      },
      "WitnessAttestation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "provider",
          "calendar",
          "digest_profile",
          "proof_format",
          "proof",
          "status",
          "block_height",
          "submitted_at",
          "upgraded_at"
        ],
        "properties": {
          "provider": {
            "const": "opentimestamps"
          },
          "calendar": {
            "type": "string",
            "pattern": "^https://[a-z0-9.-]+$",
            "description": "HTTPS origin of the calendar, without a path"
          },
          "digest_profile": {
            "const": "tokimi-timestamp/witness-digest/1",
            "description": "SHA-256 of the exact canonical bytes of the attested head body"
          },
          "proof_format": {
            "const": "ots-detached/1"
          },
          "proof": {
            "type": "string",
            "maxLength": 43691,
            "pattern": "^[A-Za-z0-9_-]*$",
            "description": "Canonical unpadded base64url of the detached OpenTimestamps file; at most 32768 bytes decoded"
          },
          "status": {
            "enum": [
              "pending",
              "bitcoin"
            ]
          },
          "block_height": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 4294967295,
            "description": "null while pending; otherwise the smallest Bitcoin height reachable in the proof"
          },
          "submitted_at": {
            "type": "string",
            "format": "date-time"
          },
          "upgraded_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "null while pending"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "const": "pending"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "block_height": {
                  "type": "null"
                },
                "upgraded_at": {
                  "type": "null"
                }
              }
            },
            "else": {
              "properties": {
                "block_height": {
                  "type": "integer"
                },
                "upgraded_at": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "WitnessRecord": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "log_id",
          "tree_size",
          "attestations"
        ],
        "properties": {
          "schema": {
            "const": "tokimi-timestamp-witness/v2"
          },
          "log_id": {
            "const": "tokimi.space/timestamp/pq-2"
          },
          "tree_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "attestations": {
            "type": "array",
            "maxItems": 8,
            "items": {
              "$ref": "#/components/schemas/WitnessAttestation"
            }
          }
        }
      },
      "Evidence": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema",
          "log_id",
          "receipt_tree_size",
          "attested_head",
          "head_bridge",
          "attestations"
        ],
        "properties": {
          "schema": {
            "const": "tokimi-timestamp-evidence/v2"
          },
          "log_id": {
            "const": "tokimi.space/timestamp/pq-2"
          },
          "receipt_tree_size": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991,
            "description": "The receipt's original inclusion tree size; at most attested_head.body.tree_size"
          },
          "attested_head": {
            "$ref": "#/components/schemas/SignedTreeHead"
          },
          "head_bridge": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "first",
              "second",
              "hashes"
            ],
            "description": "SHA-512 consistency proof from first (the receipt's tree size) to second (the attested head's tree size); hashes is empty when they are equal",
            "properties": {
              "first": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991
              },
              "second": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991
              },
              "hashes": {
                "type": "array",
                "maxItems": 64,
                "items": {
                  "$ref": "#/components/schemas/Hex64"
                }
              }
            }
          },
          "attestations": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "items": {
              "$ref": "#/components/schemas/WitnessAttestation"
            }
          }
        },
        "description": "Additive evidence for a receipt; the whole object is at most 64 KiB of JSON. It is not a verification result: the receiver checks it offline against a pin and a block header they obtained themselves."
      }
    }
  }
}
