{ "openapi": "3.1.0", "info": { "title": "SettleBolt Agent API", "version": "2026-07-03", "description": "Scoped server-to-server API for SettleBolt agents and backend automations. API keys require an active paid Pro or Business billing period and are accepted only on /api/agent endpoints." }, "servers": [ { "url": "https://api.settlebolt.com" } ], "security": [ { "bearerApiKey": [] } ], "paths": { "/api/agent/me": { "get": { "summary": "Inspect the authenticated agent key and merchant", "operationId": "getAgentMe", "responses": { "200": { "description": "Authenticated merchant and API-key details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentMe" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/agent/invoices": { "get": { "summary": "List invoices", "operationId": "listAgentInvoices", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "sent", "paid", "overdue", "cancelled" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "x-settlebolt-scope": "invoices:read", "responses": { "200": { "description": "Invoice list", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "invoices", "limit", "offset" ] } } } }, "403": { "$ref": "#/components/responses/InsufficientScope" } } }, "post": { "summary": "Create a draft invoice", "operationId": "createAgentInvoice", "x-settlebolt-scope": "invoices:create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreate" } } } }, "responses": { "201": { "description": "Draft invoice created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/api/agent/invoices/send": { "post": { "summary": "Create and send an invoice", "description": "Requires invoices:create and invoices:send. No additional dashboard confirmation is required.", "operationId": "createAndSendAgentInvoice", "x-settlebolt-scopes": [ "invoices:create", "invoices:send" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreate" } } } }, "responses": { "201": { "description": "Invoice created and sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceSendResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/InsufficientScope" } } } }, "/api/agent/invoices/{id}": { "get": { "summary": "Get an invoice", "operationId": "getAgentInvoice", "x-settlebolt-scope": "invoices:read", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/invoices/{id}/send": { "post": { "summary": "Send a draft invoice", "description": "Requires invoices:send. No additional dashboard confirmation is required.", "operationId": "sendAgentInvoice", "x-settlebolt-scope": "invoices:send", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Invoice sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceSendResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/InsufficientScope" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/agent/payment-links": { "get": { "summary": "List payment links", "operationId": "listAgentPaymentLinks", "x-settlebolt-scope": "payment_links:read", "responses": { "200": { "description": "Payment links", "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentLinks": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } }, "required": [ "paymentLinks" ] } } } } } }, "post": { "summary": "Create a payment link", "operationId": "createAgentPaymentLink", "x-settlebolt-scope": "payment_links:create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreate" } } } }, "responses": { "201": { "description": "Payment link created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreateResponse" } } } } } } }, "/api/agent/payments": { "get": { "summary": "List recorded payments", "operationId": "listAgentPayments", "x-settlebolt-scope": "payments:read", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "token", "in": "query", "schema": { "type": "string" } }, { "name": "chain", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "payments", "limit", "offset" ] } } } } } } }, "/api/agent/customers": { "get": { "summary": "List customers", "operationId": "listAgentCustomers", "x-settlebolt-scope": "customers:read", "responses": { "200": { "description": "Customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } } }, "required": [ "customers" ] } } } } } }, "post": { "summary": "Create a customer", "operationId": "createAgentCustomer", "x-settlebolt-scope": "customers:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreate" } } } }, "responses": { "201": { "description": "Customer created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" } }, "required": [ "id", "email" ] } } } } } } }, "/api/agent/support/tickets": { "post": { "summary": "Open a support ticket", "operationId": "createAgentSupportTicket", "x-settlebolt-scope": "support:create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "message" ], "properties": { "subject": { "type": "string", "minLength": 3, "maxLength": 140 }, "message": { "type": "string", "minLength": 10, "maxLength": 4000 }, "category": { "type": "string", "enum": [ "general", "billing", "payments", "wallets", "technical", "security" ], "default": "general" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ], "default": "normal" } } } } } }, "responses": { "201": { "description": "Ticket created", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string" }, "subject": { "type": "string" }, "category": { "type": "string" }, "priority": { "type": "string" }, "status": { "type": "string" } } } } } } } } }, "/api/whatsapp/webhook": { "get": { "summary": "Verify Meta WhatsApp webhook", "operationId": "verifyWhatsAppWebhook", "security": [], "parameters": [ { "name": "hub.mode", "in": "query", "schema": { "type": "string" } }, { "name": "hub.verify_token", "in": "query", "schema": { "type": "string" } }, { "name": "hub.challenge", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Challenge accepted" }, "403": { "description": "Invalid verify token" } } }, "post": { "summary": "Receive Meta WhatsApp messages", "operationId": "receiveWhatsAppWebhook", "security": [], "description": "Requires a valid X-Hub-Signature-256 header signed with the Meta app secret. Inbound messages are deduped and routed to a paired WhatsApp sender.", "responses": { "200": { "description": "Accepted" }, "401": { "description": "Invalid Meta signature" } } } }, "/api/whatsapp/links": { "get": { "summary": "List WhatsApp agent connections", "operationId": "listWhatsAppLinks", "description": "Dashboard bearer session required. Requires an active paid Pro or Business billing period.", "responses": { "200": { "description": "WhatsApp connections" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/whatsapp/links/pairing-code": { "post": { "summary": "Create a WhatsApp pairing code", "operationId": "createWhatsAppPairingCode", "description": "Dashboard bearer session required. Creates a 10-minute code such as link 123456 with selected safe agent scopes.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "201": { "description": "Pairing code created" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/whatsapp/links/{id}": { "delete": { "summary": "Revoke a WhatsApp agent connection", "operationId": "revokeWhatsAppLink", "description": "Dashboard bearer session required.", "parameters": [ { "$ref": "#/components/parameters/IdPath" } ], "responses": { "200": { "description": "Revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "description": "SettleBolt API key beginning with sb_live_." } }, "parameters": { "IdPath": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key" }, "BadRequest": { "description": "Invalid request" }, "InsufficientScope": { "description": "The API key is valid but lacks the required scope" }, "NotFound": { "description": "Resource not found" } }, "schemas": { "AgentMe": { "type": "object", "properties": { "merchant": { "type": "object" }, "apiKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } }, "LineItem": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 240 }, "qty": { "type": "integer", "minimum": 0 }, "unitPrice": { "type": "integer", "minimum": 0, "description": "EUR cents" } }, "required": [ "description", "qty", "unitPrice" ] }, "InvoiceCreate": { "type": "object", "properties": { "customerName": { "type": "string", "maxLength": 120 }, "customerEmail": { "type": "string", "format": "email" }, "invoiceNumber": { "type": "string", "maxLength": 60 }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "EUR cents" }, "currency": { "type": "string", "enum": [ "EUR" ], "default": "EUR" }, "token": { "type": "string", "default": "USDC" }, "chain": { "type": "string", "default": "base" }, "dueDate": { "type": "string", "format": "date" }, "notes": { "type": "string", "maxLength": 2000 }, "lineItems": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/LineItem" } } }, "required": [ "customerName", "customerEmail", "invoiceNumber", "amount" ] }, "InvoiceCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "invoiceNumber": { "type": "string" }, "status": { "type": "string" }, "payUrl": { "type": "string", "format": "uri" } } }, "InvoiceSendResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "id": { "type": "string" }, "status": { "type": "string", "enum": [ "sent" ] }, "email": { "type": "object" } } }, "Invoice": { "type": "object", "additionalProperties": true }, "PaymentLinkCreate": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "amount": { "type": "integer", "minimum": 1, "maximum": 100000000, "description": "EUR cents" }, "currency": { "type": "string", "enum": [ "EUR" ], "default": "EUR" }, "token": { "type": "string", "default": "USDC" }, "chain": { "type": "string", "default": "base" } }, "required": [ "title", "amount" ] }, "PaymentLinkCreateResponse": { "type": "object", "properties": { "id": { "type": "string" }, "checkoutSlug": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "PaymentLink": { "type": "object", "additionalProperties": true }, "Payment": { "type": "object", "additionalProperties": true }, "Customer": { "type": "object", "additionalProperties": true }, "CustomerCreate": { "type": "object", "properties": { "customerType": { "type": "string", "enum": [ "business", "individual" ], "default": "business" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "maxLength": 200 }, "firstName": { "type": "string", "maxLength": 100 }, "middleName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "maxLength": 40 }, "companyName": { "type": "string", "maxLength": 200 }, "contactName": { "type": "string", "maxLength": 160 }, "billingEmail": { "type": "string", "format": "email" }, "taxStatus": { "type": "string", "enum": [ "taxable", "exempt", "reverse_charge" ] } }, "required": [ "email" ] } } } }