Get OpenAPI YAML

GET

openapi.yaml

This OpenAPI document (YAML)

curl --request GET \
  --url https://billing.example.com/openapi.yaml \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://billing.example.com/openapi.yaml', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/openapi.yaml",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/openapi.yaml"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/openapi.yaml")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

"<string>"

Serves the OpenAPI 3.1 document that describes every route on this instance, exactly as authored. The spec is embedded into the binary at build time, so what you download always matches the code that is running — it is the same file this reference is generated from and the source the SDKs are kept in sync with. No authentication is required. For the same document as JSON, use Get OpenAPI JSON; to confirm which build you are reading, pair it with Get Version.

Example Request

curl https://api.recurso.dev/openapi.yaml -o recurso-openapi.yaml

Response

Content-Type: application/yaml. The body is the specification document itself, byte-for-byte as authored, not a JSON envelope. The excerpt below is abridged — # … comments mark where the real document continues — but every line shown is verbatim.

openapi: 3.1.0
info:
  title: Recurso API
  version: 1.0.0
  # … description and license
servers:
  - url: https://billing.example.com
    description: Example deployment — substitute the base URL of your own Recurso deployment.

security:
  - bearerAuth: []

# … tags

paths:
  /health:
    get:
      operationId: getHealth
      tags: [System]
      summary: Health check
      description: Reports overall service health plus per-component status (Postgres, Redis, TigerBeetle).
      security: []
      responses:
        '200':
          description: Service is healthy (or degraded but serving).
          # … content, and the '503' response
  # … every other path
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Tenant API key obtained from `POST /auth/register` or `POST /v1/developer/keys`.
    # … portalSession and sessionCookie
  # … parameters, responses and schemas

Errors

This endpoint has no failure modes of its own and always returns 200. A build whose embedded spec fails to parse does not start, so a running instance always has a valid document to serve.

Authorizations

Authorization

string

header

required

Response

200 - application/yaml

The OpenAPI 3.1 specification in YAML.

The response is of type string.

This OpenAPI document (YAML)

curl --request GET \
  --url https://billing.example.com/openapi.yaml \
  --header 'Authorization: <api-key>'

const options = {method: 'GET', headers: {Authorization: '<api-key>'}};

fetch('https://billing.example.com/openapi.yaml', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/openapi.yaml",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/openapi.yaml"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/openapi.yaml")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

"<string>"

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Example Request

Response

Errors

Authorizations

Response

​Example Request

​Response

​Errors

Authorizations

Response

Example Request

Response

Errors