API Reference

The Loyva partner API is a RESTful JSON API served over HTTPS. All partner endpoints are versioned under /api/v2/partner/* and authenticated with an API key.

Base URL

https://api.stg.loyva.net/api/v2

Request format

• All request bodies must be JSON with Content-Type: application/json
• File uploads use Content-Type: multipart/form-data
• Dates are ISO 8601 strings (2026-04-11T10:00:00.000Z)
• IDs are prefixed strings (e.g., env_, cust_, lk_)

Authentication

Every partner API request is authenticated with your lk_... key in the X-API-Key header:

X-API-Key: lk_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

The organization is derived from the key — no additional org header is required.

See Authentication for full details, including short-lived embed tokens for iframe widgets.

Pagination

List endpoints return paginated results:

Request:

GET /api/v2/partner/envelopes?page=2&limit=25

Response:

{
  "data": [...],
  "meta": {
    "page": 2,
    "limit": 25,
    "total": 142
  }
}

Parameter	Default	Max	Description
page	1	—	Page number (1-indexed)
limit	20 (50 for some endpoints)	100–200 depending on endpoint	Items per page

note

The page count is not returned — compute it client-side as Math.ceil(total / limit).

Response envelope

Every 2xx response wraps resources under a top-level data field. Mutation endpoints wrap the created/updated resource the same way. Errors use { "error": "...", "details"?: [...] } instead.

{ "data": { /* resource */ } }
{ "data": [ /* resources */ ], "meta": { "page": 1, "limit": 20, "total": 42 } }

Rate limits

Partner keys have an rate_limit_rpm configured at provisioning time (default 60). Rate limit headers are returned on every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1712836860

When rate limited, you'll receive a 429 Too Many Requests response.

Common headers

Request headers

Header	Required	Description
X-API-Key	Yes	Your partner key (lk_...)
Content-Type	Yes (writes)	application/json

Response headers

Header	Description
X-Request-Id	Unique request ID for debugging
X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset	Rate limit state

ID formats

Resource	Prefix	Example
Envelope	env_	env_x7k9m2p4q1w3
Customer	cust_	cust_abc123def456
API Key	lk_	lk_a1b2c3d4e5f6...
Organization	org_	org_main789

Status codes

Code	Meaning
200	Success
201	Created
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient scope
404	Not found
409	Conflict — resource already exists
422	Unprocessable — valid JSON but semantic error
429	Rate limited
500	Internal server error

See Errors for the error response format.