{
  "openapi": "3.1.0",
  "info": {
    "title": "Mark",
    "description": "Stamp content with a permanent, verifiable provenance record. Hash content locally (SHA-256), send the fingerprint, get a public verify URL back. Verification is free forever, no auth required.",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "https://makemark.io"
    }
  ],
  "paths": {
    "/keys": {
      "post": {
        "operationId": "createFreeKey",
        "summary": "Create a free API key",
        "description": "Mints an API key with no email or account required. Returns the secret key; store it because it is shown only once. A network gets one free stamp in total however many keys it mints; freeStamp says whether this key still has it.",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Optional label for this key (e.g. 'chatgpt-action')",
                    "maxLength": 80
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Key created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "secret": {
                      "type": "string",
                      "description": "The API key (pk_...). Shown once, store it now."
                    },
                    "creatorId": {
                      "type": "string"
                    },
                    "plan": {
                      "type": "string"
                    },
                    "freeStamp": {
                      "type": "boolean",
                      "description": "Whether this key can make one free stamp (one per network)."
                    },
                    "message": {
                      "type": "string",
                      "description": "What to do next, including how to buy stamps when freeStamp is false."
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: 3 self-serve keys per network per day."
          }
        }
      }
    },
    "/proof": {
      "post": {
        "operationId": "stampContent",
        "summary": "Stamp a content hash",
        "description": "Records a SHA-256 content fingerprint with your creator identity and a timestamp. Hash the content bytes locally, the content itself never leaves the client. Returns a permanent verify URL.",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contentHash"
                ],
                "properties": {
                  "contentHash": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$",
                    "description": "SHA-256 hex digest of the exact content bytes (64 lowercase hex chars)"
                  },
                  "title": {
                    "type": "string",
                    "maxLength": 300,
                    "description": "Optional human-readable title"
                  },
                  "visibility": {
                    "type": "string",
                    "enum": [
                      "public",
                      "private"
                    ],
                    "default": "private",
                    "description": "public: title and stamp appear on the publisher's public feed and are eligible for search indexing. private (the default): the record is unlisted and noindex, and shows no title, but anyone with its link or the file can still see its time, fingerprint, signature and verified publisher. Pass public explicitly when the caller wants a shareable record that names the file."
                  },
                  "contentType": {
                    "type": "string",
                    "description": "Optional MIME type (e.g. text/markdown, image/png)"
                  },
                  "displayName": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Only used when calling without an API key. A self-asserted human label shown on public stamps as unverified (never as a verified identity). Ignored if a key is present."
                  },
                  "claimEmail": {
                    "type": "string",
                    "format": "email",
                    "description": "Only used when calling without an API key. The human's email; they get a one-time link to sign in (a free Mark account is created automatically, no password) and these stamps move into that account. Never shown publicly, and nothing is created until they click. Ignored if a key is present."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Stamp created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "proofId": {
                      "type": "string"
                    },
                    "verifyUrl": {
                      "type": "string",
                      "description": "Public URL anyone can open to verify this stamp"
                    },
                    "byline": {
                      "type": "string",
                      "description": "Attribution string to embed in the content"
                    },
                    "badgeEmbed": {
                      "type": "string",
                      "description": "HTML snippet for an embeddable proof badge"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "SIGNED",
                        "ANCHORED",
                        "CONFIRMED",
                        "REVOKED"
                      ]
                    },
                    "signedAt": {
                      "type": "integer",
                      "description": "Unix ms timestamp of the stamp"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Quota exhausted or payment required. The response body's `next` field says what to do (get a key, buy prepaid stamps with POST /checkout, or pay via x402)."
          }
        }
      }
    },
    "/verify": {
      "post": {
        "operationId": "verifyContent",
        "summary": "Verify a content hash",
        "description": "Returns all stamps for the given SHA-256 hash, earliest anchored first. Free and unauthenticated, no API key needed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "contentHash"
                ],
                "properties": {
                  "contentHash": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{64}$",
                    "description": "SHA-256 hex digest to look up"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contentHash": {
                      "type": "string"
                    },
                    "proofs": {
                      "type": "array",
                      "description": "All stamps for this hash, earliest anchored first. Revoked stamps are included with status REVOKED.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "proofId": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string"
                          },
                          "signedAt": {
                            "type": "integer"
                          },
                          "verifyUrl": {
                            "type": "string"
                          },
                          "publisher": {
                            "type": [
                              "object",
                              "null"
                            ],
                            "description": "The verified publisher (type, value, tier), or null for an unverified account. Never trust a name that isn't here."
                          }
                        }
                      }
                    },
                    "conflict": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "description": "Null unless two or more distinct signers hold standing (not revoked) stamps of this exact hash.",
                      "properties": {
                        "distinctSigners": {
                          "type": "integer"
                        },
                        "earliest": {
                          "type": "object",
                          "description": "The earliest standing stamp, as in proofs."
                        }
                      }
                    },
                    "matchCount": {
                      "type": "integer",
                      "description": "How many stamps exist for this hash, revoked ones included."
                    },
                    "exact": {
                      "type": "boolean",
                      "description": "True if at least one stamp that isn't revoked covers these exact bytes."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/proof/{id}": {
      "get": {
        "operationId": "getProof",
        "summary": "Get a proof by id",
        "description": "Public projection of one proof: status, times, anchors, and the verified publisher (if any). No auth required.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The proof"
          },
          "404": {
            "description": "No such proof id"
          }
        }
      }
    },
    "/billing": {
      "get": {
        "operationId": "getBalance",
        "summary": "Show this key's stamp balance",
        "description": "Plan, included stamps used and left, prepaid balance, whether the free stamp is unused, and recent purchases. Poll after a person pays a checkout link.",
        "responses": {
          "200": {
            "description": "Balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "plan": {
                      "type": "string"
                    },
                    "allowance": {
                      "type": "integer"
                    },
                    "used": {
                      "type": "integer"
                    },
                    "remaining": {
                      "type": "integer"
                    },
                    "balance": {
                      "type": "integer",
                      "description": "Prepaid stamps left (never expire)"
                    },
                    "lifetimeSampleAvailable": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing, mistyped or revoked API key."
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/checkout": {
      "post": {
        "operationId": "buyStamps",
        "summary": "Start buying prepaid stamps for this key",
        "description": "Returns a Stripe Checkout link that a PERSON must open and pay; the stamps land on this key's account within seconds. Packs: bundle_5 ($1), bundle_10 ($1.50), bundle_50 ($5), bundle_100 ($8), bundle_500 ($35), bundle_1000 ($65), bundle_2000 ($120).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "bundle"
                ],
                "properties": {
                  "bundle": {
                    "type": "string",
                    "enum": [
                      "bundle_5",
                      "bundle_10",
                      "bundle_50",
                      "bundle_100",
                      "bundle_500",
                      "bundle_1000",
                      "bundle_2000"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Checkout link",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string",
                      "description": "Give this link to a person to pay."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Unknown bundle id."
          },
          "401": {
            "description": "Missing, mistyped or revoked API key."
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "pk_...",
        "description": "An API key from POST /keys (no auth, built for agents) or https://makemark.io/account (human sign-in). Each durable account includes one lifetime sample stamp."
      }
    }
  }
}
