{
  "openapi": "3.0.3",
  "info": {
    "title": "Tyms Developer API",
    "version": "1.0.0",
    "description": "REST API for Tyms — the AI-Native Accounting Platform for small and medium-sized businesses across service, consulting, retail, and manufacturing. Paths are appended to the server URL.\n\n**Business key** (`tyms_sk_...`): all routes except partner distributor routes and OAuth authorization steps that document their own auth. **Partner key** (`adam_partner_sk_...` or equivalent): `POST /register-business`, `GET /referred-businesses`, billing status, and seat/credit grants on referred businesses. **OAuth**: integration apps use `tyms_pk_...` / `tyms_sk_...` plus user Bearer tokens — see the OAuth guide.\n\nFinancial reports match what you see in the Tyms app. AI create endpoints accept optional attachment objects (`name`, `file`, `type`) — see the Attachments page in this docs site."
  },
  "servers": [
    {
      "url": "https://staging-api.usetyms.com/v1/adam",
      "description": "Sandbox (pre-production). Request credentials at developer@usetyms.com."
    },
    {
      "url": "https://api.usetyms.com/v1/adam",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Partners",
      "description": "Referral partner (distributor) flows — partner API key only. Register businesses, list referrals, read billing, and grant Plus seats or AI credits from partner holding."
    },
    {
      "name": "Authentication",
      "description": "Validate a business Developer API key."
    },
    {
      "name": "OAuth",
      "description": "Third-party integration authorization — connect Tyms users to your app without sharing their business secret keys."
    },
    {
      "name": "Chart of accounts",
      "description": "COA and bank-linked accounts."
    },
    {
      "name": "Invoices",
      "description": "Invoice CRUD and payments."
    },
    {
      "name": "Bills",
      "description": "Bill CRUD and payments."
    },
    {
      "name": "Expenses",
      "description": "Expense CRUD."
    },
    {
      "name": "Income",
      "description": "Income record CRUD."
    },
    {
      "name": "Journals",
      "description": "Journal entry CRUD."
    },
    {
      "name": "Contacts",
      "description": "Contact CRUD."
    },
    {
      "name": "Banks",
      "description": "Bank accounts."
    },
    {
      "name": "Bank transactions",
      "description": "Statement lines and AI-assisted upload."
    },
    {
      "name": "Reports",
      "description": "Financial statements (aligned with in-app reports)."
    },
    {
      "name": "Inventory",
      "description": "Product and service catalog; stock tracking, sell, and restock."
    },
    {
      "name": "Fixed Assets",
      "description": "Capital asset acquisition and tracking."
    },
    {
      "name": "Quotes",
      "description": "Sales proposals that can be converted to invoices, income, or prepaid income."
    },
    {
      "name": "Purchase Orders",
      "description": "Vendor buying commitments that convert to inventory restocks."
    },
    {
      "name": "Departments",
      "description": "Reporting dimension for cost/profit allocation within a branch."
    },
    {
      "name": "Projects",
      "description": "Job costing and project tracking dimension attached to transactions."
    },
    {
      "name": "Branches",
      "description": "Multi-location dimension; reports and lists can filter by branch."
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Business secret `tyms_sk_...` for business-scoped routes. Partner secret for register-business and referred-business distributor routes.",
        "x-default": "your_tyms_sk_or_partner_key"
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "failed"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Attachment": {
        "type": "object",
        "required": [
          "file",
          "type"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Filename with extension (recommended for type detection)."
          },
          "file": {
            "type": "string",
            "description": "Content per `type`. For Base64, send raw bytes encoded as a string (no `data:...;base64,` prefix)."
          },
          "type": {
            "type": "string",
            "enum": [
              "base64",
              "url",
              "raw"
            ],
            "description": "How `file` is encoded. **Required on every attachment.** Base64 payloads must use `\"type\": \"base64\"` explicitly — the API does not infer Base64 from the `file` string alone."
          }
        }
      },
      "AiCreateRequest": {
        "type": "object",
        "example": {
          "prompt": "Create an invoice for ACME LLC for $250 for consulting, dated today, due in 14 days",
          "process_type": "async"
        },
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string"
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Attachment"
            }
          },
          "text_attachment": {
            "type": "string"
          },
          "process_type": {
            "type": "string",
            "enum": [
              "async",
              "direct"
            ],
            "description": "`async` (default) or `direct`."
          }
        }
      },
      "RegisterBusinessRequest": {
        "type": "object",
        "example": {
          "email": "owner@example.com",
          "firstname": "Jane",
          "lastname": "Smith",
          "business_name": "Smith Enterprises",
          "password": "Secure1!",
          "country": "US",
          "currency": "USD",
          "timezone": "America/New_York",
          "grant_access": "admin",
          "credit_from_referral_partner": false
        },
        "required": [
          "email",
          "firstname",
          "lastname",
          "business_name",
          "password"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "firstname": {
            "type": "string"
          },
          "lastname": {
            "type": "string"
          },
          "business_name": {
            "type": "string"
          },
          "password": {
            "type": "string",
            "minLength": 8,
            "description": "Owner account password. Must be at least 8 characters and include a letter, a number, and a special character (e.g. !@#$%^&*).",
            "example": "Secure1!"
          },
          "country": {
            "type": "string",
            "default": "US"
          },
          "currency": {
            "type": "string",
            "default": "USD"
          },
          "timezone": {
            "type": "string",
            "default": "America/New_York"
          },
          "industry": {
            "type": "string"
          },
          "grant_access": {
            "type": "string",
            "enum": [
              "admin",
              "viewer",
              "editor"
            ],
            "description": "`admin` returns `api_public_key` and `api_secret_key` in the response."
          },
          "credit_from_referral_partner": {
            "type": "boolean",
            "default": false,
            "description": "When `true`, Tyms credit usage for this business is charged to the referring partner's credit balance in the partner portal (the partner manages credit for the business). Optional; defaults to `false`."
          }
        }
      },
      "RegisterBusinessSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "business_uuid": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "currency": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "api_public_key": {
                "type": "string"
              },
              "api_secret_key": {
                "type": "string"
              }
            }
          }
        }
      },
      "AddSeatsRequest": {
        "type": "object",
        "required": [
          "seats"
        ],
        "properties": {
          "seats": {
            "type": "integer",
            "minimum": 1,
            "maximum": 500,
            "description": "Plus seats to grant, or add when a partner grant is already active."
          },
          "months": {
            "type": "integer",
            "minimum": 1,
            "maximum": 24,
            "default": 1,
            "description": "Length of the Plus period. Used on the **first** grant only; ignored when adding seats mid-period (remaining time is prorated)."
          }
        },
        "example": {
          "seats": 3,
          "months": 1
        }
      },
      "AddCreditsRequest": {
        "type": "object",
        "required": [
          "credits"
        ],
        "properties": {
          "credits": {
            "type": "number",
            "minimum": 1,
            "maximum": 1000000,
            "description": "Holding credits to transfer to the business at 1:1."
          }
        },
        "example": {
          "credits": 500
        }
      },
      "PartnerAllocation": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string"
          },
          "allocation_type": {
            "type": "string",
            "enum": [
              "seats",
              "credits"
            ]
          },
          "quantity": {
            "type": "integer",
            "description": "Holding credits charged (rounded up)."
          },
          "seats": {
            "type": "integer",
            "nullable": true
          },
          "months": {
            "type": "integer",
            "nullable": true
          },
          "prorated": {
            "type": "boolean"
          },
          "proration_factor": {
            "type": "number",
            "nullable": true
          },
          "resulting_seats": {
            "type": "integer",
            "nullable": true
          },
          "subscription_reference": {
            "type": "string"
          },
          "subscription_starts_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "subscription_expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "meta": {
            "type": "object",
            "properties": {
              "holding_credits_charged": {
                "type": "number"
              },
              "credits_granted": {
                "type": "number"
              }
            }
          }
        }
      },
      "AddSeatsSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "allocation": {
                "$ref": "#/components/schemas/PartnerAllocation"
              },
              "holding_credits_charged": {
                "type": "number"
              },
              "partner_holding_balance": {
                "type": "number"
              },
              "subscription_expires_at": {
                "type": "string",
                "format": "date-time"
              },
              "resulting_seats": {
                "type": "integer"
              },
              "transaction_credits_granted": {
                "type": "number"
              }
            }
          }
        }
      },
      "AddCreditsSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "allocation": {
                "$ref": "#/components/schemas/PartnerAllocation"
              },
              "holding_credits_charged": {
                "type": "number"
              },
              "partner_holding_balance": {
                "type": "number"
              },
              "business_credit_balance": {
                "type": "number"
              }
            }
          }
        }
      },
      "ReferredBusinessBillingStatus": {
        "type": "object",
        "properties": {
          "business_uuid": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "billing_currency": {
            "type": "string"
          },
          "subscription_status": {
            "type": "string",
            "description": "`active`, `cancelling`, or `inactive` for partner-provided Plus."
          },
          "available_seats": {
            "type": "integer",
            "description": "Licensed Plus seats from your partner grant. `0` when no active partner grant."
          },
          "subscription_plan": {
            "type": "string",
            "nullable": true
          },
          "credit_balance": {
            "type": "number"
          },
          "subscription_expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "credit_from_referral_partner": {
            "type": "boolean"
          },
          "gateway": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ReferredBusinessListItem": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "credit_from_referral_partner": {
            "type": "boolean"
          },
          "is_subscribed_to_adam": {
            "type": "boolean"
          },
          "billing_currency": {
            "type": "string"
          },
          "subscription_status": {
            "type": "string"
          },
          "available_seats": {
            "type": "integer"
          },
          "subscription_plan": {
            "type": "string",
            "nullable": true
          },
          "credit_balance": {
            "type": "number"
          },
          "subscription_expires_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "gateway": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ValidateBusinessSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "uuid": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "logo": {
                "type": "string",
                "nullable": true
              },
              "currency": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "timezone": {
                "type": "string"
              }
            }
          }
        }
      },
      "PaymentLine": {
        "type": "object",
        "required": [
          "amount_paid",
          "category",
          "date"
        ],
        "properties": {
          "uuid": {
            "type": "string",
            "description": "Include to update an existing payment."
          },
          "amount_paid": {
            "type": "number"
          },
          "category": {
            "type": "string",
            "description": "Payment method / category (e.g. Cash, Bank Transfer)."
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "exchange_rate": {
            "type": "number"
          }
        }
      },
      "PaymentsRequest": {
        "type": "object",
        "required": [
          "payments"
        ],
        "properties": {
          "payments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentLine"
            }
          },
          "overwrite": {
            "type": "boolean",
            "default": false,
            "description": "If true, replaces all existing payments."
          }
        }
      },
      "BankTransactionUploadRequest": {
        "type": "object",
        "example": {
          "prompt": "Record debit 2024-01-10 -250.00 Office supplies STAPLES ref 7788; credit 2024-01-12 +2000.00 ACH Client ACME",
          "bank": "your-bank-uuid-here",
          "process_type": "async"
        },
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string"
          },
          "attachments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Attachment"
            }
          },
          "bank": {
            "type": "string",
            "description": "Bank account UUID."
          },
          "text_attachment": {
            "type": "string"
          },
          "process_type": {
            "type": "string",
            "enum": [
              "async",
              "direct"
            ]
          },
          "apply_adam_rule": {
            "type": "boolean",
            "default": true
          },
          "date_format": {
            "type": "string",
            "default": "Y-m-d"
          },
          "bank_statement_uuid": {
            "type": "string"
          }
        }
      },
      "BankTransactionUpdate": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "narration": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "account": {
            "type": "string"
          },
          "link_destination": {
            "type": "string"
          }
        }
      },
      "ContactUpdate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        }
      },
      "InvoiceUpdate": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "due_date": {
            "type": "string",
            "format": "date"
          },
          "narration": {
            "type": "string"
          },
          "record_items": {
            "type": "array",
            "items": {}
          }
        }
      },
      "AccountUpdate": {
        "type": "object",
        "properties": {
          "account_number": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "parent": {
            "type": "string",
            "description": "Parent account name, or empty to clear."
          },
          "opening_balance": {
            "type": "number"
          },
          "opening_balance_date": {
            "type": "string"
          },
          "opening_balance_exchange_rate": {
            "type": "number"
          }
        }
      },
      "AdamSuccessResponse": {
        "type": "object",
        "required": [
          "status",
          "message"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "description": "Single resource, array of resources, statement sections, or async job metadata — see each operation's example."
          },
          "meta": {
            "type": "object",
            "additionalProperties": true,
            "description": "Pagination (`page`, `limit`, `total`) and/or report range (`from`, `to`). Cash flow may include `previous_period_end`."
          }
        }
      },
      "OAuthAuthorizationSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "success"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "authorization_url": {
                "type": "string",
                "description": "HTTPS URL to redirect the user for Tyms sign-in and business selection."
              }
            }
          }
        }
      },
      "OAuthAccessTokenRequest": {
        "type": "object",
        "required": [
          "authorization_code",
          "business_id"
        ],
        "properties": {
          "authorization_code": {
            "type": "string"
          },
          "business_id": {
            "type": "string"
          }
        }
      },
      "OAuthRefreshTokenRequest": {
        "type": "object",
        "required": [
          "refresh_token",
          "business_id"
        ],
        "properties": {
          "refresh_token": {
            "type": "string"
          },
          "business_id": {
            "type": "string"
          }
        }
      },
      "OAuthRevokeTokenRequest": {
        "type": "object",
        "required": [
          "business_id"
        ],
        "properties": {
          "business_id": {
            "type": "string"
          },
          "access_token": {
            "type": "string"
          },
          "refresh_token": {
            "type": "string",
            "description": "Provide `access_token` or `refresh_token` (or both)."
          }
        }
      },
      "OAuthTokenSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "access_token": {
                "type": "string"
              },
              "refresh_token": {
                "type": "string"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              },
              "token_type": {
                "type": "string",
                "example": "Bearer"
              },
              "business_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "OAuthValidateSuccess": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "properties": {
              "uuid": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "email": {
                "type": "string"
              },
              "logo": {
                "type": "string",
                "nullable": true
              },
              "currency": {
                "type": "string"
              },
              "country": {
                "type": "string"
              },
              "timezone": {
                "type": "string"
              },
              "authentication_method": {
                "type": "string",
                "example": "oauth"
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "ManualDocumentLineItem": {
        "type": "object",
        "required": [
          "item_name",
          "quantity",
          "selling_price",
          "category"
        ],
        "properties": {
          "item_name": {
            "type": "string",
            "description": "Line label. Alias: `name`."
          },
          "quantity": {
            "type": "number",
            "description": "Quantity sold or purchased."
          },
          "selling_price": {
            "type": "number",
            "description": "Unit price. On bills this is unit cost. Alias: `price`."
          },
          "category": {
            "type": "string",
            "description": "Required. Revenue, expense, or inventory account — name, uuid, or account code."
          },
          "description": {
            "type": "string",
            "description": "Optional line description."
          },
          "tax": {
            "type": "number",
            "description": "Tax rate as a percentage (e.g. `7.5` = 7.5%). Preferred over `tax_uuid`."
          },
          "tax_uuid": {
            "type": "string",
            "description": "Optional tax record uuid instead of `tax` percentage."
          },
          "withholding_tax": {
            "type": "number",
            "description": "Withholding tax (WHT) rate as a percentage."
          },
          "withholding_tax_uuid": {
            "type": "string",
            "description": "Optional WHT uuid instead of `withholding_tax` percentage."
          },
          "discount": {
            "type": "number",
            "description": "Line discount value."
          },
          "discount_type": {
            "type": "string",
            "enum": [
              "percent",
              "amount",
              "fixed"
            ],
            "description": "`percent` or `amount` / `fixed`."
          },
          "is_inventory": {
            "type": "boolean",
            "description": "`true` if the line affects stock."
          },
          "uuid": {
            "type": "string",
            "description": "Existing inventory item uuid when linking stock."
          }
        }
      },
      "ManualInvoiceCreate": {
        "type": "object",
        "required": [
          "date",
          "document_due",
          "currency",
          "items"
        ],
        "example": {
          "date": "2026-03-01",
          "document_due": "2026-03-15",
          "currency": "NGN",
          "document_number": "INV-1042",
          "narration": "Website design services — March",
          "customer": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
          "status": "pending",
          "amount_paid": 0,
          "items": [
            {
              "item_name": "UI/UX design",
              "quantity": 1,
              "selling_price": 100000,
              "category": "Design Income",
              "tax": 7.5
            },
            {
              "item_name": "Implementation support",
              "quantity": 1,
              "selling_price": 50000,
              "category": "Service Income",
              "tax": 7.5,
              "discount": 5,
              "discount_type": "percent"
            }
          ]
        },
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Invoice date."
          },
          "document_due": {
            "type": "string",
            "format": "date",
            "description": "Due date. Alias: `due_date`."
          },
          "currency": {
            "type": "string",
            "description": "Currency code, e.g. `NGN`."
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ManualDocumentLineItem"
            },
            "description": "Line items. Document total is computed from here."
          },
          "customer": {
            "type": "string",
            "description": "Contact uuid, name, or email. Aliases: `contact`, `contact_uuid`, `vendor`."
          },
          "document_number": {
            "type": "string",
            "description": "Invoice number. Auto-suggested if omitted."
          },
          "narration": {
            "type": "string",
            "description": "Document title. Alias: `title`."
          },
          "memo": {
            "type": "string",
            "description": "Internal note. Alias: `note`."
          },
          "document_note": {
            "type": "string",
            "description": "Note printed on the invoice."
          },
          "status": {
            "type": "string",
            "description": "Default `pending`. Use `draft` to save without posting."
          },
          "exchange_rate": {
            "type": "number",
            "description": "Default `1`."
          },
          "shipping_fee": {
            "type": "number",
            "description": "Shipping amount added to the invoice."
          },
          "receivable_account": {
            "type": "string",
            "description": "Accounts receivable control account — name, uuid, or code."
          },
          "amount_paid": {
            "type": "number",
            "description": "Payment collected on create. `0` or omit for unpaid."
          },
          "payment_category": {
            "type": "string",
            "description": "Cash or bank account **name** when recording payment on create. Aliases: `paid_through`, `payment_account`."
          }
        }
      },
      "ManualBillCreate": {
        "type": "object",
        "required": [
          "date",
          "document_due",
          "currency",
          "items"
        ],
        "example": {
          "date": "2026-03-02",
          "document_due": "2026-03-16",
          "currency": "NGN",
          "document_number": "BILL-550",
          "narration": "Office supplies — Q1 restock",
          "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
          "payment_category": "Petty Cash",
          "amount_paid": 42000,
          "items": [
            {
              "item_name": "Printer paper A4",
              "quantity": 10,
              "selling_price": 3200,
              "category": "Office Supplies",
              "tax": 0
            },
            {
              "item_name": "Toner cartridge",
              "quantity": 1,
              "selling_price": 10000,
              "category": "Office Supplies"
            }
          ]
        },
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Bill date."
          },
          "document_due": {
            "type": "string",
            "format": "date",
            "description": "Payment due date. Alias: `due_date`."
          },
          "currency": {
            "type": "string",
            "description": "Currency code."
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ManualDocumentLineItem"
            }
          },
          "customer": {
            "type": "string",
            "description": "Vendor uuid, name, or email. Alias: `vendor`."
          },
          "document_number": {
            "type": "string",
            "description": "Bill reference. Alias: `bill_no`."
          },
          "narration": {
            "type": "string",
            "description": "Document title."
          },
          "memo": {
            "type": "string",
            "description": "Internal note."
          },
          "payable_account": {
            "type": "string",
            "description": "Optional accounts payable control account."
          },
          "amount_paid": {
            "type": "number",
            "description": "Amount paid now. Omit for an open bill."
          },
          "payment_category": {
            "type": "string",
            "description": "Cash or bank account **name** payment came from."
          },
          "exchange_rate": {
            "type": "number",
            "description": "Default `1`."
          },
          "status": {
            "type": "string",
            "description": "Default `pending`. Use `draft` to save without posting."
          }
        }
      },
      "ManualExpenseCreate": {
        "type": "object",
        "required": [
          "date",
          "items",
          "payment_category"
        ],
        "example": {
          "date": "2026-03-03",
          "currency": "NGN",
          "document_number": "EXP-220",
          "narration": "Team lunch — client meeting",
          "customer": "c9b8a7d6e5f4438290a1b2c3d4e5f6c0",
          "payment_category": "Main Operating Account",
          "items": [
            {
              "item_name": "Meals and entertainment",
              "quantity": 1,
              "selling_price": 18500,
              "category": "Meals & Entertainment"
            }
          ]
        },
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Expense date."
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ManualDocumentLineItem"
            }
          },
          "payment_category": {
            "type": "string",
            "description": "Cash or bank **name** paid from. Payment is assumed in full from the line totals — do not send `amount_paid` (that key is only for invoices and bills)."
          },
          "currency": {
            "type": "string"
          },
          "customer": {
            "type": "string"
          },
          "document_number": {
            "type": "string",
            "description": "Alias: `bill_no`."
          },
          "narration": {
            "type": "string"
          },
          "is_prepayment": {
            "type": "boolean",
            "description": "Set `true` (or `1`) to create a `prepaid_expenses` record instead of a regular expense. The expense amount is deferred and recognized monthly over `prepayment_duration`."
          },
          "prepayment_duration": {
            "type": "integer",
            "description": "Number of months to recognize the prepaid expense over. Required when `is_prepayment` is true."
          },
          "prepayment_account": {
            "type": "string",
            "description": "Asset account name for the prepaid balance. Defaults to the business prepaid expenses account."
          }
        }
      },
      "ManualIncomeCreate": {
        "type": "object",
        "required": [
          "date",
          "items",
          "payment_category"
        ],
        "example": {
          "date": "2026-03-04",
          "currency": "NGN",
          "document_number": "RCT-881",
          "narration": "Walk-in sale — March 4",
          "customer": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
          "payment_category": "Cash on Hand",
          "items": [
            {
              "item_name": "Consulting package",
              "quantity": 1,
              "selling_price": 75000,
              "category": "Service Income",
              "tax": 7.5
            }
          ]
        },
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ManualDocumentLineItem"
            }
          },
          "payment_category": {
            "type": "string",
            "description": "Cash or bank **name** received into. Payment is assumed in full from the line totals — do not send `amount_paid` (that key is only for invoices and bills)."
          },
          "currency": {
            "type": "string"
          },
          "customer": {
            "type": "string"
          },
          "document_number": {
            "type": "string",
            "description": "Returned as `receipt_no`."
          },
          "narration": {
            "type": "string"
          },
          "is_prepayment": {
            "type": "boolean",
            "description": "Set `true` (or `1`) to create a `prepaid_income` record (unearned revenue). The income is deferred and recognized monthly over `prepayment_duration`."
          },
          "prepayment_duration": {
            "type": "integer",
            "description": "Number of months to recognize the prepaid income over. Required when `is_prepayment` is true."
          },
          "prepayment_account": {
            "type": "string",
            "description": "Liability account name (unearned revenue) for the deferred balance. Defaults to the business unearned revenue account."
          }
        }
      },
      "ManualJournalLineItem": {
        "type": "object",
        "required": [
          "category"
        ],
        "properties": {
          "category": {
            "type": "string",
            "description": "Account name, uuid, or code. Alias: `account`."
          },
          "debit": {
            "type": "number"
          },
          "credit": {
            "type": "number"
          },
          "side": {
            "type": "string",
            "enum": [
              "debit",
              "credit"
            ]
          },
          "amount": {
            "type": "number"
          },
          "description": {
            "type": "string"
          },
          "tax": {
            "type": "number"
          },
          "tax_uuid": {
            "type": "string"
          }
        }
      },
      "ManualJournalCreate": {
        "type": "object",
        "required": [
          "description",
          "date",
          "items"
        ],
        "example": {
          "description": "Accrue March rent",
          "date": "2026-03-31",
          "journal_no": "JE-2026-031",
          "currency": "NGN",
          "status": "draft",
          "items": [
            {
              "category": "Rent Expense",
              "debit": 250000,
              "credit": 0,
              "description": "March office rent"
            },
            {
              "category": "Accrued Expenses",
              "debit": 0,
              "credit": 250000,
              "description": "March office rent accrual"
            }
          ]
        },
        "properties": {
          "description": {
            "type": "string",
            "description": "Journal title. Alias: `title`."
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "items": {
            "type": "array",
            "minItems": 2,
            "items": {
              "$ref": "#/components/schemas/ManualJournalLineItem"
            }
          },
          "journal_no": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Default `draft`. Use `published` to post."
          },
          "currency": {
            "type": "string"
          },
          "exchange_rate": {
            "type": "number"
          }
        }
      },
      "ManualContactCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "example": {
          "name": "Acme Supplies Ltd",
          "type": "vendor",
          "business_name": "Acme Supplies Limited",
          "email": "billing@acmesupplies.example",
          "phone": "+2348012345678",
          "address": "12 Industrial Avenue, Lagos",
          "tax_id": "RC-123456",
          "country": "NG",
          "contact_number": "VND-0091",
          "payment_terms": 14,
          "receivable_account": "Accounts Receivable",
          "payable_account": "Accounts Payable",
          "opening_balance": 0
        },
        "properties": {
          "name": {
            "type": "string",
            "description": "Contact display name."
          },
          "type": {
            "type": "string",
            "enum": [
              "customer",
              "vendor",
              "both"
            ]
          },
          "email": {
            "type": "string",
            "description": "Used to match existing contacts."
          },
          "phone": {
            "type": "string"
          },
          "business_name": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "tax_id": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "contact_number": {
            "type": "string"
          },
          "payment_terms": {
            "type": "number"
          },
          "receivable_account": {
            "type": "string"
          },
          "payable_account": {
            "type": "string"
          },
          "opening_balance": {
            "type": "number"
          },
          "opening_balance_date": {
            "type": "string",
            "format": "date"
          },
          "opening_balance_exchange_rate": {
            "type": "number"
          }
        }
      },
      "ManualAccountCreate": {
        "type": "object",
        "required": [
          "name",
          "type",
          "subtype"
        ],
        "example": {
          "name": "Software Subscriptions",
          "type": "Expenses",
          "subtype": "Expenses",
          "account_code": "6105",
          "description": "SaaS and cloud tools"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "`Assets`, `Liabilities`, `Equity`, `Revenue`, or `Expenses`."
          },
          "subtype": {
            "type": "string",
            "description": "From `GET /accounts/types`. Alias: `sub_type`."
          },
          "account_code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "parent_account_uuid": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "ManualBankTransactionCreate": {
        "type": "object",
        "required": [
          "bank",
          "amount",
          "type",
          "date",
          "narration"
        ],
        "example": {
          "bank": "f9e8d7c6b5a4438291f0e9d8c7b6a5948",
          "amount": 45000,
          "type": "debit",
          "date": "2026-03-06",
          "narration": "POS settlement — March 6",
          "balance": 1250000,
          "apply_adam_rule": true,
          "source": "manually_added"
        },
        "properties": {
          "bank": {
            "type": "string",
            "description": "Bank uuid. Alias: `bank_uuid`."
          },
          "amount": {
            "type": "number",
            "description": "Positive amount."
          },
          "type": {
            "type": "string",
            "enum": [
              "credit",
              "debit"
            ],
            "description": "`credit` = money in, `debit` = money out."
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "narration": {
            "type": "string"
          },
          "balance": {
            "type": "number"
          },
          "exchange_rate": {
            "type": "number"
          },
          "group_reference": {
            "type": "string"
          },
          "batch_id": {
            "type": "string"
          },
          "apply_bank_rules": {
            "type": "boolean"
          },
          "apply_adam_rule": {
            "type": "boolean"
          },
          "source": {
            "type": "string"
          }
        }
      },
      "ManualBankCreate": {
        "type": "object",
        "required": [
          "nuban",
          "account_name",
          "bank_name",
          "opening_balance",
          "opening_balance_date"
        ],
        "example": {
          "nuban": "0123456789",
          "account_name": "Acme Trading Limited",
          "bank_name": "Main Operating Account",
          "opening_balance": 1000000,
          "opening_balance_date": "2026-01-01",
          "account_code": "1001",
          "currency": "NGN",
          "country": "NG",
          "opening_balance_exchange_rate": 1
        },
        "properties": {
          "nuban": {
            "type": "string",
            "description": "Account number / NUBAN."
          },
          "account_name": {
            "type": "string",
            "description": "Legal account holder name."
          },
          "bank_name": {
            "type": "string",
            "description": "Unique display name for this bank in Tyms. Used as `payment_category` on transactions."
          },
          "opening_balance": {
            "type": "number",
            "description": "Opening balance amount (can be negative for overdraft)."
          },
          "opening_balance_date": {
            "type": "string",
            "format": "date",
            "description": "Date of the opening balance entry."
          },
          "account_code": {
            "type": "string",
            "description": "GL code; auto-assigned if omitted."
          },
          "currency": {
            "type": "string",
            "description": "Currency code; defaults to business currency."
          },
          "country": {
            "type": "string",
            "description": "Country code; defaults to business country."
          },
          "opening_balance_exchange_rate": {
            "type": "number",
            "description": "Exchange rate for the opening balance. Default `1`."
          }
        }
      },
      "ManualInventoryCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "example": {
          "name": "Wireless Mouse",
          "selling_price": 15000,
          "cost_price": 9000,
          "stock": 100,
          "unit": "pcs",
          "type": "product",
          "is_inventory": true,
          "currency": "NGN"
        },
        "properties": {
          "name": {
            "type": "string",
            "description": "Item name."
          },
          "selling_price": {
            "type": "number",
            "description": "Default selling price."
          },
          "cost_price": {
            "type": "number",
            "description": "Unit cost for COGS and stock valuation."
          },
          "stock": {
            "type": "number",
            "description": "Opening stock quantity."
          },
          "unit": {
            "type": "string",
            "description": "Unit of measure (e.g. `pcs`, `kg`)."
          },
          "is_inventory": {
            "type": "boolean",
            "description": "Set `true` to track stock movements. Omit for non-stocked services."
          },
          "type": {
            "type": "string",
            "enum": [
              "product",
              "service"
            ],
            "description": "Item type."
          },
          "currency": {
            "type": "string",
            "description": "Item currency; defaults to business currency."
          },
          "description": {
            "type": "string",
            "description": "Item description."
          },
          "category": {
            "type": "string",
            "description": "Revenue account name/uuid/code for sales lines."
          },
          "category_cost": {
            "type": "string",
            "description": "Expense or COGS account name/uuid/code for cost lines."
          }
        }
      },
      "ManualAssetCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "example": {
          "name": "Dell Laptop",
          "date": "2026-02-01",
          "amount": 850000,
          "amount_paid": 850000,
          "payment_category": "Main Operating Account",
          "description": "Engineering laptop",
          "status": "active"
        },
        "properties": {
          "name": {
            "type": "string",
            "description": "Asset name. Alias: `title`."
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Acquisition date."
          },
          "amount": {
            "type": "number",
            "description": "Asset cost / purchase price."
          },
          "amount_paid": {
            "type": "number",
            "description": "Cash paid on acquisition."
          },
          "payment_category": {
            "type": "string",
            "description": "Cash or bank name used to pay for the asset."
          },
          "description": {
            "type": "string",
            "description": "Asset description."
          },
          "status": {
            "type": "string",
            "description": "Default `active`."
          }
        }
      },
      "ManualQuoteCreate": {
        "type": "object",
        "required": [
          "date",
          "items"
        ],
        "example": {
          "date": "2026-04-01",
          "expiry_date": "2026-04-30",
          "currency": "NGN",
          "document_number": "QUO-0021",
          "narration": "Website redesign proposal",
          "customer": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
          "items": [
            {
              "item_name": "UI/UX Design",
              "quantity": 1,
              "selling_price": 200000,
              "category": "Design Income"
            }
          ]
        },
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Quote date."
          },
          "expiry_date": {
            "type": "string",
            "format": "date",
            "description": "Optional expiry date for the quote."
          },
          "currency": {
            "type": "string",
            "description": "Currency code."
          },
          "document_number": {
            "type": "string",
            "description": "Quote number; auto-assigned if omitted."
          },
          "narration": {
            "type": "string",
            "description": "Quote title / description."
          },
          "memo": {
            "type": "string",
            "description": "Internal note."
          },
          "document_note": {
            "type": "string",
            "description": "Note shown on the printed quote."
          },
          "customer": {
            "type": "string",
            "description": "Contact uuid, name, or email."
          },
          "exchange_rate": {
            "type": "number",
            "description": "Default `1`."
          },
          "shipping_fee": {
            "type": "number",
            "description": "Shipping amount."
          },
          "status": {
            "type": "string",
            "description": "Default `draft`."
          },
          "branch_uuid": {
            "type": "string",
            "nullable": true
          },
          "department_uuid": {
            "type": "string",
            "nullable": true
          },
          "project_uuid": {
            "type": "string",
            "nullable": true
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ManualDocumentLineItem"
            },
            "description": "Line items. Total is computed from lines."
          }
        }
      },
      "ManualPurchaseOrderCreate": {
        "type": "object",
        "required": [
          "date",
          "items"
        ],
        "example": {
          "date": "2026-04-05",
          "delivery_date": "2026-04-20",
          "currency": "NGN",
          "document_number": "PO-0042",
          "narration": "Q2 stock replenishment",
          "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
          "items": [
            {
              "item_name": "Wireless Mouse",
              "quantity": 50,
              "selling_price": 9000,
              "category": "Inventory"
            }
          ]
        },
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "Purchase order date."
          },
          "delivery_date": {
            "type": "string",
            "format": "date",
            "description": "Expected delivery date."
          },
          "currency": {
            "type": "string",
            "description": "Currency code."
          },
          "document_number": {
            "type": "string",
            "description": "PO number; auto-assigned if omitted."
          },
          "narration": {
            "type": "string",
            "description": "PO title / description."
          },
          "memo": {
            "type": "string",
            "description": "Internal note."
          },
          "customer": {
            "type": "string",
            "description": "Vendor contact uuid, name, or email. Alias: `vendor`."
          },
          "exchange_rate": {
            "type": "number",
            "description": "Default `1`."
          },
          "status": {
            "type": "string",
            "description": "Default `draft`."
          },
          "branch_uuid": {
            "type": "string",
            "nullable": true
          },
          "department_uuid": {
            "type": "string",
            "nullable": true
          },
          "project_uuid": {
            "type": "string",
            "nullable": true
          },
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/ManualDocumentLineItem"
            },
            "description": "Line items."
          }
        }
      },
      "ManualDepartmentCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "example": {
          "name": "Marketing",
          "branch_uuid": null
        },
        "properties": {
          "name": {
            "type": "string",
            "description": "Department name."
          },
          "branch_uuid": {
            "type": "string",
            "nullable": true,
            "description": "Optional parent branch uuid."
          }
        }
      },
      "ManualProjectCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "example": {
          "name": "Website Redesign",
          "description": "Q1 redesign for Acme",
          "customer_uuid": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
          "start_date": "2026-01-15",
          "end_date": "2026-04-15",
          "currency": "NGN",
          "cost": 500000,
          "status": "active"
        },
        "properties": {
          "name": {
            "type": "string",
            "description": "Project title."
          },
          "description": {
            "type": "string",
            "description": "Project details."
          },
          "customer_uuid": {
            "type": "string",
            "description": "Linked customer contact uuid."
          },
          "start_date": {
            "type": "string",
            "format": "date"
          },
          "end_date": {
            "type": "string",
            "format": "date"
          },
          "cost": {
            "type": "number",
            "description": "Budget or target cost."
          },
          "currency": {
            "type": "string"
          },
          "exchange_rate": {
            "type": "number"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "active",
              "on_hold",
              "paused",
              "completed"
            ],
            "description": "Project status."
          },
          "revenue_recognition_method": {
            "type": "string",
            "description": "Advanced revenue recognition method."
          },
          "revenue_recognition_point": {
            "type": "string",
            "description": "Point at which revenue is recognized."
          },
          "revenue_holding_account": {
            "type": "string",
            "description": "Account to hold deferred revenue."
          },
          "project_group_uuid": {
            "type": "string",
            "nullable": true,
            "description": "Optional project group."
          }
        }
      },
      "ManualBranchCreate": {
        "type": "object",
        "required": [
          "name",
          "address",
          "state",
          "country"
        ],
        "example": {
          "name": "Lagos HQ",
          "address": "12 Adeola Odeku, Victoria Island",
          "state": "Lagos",
          "country": "NG",
          "phone": "+2348011111111",
          "email": "lagos@acme.example"
        },
        "properties": {
          "name": {
            "type": "string",
            "description": "Branch name."
          },
          "address": {
            "type": "string",
            "description": "Street address."
          },
          "state": {
            "type": "string",
            "description": "State or region."
          },
          "country": {
            "type": "string",
            "description": "Country code."
          },
          "phone": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "logo": {
            "type": "string",
            "description": "Base64-encoded logo when overriding branding."
          },
          "override_main_business_logo": {
            "type": "boolean",
            "description": "When `true`, uses `logo` instead of the business logo on branch documents."
          }
        }
      }
    }
  },
  "security": [
    {
      "apiKey": []
    }
  ],
  "paths": {
    "/oauth/authorization": {
      "get": {
        "operationId": "oauthAuthorization",
        "tags": [
          "OAuth"
        ],
        "summary": "Get authorization URL",
        "description": "Start the OAuth flow. Returns an HTTPS URL to redirect the user for Tyms sign-in and business selection.",
        "security": [],
        "parameters": [
          {
            "name": "client_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Your app public key (`tyms_pk_...`)."
          },
          {
            "name": "redirect_uri",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "HTTPS callback URL on your app."
          },
          {
            "name": "reference",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Your correlation id for this authorization attempt."
          },
          {
            "name": "privacy_url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Link to your app's privacy policy."
          },
          {
            "name": "terms_url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Link to your app's terms of service."
          }
        ],
        "responses": {
          "200": {
            "description": "Authorization URL for user redirect",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthAuthorizationSuccess"
                },
                "example": {
                  "status": "success",
                  "message": "Authorization request initiated successfully",
                  "data": {
                    "authorization_url": "https://app.usetyms.com/auth/oauth/self?client_id=tyms_pk_example&redirect_uri=https%3A%2F%2Fyourapp.com%2Foauth%2Fcallback&reference=conn_abc123"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid client id or parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "message": "Invalid client id"
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Note>Guide: [OAuth 2.0](/oauth). No API key on this request — only query parameters.</Note>"
        }
      }
    },
    "/oauth/access/token": {
      "post": {
        "operationId": "oauthAccessToken",
        "tags": [
          "OAuth"
        ],
        "summary": "Exchange authorization code",
        "description": "Exchange a single-use authorization code for access and refresh tokens. Requires your app **secret key** in `X-API-Key`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OAuthAccessTokenRequest"
              },
              "example": {
                "authorization_code": "AD_example",
                "business_id": "business-uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Access and refresh tokens",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthTokenSuccess"
                },
                "example": {
                  "status": "success",
                  "message": "Business access token retrieved successfully",
                  "data": {
                    "access_token": "oauth_access_token",
                    "refresh_token": "oauth_refresh_token",
                    "expires_at": "2026-06-16T15:30:00+00:00",
                    "token_type": "Bearer",
                    "business_id": "business-uuid"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Expired or invalid authorization code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "message": "Authorization code expired"
                }
              }
            }
          },
          "401": {
            "description": "Invalid app secret key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Note>Send your integration app `tyms_sk_...` in `X-API-Key` (or `api-key` / `sk`). Access tokens expire after **60 minutes**.</Note>"
        }
      }
    },
    "/oauth/refresh/token": {
      "post": {
        "operationId": "oauthRefreshToken",
        "tags": [
          "OAuth"
        ],
        "summary": "Refresh access token",
        "description": "Obtain a new access token using a refresh token. Requires your app **secret key** in `X-API-Key`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OAuthRefreshTokenRequest"
              },
              "example": {
                "refresh_token": "oauth_refresh_token",
                "business_id": "business-uuid"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New access and refresh tokens",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthTokenSuccess"
                },
                "example": {
                  "status": "success",
                  "message": "Business access token retrieved successfully",
                  "data": {
                    "access_token": "new_oauth_access_token",
                    "refresh_token": "new_oauth_refresh_token",
                    "expires_at": "2026-06-16T16:30:00+00:00",
                    "token_type": "Bearer",
                    "business_id": "business-uuid"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid refresh token or app secret",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/oauth/revoke/token": {
      "post": {
        "operationId": "oauthRevokeToken",
        "tags": [
          "OAuth"
        ],
        "summary": "Revoke access",
        "description": "Revoke an access or refresh token when a user disconnects your app. Requires your app **secret key** in `X-API-Key`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OAuthRevokeTokenRequest"
              },
              "example": {
                "business_id": "business-uuid",
                "refresh_token": "oauth_refresh_token"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Token revoked successfully",
                  "data": {}
                }
              }
            }
          }
        }
      }
    },
    "/oauth/token/validate": {
      "get": {
        "operationId": "oauthTokenValidate",
        "tags": [
          "OAuth"
        ],
        "summary": "Validate OAuth session",
        "description": "Validate the current OAuth access token and return authorized business profile fields.",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Bearer OAuth access token from exchange or refresh."
          }
        ],
        "responses": {
          "200": {
            "description": "Authorized business profile",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthValidateSuccess"
                },
                "example": {
                  "status": "success",
                  "message": "Business validated successfully",
                  "data": {
                    "uuid": "business-uuid",
                    "name": "Acme LLC",
                    "email": "owner@example.com",
                    "logo": null,
                    "currency": "USD",
                    "country": "US",
                    "timezone": "America/New_York",
                    "authentication_method": "oauth",
                    "expires_at": "2026-06-16T15:30:00+00:00"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing app secret, or invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "message": "App secret required with Bearer"
                }
              }
            }
          },
          "403": {
            "description": "Subscription or access revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Warning>Send **both** `X-API-Key` (your app `tyms_sk_...`) and `Authorization: Bearer <access_token>`. Same requirement applies to all other business-scoped endpoints when using OAuth.</Warning>"
        }
      }
    },
    "/register-business": {
      "post": {
        "operationId": "registerBusiness",
        "tags": [
          "Partners"
        ],
        "summary": "Register business",
        "description": "Create a new Tyms business using a **partner** API key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterBusinessRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Business created; `api_secret_key` only when `grant_access` is `admin`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegisterBusinessSuccess"
                },
                "example": {
                  "status": "success",
                  "message": "Business registered successfully.",
                  "data": {
                    "business_uuid": "550e8400-e29b-41d4-a716-446655440000",
                    "name": "Smith Enterprises",
                    "currency": "USD",
                    "country": "US",
                    "api_public_key": "tyms_pk_example",
                    "api_secret_key": "tyms_sk_example"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid partner key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "message": "Invalid partner API key. Use your distributor partner secret, not a business tyms_sk key."
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Warning>Call with your **partner** API key in `X-API-Key`. Do not use a business `tyms_sk_` key. After success, use the returned **`api_secret_key`** for all other endpoints.</Warning>"
        }
      }
    },
    "/referred-businesses": {
      "get": {
        "operationId": "listReferredBusinesses",
        "tags": [
          "Partners"
        ],
        "summary": "List referred businesses",
        "description": "Paginated list of businesses you referred, with a billing snapshot on each row.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Referred businesses page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Referred businesses retrieved successfully.",
                  "data": {
                    "current_page": 1,
                    "data": [
                      {
                        "uuid": "a1b2c3d4e5f6",
                        "name": "Smith Enterprises",
                        "email": "owner@example.com",
                        "currency": "USD",
                        "country": "US",
                        "credit_from_referral_partner": false,
                        "is_subscribed_to_adam": true,
                        "billing_currency": "USD",
                        "subscription_status": "active",
                        "available_seats": 3,
                        "subscription_plan": "plus",
                        "credit_balance": 450,
                        "subscription_expires_at": "2026-08-09T02:00:00.000000Z",
                        "gateway": "referral_partner"
                      }
                    ],
                    "per_page": 20,
                    "total": 1
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid partner key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Partner inactive",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Note>Partner key only. Each item includes identity fields plus the same billing snapshot as [Billing status](/api-reference/partners/get-referred-business-billing-status).</Note>"
        }
      }
    },
    "/referred-businesses/{business_uuid}/billing-status": {
      "get": {
        "operationId": "getReferredBusinessBillingStatus",
        "tags": [
          "Partners"
        ],
        "summary": "Billing status",
        "description": "Subscription state, licensed seats, plan, and AI credit balance for one referred business.",
        "parameters": [
          {
            "name": "business_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "UUID from register-business or your referred-businesses list."
          }
        ],
        "responses": {
          "200": {
            "description": "Billing snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Billing status retrieved successfully.",
                  "data": {
                    "business_uuid": "a1b2c3d4e5f6",
                    "name": "Smith Enterprises",
                    "billing_currency": "USD",
                    "subscription_status": "active",
                    "available_seats": 3,
                    "subscription_plan": "plus",
                    "credit_balance": 1250.5,
                    "subscription_expires_at": "2026-08-09T02:00:00.000000Z",
                    "credit_from_referral_partner": false,
                    "gateway": "referral_partner"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid partner key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Partner inactive or business not referred by you",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Business not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Note>`available_seats` counts only **partner-provided** Plus seats — `0` even if the business pays for Plus themselves. Call before [Add seats](/api-reference/partners/add-referred-business-seats) or [Add credits](/api-reference/partners/add-referred-business-credits).</Note>"
        }
      }
    },
    "/referred-businesses/{business_uuid}/add-seats": {
      "post": {
        "operationId": "addReferredBusinessSeats",
        "tags": [
          "Partners"
        ],
        "summary": "Add seats",
        "description": "Grant Plus seats from partner holding. First call activates Plus for the requested period; later calls add prorated seats for the remaining period.",
        "parameters": [
          {
            "name": "business_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddSeatsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Seats granted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddSeatsSuccess"
                },
                "example": {
                  "status": "success",
                  "message": "Plus seats granted successfully.",
                  "data": {
                    "allocation": {
                      "uuid": "f8e2a1b0c3d4",
                      "allocation_type": "seats",
                      "quantity": 450,
                      "seats": 3,
                      "months": 1,
                      "prorated": false,
                      "resulting_seats": 3,
                      "subscription_reference": "partner_alloc_9c4f2a",
                      "subscription_expires_at": "2026-08-09T02:00:00.000000Z",
                      "meta": {
                        "holding_credits_charged": 450,
                        "credits_granted": 450
                      }
                    },
                    "holding_credits_charged": 450,
                    "partner_holding_balance": 9550,
                    "subscription_expires_at": "2026-08-09T02:00:00.000000Z",
                    "transaction_credits_granted": 450
                  }
                }
              }
            }
          },
          "400": {
            "description": "Managed-credit business, existing self-paid subscription, or incompatible billing state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid partner key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient partner holding balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "message": "Insufficient partner credit holding.",
                  "error_code": "insufficient_partner_credit_holding"
                }
              }
            }
          },
          "403": {
            "description": "Partner inactive or business not referred by you",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Business not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Warning>Requires `credit_from_referral_partner: false` at registration. Holding cost: **150 × seats × months** on first grant (default 150 credits per seat per month). Adding seats mid-period is prorated. Fails if the business already has its own active Plus subscription.</Warning>"
        }
      }
    },
    "/referred-businesses/{business_uuid}/add-credits": {
      "post": {
        "operationId": "addReferredBusinessCredits",
        "tags": [
          "Partners"
        ],
        "summary": "Add credits",
        "description": "Transfer AI credits from partner holding to the business at 1:1. Does not require Plus. Transferred credits expire 12 months after grant.",
        "parameters": [
          {
            "name": "business_uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddCreditsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credits transferred",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddCreditsSuccess"
                },
                "example": {
                  "status": "success",
                  "message": "Credits granted successfully.",
                  "data": {
                    "allocation": {
                      "uuid": "c3d4e5f6",
                      "allocation_type": "credits",
                      "quantity": 500,
                      "subscription_reference": "partner_credit_7a8b9c",
                      "subscription_expires_at": "2027-07-09T02:00:00.000000Z",
                      "meta": {
                        "holding_credits_charged": 500,
                        "credits_granted": 500
                      }
                    },
                    "holding_credits_charged": 500,
                    "partner_holding_balance": 8825,
                    "business_credit_balance": 1250.5
                  }
                }
              }
            }
          },
          "400": {
            "description": "Managed-credit business or incompatible billing state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Invalid partner key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "402": {
            "description": "Insufficient partner holding balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "message": "Insufficient partner credit holding.",
                  "error_code": "insufficient_partner_credit_holding"
                }
              }
            }
          },
          "403": {
            "description": "Partner inactive or business not referred by you",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Business not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Note>1:1 transfer from holding to the business ledger. Use when plan credits run low or you prefer pay-as-you-go top-ups instead of [Add seats](/api-reference/partners/add-referred-business-seats). Blocked when `credit_from_referral_partner` is `true`.</Note>"
        }
      }
    },
    "/auth/validate": {
      "get": {
        "operationId": "validateBusiness",
        "tags": [
          "Authentication"
        ],
        "summary": "Validate business",
        "description": "Validate a **business** `tyms_sk_...` key and return business profile fields.",
        "responses": {
          "200": {
            "description": "Business profile for the authenticated key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidateBusinessSuccess"
                },
                "example": {
                  "status": "success",
                  "message": "Business validated successfully",
                  "data": {
                    "uuid": "business-uuid",
                    "name": "Business Name",
                    "email": "business@example.com",
                    "logo": "https://example.com/logo.png",
                    "currency": "USD",
                    "country": "US",
                    "timezone": "America/New_York"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "message": "Invalid API key. Please check your API key and try again."
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "<Note>Use a **business** `tyms_sk_...` key, not a partner key. After [Register business](/api-reference/partners/register-business), validate with that business's secret.</Note>"
        }
      }
    },
    "/accounts": {
      "get": {
        "operationId": "listAccounts",
        "tags": [
          "Chart of accounts"
        ],
        "summary": "List accounts",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by account type."
          }
        ],
        "responses": {
          "200": {
            "description": "Chart of accounts (minimal full COA structure)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Accounts retrieved successfully",
                  "data": [
                    {
                      "uuid": "acc-uuid-1",
                      "name": "Operating Expenses",
                      "type": "expense",
                      "description": "General operating costs",
                      "account_number": "6000"
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 20,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "The chart of accounts is the complete list of ledger accounts your business uses — assets, liabilities, equity, revenue, and expenses."
        }
      },
      "post": {
        "operationId": "createAccount",
        "tags": [
          "Chart of accounts"
        ],
        "summary": "Create account (AI)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AiCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI job accepted or completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Account creation request received and queued for processing",
                  "data": {
                    "process_type": "async",
                    "job_reference": "job_01HZXK8QEXAMPLE"
                  }
                }
              }
            }
          },
          "201": {
            "description": "Account created (`direct` mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Account created successfully",
                  "data": {
                    "uuid": "acc-new-1",
                    "name": "Software Subscriptions",
                    "type": "expense"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/accounts/{uuid}": {
      "get": {
        "operationId": "getAccount",
        "tags": [
          "Chart of accounts"
        ],
        "summary": "Get account",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Account UUID (preferred) or account name; bank accounts may resolve by UUID or name."
          }
        ],
        "responses": {
          "200": {
            "description": "Single account or bank-linked account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Account retrieved successfully",
                  "data": {
                    "uuid": "acc-uuid-1",
                    "name": "Operating Expenses",
                    "type": "expense",
                    "description": "General operating costs",
                    "account_number": "6000",
                    "parent": null
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        },
        "x-mint": {}
      },
      "put": {
        "operationId": "updateAccountPut",
        "tags": [
          "Chart of accounts"
        ],
        "summary": "Update account",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Account updated successfully",
                  "data": {
                    "uuid": "acc-uuid-1",
                    "description": "Updated description"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "patch": {
        "operationId": "updateAccountPatch",
        "tags": [
          "Chart of accounts"
        ],
        "summary": "Update account (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account updated (partial)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Account updated successfully",
                  "data": {
                    "uuid": "acc-uuid-1",
                    "description": "Updated description"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteAccount",
        "tags": [
          "Chart of accounts"
        ],
        "summary": "Delete account",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account removed (when allowed)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Account deleted successfully"
                }
              }
            }
          },
          "400": {
            "description": "Default account or restricted usage",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/invoices": {
      "get": {
        "operationId": "listInvoices",
        "tags": [
          "Invoices"
        ],
        "summary": "List invoices",
        "parameters": [
          {
            "name": "schema",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated invoice list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoices retrieved successfully",
                  "data": [
                    {
                      "uuid": "550e8400-e29b-41d4-a716-446655440001",
                      "date": "2024-01-15",
                      "due_date": "2024-02-15",
                      "narration": "Web development services",
                      "total_amount": 1000,
                      "amount_paid": 0,
                      "balance": 1000,
                      "currency": "USD",
                      "source_uuid": null
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 20,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "Invoices are amounts you bill customers for goods or services, creating accounts receivable until paid."
        }
      },
      "post": {
        "operationId": "createInvoice",
        "tags": [
          "Invoices"
        ],
        "summary": "Create invoice (AI)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AiCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI job accepted or completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoice creation request received and queued for processing",
                  "data": {
                    "process_type": "async",
                    "job_reference": "job_01HZXK8QEXAMPLE"
                  }
                }
              }
            }
          },
          "201": {
            "description": "Invoice created (`direct` mode)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoice created successfully",
                  "data": {
                    "uuid": "550e8400-e29b-41d4-a716-446655440001",
                    "narration": "Consulting services",
                    "total_amount": 1000
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/invoices/{uuid}": {
      "get": {
        "operationId": "getInvoice",
        "tags": [
          "Invoices"
        ],
        "summary": "Get invoice",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Invoice `uuid` or `source_uuid`."
          }
        ],
        "responses": {
          "200": {
            "description": "Single invoice",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoice retrieved successfully",
                  "data": {
                    "uuid": "550e8400-e29b-41d4-a716-446655440001",
                    "date": "2024-01-15",
                    "due_date": "2024-02-15",
                    "narration": "Web development services",
                    "total_amount": 1000,
                    "amount_paid": 250,
                    "balance": 750,
                    "currency": "USD",
                    "record_items": [],
                    "payments": []
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "put": {
        "operationId": "updateInvoicePut",
        "tags": [
          "Invoices"
        ],
        "summary": "Update invoice",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoice updated successfully",
                  "data": {
                    "uuid": "550e8400-e29b-41d4-a716-446655440001",
                    "narration": "Updated invoice description"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "patch": {
        "operationId": "updateInvoicePatch",
        "tags": [
          "Invoices"
        ],
        "summary": "Update invoice (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvoiceUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice updated (partial)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoice updated successfully",
                  "data": {
                    "uuid": "550e8400-e29b-41d4-a716-446655440001",
                    "narration": "Updated invoice description"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteInvoice",
        "tags": [
          "Invoices"
        ],
        "summary": "Delete invoice",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoice deleted successfully"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/invoices/{uuid}/payments": {
      "post": {
        "operationId": "updateInvoicePayments",
        "tags": [
          "Invoices"
        ],
        "summary": "Update invoice payments",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payments applied to invoice",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoice payments updated successfully",
                  "data": {
                    "uuid": "550e8400-e29b-41d4-a716-446655440001",
                    "payments": [
                      {
                        "uuid": "pay-uuid-1",
                        "amount_paid": 500,
                        "category": "Bank Transfer",
                        "date": "2024-01-20",
                        "exchange_rate": 1
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/bills": {
      "get": {
        "operationId": "listBills",
        "tags": [
          "Bills"
        ],
        "summary": "List bills",
        "parameters": [
          {
            "name": "schema",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated bill list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bills retrieved successfully",
                  "data": [
                    {
                      "uuid": "660e8400-e29b-41d4-a716-446655440002",
                      "date": "2024-01-10",
                      "due_date": "2024-02-10",
                      "narration": "Office supplies — XYZ Supplier",
                      "total_amount": 300,
                      "amount_paid": 0,
                      "balance": 300,
                      "currency": "USD"
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 20,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "Bills are vendor invoices your business owes. On bills, `customer` refers to the vendor."
        }
      },
      "post": {
        "operationId": "createBill",
        "tags": [
          "Bills"
        ],
        "summary": "Create bill (AI)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AiCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI job accepted or completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bill creation request received and queued for processing",
                  "data": {
                    "process_type": "async",
                    "job_reference": "job_01HZXK8QEXAMPLE"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/bills/{uuid}": {
      "get": {
        "operationId": "getBill",
        "tags": [
          "Bills"
        ],
        "summary": "Get bill",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single bill",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bill retrieved successfully",
                  "data": {
                    "uuid": "660e8400-e29b-41d4-a716-446655440002",
                    "date": "2024-01-10",
                    "due_date": "2024-02-10",
                    "narration": "Office supplies — XYZ Supplier",
                    "total_amount": 300,
                    "amount_paid": 0,
                    "balance": 300,
                    "currency": "USD"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "put": {
        "operationId": "updateBillPut",
        "tags": [
          "Bills"
        ],
        "summary": "Update bill",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bill updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bill updated successfully",
                  "data": {
                    "uuid": "660e8400-e29b-41d4-a716-446655440002",
                    "narration": "Updated bill narration"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "patch": {
        "operationId": "updateBillPatch",
        "tags": [
          "Bills"
        ],
        "summary": "Update bill (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bill updated (partial)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bill updated successfully",
                  "data": {
                    "uuid": "660e8400-e29b-41d4-a716-446655440002",
                    "narration": "Updated bill narration"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteBill",
        "tags": [
          "Bills"
        ],
        "summary": "Delete bill",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bill deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bill deleted successfully"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/bills/{uuid}/payments": {
      "post": {
        "operationId": "updateBillPayments",
        "tags": [
          "Bills"
        ],
        "summary": "Update bill payments",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payments applied to bill",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bill payments updated successfully",
                  "data": {
                    "uuid": "660e8400-e29b-41d4-a716-446655440002",
                    "payments": [
                      {
                        "amount_paid": 300,
                        "category": "Bank Transfer",
                        "date": "2024-01-25",
                        "exchange_rate": 1
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/expenses": {
      "get": {
        "operationId": "listExpenses",
        "tags": [
          "Expenses"
        ],
        "summary": "List expenses",
        "parameters": [
          {
            "name": "schema",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated expense list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Expenses retrieved successfully",
                  "data": [
                    {
                      "uuid": "770e8400-e29b-41d4-a716-446655440003",
                      "date": "2024-01-20",
                      "narration": "Client lunch meeting",
                      "amount": 50,
                      "currency": "USD"
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 20,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "Expenses are cash outflows paid immediately from cash or bank. They default to `status: paid`."
        }
      },
      "post": {
        "operationId": "createExpense",
        "tags": [
          "Expenses"
        ],
        "summary": "Create expense (AI)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AiCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI job accepted or completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Expense creation request received and queued for processing",
                  "data": {
                    "process_type": "async",
                    "job_reference": "job_01HZXK8QEXAMPLE"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/expenses/{uuid}": {
      "get": {
        "operationId": "getExpense",
        "tags": [
          "Expenses"
        ],
        "summary": "Get expense",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single expense",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Expense retrieved successfully",
                  "data": {
                    "uuid": "770e8400-e29b-41d4-a716-446655440003",
                    "date": "2024-01-20",
                    "narration": "Client lunch meeting",
                    "amount": 50,
                    "currency": "USD"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "put": {
        "operationId": "updateExpensePut",
        "tags": [
          "Expenses"
        ],
        "summary": "Update expense",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Expense updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Expense updated successfully",
                  "data": {
                    "uuid": "770e8400-e29b-41d4-a716-446655440003",
                    "narration": "Updated expense narration"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "patch": {
        "operationId": "updateExpensePatch",
        "tags": [
          "Expenses"
        ],
        "summary": "Update expense (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Expense updated (partial)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Expense updated successfully",
                  "data": {
                    "uuid": "770e8400-e29b-41d4-a716-446655440003",
                    "narration": "Updated expense narration"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteExpense",
        "tags": [
          "Expenses"
        ],
        "summary": "Delete expense",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expense deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Expense deleted successfully"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/income": {
      "get": {
        "operationId": "listIncome",
        "tags": [
          "Income"
        ],
        "summary": "List income",
        "parameters": [
          {
            "name": "schema",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated income list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Income records retrieved successfully",
                  "data": [
                    {
                      "uuid": "880e8400-e29b-41d4-a716-446655440004",
                      "date": "2024-01-18",
                      "narration": "Product sales",
                      "amount": 2000,
                      "currency": "USD"
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 20,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "Income records (sales receipts) are cash sales received without an open invoice. They default to `status: paid`. `document_number` is returned as `receipt_no`."
        }
      },
      "post": {
        "operationId": "createIncome",
        "tags": [
          "Income"
        ],
        "summary": "Create income (AI)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AiCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI job accepted or completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Income creation request received and queued for processing",
                  "data": {
                    "process_type": "async",
                    "job_reference": "job_01HZXK8QEXAMPLE"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/income/{uuid}": {
      "get": {
        "operationId": "getIncome",
        "tags": [
          "Income"
        ],
        "summary": "Get income",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single income record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Income record retrieved successfully",
                  "data": {
                    "uuid": "880e8400-e29b-41d4-a716-446655440004",
                    "date": "2024-01-18",
                    "narration": "Product sales",
                    "amount": 2000,
                    "currency": "USD"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "put": {
        "operationId": "updateIncomePut",
        "tags": [
          "Income"
        ],
        "summary": "Update income",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Income updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Income updated successfully",
                  "data": {
                    "uuid": "880e8400-e29b-41d4-a716-446655440004",
                    "narration": "Updated income narration"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "patch": {
        "operationId": "updateIncomePatch",
        "tags": [
          "Income"
        ],
        "summary": "Update income (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Income updated (partial)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Income updated successfully",
                  "data": {
                    "uuid": "880e8400-e29b-41d4-a716-446655440004",
                    "narration": "Updated income narration"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteIncome",
        "tags": [
          "Income"
        ],
        "summary": "Delete income",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Income deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Income deleted successfully"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/journals": {
      "get": {
        "operationId": "listJournals",
        "tags": [
          "Journals"
        ],
        "summary": "List journals",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated journal list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Journal entries retrieved successfully",
                  "data": [
                    {
                      "uuid": "990e8400-e29b-41d4-a716-446655440005",
                      "date": "2024-01-31",
                      "narration": "Monthly depreciation — office equipment",
                      "reference": "JE-2024-001"
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 20,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "Journal entries are debit-and-credit postings. Total debits must equal total credits."
        }
      },
      "post": {
        "operationId": "createJournal",
        "tags": [
          "Journals"
        ],
        "summary": "Create journal (AI)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AiCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI job accepted or completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Journal creation request received and queued for processing",
                  "data": {
                    "process_type": "async",
                    "job_reference": "job_01HZXK8QEXAMPLE"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/journals/{uuid}": {
      "get": {
        "operationId": "getJournal",
        "tags": [
          "Journals"
        ],
        "summary": "Get journal",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single journal entry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Journal entry retrieved successfully",
                  "data": {
                    "uuid": "990e8400-e29b-41d4-a716-446655440005",
                    "date": "2024-01-31",
                    "narration": "Monthly depreciation — office equipment",
                    "reference": "JE-2024-001",
                    "lines": []
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "put": {
        "operationId": "updateJournalPut",
        "tags": [
          "Journals"
        ],
        "summary": "Update journal",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Journal updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Journal updated successfully",
                  "data": {
                    "uuid": "990e8400-e29b-41d4-a716-446655440005",
                    "narration": "Updated journal narration"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "patch": {
        "operationId": "updateJournalPatch",
        "tags": [
          "Journals"
        ],
        "summary": "Update journal (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Journal updated (partial)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Journal updated successfully",
                  "data": {
                    "uuid": "990e8400-e29b-41d4-a716-446655440005",
                    "narration": "Updated journal narration"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteJournal",
        "tags": [
          "Journals"
        ],
        "summary": "Delete journal",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Journal deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Journal deleted successfully"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/contacts": {
      "get": {
        "operationId": "listContacts",
        "tags": [
          "Contacts"
        ],
        "summary": "List contacts",
        "parameters": [
          {
            "name": "schema",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated contact list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Contacts retrieved successfully",
                  "data": [
                    {
                      "uuid": "aa0e8400-e29b-41d4-a716-446655440006",
                      "name": "John Smith",
                      "email": "john@example.com",
                      "phone": "+1234567890",
                      "type": "customer"
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 20,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "Contacts are customers and vendors used on invoices, bills, and other transactions."
        }
      },
      "post": {
        "operationId": "createContact",
        "tags": [
          "Contacts"
        ],
        "summary": "Create contact (AI)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AiCreateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "AI job accepted or completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Contact creation request received and queued for processing",
                  "data": {
                    "process_type": "async",
                    "job_reference": "job_01HZXK8QEXAMPLE"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/contacts/{uuid}": {
      "get": {
        "operationId": "getContact",
        "tags": [
          "Contacts"
        ],
        "summary": "Get contact",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single contact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Contact retrieved successfully",
                  "data": {
                    "uuid": "aa0e8400-e29b-41d4-a716-446655440006",
                    "name": "John Smith",
                    "email": "john@example.com",
                    "phone": "+1234567890",
                    "address": "123 Main St",
                    "type": "customer"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "put": {
        "operationId": "updateContactPut",
        "tags": [
          "Contacts"
        ],
        "summary": "Update contact",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Contact updated successfully",
                  "data": {
                    "uuid": "aa0e8400-e29b-41d4-a716-446655440006",
                    "name": "John Smith"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "patch": {
        "operationId": "updateContactPatch",
        "tags": [
          "Contacts"
        ],
        "summary": "Update contact (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact updated (partial)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Contact updated successfully",
                  "data": {
                    "uuid": "aa0e8400-e29b-41d4-a716-446655440006",
                    "name": "John Smith"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteContact",
        "tags": [
          "Contacts"
        ],
        "summary": "Delete contact",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Contact deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Contact deleted successfully"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/banks": {
      "get": {
        "operationId": "listBanks",
        "tags": [
          "Banks"
        ],
        "summary": "List banks",
        "responses": {
          "200": {
            "description": "Bank accounts for the business",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Banks retrieved successfully",
                  "data": [
                    {
                      "uuid": "bb0e8400-e29b-41d4-a716-446655440007",
                      "name": "Chase Bank",
                      "account_name": "Business Account",
                      "currency": "USD",
                      "country": "US"
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 50,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "post": {
        "operationId": "createBank",
        "tags": [
          "Banks"
        ],
        "summary": "Create bank account",
        "description": "Create a new bank or cash account with an opening balance. The `bank_name` becomes the display name used as `payment_category` on transactions. `nuban`, `account_name`, `bank_name`, `opening_balance`, and `opening_balance_date` are required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualBankCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bank created with opening balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank created successfully with opening balance",
                  "data": {
                    "uuid": "f1e2d3c4b5a6478990a1b2c3d4e5f6aa",
                    "name": "Main Operating Account",
                    "nuban": "0123456789",
                    "account_name": "Acme Trading Limited",
                    "currency": "NGN",
                    "country": "NG",
                    "balance": 1000000,
                    "opening_balance": 1000000
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/banks/{uuid}": {
      "get": {
        "operationId": "getBank",
        "tags": [
          "Banks"
        ],
        "summary": "Get bank",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single bank account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank retrieved successfully",
                  "data": {
                    "uuid": "bank-uuid",
                    "name": "Chase Bank",
                    "nuban": "1234567890",
                    "account_name": "Business Account",
                    "currency": "USD",
                    "country": "US",
                    "balance": 10000,
                    "opening_balance": 5000
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteBank",
        "tags": [
          "Banks"
        ],
        "summary": "Delete bank account",
        "description": "Delete a bank account. Fails if the bank has non-opening-balance ledger activity or an uncleared opening balance remains.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Bank uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Bank deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank account deleted successfully",
                  "data": []
                }
              }
            }
          },
          "400": {
            "description": "Bank has non-opening-balance activity and cannot be deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/bank-transactions": {
      "get": {
        "operationId": "listBankTransactions",
        "tags": [
          "Bank transactions"
        ],
        "summary": "List bank transactions",
        "parameters": [
          {
            "name": "bank",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated bank transactions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank transactions retrieved successfully",
                  "data": [
                    {
                      "uuid": "cc0e8400-e29b-41d4-a716-446655440008",
                      "date": "2024-01-15",
                      "narration": "POS Coffee Shop",
                      "amount": -50,
                      "status": "uncategorized",
                      "currency": "USD"
                    }
                  ],
                  "meta": {
                    "page": 1,
                    "limit": 20,
                    "total": 1
                  }
                }
              }
            }
          }
        },
        "x-mint": {
          "content": "Bank transactions are individual statement lines — debits (money out) and credits (money in)."
        }
      },
      "post": {
        "operationId": "createBankTransaction",
        "tags": [
          "Bank transactions"
        ],
        "summary": "Create bank transaction",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualBankTransactionCreate"
              },
              "example": {
                "bank": "f9e8d7c6b5a4438291f0e9d8c7b6a5948",
                "amount": 45000,
                "type": "debit",
                "date": "2026-03-06",
                "narration": "POS settlement — March 6",
                "balance": 1250000,
                "exchange_rate": 1,
                "group_reference": "BATCH-20260306-01",
                "apply_adam_rule": true,
                "source": "manually_added"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank transaction created successfully",
                  "data": {
                    "uuid": "f6a7b8c9d0e1428290a1b2c3d4e5f6b8",
                    "type": "debit"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {},
        "description": "Manual single transaction. Requires an existing bank on the business."
      }
    },
    "/bank-transactions/upload": {
      "post": {
        "operationId": "uploadBankTransactions",
        "tags": [
          "Bank transactions"
        ],
        "summary": "Create bank transactions (AI)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BankTransactionUploadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Import queued (`async`) or extracted rows returned (`direct`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank transaction import queued for processing",
                  "data": {
                    "process_type": "async",
                    "job_reference": "job_01HZXK8QBANKTX"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing prompt or invalid body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "status": "failed",
                  "message": "The prompt field is required."
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/bank-transactions/{uuid}": {
      "get": {
        "operationId": "getBankTransaction",
        "tags": [
          "Bank transactions"
        ],
        "summary": "Get bank transaction",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single bank transaction",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank transaction retrieved successfully",
                  "data": {
                    "uuid": "cc0e8400-e29b-41d4-a716-446655440008",
                    "date": "2024-01-15",
                    "narration": "POS Coffee Shop",
                    "amount": -50,
                    "status": "categorized",
                    "account": "Meals & Entertainment",
                    "currency": "USD"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "put": {
        "operationId": "updateBankTransactionPut",
        "tags": [
          "Bank transactions"
        ],
        "summary": "Update bank transaction",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BankTransactionUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bank transaction updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank transaction updated successfully",
                  "data": {
                    "uuid": "cc0e8400-e29b-41d4-a716-446655440008",
                    "narration": "Updated description",
                    "status": "categorized"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "patch": {
        "operationId": "updateBankTransactionPatch",
        "tags": [
          "Bank transactions"
        ],
        "summary": "Update bank transaction (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BankTransactionUpdate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bank transaction updated (partial)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank transaction updated successfully",
                  "data": {
                    "uuid": "cc0e8400-e29b-41d4-a716-446655440008",
                    "narration": "Updated description"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      },
      "delete": {
        "operationId": "deleteBankTransaction",
        "tags": [
          "Bank transactions"
        ],
        "summary": "Delete bank transaction",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Bank transaction deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bank transaction deleted successfully"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/reports/income-statement": {
      "get": {
        "operationId": "getIncomeStatement",
        "tags": [
          "Reports"
        ],
        "summary": "Income statement",
        "parameters": [
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transaction_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contact",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "employee",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "creator",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "department",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "project",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "account",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cut_off_date",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Profit and loss (same basis as in-app reports)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Income statement generated successfully",
                  "data": {
                    "headings": [
                      {
                        "label": "Revenue",
                        "level": 1
                      }
                    ],
                    "content": [
                      {
                        "label": "Sales",
                        "amount": 12500.5,
                        "children": []
                      }
                    ],
                    "totals": {
                      "net_income": 4200
                    }
                  },
                  "meta": {
                    "from": "2024-01-01",
                    "to": "2024-03-31"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/reports/balance-sheet": {
      "get": {
        "operationId": "getBalanceSheet",
        "tags": [
          "Reports"
        ],
        "summary": "Balance sheet",
        "parameters": [
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transaction_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contact",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "employee",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "creator",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "department",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "project",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "account",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cut_off_date",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Statement of financial position as at end of `to_date`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Balance sheet generated successfully",
                  "data": {
                    "headings": [
                      {
                        "label": "Revenue",
                        "level": 1
                      }
                    ],
                    "content": [
                      {
                        "label": "Sales",
                        "amount": 12500.5,
                        "children": []
                      }
                    ],
                    "totals": {
                      "net_income": 4200
                    }
                  },
                  "meta": {
                    "from": "2024-01-01",
                    "to": "2024-03-31"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/reports/trial-balance": {
      "get": {
        "operationId": "getTrialBalance",
        "tags": [
          "Reports"
        ],
        "summary": "Trial balance",
        "parameters": [
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transaction_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contact",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "employee",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "creator",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "department",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "project",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "account",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cut_off_date",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Trial balance for the range",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Trial balance generated successfully",
                  "data": {
                    "headings": [
                      {
                        "label": "Revenue",
                        "level": 1
                      }
                    ],
                    "content": [
                      {
                        "label": "Sales",
                        "amount": 12500.5,
                        "children": []
                      }
                    ],
                    "totals": {
                      "net_income": 4200
                    }
                  },
                  "meta": {
                    "from": "2024-01-01",
                    "to": "2024-03-31"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/reports/cash-flow-statement": {
      "get": {
        "operationId": "getCashFlowStatement",
        "tags": [
          "Reports"
        ],
        "summary": "Cash flow statement",
        "parameters": [
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "transaction_type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "contact",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "employee",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "creator",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "department",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "project",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "account",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cut_off_date",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Indirect-style cash flow; `meta.previous_period_end` when present",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Cash flow statement generated successfully",
                  "data": {
                    "headings": [
                      {
                        "label": "Operating activities",
                        "level": 1
                      }
                    ],
                    "content": [],
                    "totals": {
                      "net_change_in_cash": 1500
                    }
                  },
                  "meta": {
                    "from": "2024-01-01",
                    "to": "2024-03-31",
                    "previous_period_end": "2023-12-31"
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/accounts/types": {
      "get": {
        "operationId": "getAccountTypes",
        "tags": [
          "Chart of accounts"
        ],
        "summary": "Get account types",
        "description": "Returns allowed account `type` and `subtype` values for `POST /create/chart_of_account`. Bank subtype is for reference only — bank accounts are created through banking.",
        "responses": {
          "200": {
            "description": "Account types and subtypes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Account types retrieved successfully",
                  "data": {
                    "types_with_subtypes": [
                      {
                        "type": "Assets",
                        "subtypes": [
                          "Cash",
                          "Bank",
                          "Current assets",
                          "Fixed assets",
                          "Accounts receivable",
                          "Inventory"
                        ]
                      },
                      {
                        "type": "Liabilities",
                        "subtypes": [
                          "Long-term liabilities",
                          "Current liabilities",
                          "Accounts payable"
                        ]
                      },
                      {
                        "type": "Revenue",
                        "subtypes": [
                          "Revenue",
                          "Other income"
                        ]
                      },
                      {
                        "type": "Expenses",
                        "subtypes": [
                          "Expenses",
                          "Cost of goods sold",
                          "Other expenses",
                          "Interest expenses",
                          "Income tax expenses",
                          "Depreciation",
                          "Amortization"
                        ]
                      },
                      {
                        "type": "Equity",
                        "subtypes": [
                          "Equity"
                        ]
                      }
                    ],
                    "types": [
                      "Assets",
                      "Liabilities",
                      "Revenue",
                      "Expenses",
                      "Equity"
                    ],
                    "subtypes": [
                      "Cash",
                      "Bank",
                      "Accounts receivable",
                      "Inventory",
                      "Accounts payable",
                      "Revenue",
                      "Expenses",
                      "Equity"
                    ]
                  }
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/create/chart_of_account": {
      "post": {
        "operationId": "createAccountManual",
        "tags": [
          "Chart of accounts"
        ],
        "summary": "Create account",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualAccountCreate"
              },
              "examples": {
                "default": {
                  "value": {
                    "name": "Software Subscriptions",
                    "type": "Expenses",
                    "subtype": "Expenses",
                    "account_code": "6105",
                    "description": "SaaS and cloud tools"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Accounts created successfully"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/create/invoice": {
      "post": {
        "operationId": "createInvoiceManual",
        "tags": [
          "Invoices"
        ],
        "summary": "Create invoice",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualInvoiceCreate"
              },
              "examples": {
                "default": {
                  "value": {
                    "date": "2026-03-01",
                    "document_due": "2026-03-15",
                    "currency": "NGN",
                    "document_number": "INV-1042",
                    "narration": "Website design services — March",
                    "customer": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
                    "status": "pending",
                    "amount_paid": 0,
                    "items": [
                      {
                        "item_name": "UI/UX design",
                        "quantity": 1,
                        "selling_price": 100000,
                        "category": "Design Income",
                        "tax": 7.5
                      },
                      {
                        "item_name": "Implementation support",
                        "quantity": 1,
                        "selling_price": 50000,
                        "category": "Service Income",
                        "tax": 7.5,
                        "discount": 5,
                        "discount_type": "percent"
                      }
                    ]
                  }
                },
                "paid": {
                  "value": {
                    "date": "2026-03-01",
                    "document_due": "2026-03-15",
                    "currency": "NGN",
                    "customer": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
                    "payment_category": "Main Operating Account",
                    "amount_paid": 161250,
                    "items": [
                      {
                        "item_name": "UI/UX design",
                        "quantity": 1,
                        "selling_price": 100000,
                        "category": "Design Income",
                        "tax": 7.5
                      },
                      {
                        "item_name": "Implementation support",
                        "quantity": 1,
                        "selling_price": 50000,
                        "category": "Service Income",
                        "tax": 7.5
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Invoice imported successfully.",
                  "data": [
                    {
                      "uuid": "c4d5e6f7a8b9401a9c2d3e4f5a6b7c8d",
                      "transaction_type": "invoice",
                      "status": "pending",
                      "document_number": "INV-1042"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/create/bill": {
      "post": {
        "operationId": "createBillManual",
        "tags": [
          "Bills"
        ],
        "summary": "Create bill",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualBillCreate"
              },
              "examples": {
                "default": {
                  "value": {
                    "date": "2026-03-02",
                    "document_due": "2026-03-16",
                    "currency": "NGN",
                    "document_number": "BILL-550",
                    "narration": "Office supplies — Q1 restock",
                    "customer": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
                    "payment_category": "Petty Cash",
                    "amount_paid": 42000,
                    "items": [
                      {
                        "item_name": "Printer paper A4",
                        "quantity": 10,
                        "selling_price": 3200,
                        "category": "Office Supplies",
                        "tax": 0
                      },
                      {
                        "item_name": "Toner cartridge",
                        "quantity": 1,
                        "selling_price": 10000,
                        "category": "Office Supplies"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bill created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Bill imported successfully.",
                  "data": [
                    {
                      "uuid": "b5c6d7e8f9a0418290a1b2c3d4e5f6b7",
                      "transaction_type": "bills",
                      "status": "pending",
                      "document_number": "BILL-550"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/create/expense": {
      "post": {
        "operationId": "createExpenseManual",
        "tags": [
          "Expenses"
        ],
        "summary": "Create expense",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualExpenseCreate"
              },
              "examples": {
                "default": {
                  "value": {
                    "date": "2026-03-03",
                    "currency": "NGN",
                    "document_number": "EXP-220",
                    "narration": "Team lunch — client meeting",
                    "customer": "c9b8a7d6e5f4438290a1b2c3d4e5f6c0",
                    "payment_category": "Main Operating Account",
                    "items": [
                      {
                        "item_name": "Meals and entertainment",
                        "quantity": 1,
                        "selling_price": 18500,
                        "category": "Meals & Entertainment"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Expense created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Expenses imported successfully",
                  "data": [
                    {
                      "uuid": "a0b1c2d3e4f5428290a1b2c3d4e5f6b1",
                      "transaction_type": "expenses",
                      "status": "paid"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/create/income": {
      "post": {
        "operationId": "createIncomeManual",
        "tags": [
          "Income"
        ],
        "summary": "Create income",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualIncomeCreate"
              },
              "examples": {
                "default": {
                  "value": {
                    "date": "2026-03-04",
                    "currency": "NGN",
                    "document_number": "RCT-881",
                    "narration": "Walk-in sale — March 4",
                    "customer": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
                    "payment_category": "Cash on Hand",
                    "items": [
                      {
                        "item_name": "Consulting package",
                        "quantity": 1,
                        "selling_price": 75000,
                        "category": "Service Income",
                        "tax": 7.5
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Income created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Income imported successfully",
                  "data": [
                    {
                      "uuid": "d3e4f5a6b7c8428290a1b2c3d4e5f6e4",
                      "transaction_type": "sales_receipt",
                      "status": "paid",
                      "receipt_no": "RCT-881"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/create/journal": {
      "post": {
        "operationId": "createJournalManual",
        "tags": [
          "Journals"
        ],
        "summary": "Create journal",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualJournalCreate"
              },
              "examples": {
                "default": {
                  "value": {
                    "description": "Accrue March rent",
                    "date": "2026-03-31",
                    "journal_no": "JE-2026-031",
                    "currency": "NGN",
                    "status": "draft",
                    "items": [
                      {
                        "category": "Rent Expense",
                        "debit": 250000,
                        "credit": 0,
                        "description": "March office rent"
                      },
                      {
                        "category": "Accrued Expenses",
                        "debit": 0,
                        "credit": 250000,
                        "description": "March office rent accrual"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Journal created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Journal created successfully",
                  "data": {
                    "uuid": "a6b7c8d9e0f1428290a1b2c3d4e5f6b7",
                    "status": "draft",
                    "journal_no": "JE-2026-031"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/create/contact": {
      "post": {
        "operationId": "createContactManual",
        "tags": [
          "Contacts"
        ],
        "summary": "Create contact",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualContactCreate"
              },
              "examples": {
                "default": {
                  "value": {
                    "name": "Acme Supplies Ltd",
                    "type": "vendor",
                    "business_name": "Acme Supplies Limited",
                    "email": "billing@acmesupplies.example",
                    "phone": "+2348012345678",
                    "address": "12 Industrial Avenue, Lagos",
                    "tax_id": "RC-123456",
                    "country": "NG",
                    "contact_number": "VND-0091",
                    "payment_terms": 14,
                    "receivable_account": "Accounts Receivable",
                    "payable_account": "Accounts Payable",
                    "opening_balance": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Contact created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Contacts imported successfully",
                  "data": {
                    "imported": 1,
                    "contacts": [
                      {
                        "uuid": "v8e7d6c5b4a3418290f0e9d8c7b6a5947",
                        "name": "Acme Supplies Ltd",
                        "type": "vendor"
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "x-mint": {}
      }
    },
    "/inventories": {
      "get": {
        "operationId": "listInventories",
        "tags": [
          "Inventory"
        ],
        "summary": "List inventory items",
        "description": "Return the paginated product and service catalog for the business. Use `search` to filter by item name.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size."
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Full-text search."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return only `data` without the `status`/`message` wrapper."
          }
        ],
        "responses": {
          "200": {
            "description": "Inventory list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Inventory retrieved successfully",
                  "data": [
                    {
                      "uuid": "inv-uuid-1",
                      "name": "Wireless Mouse",
                      "selling_price": 15000,
                      "cost_price": 9000,
                      "stock": 100,
                      "unit": "pcs",
                      "type": "product",
                      "is_inventory": true,
                      "currency": "NGN"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createInventory",
        "tags": [
          "Inventory"
        ],
        "summary": "Create inventory item (manual or AI)",
        "description": "Create a new product or service item in the Tyms catalog. Set `is_inventory: true` to track stock; omit for non-stocked services. Supports AI create when `prompt` is present.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualInventoryCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Item created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Inventory item created successfully",
                  "data": {
                    "uuid": "inv-uuid-1",
                    "name": "Wireless Mouse",
                    "selling_price": 15000,
                    "cost_price": 9000,
                    "stock": 100,
                    "unit": "pcs",
                    "type": "product",
                    "is_inventory": true,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/inventories/{uuid}": {
      "get": {
        "operationId": "getInventory",
        "tags": [
          "Inventory"
        ],
        "summary": "Get inventory item",
        "description": "Retrieve a single product or service by uuid.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Inventory item uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Single inventory item",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Inventory item retrieved successfully",
                  "data": {
                    "uuid": "inv-uuid-1",
                    "name": "Wireless Mouse",
                    "selling_price": 15000,
                    "cost_price": 9000,
                    "stock": 100,
                    "unit": "pcs",
                    "type": "product",
                    "is_inventory": true,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateInventoryPut",
        "tags": [
          "Inventory"
        ],
        "summary": "Update inventory item",
        "description": "Full update of an inventory item. Send all fields.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualInventoryCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Item updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateInventoryPatch",
        "tags": [
          "Inventory"
        ],
        "summary": "Update inventory item (partial)",
        "description": "Partial update — send only fields you want to change.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualInventoryCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Item updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteInventory",
        "tags": [
          "Inventory"
        ],
        "summary": "Delete inventory item",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Item deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Inventory item deleted successfully"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/inventories/sell": {
      "post": {
        "operationId": "sellInventory",
        "tags": [
          "Inventory"
        ],
        "summary": "Sell stock",
        "description": "Create a stock sale document that reduces inventory quantities. The payload follows the same line-item structure as income/invoice (`date`, `customer`, `items[]` with `item_name`, `quantity`, `selling_price`, `category`). COGS is computed automatically from cost_price.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualIncomeCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sale document created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Inventory sold successfully",
                  "data": {
                    "uuid": "sell-uuid-1",
                    "transaction_type": "sales_receipt"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/inventories/restock": {
      "post": {
        "operationId": "restockInventory",
        "tags": [
          "Inventory"
        ],
        "summary": "Restock inventory",
        "description": "Create a restock document that increases stock quantities. The payload follows the same line-item structure as a bill (`date`, `customer` (vendor), `items[]` with `item_name`, `quantity`, `selling_price` (unit cost), `category`). Stock is updated after save.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualBillCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Restock document created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Inventory restocked successfully",
                  "data": {
                    "uuid": "restock-uuid-1",
                    "transaction_type": "restock"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/create/inventory": {
      "post": {
        "operationId": "createInventoryAlias",
        "tags": [
          "Inventory"
        ],
        "summary": "Create inventory item (alias)",
        "description": "Alias for `POST /inventories`. Prefer `/inventories` for new integrations. Same request body and response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualInventoryCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Item created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Inventory item created successfully",
                  "data": {
                    "uuid": "inv-uuid-1",
                    "name": "Wireless Mouse",
                    "selling_price": 15000,
                    "cost_price": 9000,
                    "stock": 100,
                    "unit": "pcs",
                    "type": "product",
                    "is_inventory": true,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/assets": {
      "get": {
        "operationId": "listAssets",
        "tags": [
          "Fixed Assets"
        ],
        "summary": "List fixed assets",
        "description": "Return the paginated list of capital assets for the business.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size."
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Full-text search."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return only `data` without the `status`/`message` wrapper."
          }
        ],
        "responses": {
          "200": {
            "description": "Asset list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Assets retrieved successfully",
                  "data": [
                    {
                      "uuid": "asset-uuid-1",
                      "name": "Dell Laptop",
                      "date": "2026-02-01",
                      "amount": 850000,
                      "status": "active",
                      "currency": "NGN"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createAsset",
        "tags": [
          "Fixed Assets"
        ],
        "summary": "Create fixed asset",
        "description": "Capitalize a new fixed asset. Set `amount_paid` and `payment_category` to record an immediate cash payment. Asset depreciation schedules are managed in-app.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualAssetCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Asset created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Asset created successfully",
                  "data": {
                    "uuid": "asset-uuid-1",
                    "name": "Dell Laptop",
                    "date": "2026-02-01",
                    "amount": 850000,
                    "status": "active",
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/assets/{uuid}": {
      "get": {
        "operationId": "getAsset",
        "tags": [
          "Fixed Assets"
        ],
        "summary": "Get fixed asset",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Asset uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Single asset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Asset retrieved successfully",
                  "data": {
                    "uuid": "asset-uuid-1",
                    "name": "Dell Laptop",
                    "date": "2026-02-01",
                    "amount": 850000,
                    "status": "active",
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateAssetPut",
        "tags": [
          "Fixed Assets"
        ],
        "summary": "Update fixed asset",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualAssetCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Asset updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateAssetPatch",
        "tags": [
          "Fixed Assets"
        ],
        "summary": "Update fixed asset (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualAssetCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Asset updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteAsset",
        "tags": [
          "Fixed Assets"
        ],
        "summary": "Delete fixed asset",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Asset deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Asset deleted successfully"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/create/asset": {
      "post": {
        "operationId": "createAssetAlias",
        "tags": [
          "Fixed Assets"
        ],
        "summary": "Create fixed asset (alias)",
        "description": "Alias for `POST /assets`. Prefer `/assets` for new integrations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualAssetCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Asset created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Asset created successfully",
                  "data": {
                    "uuid": "asset-uuid-1",
                    "name": "Dell Laptop",
                    "date": "2026-02-01",
                    "amount": 850000,
                    "status": "active",
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/quotes": {
      "get": {
        "operationId": "listQuotes",
        "tags": [
          "Quotes"
        ],
        "summary": "List quotes",
        "description": "Return the paginated list of sales quotes. Accepted quotes can be converted to invoices, income, or prepaid income.",
        "parameters": [
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size."
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Full-text search."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return only `data` without the `status`/`message` wrapper."
          }
        ],
        "responses": {
          "200": {
            "description": "Quote list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Quotes retrieved successfully",
                  "data": [
                    {
                      "uuid": "quote-uuid-1",
                      "transaction_type": "quote",
                      "status": "draft",
                      "document_number": "QUO-0021",
                      "narration": "Website redesign proposal",
                      "amount": 200000,
                      "currency": "NGN"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createQuote",
        "tags": [
          "Quotes"
        ],
        "summary": "Create quote (manual or AI)",
        "description": "Create a sales proposal with line items. Supports AI create when `prompt` is present. Use `/quotes/{uuid}/convert-to-invoice` once the customer accepts.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualQuoteCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Quote created successfully",
                  "data": {
                    "uuid": "quote-uuid-1",
                    "transaction_type": "quote",
                    "status": "draft",
                    "document_number": "QUO-0021",
                    "narration": "Website redesign proposal",
                    "amount": 200000,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{uuid}": {
      "get": {
        "operationId": "getQuote",
        "tags": [
          "Quotes"
        ],
        "summary": "Get quote",
        "description": "Retrieve a single quote with line items.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Quote uuid or source_uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Single quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Quote retrieved successfully",
                  "data": {
                    "uuid": "quote-uuid-1",
                    "transaction_type": "quote",
                    "status": "draft",
                    "document_number": "QUO-0021",
                    "narration": "Website redesign proposal",
                    "amount": 200000,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateQuotePut",
        "tags": [
          "Quotes"
        ],
        "summary": "Update quote",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualQuoteCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateQuotePatch",
        "tags": [
          "Quotes"
        ],
        "summary": "Update quote (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualQuoteCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteQuote",
        "tags": [
          "Quotes"
        ],
        "summary": "Delete quote",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Quote deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Quote deleted successfully"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{uuid}/convert-to-invoice": {
      "post": {
        "operationId": "convertQuoteToInvoice",
        "tags": [
          "Quotes"
        ],
        "summary": "Convert quote to invoice",
        "description": "Convert an accepted quote to a posted invoice. The quote items, customer, and amounts are copied to a new invoice. Pass an empty body `{}`.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Quote uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invoice created from quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Quote converted to invoice successfully",
                  "data": {
                    "uuid": "invoice-uuid-1",
                    "transaction_type": "invoice"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{uuid}/convert-to-income": {
      "post": {
        "operationId": "convertQuoteToIncome",
        "tags": [
          "Quotes"
        ],
        "summary": "Convert quote to income",
        "description": "Convert an accepted quote to a cash receipt (sales income). The quote items and customer are copied to a new income record. Pass an empty body `{}`.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Quote uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Income created from quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Quote converted to income successfully",
                  "data": {
                    "uuid": "income-uuid-1",
                    "transaction_type": "sales_receipt"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/quotes/{uuid}/convert-to-prepaid-income": {
      "post": {
        "operationId": "convertQuoteToPrepaidIncome",
        "tags": [
          "Quotes"
        ],
        "summary": "Convert quote to prepaid income",
        "description": "Convert an accepted quote to a prepaid income (unearned revenue) record. The amount is deferred and recognized monthly. Pass an empty body `{}`.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Quote uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prepaid income created from quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Quote converted to prepaid income successfully",
                  "data": {
                    "uuid": "prepaid-uuid-1",
                    "transaction_type": "prepaid_income"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/create/quote": {
      "post": {
        "operationId": "createQuoteAlias",
        "tags": [
          "Quotes"
        ],
        "summary": "Create quote (alias)",
        "description": "Alias for `POST /quotes`. Prefer `/quotes` for new integrations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualQuoteCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Quote created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Quote created successfully",
                  "data": {
                    "uuid": "quote-uuid-1",
                    "transaction_type": "quote",
                    "status": "draft",
                    "document_number": "QUO-0021",
                    "narration": "Website redesign proposal",
                    "amount": 200000,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/purchase-orders": {
      "get": {
        "operationId": "listPurchaseOrders",
        "tags": [
          "Purchase Orders"
        ],
        "summary": "List purchase orders",
        "description": "Return the paginated list of purchase orders. Convert to restock when goods arrive.",
        "parameters": [
          {
            "name": "date_order",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "asc",
                "desc"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size."
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Full-text search."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return only `data` without the `status`/`message` wrapper."
          }
        ],
        "responses": {
          "200": {
            "description": "Purchase order list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Purchase orders retrieved successfully",
                  "data": [
                    {
                      "uuid": "po-uuid-1",
                      "transaction_type": "purchase_order",
                      "status": "draft",
                      "document_number": "PO-0042",
                      "narration": "Q2 stock replenishment",
                      "amount": 450000,
                      "currency": "NGN"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createPurchaseOrder",
        "tags": [
          "Purchase Orders"
        ],
        "summary": "Create purchase order (manual or AI)",
        "description": "Create a buying commitment to a vendor. Supports AI create when `prompt` is present. Use `/purchase-orders/{uuid}/convert-to-restock` when goods arrive.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualPurchaseOrderCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Purchase order created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Purchase order created successfully",
                  "data": {
                    "uuid": "po-uuid-1",
                    "transaction_type": "purchase_order",
                    "status": "draft",
                    "document_number": "PO-0042",
                    "narration": "Q2 stock replenishment",
                    "amount": 450000,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/purchase-orders/{uuid}": {
      "get": {
        "operationId": "getPurchaseOrder",
        "tags": [
          "Purchase Orders"
        ],
        "summary": "Get purchase order",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Purchase order uuid or source_uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Single purchase order",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Purchase order retrieved successfully",
                  "data": {
                    "uuid": "po-uuid-1",
                    "transaction_type": "purchase_order",
                    "status": "draft",
                    "document_number": "PO-0042",
                    "narration": "Q2 stock replenishment",
                    "amount": 450000,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updatePurchaseOrderPut",
        "tags": [
          "Purchase Orders"
        ],
        "summary": "Update purchase order",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualPurchaseOrderCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Purchase order updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updatePurchaseOrderPatch",
        "tags": [
          "Purchase Orders"
        ],
        "summary": "Update purchase order (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualPurchaseOrderCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Purchase order updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deletePurchaseOrder",
        "tags": [
          "Purchase Orders"
        ],
        "summary": "Delete purchase order",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Purchase order deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Purchase order deleted successfully"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/purchase-orders/{uuid}/convert-to-restock": {
      "post": {
        "operationId": "convertPurchaseOrderToRestock",
        "tags": [
          "Purchase Orders"
        ],
        "summary": "Convert purchase order to restock",
        "description": "Convert a purchase order to an inventory restock document when goods arrive. Stock quantities are increased per line item. Pass an empty body `{}`.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Purchase order uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "Restock created from PO",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Purchase order converted to restock successfully",
                  "data": {
                    "uuid": "restock-uuid-1",
                    "transaction_type": "restock"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/create/purchase_order": {
      "post": {
        "operationId": "createPurchaseOrderAlias",
        "tags": [
          "Purchase Orders"
        ],
        "summary": "Create purchase order (alias)",
        "description": "Alias for `POST /purchase-orders`. Prefer `/purchase-orders` for new integrations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualPurchaseOrderCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Purchase order created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Purchase order created successfully",
                  "data": {
                    "uuid": "po-uuid-1",
                    "transaction_type": "purchase_order",
                    "status": "draft",
                    "document_number": "PO-0042",
                    "narration": "Q2 stock replenishment",
                    "amount": 450000,
                    "currency": "NGN"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/departments": {
      "get": {
        "operationId": "listDepartments",
        "tags": [
          "Departments"
        ],
        "summary": "List departments",
        "description": "Return all departments for the business. Use `department_uuid` on invoices, bills, expenses, income, and journals to tag transactions.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size."
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Full-text search."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return only `data` without the `status`/`message` wrapper."
          }
        ],
        "responses": {
          "200": {
            "description": "Department list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Departments retrieved successfully",
                  "data": [
                    {
                      "uuid": "dep1234567890abcdef1234567890ab",
                      "business_uuid": "b1b2b3...",
                      "name": "Marketing",
                      "branch_uuid": null,
                      "deleted": false,
                      "created_at": "2026-03-05T09:00:00.000000Z"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createDepartment",
        "tags": [
          "Departments"
        ],
        "summary": "Create department",
        "description": "Create a new department dimension. Optionally link to a branch with `branch_uuid`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualDepartmentCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Department created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Department created successfully",
                  "data": {
                    "uuid": "dep1234567890abcdef1234567890ab",
                    "business_uuid": "b1b2b3...",
                    "name": "Marketing",
                    "branch_uuid": null,
                    "deleted": false,
                    "created_at": "2026-03-05T09:00:00.000000Z"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/departments/{uuid}": {
      "put": {
        "operationId": "updateDepartmentPut",
        "tags": [
          "Departments"
        ],
        "summary": "Update department",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Department uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualDepartmentCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Department updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateDepartmentPatch",
        "tags": [
          "Departments"
        ],
        "summary": "Update department (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Department uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualDepartmentCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Department updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteDepartment",
        "tags": [
          "Departments"
        ],
        "summary": "Delete department",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Department uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Department deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Department deleted successfully"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/projects": {
      "get": {
        "operationId": "listProjects",
        "tags": [
          "Projects"
        ],
        "summary": "List projects",
        "description": "Return the paginated list of projects. Tag transactions with `project_uuid` to track job costs.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size."
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Full-text search."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return only `data` without the `status`/`message` wrapper."
          }
        ],
        "responses": {
          "200": {
            "description": "Project list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Projects retrieved successfully",
                  "data": [
                    {
                      "uuid": "proj-uuid-1",
                      "name": "Website Redesign",
                      "status": "active",
                      "cost": 500000,
                      "currency": "NGN",
                      "customer_uuid": "a1b2c3..."
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createProject",
        "tags": [
          "Projects"
        ],
        "summary": "Create project",
        "description": "Create a new project for job costing and revenue tracking. Attach to invoices, journals, and other transactions via `project_uuid`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualProjectCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Project created successfully",
                  "data": {
                    "uuid": "proj-uuid-1",
                    "name": "Website Redesign",
                    "status": "active",
                    "cost": 500000,
                    "currency": "NGN",
                    "customer_uuid": "a1b2c3..."
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/projects/{uuid}": {
      "get": {
        "operationId": "getProject",
        "tags": [
          "Projects"
        ],
        "summary": "Get project",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Project uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Single project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Project retrieved successfully",
                  "data": {
                    "uuid": "proj-uuid-1",
                    "name": "Website Redesign",
                    "status": "active",
                    "cost": 500000,
                    "currency": "NGN",
                    "customer_uuid": "a1b2c3..."
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "updateProjectPut",
        "tags": [
          "Projects"
        ],
        "summary": "Update project",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualProjectCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateProjectPatch",
        "tags": [
          "Projects"
        ],
        "summary": "Update project (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualProjectCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteProject",
        "tags": [
          "Projects"
        ],
        "summary": "Delete project",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Record uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Project deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Project deleted successfully"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/branches": {
      "get": {
        "operationId": "listBranches",
        "tags": [
          "Branches"
        ],
        "summary": "List branches",
        "description": "Return all branches for the business. Tag transactions with `branch_uuid` to track performance by location.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size."
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Full-text search."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return only `data` without the `status`/`message` wrapper."
          }
        ],
        "responses": {
          "200": {
            "description": "Branch list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Branches retrieved successfully",
                  "data": [
                    {
                      "uuid": "br1234567890abcdef1234567890abcd",
                      "business_uuid": "b1b2b3...",
                      "name": "Lagos HQ",
                      "address": "12 Adeola Odeku, Victoria Island",
                      "state": "Lagos",
                      "country": "NG",
                      "is_default": false,
                      "phone": "+2348011111111",
                      "email": "lagos@acme.example"
                    }
                  ]
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createBranch",
        "tags": [
          "Branches"
        ],
        "summary": "Create branch",
        "description": "Create a new branch location. `name`, `address`, `state`, and `country` are required. The default branch cannot be deleted.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualBranchCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Branch created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Branch created successfully",
                  "data": {
                    "uuid": "br1234567890abcdef1234567890abcd",
                    "business_uuid": "b1b2b3...",
                    "name": "Lagos HQ",
                    "address": "12 Adeola Odeku, Victoria Island",
                    "state": "Lagos",
                    "country": "NG",
                    "is_default": false,
                    "phone": "+2348011111111",
                    "email": "lagos@acme.example"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/branches/{uuid}": {
      "put": {
        "operationId": "updateBranchPut",
        "tags": [
          "Branches"
        ],
        "summary": "Update branch",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Branch uuid."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualBranchCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Branch updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "operationId": "updateBranchPatch",
        "tags": [
          "Branches"
        ],
        "summary": "Update branch (partial)",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Branch uuid."
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ManualBranchCreate"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Branch updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "deleteBranch",
        "tags": [
          "Branches"
        ],
        "summary": "Delete branch",
        "description": "Delete a non-default branch. The default branch cannot be deleted.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Branch uuid."
          }
        ],
        "responses": {
          "200": {
            "description": "Branch deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Branch deleted successfully"
                }
              }
            }
          },
          "400": {
            "description": "Cannot delete the default branch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/reports/general-ledger": {
      "get": {
        "operationId": "getGeneralLedger",
        "tags": [
          "Reports"
        ],
        "summary": "General ledger",
        "description": "Paginated chronological ledger of all posted journal legs across the business — the complete double-entry audit trail. Filter by account name, contact, transaction type, or date range. Each row includes debit/credit amounts in both transaction and base currency.",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Period start date (`Y-m-d`). Alias: `from_date`."
          },
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Alias for `from`."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Period end date (`Y-m-d`). Alias: `to_date`."
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Alias for `to`."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return raw `data` only without the `status`/`message` wrapper."
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Match narration, journal no, contact name, or account name."
          },
          {
            "name": "transaction_type",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by transaction type (e.g. `invoice`, `expenses`, `sales_receipt`)."
          },
          {
            "name": "account",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by account name."
          },
          {
            "name": "contact",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by contact identifier."
          },
          {
            "name": "branch",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by branch."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size (default `100`)."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated general ledger",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "General ledger retrieved successfully",
                  "data": {
                    "current_page": 1,
                    "data": [
                      {
                        "uuid": "gl111111111111111111111111111111",
                        "date": "2026-03-01T00:00:00.000000Z",
                        "journal_no": "JNL-1001",
                        "narration": "Invoice INV-1042 — Website design services",
                        "account": "Accounts Receivable",
                        "account_type": "Assets",
                        "account_sub_type": "Accounts receivable",
                        "transaction_type": "Invoice",
                        "debit_amount": 150000,
                        "credit_amount": 0,
                        "main_debit_amount": 150000,
                        "main_credit_amount": 0,
                        "currency": "NGN",
                        "contact": "a1b2c3d4e5f6478990a1b2c3d4e5f678",
                        "contact_name": "John Smith",
                        "branch": null,
                        "department": null,
                        "project": null
                      }
                    ],
                    "per_page": 100,
                    "total": 1
                  }
                }
              }
            }
          }
        }
      }
    },
    "/reports/account-ledger/{uuid}": {
      "get": {
        "operationId": "getAccountLedger",
        "tags": [
          "Reports"
        ],
        "summary": "Account ledger",
        "description": "Running balance ledger for a single chart-of-account or bank account. Pass a COA uuid or bank uuid as `{uuid}`. Returns all movements with opening and closing balance per line, plus the period closing balance and debit/credit side.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Chart-of-account uuid or bank account uuid."
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Period start date (`Y-m-d`). Alias: `from_date`."
          },
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Alias for `from`."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Period end date (`Y-m-d`). Alias: `to_date`."
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Alias for `to`."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return raw `data` only without the `status`/`message` wrapper."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page size (default `100`)."
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "Page number."
          }
        ],
        "responses": {
          "200": {
            "description": "Account ledger with running balance",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Ledger retrieved successfully",
                  "data": {
                    "data": {
                      "current_page": 1,
                      "data": [
                        {
                          "uuid": "mj333333333333333333333333333333",
                          "transaction_no": "INV-1042",
                          "transaction_type": "invoice",
                          "narration": "Website design services — March",
                          "account": "Accounts Receivable",
                          "account_type": "Assets",
                          "debit_amount": 150000,
                          "credit_amount": 0,
                          "currency": "NGN",
                          "date": "2026-03-01T00:00:00.000000Z",
                          "opening_balance": 0,
                          "closing_balance": 150000
                        }
                      ],
                      "per_page": 100,
                      "total": 1
                    },
                    "balance": 150000,
                    "side": "Debit",
                    "currency": "NGN",
                    "account_name": "Accounts Receivable",
                    "account_currency": "NGN",
                    "date": "2026-03-31T23:59:59.000000Z"
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/reports/contact-statement/{uuid}": {
      "get": {
        "operationId": "getContactStatement",
        "tags": [
          "Reports"
        ],
        "summary": "Contact statement",
        "description": "Customer or vendor account statement. Returns opening balance, closing balance, total charges, total payments, and each movement (invoice, bill, payment) with running balance. Used for portal statements and collections.",
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Contact uuid."
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Period start date (`Y-m-d`). Alias: `from_date`."
          },
          {
            "name": "from_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Alias for `from`."
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Period end date (`Y-m-d`). Alias: `to_date`."
          },
          {
            "name": "to_date",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Alias for `to`."
          },
          {
            "name": "list",
            "in": "query",
            "schema": {
              "type": "integer",
              "enum": [
                1
              ]
            },
            "description": "Pass `1` to return raw `data` only without the `status`/`message` wrapper."
          }
        ],
        "responses": {
          "200": {
            "description": "Contact statement with running balances",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AdamSuccessResponse"
                },
                "example": {
                  "status": "success",
                  "message": "Customer statement retrieved successfully",
                  "data": {
                    "opening_balance": 25000,
                    "closing_balance": 125000,
                    "total_charges": 150000,
                    "total_payments": 50000,
                    "currency": "NGN",
                    "statement": [
                      {
                        "uuid": "st444444444444444444444444444444",
                        "transaction_type": "sales",
                        "type": "record",
                        "date": "2026-03-01T00:00:00.000000Z",
                        "transaction_no": "INV-1042",
                        "narration": "Website design services — March",
                        "charges": 150000,
                        "payment": 0,
                        "opening_balance": 25000,
                        "closing_balance": 175000,
                        "currency": "NGN"
                      }
                    ]
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}