{
    "openapi": "3.1.0",
    "info": {
        "title": "AWRA OpsHub Developer API",
        "version": "v1",
        "summary": "Read access to your organization's inventory, sales, and procurement records.",
        "description": "Read-only HTTP API over the records in your AWRA OpsHub workspace.\n\nAuthentication is a bearer key. The key carries the organization, so every response is already scoped to it — there is no organization parameter and no way to read across organizations.\n\nScopes:\n\n- `developer:read` — Umbrella scope. Satisfies every resource scope below. Convenient for a trusted internal integration; prefer narrow scopes for third parties.\n- `inventory:read` — Items, categories, warehouses.\n- `sales:read` — Customers and customer invoices, including invoice line items.\n- `procurement:read` — Vendors and purchase orders, including order line items.\n\nList endpoints paginate. Use `paginate=cursor` and follow `links.next` when reading a whole resource; numbered pages are for browsing, not for sync.",
        "contact": {
            "name": "AWRA OpsHub API documentation",
            "url": "https://awraops.com/api-docs"
        },
        "termsOfService": "https://awraops.com/terms-of-service"
    },
    "servers": [
        {
            "url": "https://awraops.com/api/v1",
            "description": "Production"
        }
    ],
    "externalDocs": {
        "description": "Developer API reference",
        "url": "https://awraops.com/api-docs"
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "tags": [
        {
            "name": "Identity",
            "description": "Confirms a key works and shows which organization it is bound to. Call this first when wiring up a new integration."
        },
        {
            "name": "Inventory",
            "description": "Stock positions and the reference data around them. Stock figures are the current on-hand quantity across the organization."
        },
        {
            "name": "Sales",
            "description": "Customers and the invoices raised against them — the surface most accounting and BI integrations need."
        },
        {
            "name": "Procurement",
            "description": "Vendors and purchase orders. Vendor banking and mobile-money details are deliberately excluded from every response — a read key is for reporting and sync, not for harvesting payout destinations."
        }
    ],
    "paths": {
        "/me": {
            "get": {
                "operationId": "getMe",
                "tags": [
                    "Identity"
                ],
                "summary": "Introspect the calling API key: the organization it belongs to, its scopes, and its expiry.",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "organization": {
                                            "id": "1",
                                            "name": "Example Organization"
                                        },
                                        "key": {
                                            "name": "Warehouse sync",
                                            "prefix": "awra_1A6Kw",
                                            "scopes": [
                                                "inventory:read"
                                            ],
                                            "created_at": "2026-08-03T18:35:26+03:00",
                                            "expires_at": null
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: any valid key."
            }
        },
        "/items": {
            "get": {
                "operationId": "getItems",
                "tags": [
                    "Inventory"
                ],
                "summary": "List items with current stock levels.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    },
                    {
                        "$ref": "#/components/parameters/UpdatedSince"
                    },
                    {
                        "$ref": "#/components/parameters/Paginate"
                    },
                    {
                        "$ref": "#/components/parameters/Cursor"
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Matches name, SKU (barcode), or description.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "category",
                        "in": "query",
                        "required": false,
                        "description": "Exact category name.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "low_stock",
                        "in": "query",
                        "required": false,
                        "description": "When true, only items whose stock has fallen to or below their reorder point.",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": "11111111-2222-3333-4444-555555555555",
                                            "sku": "SKU-EXAMPLE-001",
                                            "name": "Example Widget",
                                            "description": "Illustrative item description",
                                            "category": "Office Supplies",
                                            "stock": 681,
                                            "reorder_point": 100,
                                            "safety_stock": 40,
                                            "lead_time_days": 7,
                                            "tracking_mode": "none",
                                            "buying_price": "540.00",
                                            "selling_price": "700.00",
                                            "last_movement_at": "2026-08-01T09:12:44+03:00",
                                            "created_at": "2026-05-02T10:00:00+03:00",
                                            "updated_at": "2026-08-01T09:12:44+03:00"
                                        }
                                    ],
                                    "meta": {
                                        "page": 1,
                                        "per_page": 25,
                                        "total": 37,
                                        "total_pages": 2
                                    },
                                    "links": {
                                        "next": "https://app.example.com/api/v1/items?page=2",
                                        "prev": null
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: inventory:read."
            }
        },
        "/items/{id}": {
            "get": {
                "operationId": "getItemsById",
                "tags": [
                    "Inventory"
                ],
                "summary": "Fetch a single item by its ID.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Identifier of the record, as returned in `data.id`.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": "11111111-2222-…",
                                        "sku": "SKU-EXAMPLE-001",
                                        "name": "Example Widget",
                                        "stock": 681,
                                        "…": "…"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: inventory:read."
            }
        },
        "/categories": {
            "get": {
                "operationId": "getCategories",
                "tags": [
                    "Inventory"
                ],
                "summary": "List item categories. Returns the full set, unpaginated.",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 6,
                                            "name": "Electronics"
                                        },
                                        {
                                            "id": 4,
                                            "name": "Food"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: inventory:read."
            }
        },
        "/warehouses": {
            "get": {
                "operationId": "getWarehouses",
                "tags": [
                    "Inventory"
                ],
                "summary": "List warehouses. Returns the full set, unpaginated.",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 1,
                                            "name": "Main Warehouse"
                                        },
                                        {
                                            "id": 4,
                                            "name": "Field Store"
                                        }
                                    ]
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: inventory:read."
            }
        },
        "/customers": {
            "get": {
                "operationId": "getCustomers",
                "tags": [
                    "Sales"
                ],
                "summary": "List customers with balances and credit limits.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    },
                    {
                        "$ref": "#/components/parameters/UpdatedSince"
                    },
                    {
                        "$ref": "#/components/parameters/Paginate"
                    },
                    {
                        "$ref": "#/components/parameters/Cursor"
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Matches company name, first or last name, email, or phone.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Exact status value.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 2,
                                            "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                                            "company_name": "Example Trading Ltd",
                                            "first_name": "Jane",
                                            "last_name": "Doe",
                                            "email": "jane.doe@example.com",
                                            "phone": "+254700000000",
                                            "country": "Kenya",
                                            "address": "Nairobi",
                                            "currency_code": "KES",
                                            "credit_limit": "500000.00",
                                            "balance": "128400.00",
                                            "status": "active",
                                            "created_at": "2026-04-11T08:20:00+03:00",
                                            "updated_at": "2026-07-30T16:02:11+03:00"
                                        }
                                    ],
                                    "meta": {
                                        "page": 1,
                                        "per_page": 25,
                                        "total": 2,
                                        "total_pages": 1
                                    },
                                    "links": {
                                        "next": null,
                                        "prev": null
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: sales:read."
            }
        },
        "/customers/{id}": {
            "get": {
                "operationId": "getCustomersById",
                "tags": [
                    "Sales"
                ],
                "summary": "Fetch a single customer by ID.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Identifier of the record, as returned in `data.id`.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 2,
                                        "company_name": "Example Trading Ltd",
                                        "balance": "128400.00",
                                        "…": "…"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: sales:read."
            }
        },
        "/invoices": {
            "get": {
                "operationId": "getInvoices",
                "tags": [
                    "Sales"
                ],
                "summary": "List customer invoices with totals and outstanding balances.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    },
                    {
                        "$ref": "#/components/parameters/UpdatedSince"
                    },
                    {
                        "$ref": "#/components/parameters/Paginate"
                    },
                    {
                        "$ref": "#/components/parameters/Cursor"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Exact invoice status, e.g. draft, sent, paid.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "customer_id",
                        "in": "query",
                        "required": false,
                        "description": "Only invoices for this customer.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "issued_from",
                        "in": "query",
                        "required": false,
                        "description": "Invoice date on or after this date (YYYY-MM-DD).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "issued_to",
                        "in": "query",
                        "required": false,
                        "description": "Invoice date on or before this date (YYYY-MM-DD).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "unpaid",
                        "in": "query",
                        "required": false,
                        "description": "When true, only invoices with a balance still due.",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 10,
                                            "invoice_number": "INV-2026-000010",
                                            "status": "draft",
                                            "customer": {
                                                "id": 1,
                                                "name": "Example Trading Ltd"
                                            },
                                            "invoice_date": "2026-07-14T00:00:00+03:00",
                                            "due_date": "2026-08-13T00:00:00+03:00",
                                            "currency_code": "KES",
                                            "subtotal": "120000.00",
                                            "discount_total": "0.00",
                                            "tax_amount": "19200.00",
                                            "total": "139200.00",
                                            "amount_paid": "0.00",
                                            "balance_due": "139200.00",
                                            "created_at": "2026-07-14T11:05:00+03:00",
                                            "updated_at": "2026-07-14T11:05:00+03:00"
                                        }
                                    ],
                                    "meta": {
                                        "page": 1,
                                        "per_page": 25,
                                        "total": 10,
                                        "total_pages": 1
                                    },
                                    "links": {
                                        "next": null,
                                        "prev": null
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: sales:read."
            }
        },
        "/invoices/{id}": {
            "get": {
                "operationId": "getInvoicesById",
                "tags": [
                    "Sales"
                ],
                "summary": "Fetch a single invoice, including its line items.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Identifier of the record, as returned in `data.id`.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 10,
                                        "invoice_number": "INV-2026-000010",
                                        "status": "draft",
                                        "total": "139200.00",
                                        "balance_due": "139200.00",
                                        "line_items": [
                                            {
                                                "item_id": "11111111-2222-3333-4444-555555555555",
                                                "description": "Example Widget",
                                                "quantity": 200,
                                                "unit_price": "600.00",
                                                "discount": "0.00",
                                                "tax_rate": 16,
                                                "line_total": "120000.00"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: sales:read."
            }
        },
        "/vendors": {
            "get": {
                "operationId": "getVendors",
                "tags": [
                    "Procurement"
                ],
                "summary": "List vendors.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    },
                    {
                        "$ref": "#/components/parameters/UpdatedSince"
                    },
                    {
                        "$ref": "#/components/parameters/Paginate"
                    },
                    {
                        "$ref": "#/components/parameters/Cursor"
                    },
                    {
                        "name": "search",
                        "in": "query",
                        "required": false,
                        "description": "Matches name, company, email, or phone.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "is_active",
                        "in": "query",
                        "required": false,
                        "description": "Filter by active flag.",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "preferred_only",
                        "in": "query",
                        "required": false,
                        "description": "When true, only vendors marked preferred.",
                        "schema": {
                            "type": "boolean"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 5,
                                            "name": "Example Supplies",
                                            "company": "Example Supplies Ltd",
                                            "email": "sales@example.com",
                                            "phone": "254700000000",
                                            "country": "Kenya",
                                            "address": "Nairobi",
                                            "is_active": true,
                                            "is_preferred": false,
                                            "is_blacklisted": false,
                                            "created_at": "2026-03-02T09:00:00+03:00",
                                            "updated_at": "2026-07-19T14:41:00+03:00"
                                        }
                                    ],
                                    "meta": {
                                        "page": 1,
                                        "per_page": 25,
                                        "total": 8,
                                        "total_pages": 1
                                    },
                                    "links": {
                                        "next": null,
                                        "prev": null
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: procurement:read."
            }
        },
        "/vendors/{id}": {
            "get": {
                "operationId": "getVendorsById",
                "tags": [
                    "Procurement"
                ],
                "summary": "Fetch a single vendor by ID.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Identifier of the record, as returned in `data.id`.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 5,
                                        "name": "Example Supplies",
                                        "is_active": true,
                                        "…": "…"
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: procurement:read."
            }
        },
        "/purchase-orders": {
            "get": {
                "operationId": "getPurchaseOrders",
                "tags": [
                    "Procurement"
                ],
                "summary": "List purchase orders with payment and shipping state.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/Page"
                    },
                    {
                        "$ref": "#/components/parameters/PerPage"
                    },
                    {
                        "$ref": "#/components/parameters/UpdatedSince"
                    },
                    {
                        "$ref": "#/components/parameters/Paginate"
                    },
                    {
                        "$ref": "#/components/parameters/Cursor"
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Exact order status.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "payment_status",
                        "in": "query",
                        "required": false,
                        "description": "Exact payment status, e.g. unpaid, partial, paid.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "vendor_id",
                        "in": "query",
                        "required": false,
                        "description": "Only orders for this vendor.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "ordered_from",
                        "in": "query",
                        "required": false,
                        "description": "Order date on or after this date (YYYY-MM-DD).",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "ordered_to",
                        "in": "query",
                        "required": false,
                        "description": "Order date on or before this date (YYYY-MM-DD).",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": [
                                        {
                                            "id": 5,
                                            "po_number": "PO-2026-000003",
                                            "status": "paid",
                                            "payment_status": "paid",
                                            "shipping_status": "delivered",
                                            "vendor": {
                                                "id": 1,
                                                "name": "Example Supplies Ltd"
                                            },
                                            "order_date": "2026-08-02T14:50:40+03:00",
                                            "delivery_date": "2026-08-09T00:00:00+03:00",
                                            "total_amount": "84000.00",
                                            "amount_paid": "84000.00",
                                            "balance_due": "0.00",
                                            "tracking_number": "TRK-99120",
                                            "created_at": "2026-08-02T14:50:40+03:00",
                                            "updated_at": "2026-08-02T15:10:02+03:00"
                                        }
                                    ],
                                    "meta": {
                                        "page": 1,
                                        "per_page": 25,
                                        "total": 5,
                                        "total_pages": 1
                                    },
                                    "links": {
                                        "next": null,
                                        "prev": null
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: procurement:read."
            }
        },
        "/purchase-orders/{id}": {
            "get": {
                "operationId": "getPurchaseOrdersById",
                "tags": [
                    "Procurement"
                ],
                "summary": "Fetch a single purchase order, including its line items.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "description": "Identifier of the record, as returned in `data.id`.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Success.",
                        "content": {
                            "application/json": {
                                "example": {
                                    "data": {
                                        "id": 5,
                                        "po_number": "PO-2026-000003",
                                        "status": "paid",
                                        "total_amount": "84000.00",
                                        "line_items": [
                                            {
                                                "item_id": "11111111-2222-…",
                                                "quantity": 120,
                                                "price": "700.00",
                                                "total_cost": "84000.00"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "$ref": "#/components/responses/401"
                    },
                    "403": {
                        "$ref": "#/components/responses/403"
                    },
                    "404": {
                        "$ref": "#/components/responses/404"
                    },
                    "422": {
                        "$ref": "#/components/responses/422"
                    },
                    "429": {
                        "$ref": "#/components/responses/429"
                    }
                },
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "description": "Required scope: procurement:read."
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "A Developer API key, sent as `Authorization: Bearer <key>`. The key identifies the organization, so no organization identifier is passed in the request."
            }
        },
        "parameters": {
            "Page": {
                "name": "page",
                "in": "query",
                "required": false,
                "description": "Page number. Defaults to 1.",
                "schema": {
                    "type": "integer"
                }
            },
            "PerPage": {
                "name": "per_page",
                "in": "query",
                "required": false,
                "description": "Results per page. Defaults to 25, capped at 100. Values below 1 fall back to the default.",
                "schema": {
                    "type": "integer"
                }
            },
            "UpdatedSince": {
                "name": "updated_since",
                "in": "query",
                "required": false,
                "description": "Only records changed at or after this timestamp — use it for incremental sync instead of re-reading everything. An unparseable value returns 422 rather than being ignored.",
                "schema": {
                    "type": "string",
                    "format": "date-time"
                }
            },
            "Paginate": {
                "name": "paginate",
                "in": "query",
                "required": false,
                "description": "Set to \"cursor\" to start a cursor walk instead of numbered pages. Use this when reading a whole resource: page 1,000 costs what page 1 costs, and no row is skipped or repeated if records change while you page. The response carries no total, and you follow links.next rather than incrementing a page number.",
                "schema": {
                    "type": "string"
                }
            },
            "Cursor": {
                "name": "cursor",
                "in": "query",
                "required": false,
                "description": "The opaque cursor from a previous response's links.next or links.prev. Sending one implies cursor mode, so following links.next needs nothing else. Do not construct these yourself — they encode the sort key of the last row returned.",
                "schema": {
                    "type": "string"
                }
            }
        },
        "responses": {
            "401": {
                "description": "No bearer token, or the key is unknown, revoked, or past its expiry date. Not retryable — check the credential.",
                "content": {
                    "application/json": {
                        "example": {
                            "error": {
                                "code": "unauthorized",
                                "message": "No bearer token, or the key is unknown, revoked, or past its expiry date. Not retryable — check the credential."
                            }
                        }
                    }
                }
            },
            "403": {
                "description": "The key is valid but lacks the scope this endpoint requires. Mint a key with the right scope; retrying will not help.",
                "content": {
                    "application/json": {
                        "example": {
                            "error": {
                                "code": "insufficient_scope",
                                "message": "The key is valid but lacks the scope this endpoint requires. Mint a key with the right scope; retrying will not help."
                            }
                        }
                    }
                }
            },
            "404": {
                "description": "No such record in your organization. Also returned for records that exist but belong to another organization — the API never confirms that an ID exists elsewhere.",
                "content": {
                    "application/json": {
                        "example": {
                            "error": {
                                "code": "not_found",
                                "message": "No such record in your organization. Also returned for records that exist but belong to another organization — the API never confirms that an ID exists elsewhere."
                            }
                        }
                    }
                }
            },
            "422": {
                "description": "A query parameter was malformed. The message names the offending parameter.",
                "content": {
                    "application/json": {
                        "example": {
                            "error": {
                                "code": "invalid_parameter",
                                "message": "A query parameter was malformed. The message names the offending parameter."
                            }
                        }
                    }
                }
            },
            "429": {
                "description": "Rate limit exceeded. Back off and retry after the window resets."
            }
        }
    }
}