API Introduction

Base URL

https://api.recurso.dev/v1

api.recurso.dev is a placeholder — substitute the domain where your Recurso instance is deployed. All API examples in this reference use the same placeholder.

OpenAPI Specification

Every Recurso instance serves its own OpenAPI 3.1 spec at /openapi.json (and /openapi.yaml) — no authentication required. The interactive playground in this reference is powered by a vendored copy of the same spec, so you can also point code generators or API clients directly at your running instance:

curl https://api.recurso.dev/openapi.json

Postman collection

A ready-to-import Postman collection covering every endpoint (generated from the OpenAPI spec, grouped by resource) lives in the repository under postman/. Import both recurso.postman_collection.json and recurso.postman_environment.json, select the Recurso environment, then set baseUrl (your instance) and bearerToken (an API key from Developers). Every request then authenticates automatically — see postman/README.md for the regenerate command.

Authentication

Authenticate using API keys in the Authorization header:

curl https://api.recurso.dev/v1/customers \
  -H "Authorization: Bearer rsk_live_xxx"

Keep your API keys secret. Never expose them in client-side code.

API Key Types

Type	Prefix	Use Case
Live	`rsk_live_`	Production
Test	`rsk_test_`	Development/testing

Test keys only work with test data and test payment methods.

Request Format

All requests use JSON:

curl -X POST https://api.recurso.dev/v1/customers \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }'

Response Format

Success responses wrap the result in a data envelope:

{
  "data": {
    "id": "cust_abc123",
    "name": "Acme Corp",
    "email": "billing@acme.com",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

List Responses

Collections wrap the array the same way — page through with limit/offset (there is no cursor or has_more flag; an empty or short page means you reached the end):

{
  "data": [
    { "id": "cust_abc" },
    { "id": "cust_def" }
  ]
}

Pagination

Use limit and offset for pagination:

GET /v1/customers?limit=20&offset=40

Parameter	Default	Max
`limit`	50	varies by endpoint (most lists cap at 100–1000)
`offset`	0	-

Pass an explicit limit whenever you need the full set — defaults and caps vary across list endpoints.

Errors

Every error — regardless of endpoint or status code — uses the same envelope: an error object with a stable machine-readable code and a human-readable message:

{
  "error": {
    "code": "not_found",
    "message": "Customer cust_xyz not found"
  }
}

See Errors for the full code taxonomy.

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request
`401`	Unauthorized
`404`	Not Found
`422`	Validation Error
`429`	Rate Limited
`500`	Server Error

Rate Limits

Rate limits depend on your Recurso plan:

Plan	Requests/min	Description
Open Source	Unlimited (self-configured)	Self-hosted, configure your own limits
Cloud	600	Managed hosting, free to start
Enterprise	Custom	Dedicated infrastructure with custom limits

Self-hosted users can configure their own rate limits with no restrictions. See the Developer Settings guide for configuration options.

Rate limit info in response headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1705312800

Idempotency

All mutating requests (POST, PUT, PATCH, DELETE) accept an Idempotency-Key header to prevent duplicate operations — keys are scoped per tenant, method, and path:

curl -X POST https://api.recurso.dev/v1/subscriptions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{ ... }'

Use UUIDs or your own unique identifiers as idempotency keys.

Versioning

API version in header (optional):

Recurso-Version: 2024-01-01

Without version, you get the latest stable API.

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Base URL

OpenAPI Specification

Postman collection

Authentication

API Key Types

Request Format

Response Format

List Responses

Errors

HTTP Status Codes

Rate Limits

Idempotency

Versioning

​Base URL

​OpenAPI Specification

​Postman collection

​Authentication

​API Key Types

​Request Format

​Response Format

​List Responses

​Pagination

​Errors

​HTTP Status Codes

​Rate Limits

​Idempotency

​Versioning

Base URL

OpenAPI Specification

Postman collection

Authentication

API Key Types

Request Format

Response Format

List Responses

Pagination

Errors

HTTP Status Codes

Rate Limits

Idempotency

Versioning