API reference

GET /api/v1/templates

List the templates the API offers. Public. Sends Access-Control-Allow-Origin: *, Vary: Koutei-Version, and may be cached for 5 minutes. An OPTIONS preflight gets 204 with Access-Control-Allow-Methods: GET, OPTIONS and Access-Control-Allow-Headers: Koutei-Version.

Key: none (public). Success: 200. It can also answer 400, 404, 429, 500.

GET /api/v1/templates/{slug}

One template, with the JSON Schema of its fields, its rules and an example request. Public. Sends Access-Control-Allow-Origin: *, Vary: Koutei-Version, and may be cached for 5 minutes. An OPTIONS preflight gets 204 with Access-Control-Allow-Methods: GET, OPTIONS and Access-Control-Allow-Headers: Koutei-Version.

Key: none (public). Success: 200. It can also answer 400, 404, 429, 500.

GET /api/v1/openapi.json

This API, described as OpenAPI 3.1 JSON. Public. Sends Access-Control-Allow-Origin: *, Vary: Koutei-Version, and may be cached for 5 minutes. An OPTIONS preflight gets 204 with Access-Control-Allow-Methods: GET, OPTIONS and Access-Control-Allow-Headers: Koutei-Version.

Key: none (public). Success: 200. It can also answer 404, 429, 500.

POST /api/v1/documents

Render one document and return it. mode final needs documents:create and costs 1 credit, charged only after the PDF exists; mode preview needs documents:preview and is free and watermarked. The response is the PDF unless the Accept header lists application/json and lists none of application/pdf, application/* or */*; errors are always JSON. Every response states credit_used.

Key: documents:create or documents:preview. Success: 201. It can also answer 400, 401, 402, 403, 404, 409, 413, 415, 422, 429, 500, 502, 503, 504.

POST /api/v1/documents/validate

Run exactly the checks POST /documents runs before rendering. No render, no credit. Any valid key. 200 when the request would render; 422 validation_failed, with every problem listed, when it would not. Idempotency-Key is ignored.

Key: any valid key. Success: 200. It can also answer 400, 401, 404, 409, 413, 415, 422, 429, 500, 503.

GET /api/v1/documents

The records of the documents your account made through the API in the last 90 days, newest first.

Key: documents:read. Success: 200. It can also answer 400, 401, 403, 404, 429, 500, 503.

GET /api/v1/documents/{id}

One document's stored metadata (never the file or its fields).

Key: documents:read. Success: 200. It can also answer 400, 401, 403, 404, 429, 500, 503.

GET /api/v1/documents/{id}/file

Reserved. Always 404 file_not_available, because Koutei stores no documents. The file is returned only in the response to POST /api/v1/documents. Within 24 hours, repeat that request with the same Idempotency-Key to get it again for free. A later API version may serve files here; that would be additive.

Key: documents:read. It has no success answer. It can also answer 400, 401, 403, 404, 429, 500, 503.

GET /api/v1/account

Plan, credits, the calling key and its limits.

Key: account:read. Success: 200. It can also answer 400, 401, 403, 404, 429, 500, 503.

Reserved names

These names are held for later versions. Today each is refused with 400 reserved_field, so a name is never ignored now and given a meaning later.

At the top level of the body: callback_url, webhook, file_url, einvoice, validation, jurisdiction, metadata, logo.

Inside output, only {"format":"pdf"} is accepted today. The format values "pdf-a3" and "xml" are reserved, and so is every other member of output, such as pdf_standard, standard and attachments.

Inside fields, for every template: seller, buyer, payment, document, items[].tax.

invoice · Invoice, version 2.0.0

An invoice a seller issues to a client: 1 to 50 line items, an optional discount, one optional tax line, an optional amount already paid and the balance due. Paper: "a4" or "letter".

Rules across fields:

• At least one line item. (no_items)
• At most 50 line items. (too_many_items)
• The subtotal (the sum of the rounded lines) must be at least 0. (negative_total)
• The subtotal must be below 10^15. (total_too_large)
• The discount may not exceed the subtotal. (discount_too_large)
• amount_paid may not exceed the total. (amount_paid_too_large)
• tax_label needs tax_rate. (requires_field)

What it is, and is not:

• A seller-issued invoice with the heading INVOICE.
• Totals are calculated from the line items: each amount is quantity × unit price, rounded to the currency’s minor unit.
• Not a tax invoice: the heading is never TAX INVOICE.
• Not checked for tax or legal compliance: Koutei never asserts that a document is tax-compliant or legally valid.
• Not an e-invoice: it carries no Factur-X, ZUGFeRD or XRechnung data, and it is not PDF/A.
• Not numbered by Koutei: you supply the document number, and it is never allocated or checked for uniqueness.
• Not stored: neither the fields nor the PDF are kept, and nothing is sent to anyone.

{
  "template": "invoice",
  "template_version": "2",
  "mode": "final",
  "reference": "JOB-0017",
  "paper": "a4",
  "fields": {
    "seller_name": "Aiko Tanaka Design",
    "seller_details": "aiko@example.com\n12 Example Street, Cape Town",
    "tax_id": "4000000000",
    "client_name": "Northwind Pty Ltd",
    "client_details": "accounts@northwind.example",
    "invoice_number": "INV-0042",
    "date": "2026-10-12",
    "due_date": "2026-10-26",
    "po_number": "PO-7731",
    "related_document": "Q-0042",
    "currency": "ZAR",
    "items": [
      {
        "description": "Brand workshop",
        "quantity": 1,
        "unit_price": "6000.00"
      },
      {
        "description": "Design hours",
        "quantity": "7.5",
        "unit_price": "850.00"
      }
    ],
    "discount": "10%",
    "tax_rate": "15",
    "tax_label": "VAT",
    "amount_paid": "2000.00",
    "payment_terms": "Due within 14 days",
    "payment_instructions": "Bank: Example Bank · Account no.: 000000000\nReference: INV-0042"
  }
}

