{ "openapi": "3.1.0", "info": { "title": "IOT-Lightning-Bridge API", "version": "1.0.0", "description": "Machine-to-machine API for autonomous agents, robots and AI systems. Create an account, get an API key, register Lightning-payable assets, and stream payment/action events — all over HTTPS, no UI required.", "contact": { "name": "IOT-Lightning-Bridge", "url": "https://iotpay.botrift.com" } }, "servers": [ { "url": "https://iotpay.botrift.com", "description": "Production" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "lib_", "description": "Send `Authorization: Bearer lib_xxx` with every authenticated request." } }, "schemas": { "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string", "example": "invalid_token" }, "message": { "type": "string", "example": "Authorization: Bearer required" } } }, "Account": { "type": "object", "properties": { "user_id": { "type": "string" }, "username": { "type": "string" }, "display_name": { "type": "string", "nullable": true }, "lightning_address": { "type": "string", "nullable": true }, "api_key_prefix": { "type": "string", "nullable": true, "example": "lib_a3f2b9c1" }, "role": { "type": "string", "enum": ["user", "admin"] }, "created": { "type": "string", "format": "date-time" } } }, "AccountCreated": { "type": "object", "properties": { "user_id": { "type": "string" }, "username": { "type": "string" }, "api_key": { "type": "string", "example": "lib_a3f2b9c1...64hex" }, "api_key_prefix": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "warning": { "type": "string" } } }, "KeyRotated": { "type": "object", "properties": { "api_key": { "type": "string" }, "api_key_prefix": { "type": "string" }, "rotated_at": { "type": "string", "format": "date-time" }, "warning": { "type": "string" } } }, "EventIn": { "type": "object", "required": ["asset", "type"], "properties": { "asset": { "type": "string", "description": "Asset record id" }, "type": { "type": "string", "enum": ["paid", "action", "error", "custom"] }, "source": { "type": "string", "enum": ["lnbits", "ha", "system"], "default": "ha" }, "payload": { "type": "object", "additionalProperties": true }, "external_id": { "type": "string", "description": "Idempotency key — unique per user" } } }, "Event": { "type": "object", "properties": { "id": { "type": "string" }, "asset": { "type": "string" }, "type": { "type": "string" }, "source": { "type": "string" }, "payload": { "type": "object", "nullable": true, "additionalProperties": true }, "external_id": { "type": "string", "nullable": true }, "acknowledged_at": { "type": "string", "format": "date-time", "nullable": true }, "created": { "type": "string", "format": "date-time" } } }, "LnurlpInfo": { "type": "object", "properties": { "asset_id": { "type": "string" }, "lnurlp_id": { "type": "string" }, "lnurlp_link": { "type": "string", "format": "uri", "description": "LNURL-pay link (lightning: URI or bech32)" }, "lnurlp_qr": { "type": "string", "format": "uri", "description": "PNG QR code URL" }, "status": { "type": "string", "enum": ["pending", "active", "error"] } } }, "Asset": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "price_sats": { "type": "integer", "minimum": 0 }, "lnurlp_id": { "type": "string", "nullable": true }, "lnurlp_link": { "type": "string", "nullable": true }, "lnurlp_qr": { "type": "string", "nullable": true }, "lnurlp_status": { "type": "string", "nullable": true, "enum": ["pending", "active", "error", null] }, "archived": { "type": "boolean" }, "created": { "type": "string", "format": "date-time" }, "updated": { "type": "string", "format": "date-time" } } }, "AssetCreate": { "type": "object", "required": ["name", "price"], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 2000 }, "price": { "type": "integer", "minimum": 0, "description": "Price in sats" } } }, "AssetPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": { "type": "string", "maxLength": 2000 }, "price": { "type": "integer", "minimum": 0 }, "archived": { "type": "boolean" } } }, "PaymentLink": { "type": "object", "properties": { "asset_id": { "type": "string" }, "lnurlp_id": { "type": "string" }, "lnurlp_link": { "type": "string", "description": "LNURL-pay bech32 string" }, "lnurlp_qr": { "type": "string", "description": "lightning: URI for QR encoding" }, "status": { "type": "string", "enum": ["pending", "active", "error"] } } } } }, "paths": { "/api/v1/accounts": { "post": { "summary": "Create a machine account", "description": "Public endpoint — no auth. Returns a fresh `api_key` that you MUST store immediately. Limited to 5 signups per hour per IP.", "tags": ["Accounts"], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 80, "description": "Friendly name for the machine/agent" }, "lightning_address": { "type": "string", "example": "you@getalby.com" } } } } } }, "responses": { "201": { "description": "Account created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCreated" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many signups from this IP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Backend error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/accounts/me": { "get": { "summary": "Get current account", "tags": ["Accounts"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/accounts/me/rotate-key": { "post": { "summary": "Rotate the API key", "description": "Generates a new key and invalidates the previous one. The response contains the only copy of the new key.", "tags": ["Accounts"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Rotated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyRotated" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/public/events": { "get": { "summary": "List recent events", "tags": ["Events"], "security": [{ "bearerAuth": [] }], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "asset", "schema": { "type": "string" } }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": ["paid", "action", "error", "custom"] } }, { "in": "query", "name": "unacked", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "count": { "type": "integer" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } } } }, "post": { "summary": "Append an event", "tags": ["Events"], "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventIn" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "403": { "description": "Asset not owned" }, "404": { "description": "Asset not found" }, "409": { "description": "Duplicate event (external_id)" } } } }, "/api/public/events/{id}": { "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "get": { "summary": "Get a single event", "tags": ["Events"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "404": { "description": "Not found" } } } }, "/api/public/assets/{id}/lnurlp": { "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "get": { "summary": "Get the LNURL-pay link for an asset", "description": "Returns the static LNURLp link + QR for an asset you own. Use this as the public payment URL for hardware (printed on QR stickers).", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LnurlpInfo" } } } }, "403": { "description": "Asset not owned" }, "404": { "description": "Asset not found" } } } }, "/api/v1/assets": { "get": { "summary": "List your assets", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "archived", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string" }, "count": { "type": "integer" }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } } } } } }, "post": { "summary": "Create an asset", "description": "Creates a Lightning-payable asset. Call `POST /api/v1/assets/{id}/payment-link` afterwards to provision the LNURLp link.", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreate" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/assets/{id}": { "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "get": { "summary": "Get an asset", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "404": { "description": "Not found" } } }, "patch": { "summary": "Update an asset", "description": "Partial update. If you change `name` or `price`, also call `POST /api/v1/assets/{id}/payment-link` to refresh the LNURLp.", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetPatch" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "404": { "description": "Not found" } } }, "delete": { "summary": "Delete an asset", "description": "Deletes the asset and best-effort removes its LNBits pay-link.", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Deleted" }, "404": { "description": "Not found" } } } }, "/api/v1/assets/{id}/payment-link": { "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "get": { "summary": "Get or provision the LNURL-pay link", "description": "Returns the existing active LNURLp link, or provisions a new one if missing. Idempotent — safe to call repeatedly.", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "404": { "description": "Asset not found" }, "502": { "description": "LNBits provisioning failed" } } }, "post": { "summary": "Refresh the LNURL-pay link", "description": "Rebuilds the LNBits pay-link from the current asset name + price. Call this after a PATCH that changed `name` or `price`.", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "404": { "description": "Asset not found" }, "502": { "description": "LNBits refresh failed" } } } }, "/api/v1/assets/{id}/payments": { "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }], "get": { "summary": "List paid events for an asset", "tags": ["Assets"], "security": [{ "bearerAuth": [] }], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "asset_id": { "type": "string" }, "count": { "type": "integer" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } }, "404": { "description": "Asset not found" } } } } } }