API Overview

Base URL

https://openapi.city/api/v1

Response format

All responses are JSON. Successful responses return 200 OK. Errors return appropriate HTTP status codes with a JSON body:

{
  "error": "Not found"
}

Rate limiting

Two layers of rate limiting protect the API:

1. Per-IP throttling (rack-attack)

• 60 requests/minute on public endpoints (.well-known/mcp)
• 120 requests/minute on API endpoints (/api/*, /mcp)
• Returns 429 Too Many Requests with Retry-After header

2. Per-key monthly limits (billing)

Every response includes usage headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1719792000

Pagination

List endpoints use cursor-based pagination via the page and per_page parameters:

curl "https://openapi.city/api/v1/providers?page=2&per_page=10" \
  -H "Authorization: Bearer oac_live_YOUR_KEY"

Response includes a meta object:

{
  "meta": {
    "page": 2,
    "per_page": 10,
    "total": 112,
    "total_pages": 12
  }
}

Caching

API responses support HTTP caching:

• ETag header for content-based caching
• Last-Modified header for time-based caching
• Cache-Control: must-revalidate, private

Use If-None-Match or If-Modified-Since headers to get 304 Not Modified responses, saving your monthly usage quota.

Versioning

Current API version: v1. The version is part of the URL path. Breaking changes will use a new version number.

Spec versioning

Providers can have multiple spec versions stored over time. By default, all endpoints return data from the current (latest) version. Pass a version query parameter to access a specific historical version:

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

Supported on: provider detail, spec, summary, tag, endpoints list, endpoint detail, and schema endpoints.

List all available versions:

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

Next: REST API →