REST API

Search providers

curl "https://openapi.city/api/v1/providers/search?q=payment&category=fintech" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Response:

{
  "results": [
    {
      "slug": "stripe",
      "name": "Stripe",
      "description": "Online payment processing",
      "category": "payments",
      "endpoint_count": 243
    }
  ],
  "endpoint_matches": [
    {
      "provider": "stripe",
      "method": "POST",
      "path": "/v1/charges",
      "summary": "Create a charge"
    }
  ],
  "meta": { "page": 1, "per_page": 25, "total": 1, "total_pages": 1 }
}

Parameters:

List providers

curl "https://openapi.city/api/v1/providers" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Get provider

curl "https://openapi.city/api/v1/providers/stripe" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Get full spec

curl "https://openapi.city/api/v1/providers/stripe/spec" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Returns the complete OpenAPI specification as JSON.

Versioned access

All provider-scoped endpoints accept an optional version query parameter to access a specific spec version instead of the current one:

# Get spec for a specific version
curl "https://openapi.city/api/v1/providers/stripe/spec?version=2024-01-01" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

# List endpoints for a specific version
curl "https://openapi.city/api/v1/providers/stripe/endpoints?version=2024-01-01" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

# Get schema from a specific version
curl "https://openapi.city/api/v1/providers/stripe/schemas/Charge?version=2024-01-01" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Omit version to use the latest (current) version.

List versions

curl "https://openapi.city/api/v1/providers/stripe/versions" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Get versioned spec by ID

curl "https://openapi.city/api/v1/providers/stripe/versions/42/spec" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

List endpoints

curl "https://openapi.city/api/v1/providers/stripe/endpoints" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Filter by method:

curl "https://openapi.city/api/v1/providers/stripe/endpoints?method=GET" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Get single endpoint

curl "https://openapi.city/api/v1/providers/stripe/endpoints/GET/v1/charges" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Returns parameters, request body schema, response schemas, and authentication requirements.

Get schema

curl "https://openapi.city/api/v1/providers/stripe/schemas/Charge" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Returns the full schema definition. Nested $ref references are preserved — call get_schemas for each referenced schema as needed.

Get summary

curl "https://openapi.city/api/v1/providers/stripe/summary" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Returns an AI-generated summary of the spec.

Get auth requirements

curl "https://openapi.city/api/v1/providers/stripe/auth" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Resolve a spec URL

Submit a new OpenAPI spec URL for ingestion:

curl -X POST "https://openapi.city/api/v1/resolve" \
  -H "Authorization: Bearer oac_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://petstore3.swagger.io/api/v3/openapi.json"}'

Code examples

Python:

import requests

API_KEY = "oac_live_YOUR_KEY"
BASE = "https://openapi.city/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

r = requests.get(f"{BASE}/providers/search", params={"q": "stripe"}, headers=headers)
print(r.json())

JavaScript:

const API_KEY = "oac_live_YOUR_KEY";
const BASE = "https://openapi.city/api/v1";

const res = await fetch(`${BASE}/providers/search?q=stripe`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const data = await res.json();
console.log(data);

Ruby:

require "net/http"
require "json"

API_KEY = "oac_live_YOUR_KEY"
uri = URI("https://openapi.city/api/v1/providers/search?q=stripe")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{API_KEY}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts JSON.parse(response.body)

Next: MCP Integration →