quote · Quote / Estimate, version 1.0.0

A quote or an estimate: the scope of work with either 1 to 50 line items and their total, or one fixed amount, plus optional terms and an acceptance block. Paper: "a4" or "letter".

Rules across fields:

• Exactly one of items (1 to 50) and amount. (items_or_amount)
• An items list needs at least one line item. (no_items)
• At most 50 line items. (too_many_items)

What it is, and is not:

• A seller-issued quote or estimate; document_title chooses the heading.
• Either line items with a calculated total, or a fixed amount. There is no tax arithmetic.
• Not a contract: the acceptance block is a place to sign, nothing is signed electronically.
• Not checked for tax or legal compliance: Koutei never asserts that a document is tax-compliant or legally valid.
• Not an e-invoice: it carries no Factur-X, ZUGFeRD or XRechnung data, and it is not PDF/A.
• Not numbered by Koutei: you supply the document number, and it is never allocated or checked for uniqueness.
• Not stored: neither the fields nor the PDF are kept, and nothing is sent to anyone.

{
  "template": "quote",
  "mode": "final",
  "reference": "JOB-0020",
  "fields": {
    "document_title": "Estimate",
    "seller_name": "Kumo Studio",
    "seller_details": "hello@kumo.example",
    "client_name": "Sakura Cafe",
    "quote_number": "Q-0107",
    "date": "2026-10-12",
    "valid_until": "2026-11-11",
    "scope": "Menu photography and layout for the autumn menu.",
    "currency": "JPY",
    "items": "Photography (half day) | 1 | 60000\nMenu layout | 2 | 25,000",
    "terms": "50% deposit to start.",
    "show_acceptance": true
  }
}

receipt · Payment Receipt, version 1.0.0

A receipt a seller issues after a client has paid: who paid, the amount, the payment date and method, what it was for and the invoice it settles. Paper: "a4" or "letter".

Older names, still accepted: invoice_reference (use related_document).

Rules across fields:

• amount must be more than 0. (must_be_positive)
• Send related_document or its deprecated alias invoice_reference, not both. (conflicting_fields)

What it is, and is not:

• A seller-issued payment receipt with a PAID stamp under the amount received.
• Not a till or point-of-sale receipt, and it carries no third-party branding.
• Not checked for tax or legal compliance: Koutei never asserts that a document is tax-compliant or legally valid.
• Not an e-invoice: it carries no Factur-X, ZUGFeRD or XRechnung data, and it is not PDF/A.
• Not numbered by Koutei: you supply the document number, and it is never allocated or checked for uniqueness.
• Not stored: neither the fields nor the PDF are kept, and nothing is sent to anyone.

{
  "template": "receipt",
  "mode": "final",
  "reference": "JOB-0021",
  "paper": "letter",
  "fields": {
    "seller_name": "Gulf Freight Brokers",
    "client_name": "Al Noor Trading",
    "receipt_number": "R-0051",
    "payment_date": "2026-10-14",
    "related_document": "INV-0051",
    "description": "Settlement of invoice INV-0051 (customs brokerage, October).",
    "currency": "KWD",
    "amount": "1250.5",
    "payment_method": "Bank transfer",
    "payment_reference": "TRF-88213"
  }
}

A line item

In the array form of line_items, each item is an object with these 3 names. An item with any other name is refused.

Headers of a document

The file is named after the template and your document number, for example invoice-INV-0042.pdf; a preview ends -preview.pdf.

The JSON form

The JSON form of a 201 (Accept application/json only).

The totals

The money figures the document prints, on every valid document request's answer: currency, then each figure the document prints, as a money string. A member the document does not print is absent, never null. invoice: subtotal, total and balance_due always; discount, tax and amount_paid when the request sent discount, tax_rate and amount_paid. quote: subtotal with items; total always. receipt: amount_paid (the amount received). The figures come from the same arithmetic as the document, run on the normalised request the document is rendered from; a replay states the same totals.

On a 201, each member is also a header, present exactly when the member is: Koutei-Totals-Currency, Koutei-Totals-Subtotal, Koutei-Totals-Discount, Koutei-Totals-Tax, Koutei-Totals-Total, Koutei-Totals-Amount-Paid and Koutei-Totals-Balance-Due. The PDF form has no body to hold them, so the headers are where an automation reads the total due. A check (POST /api/v1/documents/validate) states the same totals before anything is made, and a repeat with the same Idempotency-Key states the same totals as the first answer. Errors have none.

The Document object

Stored metadata of one document; the same object in every response. The values you sent in fields are never in it.

Other answers

POST /api/v1/documents/validate:

GET /api/v1/documents: Ordered by created_at, then id, both descending. A starting_after that is not one of your listable documents gets 400 invalid_request (invalid_query).

GET /api/v1/account:

GET /api/v1/templates returns a list of these; GET /api/v1/templates/{slug} returns one, with the detail rows: