API reference
Version 0.4.6
Public REST API for managing APIs (OpenAPI documents), JSON Schemas, Spectral rulesets, hosted sites, language SDKs, and generator builds.
Rulesets may define a default blocking severity (off / error / warn /
info). Attach a ruleset to an API (and optionally override severity) to
reject OpenAPI version publishes that fail Spectral lint at that threshold.
Base URL
Authentication
Organization API key (`sk_…`)
APIs
Register OpenAPI documents, attach Spectral rulesets, and publish new revisions.
List APIs
Lists OpenAPI registry entries in the API key's organization, ordered by name.
Each item may include the current spec summary when one is published.
Results are paginated with page and limit.
Parameters
page
integerquery1-based page of results to return.
Example
1
limit
integerqueryMaximum number of items to return (1–100).
Example
10
Responses
APIs in the API key's organization for the current page.
total
integerrequiredTotal number of APIs matching the request across all pages.
Example
1
Create an API
Creates a new OpenAPI registry entry. Optionally attach a Spectral ruleset and blocking severity so later spec uploads are linted before publish.
Request body *
ApiCreateRequestname
stringrequiredDisplay name for the API.
Example
Payments API
slug
string^[a-z0-9]+(?:-[a-z0-9]+)*$Optional URL slug; derived from `name` when omitted. Used in registry URLs.
Example
payments-api
visibility
stringRegistry visibility. Defaults to `private`.
Example
public
values
description
stringOptional summary shown in the console and public registry.
Example
Charge, refund, and reconcile card payments for connected accounts.
ruleset_id
stringOptional Spectral ruleset to attach for linting uploads.
Example
01J8A7B2C3D4E5F6G7H8J9KMN3
blocking_severity
stringOptional per-API lint threshold override.
Example
warn
values
Responses
data
objectrequiredThe API.
Get an API
Returns one API, including its current OpenAPI revision when published.
Parameters
Responses
data
objectrequiredThe API.
Update an API
Update metadata, attached ruleset, or per-API blocking severity override. When a ruleset is attached, new OpenAPI uploads are linted and rejected if findings meet the effective blocking threshold.
Parameters
Request body *
ApiUpdateRequestname
stringUpdated display name.
Example
Payments API
slug
string^[a-z0-9]+(?:-[a-z0-9]+)*$Updated URL slug.
Example
payments-api
visibility
stringUpdated registry visibility.
Example
public
values
description
string | nullnullableUpdated summary. Send `null` to clear.
Example
Charge, refund, and reconcile card payments for connected accounts.
logo_url
string | nullnullableUpdated logo URL. Send `null` to clear.
Example
https://cdn.example.com/logos/payments.svg
Attach or detach a Spectral ruleset. Send `null` to clear.
Example
01J8A7B2C3D4E5F6G7H8J9KMN3
Override or clear the lint blocking threshold. Send `null` to inherit the ruleset default.
Example
warn
Responses
data
objectrequiredThe API.
Upload an OpenAPI document
Validates and stores a new current SpecVersion. An unchanged checksum is a no-op that returns the existing current version.
When the API has an attached ruleset, the document is linted with Spectral.
Uploads that meet the effective blocking severity are rejected (422) and
not stored.
Parameters
Request body *
SpecUploadRequestdocument
objectrequiredOpenAPI 3.x document as a JSON string or object (YAML strings are also accepted).
Responses
data
objectrequiredThe spec version.
Schemas
JSON Schema registry entries and version history for shared models.
List schemas
Lists JSON Schema registry entries in the API key's organization, ordered by name.
Results are paginated with page and limit.
Parameters
page
integerquery1-based page of results to return.
Example
1
limit
integerqueryMaximum number of items to return (1–100).
Example
10
Responses
Schemas in the API key's organization for the current page.
total
integerrequiredTotal number of schemas matching the request across all pages.
Example
1
Create a schema
Creates a JSON Schema registry entry. Pass an optional document to publish
the first version in the same request.
Request body *
SchemaCreateRequestname
stringrequiredDisplay name for the schema.
Example
Customer
slug
string^[a-z0-9]+(?:-[a-z0-9]+)*$Optional URL slug; derived from `name` when omitted.
Example
customer
visibility
stringWhether the schema is listed on the public registry.
Example
public
values
description
stringOptional summary shown in the console and public registry.
Example
Canonical customer profile used by billing and support APIs.
document
objectOptional initial JSON Schema document to publish as the first version.
Responses
data
objectrequiredThe schema.
Get a schema
Returns one JSON Schema registry entry with its current version when published.
Parameters
Schema ULID.
Example
01J8X4K2M9N7P6Q5R4S3T2V1W0
Responses
data
objectrequiredThe schema.
Upload a JSON Schema document
Validates and stores a new current SchemaVersion. An unchanged checksum is a no-op that returns the existing current version.
Parameters
Schema ULID.
Example
01J8X4K2M9N7P6Q5R4S3T2V1W0
Request body *
DocumentUploadRequestdocument
objectrequiredDocument as a JSON string, YAML string, or JSON object.
Responses
data
objectrequiredThe schema version.
Rulesets
Spectral rulesets that lint OpenAPI uploads before they become current.
List rulesets
Lists Spectral rulesets in the API key's organization, ordered by name.
Results are paginated with page and limit.
Parameters
page
integerquery1-based page of results to return.
Example
1
limit
integerqueryMaximum number of items to return (1–100).
Example
10
Responses
Rulesets in the API key's organization for the current page.
total
integerrequiredTotal number of rulesets matching the request across all pages.
Example
1
Create a ruleset
Creates a ruleset. When document is omitted, a default Spectral OAS
ruleset (extends: spectral:oas) is stored as the first version.
Request body *
RulesetCreateRequestname
stringrequiredDisplay name for the ruleset.
Example
OAS baseline
slug
string^[a-z0-9]+(?:-[a-z0-9]+)*$Optional URL slug; derived from `name` when omitted.
Example
oas-baseline
visibility
stringWhether the ruleset is listed on the public registry.
Example
private
values
description
stringOptional summary of the ruleset.
Example
Company-wide OpenAPI style and security checks based on spectral:oas.
blocking_severity
stringDefault severity that blocks OpenAPI publishes for attached APIs.
Example
error
values
document
objectOptional initial Spectral ruleset (YAML or JSON). Defaults to `extends: [spectral:oas]`.
Responses
data
objectrequiredThe ruleset.
Get a ruleset
Returns one Spectral ruleset with its current version when published.
Parameters
Ruleset ULID.
Example
01J8X4K2M9N7P6Q5R4S3T2V1W0
Responses
data
objectrequiredThe ruleset.
Update a ruleset
Update metadata or the default blocking severity for attached APIs.
Parameters
Ruleset ULID.
Example
01J8X4K2M9N7P6Q5R4S3T2V1W0
Request body *
RulesetUpdateRequestname
stringUpdated display name.
Example
OAS baseline
slug
string^[a-z0-9]+(?:-[a-z0-9]+)*$Updated URL slug.
Example
oas-baseline
visibility
stringUpdated visibility for the ruleset.
Example
private
values
description
string | nullnullableUpdated summary. Send `null` to clear.
Example
Company-wide OpenAPI style and security checks based on spectral:oas.
blocking_severity
stringUpdated default blocking threshold for attached APIs.
Example
warn
values
Responses
data
objectrequiredThe ruleset.
Upload a Spectral ruleset document
Validates and stores a new current RulesetVersion. An unchanged checksum is a no-op that returns the existing current version.
Parameters
Ruleset ULID.
Example
01J8X4K2M9N7P6Q5R4S3T2V1W0
Request body *
DocumentUploadRequestdocument
objectrequiredDocument as a JSON string, YAML string, or JSON object.
Responses
data
objectrequiredThe ruleset version.
Sites
Hosted documentation sites with attached API references.
List sites
Lists hosted documentation sites in the API key's organization, ordered by name.
Results are paginated with page and limit.
Parameters
page
integerquery1-based page of results to return.
Example
1
limit
integerqueryMaximum number of items to return (1–100).
Example
10
Responses
Sites in the API key's organization for the current page.
total
integerrequiredTotal number of sites matching the request across all pages.
Example
1
Create a site
Creates a hosted docs site. Pass api_ids to attach APIs for the reference
section; guides and domains can be configured in the console afterward.
Request body *
SiteCreateRequestname
stringrequiredInternal site name.
Example
Payments docs
slug
stringOptional URL slug; derived from `name` when omitted.
Example
payments-docs
title
stringPublic title shown in the docs UI.
Example
Payments Documentation
api_ids
array any[]Optional APIs to attach for the reference section.
Responses
data
objectrequiredThe site.
SDKs
Language client generation configs (TypeScript, PHP) for one or more APIs.
List SDKs
Lists SDK generation configs in the API key's organization, newest first.
Results are paginated with page and limit.
Parameters
page
integerquery1-based page of results to return.
Example
1
limit
integerqueryMaximum number of items to return (1–100).
Example
10
Responses
SDKs in the API key's organization for the current page.
total
integerrequiredTotal number of SDKs matching the request across all pages.
Example
1
Create an SDK
Creates a multi-target SDK config for one or more APIs. Connect a repository per target in the console; successful builds open a pull request with generated code.
Request body *
SdkCreateRequestname
stringrequiredDisplay name for the SDK.
Example
Payments SDK
Generation targets to enable.
config
object · SdkConfigProduct-owned SDK configuration stored in the database.
One or more APIs to generate clients for.
Responses
data
objectrequiredThe SDK.
Builds
SDK generator runs and publish status.
Queue an SDK build
Queues one generator run per SDK target that has a connected output repository. Successful builds open a pull request with generated files.
Parameters
Responses
List builds
Lists SDK generator builds for the organization, newest first.
Results are paginated with page and limit.
Parameters
page
integerquery1-based page of results to return.
Example
1
limit
integerqueryMaximum number of items to return (1–100).
Example
10
Responses
Builds matching the request for the current page.
total
integerrequiredTotal number of builds matching the request across all pages.
Example
1
Models
Schemas defined in this OpenAPI document.
BlockingSeverity
Severity threshold for blocking OpenAPI version publishes when a ruleset is attached. `off` never blocks. `error` blocks only errors. `warn` blocks warnings and errors. `info` blocks info, warnings, and errors. On an API, omit or null to inherit the ruleset default.
string
DocumentSource
How this document version entered the registry. `upload` is a direct API/console upload, `github` / `gitlab` come from repository sync, and `restore` is a previous version made current again.
string
OrganizationId
Owning organization ULID. Derived from the API key — never sent in create/update bodies.
string
SdkTargetType
Language or CLI target generated for an SDK.
string
Ulid
Universally Unique Lexicographically Sortable Identifier (26 Crockford base32 characters).
string
Visibility
Access mode for registry resources and hosted docs. Private resources require authentication. Public APIs, schemas, and rulesets are served on the public registry host; public sites are reachable on their domains.
string