{
  "openapi": "3.1.0",
  "info": {
    "title": "Lumen Stars Bitcoin",
    "version": "1.0.0",
    "description": "Free signed keepsakes for confirmed mainnet address holdings. No payments or spending. Six confirmations; Native SegWit and single-key Taproot BIP322 Simple. Gold, Orange and Lightning issuance closed."
  },
  "components": {
    "securitySchemes": {
      "recipientBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Private recipient token returned by POST /api/agent-sessions. Never use wallet keys."
      }
    }
  },
  "paths": {
    "/api/collection": {
      "get": {
        "summary": "Approved colors, caps and admission state",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        }
      }
    },
    "/api/issuer": {
      "get": {
        "summary": "Public Ed25519 PEM; pin independently",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Readiness and admission state",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        }
      }
    },
    "/api/agent-sessions": {
      "post": {
        "summary": "Create private bearer access",
        "responses": {
          "201": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        }
      }
    },
    "/api/session": {
      "get": {
        "summary": "Most recent private claims",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ]
      }
    },
    "/api/session/recovery": {
      "post": {
        "summary": "Generate or replace private recovery code",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        }
      }
    },
    "/api/session/recover": {
      "post": {
        "summary": "Recover original private access with a fresh bearer",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "recoveryCode": {
                    "type": "string",
                    "maxLength": 43
                  }
                },
                "required": [
                  "recoveryCode"
                ]
              }
            }
          }
        }
      }
    },
    "/api/session/logout": {
      "post": {
        "summary": "Revoke this bearer",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        }
      }
    },
    "/api/session/personal-data": {
      "delete": {
        "summary": "Erase this principal personal data; permanent hashed script markers and counts remain",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "deletePersonalData": {
                    "type": "boolean",
                    "const": true
                  }
                },
                "required": [
                  "deletePersonalData"
                ]
              }
            }
          }
        }
      }
    },
    "/api/claims": {
      "post": {
        "summary": "Create exact short-lived signing challenge",
        "responses": {
          "201": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "address": {
                    "type": "string",
                    "maxLength": 90
                  },
                  "recipientName": {
                    "type": "string",
                    "maxLength": 48,
                    "minLength": 1
                  },
                  "story": {
                    "type": "string",
                    "maxLength": 240
                  }
                },
                "required": [
                  "address",
                  "recipientName"
                ]
              }
            }
          }
        }
      }
    },
    "/api/claims/{claimId}": {
      "get": {
        "summary": "Read private claim/preview/issued star",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/claims/{claimId}/prove": {
      "post": {
        "summary": "Verify exact BIP322 Simple signature and confirmed balance; reserve immutable preview",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "signature": {
                    "type": "string",
                    "maxLength": 1500
                  }
                },
                "required": [
                  "signature"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/claims/{claimId}/accept": {
      "post": {
        "summary": "Explicitly accept pinned preview with fresh chain evidence",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "accepted": {
                    "type": "boolean",
                    "const": true
                  },
                  "previewDigest": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-f0-9]{64}$"
                  }
                },
                "required": [
                  "accepted",
                  "previewDigest"
                ]
              }
            }
          }
        },
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/claims/{claimId}/cancel": {
      "post": {
        "summary": "Cancel unissued claim",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {},
                "required": []
              }
            }
          }
        },
        "parameters": [
          {
            "name": "claimId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/stars/{starId}": {
      "get": {
        "summary": "Private issued star and authenticated download URLs",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "parameters": [
          {
            "name": "starId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/stars/{starId}/svg": {
      "get": {
        "summary": "Download private svg artifact",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "parameters": [
          {
            "name": "starId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/stars/{starId}/png": {
      "get": {
        "summary": "Download private png artifact",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "parameters": [
          {
            "name": "starId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/stars/{starId}/json": {
      "get": {
        "summary": "Download private json artifact",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "parameters": [
          {
            "name": "starId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/stars/{starId}/story": {
      "get": {
        "summary": "Download private story artifact",
        "responses": {
          "200": {
            "description": "Private JSON result, or indicated artifact for downloads"
          },
          "400": {
            "description": "Invalid exact-field JSON input"
          },
          "401": {
            "description": "Private bearer missing or invalid"
          },
          "404": {
            "description": "Resource not owned or not found"
          },
          "409": {
            "description": "Expired/changed/duplicate/unavailable claim; create a new challenge when evidence changed"
          },
          "429": {
            "description": "Rate or resource limit"
          },
          "503": {
            "description": "Admission paused or service busy"
          }
        },
        "security": [
          {
            "recipientBearer": []
          }
        ],
        "parameters": [
          {
            "name": "starId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  }
}