Opens on reph with the template ready to start. No account needed; sign in to keep your document.
The template filled in for a made-up company, so you can see what good looks like.
Invoices API v1
Author: Mei Tanaka · Date: 2026-04-08 · Base URL: https://api.lumenlabs.io/v1
Overview
Lets partner accounting tools create, read and void invoices in a Lumen Labs workspace. Consumers are three launch partners (Ledgerly, Brightbooks, Fernhill Accounting) and, from Q3, the public API.
Authentication
Bearer API keys in the Authorization header, issued per workspace from Settings, API keys. Keys are scoped invoices:read or invoices:write.
Conventions
- Pagination: cursor based,
?cursor= and ?limit= (default 25, max 100), next_cursor in the response
- Idempotency:
Idempotency-Key header on every POST; repeats within 24 hours return the original response
- Timestamps: ISO 8601, UTC
Endpoints
POST /invoices
Creates a draft invoice for an existing customer.
Request
{
"customer_id": "cus_8Qd2",
"currency": "EUR",
"lines": [{ "description": "Consulting, March", "quantity": 12, "unit_amount": 15000 }],
"due_date": "2026-05-08"
}
Response 201 Created
{
"id": "inv_3Kp9",
"status": "draft",
"total": 180000,
"currency": "EUR"
}
Errors
| Code |
Status |
Meaning |
invalid_request |
400 |
A line has a negative quantity or the currency is unsupported |
unauthorized |
401 |
Missing key, or the key lacks invoices:write |
not_found |
404 |
customer_id is not in this workspace |
Rate limits
100 requests per 10 seconds per key. X-RateLimit-Remaining and X-RateLimit-Reset on every response; a 429 carries Retry-After.
SLOs
Availability
99.9%
▲ +0.05%
Error rate (5xx)
0.08%
▼ -0.03%
Versioning & deprecation
The major version lives in the URL. Additive fields ship without notice; a breaking change ships as /v2 with at least 6 months of overlap and a Sunset header on v1.
Changelog
| Date |
Change |
| 2026-04-08 |
First draft for partner review |
| 2026-04-15 |
Added due_date, made currency required |
Show the blank template
API spec
Author: [your name] · Date: [date] · Base URL: https://api.example.com
Overview
What this API does and who consumes it (internal service, partner, public).
Authentication
Scheme (bearer token, HMAC, OAuth), header name, and where credentials come from.
Conventions
- Pagination: cursor or offset, param names, default/max page size
- Idempotency: header name and retry semantics for unsafe methods
- Timestamps: ISO 8601, UTC
Endpoints
POST /resource
One-line description of what this does.
Request
{
"field": "value"
}
Response 201 Created
{
"id": "res_123",
"field": "value"
}
Errors
| Code |
Status |
Meaning |
invalid_request |
400 |
|
unauthorized |
401 |
|
not_found |
404 |
|
Rate limits
Requests per window, per key/IP, and the headers that report remaining quota.
SLOs
The targets consumers can design against. Measure them at the edge, per endpoint if they differ.
Versioning & deprecation
How a breaking change is introduced (URL version, header, new field) and the deprecation notice window.
Changelog
Connect Claude to reph over MCP, then paste this. The draft arrives as suggestions you accept or reject section by section. How to connect Claude.
Find my reph doc "API spec" with search_docs, then read it with read_doc. Draft endpoints, request and response shapes and the error table from the route handlers, OpenAPI file or ticket I link; fill Authentication, Rate limits and SLOs from service config. Mark any field whose type or nullability you inferred. File it with suggest_edit, one replace_section op per section (heading line kept) so each can be accepted alone. Ask each open question (unclear error codes or versioning) with add_comment quoting that section's heading line, then call request_review with a one-line summary.