Redocly platform (1.0.1)

Redocly platform API is a REST API over HTTPS for accessing and managing Redocly platform resources.

The API supports the following use cases:

Automation of organization and project workflows
Integration with internal systems
Development of customer-facing integrations

Technical characteristics:

Resource-oriented URLs
JSON request and response bodies
Standard HTTP methods and status codes
Filtering and search on selected collection endpoints

Endpoint availability depends on subscription plan, organization settings, and product rollout status. The API description is the authoritative reference. Organizations for which an endpoint is not enabled should contact support.

Authentication

The API uses API keys for authentication. Authentication requirements are defined per operation in the API description.

API keys are intended for server-to-server integration. API keys are created as described in Manage API keys. The key is transmitted as a Bearer token:

Authorization: Bearer <api_key>

Keys must meet the following requirements:

Stored in a secure secret management system (not in client-side application code)
Rotated on a regular basis
Revoked when no longer required
Limited to the minimum set of endpoints and environments necessary for the integration

Every operation states the authentication it accepts in its own security section. Typical responses include:

401 Unauthorized (missing, invalid, or expired credentials)
403 Forbidden (credentials are valid but insufficient for the requested action)

Pagination

List endpoints implement cursor-based pagination. Each response includes a page object and the results in the data array.

Supported query parameters:

limit: values from 1 to 100, default 10
after and before: cursor navigation
sort: for example -id or id

The page object contains:

nextPage: the path of the next page, or null when there is no next page
previousPage: the path of the previous page, or null when there is no previous page
limit

nextPage and previousPage are paths relative to the API server URL. They keep the query parameters of the request, such as limit, filter, and sort. nextPage sets after to the cursor of the next page, and previousPage sets before to the cursor of the previous page. To get the adjacent page, append the value to the server URL as a string:

https://app.cloud.redocly.com/api + /orgs/org_123/projects?limit=10&after=a25fgaksjf23la==
= https://app.cloud.redocly.com/api/orgs/org_123/projects?limit=10&after=a25fgaksjf23la==

Do not resolve the value as a relative URL, for example with new URL(nextPage, serverUrl). The leading / replaces the /api path of the server URL.

A typical sequence:

Request the first page with ?limit=10.
Read page.nextPage.
Request the server URL followed by page.nextPage.
Continue until nextPage is null.

The cursors are opaque, and their internal structure is subject to change. To build a request yourself, send the after value from nextPage, or the before value from previousPage, with your other query parameters.

Filter results

Filtering uses the ?filter= parameter with field:value syntax. The supported forms include:

Exact match: firstName:Casey
Case-insensitive substring match: firstName~jo
Multiple values: firstName:Casey,Jordan, status:success,pending
Numeric or date-time ranges: amount:1..10, ISO 8601 date-times
Relative durations for date-time fields: 30d, 2w, 6mo, 1y, all (units: s, m, h, d, w, mo, y)
Nested fields: team.user.email:casey.smith@acme-inc.com
Negation: -firstName:Casey
Logical operators: AND, OR

Combine multiple conditions by separating field:value pairs with a space. A space is treated as an implicit AND, so firstName:Casey isAdmin:true and firstName:Casey AND isAdmin:true are equivalent. Use OR to match alternatives. AND binds more tightly than OR, so role:admin OR role:editor isActive:true is evaluated as role:admin OR (role:editor AND isActive:true). Grouping with parentheses is not supported.

For a single-valued field, comma-separated values and OR are equivalent: role:admin,editor matches the same records as role:admin OR role:editor. They are not interchangeable when the field targets a to-many relation, when negation is applied (-role:admin,editor matches neither value, whereas -role:admin OR -role:editor matches every record), or when matching null.

Explicit date-time values use ISO 8601. Values that contain spaces, commas, or .. must be enclosed in quotation marks. number, boolean, and null values do not require quotation marks.

?filter=firstName:Casey
?filter=firstName~jo
?filter=firstName:Casey,Jordan
?filter=amount:1..10
?filter=createdAt:30d
?filter=team.user.email:casey.smith@acme-inc.com
?filter=-firstName:Casey
?filter=firstName:Casey isAdmin:true
?filter=firstName:Casey AND isAdmin:true
?filter=role:admin OR role:editor
?filter=createdAt:2021-02-14T13:30:00.000Z
?filter=description:"The story called \"The Sky and the Sea.\""
?search=casey

Search uses the ?search= parameter where the operation supports it. Its behavior is defined per endpoint in the API description.

Errors

Error responses commonly use the application/problem+json media type. Fields may include:

type
title
status
detail (optional)
instance (optional)
object (always problem)
requestId (optional)
errors (optional array)

Frequently returned HTTP status codes:

400: validation failure or malformed input
401: authentication failure
403: authorization failure
404: resource not found
409: conflict with current state
429: rate limit exceeded
500: server error

Additional behavior:

Certain endpoints may return 402 when access depends on subscription plan or billing state.

Troubleshooting:

Begin with the HTTP status code.
Review the detail and errors fields.

Include the following in support requests:

The complete response payload
Sufficient request context to reproduce the issue

Rate limits

Rate limiting preserves service stability and equitable usage.

The API description defines limits with the x-rateLimit extension. These organization quotas apply to requests authenticated with an API key that belongs to your organization. Example properties:

events - the number of events allowed within the window
window - the length of the window, for example 1m

Enforcement:

For API keys, limits apply per organization: all API keys for the same organization share a single counter for a given limit.
Unauthenticated traffic to public endpoints does not consume these organization counters. It is limited separately (for example by per-client protections at the edge). This mechanism prevents anonymous callers from exhausting an organization's quota.
Limits may be defined per endpoint.
Limits may be overridden per organization or per endpoint.

When a request exceeds the applicable limit, the API returns 429 Too Many Requests and includes a Retry-After header with the number of seconds to wait before the next request.

Send requests for increased throughput to team@redocly.com and include: