{ "openapi": "3.0.3", "info": { "title": "ClearBooks API", "description": "REST API for ClearBooks accounting platform. Provides access to accounts, customers, invoices, vendors, bills, products, reports, and webhooks.", "version": "1.0.0", "contact": { "name": "ClearBooks Support", "url": "https://github.com/amitrjain/clearbooks" } }, "servers": [ { "url": "/api/v1", "description": "API v1" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Meta", "description": "Current user and company info" }, { "name": "Accounts", "description": "Chart of accounts management" }, { "name": "Customers", "description": "Customer management" }, { "name": "Invoices", "description": "Invoice lifecycle management" }, { "name": "Vendors", "description": "Vendor management" }, { "name": "Bills", "description": "Bill lifecycle management" }, { "name": "Products", "description": "Products and services catalog" }, { "name": "Reports", "description": "Financial reports" }, { "name": "Webhooks", "description": "Webhook subscriptions" } ], "paths": { "/me": { "get": { "tags": ["Meta"], "summary": "Get current user", "operationId": "getMe", "responses": { "200": { "description": "Current authenticated user", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/company": { "get": { "tags": ["Meta"], "summary": "Get current company", "operationId": "getCompany", "responses": { "200": { "description": "Current company", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/accounts": { "get": { "tags": ["Accounts"], "summary": "List all accounts", "operationId": "listAccounts", "responses": { "200": { "description": "List of accounts", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": ["Accounts"], "summary": "Create an account", "operationId": "createAccount", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountInput" } } } }, "responses": { "201": { "description": "Account created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Account" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/accounts/{id}": { "get": { "tags": ["Accounts"], "summary": "Get an account", "operationId": "getAccount", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Account details", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Account" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": ["Accounts"], "summary": "Update an account", "operationId": "updateAccount", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountInput" } } } }, "responses": { "200": { "description": "Account updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Account" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customers": { "get": { "tags": ["Customers"], "summary": "List customers", "operationId": "listCustomers", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated list of customers", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": ["Customers"], "summary": "Create a customer", "operationId": "createCustomer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "201": { "description": "Customer created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/customers/{id}": { "get": { "tags": ["Customers"], "summary": "Get a customer", "operationId": "getCustomer", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Customer details", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": ["Customers"], "summary": "Update a customer", "operationId": "updateCustomer", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerInput" } } } }, "responses": { "200": { "description": "Customer updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Customer" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/invoices": { "get": { "tags": ["Invoices"], "summary": "List invoices", "operationId": "listInvoices", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated list of invoices", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": ["Invoices"], "summary": "Create an invoice", "operationId": "createInvoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" } } } }, "responses": { "201": { "description": "Invoice created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/invoices/{id}": { "get": { "tags": ["Invoices"], "summary": "Get an invoice", "operationId": "getInvoice", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Invoice details", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": ["Invoices"], "summary": "Update an invoice", "operationId": "updateInvoice", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceInput" } } } }, "responses": { "200": { "description": "Invoice updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/invoices/{invoice_id}/send": { "post": { "tags": ["Invoices"], "summary": "Send an invoice", "description": "Marks the invoice as sent and creates the corresponding accounts receivable journal entry.", "operationId": "sendInvoice", "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invoice sent", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/invoices/{invoice_id}/void": { "post": { "tags": ["Invoices"], "summary": "Void an invoice", "description": "Voids the invoice and reverses any associated journal entries.", "operationId": "voidInvoice", "parameters": [ { "name": "invoice_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invoice voided", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Invoice" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/vendors": { "get": { "tags": ["Vendors"], "summary": "List vendors", "operationId": "listVendors", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated list of vendors", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": ["Vendors"], "summary": "Create a vendor", "operationId": "createVendor", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorInput" } } } }, "responses": { "201": { "description": "Vendor created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vendor" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/vendors/{id}": { "get": { "tags": ["Vendors"], "summary": "Get a vendor", "operationId": "getVendor", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Vendor details", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vendor" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": ["Vendors"], "summary": "Update a vendor", "operationId": "updateVendor", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorInput" } } } }, "responses": { "200": { "description": "Vendor updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Vendor" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/bills": { "get": { "tags": ["Bills"], "summary": "List bills", "operationId": "listBills", "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Paginated list of bills", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": ["Bills"], "summary": "Create a bill", "operationId": "createBill", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillInput" } } } }, "responses": { "201": { "description": "Bill created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bill" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/bills/{id}": { "get": { "tags": ["Bills"], "summary": "Get a bill", "operationId": "getBill", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Bill details", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bill" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": ["Bills"], "summary": "Update a bill", "operationId": "updateBill", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillInput" } } } }, "responses": { "200": { "description": "Bill updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bill" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/bills/{bill_id}/receive": { "post": { "tags": ["Bills"], "summary": "Receive a bill", "description": "Marks the bill as received and creates the corresponding accounts payable journal entry.", "operationId": "receiveBill", "parameters": [ { "name": "bill_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bill received", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bill" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/bills/{bill_id}/void": { "post": { "tags": ["Bills"], "summary": "Void a bill", "description": "Voids the bill and reverses any associated journal entries.", "operationId": "voidBill", "parameters": [ { "name": "bill_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Bill voided", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Bill" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/products": { "get": { "tags": ["Products"], "summary": "List products", "operationId": "listProducts", "responses": { "200": { "description": "List of products", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": ["Products"], "summary": "Create a product", "operationId": "createProduct", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "201": { "description": "Product created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/products/{id}": { "get": { "tags": ["Products"], "summary": "Get a product", "operationId": "getProduct", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Product details", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": ["Products"], "summary": "Update a product", "operationId": "updateProduct", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductInput" } } } }, "responses": { "200": { "description": "Product updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/profit-and-loss": { "get": { "tags": ["Reports"], "summary": "Profit and loss report", "operationId": "profitAndLoss", "parameters": [ { "name": "from", "in": "query", "description": "Start date (ISO 8601)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End date (ISO 8601)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Profit and loss data", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/balance-sheet": { "get": { "tags": ["Reports"], "summary": "Balance sheet report", "operationId": "balanceSheet", "parameters": [ { "name": "as_of", "in": "query", "description": "As-of date (ISO 8601)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Balance sheet data", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/trial-balance": { "get": { "tags": ["Reports"], "summary": "Trial balance report", "operationId": "trialBalance", "parameters": [ { "name": "as_of", "in": "query", "description": "As-of date (ISO 8601)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Trial balance data", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/cash-flow": { "get": { "tags": ["Reports"], "summary": "Cash flow report", "operationId": "cashFlow", "parameters": [ { "name": "from", "in": "query", "description": "Start date (ISO 8601)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End date (ISO 8601)", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Cash flow data", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/aged-receivables": { "get": { "tags": ["Reports"], "summary": "Aged receivables report", "operationId": "agedReceivables", "responses": { "200": { "description": "Aged receivables data", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/reports/aged-payables": { "get": { "tags": ["Reports"], "summary": "Aged payables report", "operationId": "agedPayables", "responses": { "200": { "description": "Aged payables data", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks": { "get": { "tags": ["Webhooks"], "summary": "List webhooks", "operationId": "listWebhooks", "responses": { "200": { "description": "List of webhooks", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": ["Webhooks"], "summary": "Create a webhook", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "201": { "description": "Webhook created (includes secret)", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookWithSecret" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/webhooks/{id}": { "get": { "tags": ["Webhooks"], "summary": "Get a webhook", "description": "Returns webhook details including the signing secret.", "operationId": "getWebhook", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "200": { "description": "Webhook details (includes secret)", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookWithSecret" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "put": { "tags": ["Webhooks"], "summary": "Update a webhook", "operationId": "updateWebhook", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookInput" } } } }, "responses": { "200": { "description": "Webhook updated", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Webhook" } }, "required": ["data"] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": ["Webhooks"], "summary": "Delete a webhook", "operationId": "deleteWebhook", "parameters": [ { "$ref": "#/components/parameters/Id" } ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key passed as a Bearer token. Generate keys from Settings > API Keys." } }, "headers": { "X-RateLimit-Limit": { "description": "Maximum requests per minute (60)", "schema": { "type": "integer", "example": 60 } }, "X-RateLimit-Remaining": { "description": "Remaining requests in current window", "schema": { "type": "integer", "example": 59 } } }, "parameters": { "Id": { "name": "id", "in": "path", "required": true, "description": "Resource UUID", "schema": { "type": "string", "format": "uuid" } }, "Page": { "name": "page", "in": "query", "description": "Page number (default: 1)", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "description": "Items per page (default: 50, max: 100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Not found" } } } } } }, "ValidationError": { "description": "Validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "name": ["can't be blank"] } } } } } } }, "RateLimited": { "description": "Rate limit exceeded (60 requests per minute)", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Retry-After": { "description": "Seconds until rate limit resets", "schema": { "type": "integer", "example": 60 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Rate limit exceeded. Try again in 60 seconds." } } } } } } }, "schemas": { "PaginationMeta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 120 }, "total_pages": { "type": "integer", "example": 3 } }, "required": ["page", "per_page", "total", "total_pages"] }, "MeResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": ["owner", "admin", "accountant", "viewer"] } }, "required": ["id", "email", "role"] }, "CompanyResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "legal_name": { "type": "string", "nullable": true }, "base_currency": { "type": "string", "example": "USD" }, "fiscal_year_start_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "tier": { "type": "string", "enum": ["starter", "professional", "enterprise"] } }, "required": ["id", "name", "base_currency", "fiscal_year_start_month", "tier"] }, "Account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string", "example": "1000" }, "name": { "type": "string", "example": "Cash" }, "account_type": { "type": "string", "enum": ["asset", "liability", "equity", "revenue", "expense"] }, "sub_type": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "description": { "type": "string", "nullable": true }, "inserted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "code", "name", "account_type", "is_active", "inserted_at", "updated_at"] }, "AccountInput": { "type": "object", "properties": { "code": { "type": "string", "example": "1000" }, "name": { "type": "string", "example": "Cash" }, "account_type": { "type": "string", "enum": ["asset", "liability", "equity", "revenue", "expense"] }, "sub_type": { "type": "string" }, "is_active": { "type": "boolean", "default": true }, "description": { "type": "string" } }, "required": ["code", "name", "account_type"] }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "billing_address": { "type": "string", "nullable": true }, "payment_terms": { "type": "integer", "nullable": true, "example": 30 }, "currency": { "type": "string", "example": "USD", "nullable": true }, "is_active": { "type": "boolean" }, "inserted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "name", "is_active", "inserted_at", "updated_at"] }, "CustomerInput": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "billing_address": { "type": "string" }, "payment_terms": { "type": "integer" }, "currency": { "type": "string" }, "is_active": { "type": "boolean", "default": true } }, "required": ["name"] }, "CustomerListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": ["data", "meta"] }, "LineItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": "string" }, "quantity": { "type": "number", "format": "decimal" }, "unit_price": { "type": "number", "format": "decimal" }, "amount": { "type": "number", "format": "decimal" }, "account_id": { "type": "string", "format": "uuid" } }, "required": ["id", "description", "quantity", "unit_price", "amount"] }, "LineItemInput": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "number", "format": "decimal" }, "unit_price": { "type": "number", "format": "decimal" }, "account_id": { "type": "string", "format": "uuid" } }, "required": ["description", "quantity", "unit_price"] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string", "example": "INV-0001" }, "status": { "type": "string", "enum": ["draft", "sent", "paid", "partial", "overdue", "void"] }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "subtotal": { "type": "number", "format": "decimal" }, "tax_total": { "type": "number", "format": "decimal" }, "total": { "type": "number", "format": "decimal" }, "amount_paid": { "type": "number", "format": "decimal" }, "balance_due": { "type": "number", "format": "decimal" }, "currency": { "type": "string", "example": "USD" }, "notes": { "type": "string", "nullable": true }, "terms": { "type": "string", "nullable": true }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItem" } }, "inserted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "customer_id", "invoice_number", "status", "issue_date", "due_date", "subtotal", "tax_total", "total", "amount_paid", "balance_due", "currency", "line_items", "inserted_at", "updated_at"] }, "InvoiceInput": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "invoice_number": { "type": "string" }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "notes": { "type": "string" }, "terms": { "type": "string" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItemInput" } } }, "required": ["customer_id", "issue_date", "due_date", "line_items"] }, "InvoiceListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": ["data", "meta"] }, "Vendor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "billing_address": { "type": "object", "nullable": true }, "tax_id": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "payment_terms": { "type": "integer", "nullable": true, "example": 30 }, "is_active": { "type": "boolean" }, "currency": { "type": "string", "example": "USD", "nullable": true }, "inserted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "company_id", "name", "is_active", "inserted_at", "updated_at"] }, "VendorInput": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "billing_address": { "type": "object" }, "tax_id": { "type": "string" }, "notes": { "type": "string" }, "payment_terms": { "type": "integer" }, "currency": { "type": "string" }, "is_active": { "type": "boolean", "default": true } }, "required": ["name"] }, "VendorListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Vendor" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": ["data", "meta"] }, "Bill": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "vendor_id": { "type": "string", "format": "uuid" }, "bill_number": { "type": "string", "example": "BILL-0001" }, "status": { "type": "string", "enum": ["draft", "received", "paid", "partial", "overdue", "void"] }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "subtotal": { "type": "number", "format": "decimal" }, "tax_total": { "type": "number", "format": "decimal" }, "total": { "type": "number", "format": "decimal" }, "amount_paid": { "type": "number", "format": "decimal" }, "balance_due": { "type": "number", "format": "decimal" }, "currency": { "type": "string", "example": "USD" }, "notes": { "type": "string", "nullable": true }, "line_items": { "type": "array", "items": { "type": "object" } }, "inserted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "company_id", "vendor_id", "bill_number", "status", "issue_date", "due_date", "subtotal", "tax_total", "total", "amount_paid", "balance_due", "currency", "line_items", "inserted_at", "updated_at"] }, "BillInput": { "type": "object", "properties": { "vendor_id": { "type": "string", "format": "uuid" }, "bill_number": { "type": "string" }, "issue_date": { "type": "string", "format": "date" }, "due_date": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "notes": { "type": "string" }, "line_items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItemInput" } } }, "required": ["vendor_id", "issue_date", "due_date"] }, "BillListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Bill" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } }, "required": ["data", "meta"] }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "sku": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": ["product", "service"] }, "unit_price": { "type": "number", "format": "decimal" }, "cost_price": { "type": "number", "format": "decimal", "nullable": true }, "is_active": { "type": "boolean" }, "income_account_id": { "type": "string", "format": "uuid", "nullable": true }, "expense_account_id": { "type": "string", "format": "uuid", "nullable": true }, "inserted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "company_id", "name", "type", "unit_price", "is_active", "inserted_at", "updated_at"] }, "ProductInput": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "sku": { "type": "string" }, "type": { "type": "string", "enum": ["product", "service"] }, "unit_price": { "type": "number", "format": "decimal" }, "cost_price": { "type": "number", "format": "decimal" }, "is_active": { "type": "boolean", "default": true }, "income_account_id": { "type": "string", "format": "uuid" }, "expense_account_id": { "type": "string", "format": "uuid" } }, "required": ["name", "type", "unit_price"] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "example": ["invoice.created", "invoice.paid"] }, "is_active": { "type": "boolean" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "failure_count": { "type": "integer" }, "inserted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "company_id", "url", "events", "is_active", "failure_count", "inserted_at", "updated_at"] }, "WebhookWithSecret": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "secret": { "type": "string", "description": "HMAC signing secret for verifying webhook payloads" }, "is_active": { "type": "boolean" }, "last_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "failure_count": { "type": "integer" }, "inserted_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": ["id", "company_id", "url", "events", "secret", "is_active", "failure_count", "inserted_at", "updated_at"] }, "WebhookInput": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean", "default": true } }, "required": ["url", "events"] } } } }