API Reference

The Yona REST API is organized around standard HTTP methods and JSON request/response bodies.

Base URL

https://gateway.useyona.com

Authentication

All requests require an API key as a Bearer token:


Authorization: Bearer sk_test_your_key_here

Service prefixes

Service	Prefix
Invoice service	`/i/v1`
Billing service	`/b/v1`
Auth service	`/a/v1`

Response envelope

Success


{
 "meta": {
 "statusCode": 200,
 "success": true,
 "errors": [],
 "message": "Success",
 "timestamp": "2026-04-19T10:30:00.000Z"
 },
 "data": { }
}

Error


{
 "meta": {
 "statusCode": 400,
 "success": false,
 "errors": [{ "VAL001": "Validation failed" }],
 "message": "Validation failed",
 "errorCode": "VAL001",
 "timestamp": "2026-04-19T10:30:00.000Z",
 "path": "/i/v1/invoices",
 "method": "POST"
 },
 "data": null
}

Paginated


{
 "meta": {
 "statusCode": 200,
 "success": true,
 "errors": [],
 "message": "Success",
 "pagination": {
 "total": 150,
 "page": 1,
 "pageSize": 20,
 "totalPages": 8,
 "hasNext": true,
 "hasPrevious": false
 },
 "timestamp": "2026-04-19T10:30:00.000Z"
 },
 "data": []
}

Error codes

Code	Meaning	HTTP Status
AUTH001	Invalid credentials	401
AUTH002	Token expired	401
AUTH004	Unauthorized	401
AUTH005	Forbidden	403
VAL001	Validation failed	400
VAL002	Missing required field	400
RES001	Not found	404
RES002	Already exists	409
BIZ001	Insufficient balance	400
BIZ004	Invalid state	400
INV001	Invalid invoice format	400
INV002	Already submitted	400
INV003	Cannot modify	400
SYS001	Internal error	500
TAX001	Tax authority connection error	502