New to Corsair? See API access, authentication, and error handling.
Apis
cloneVersion
apis.cloneVersion
Create a version that starts as a copy of an existing one
Risk: write
Creates
newVersion as a copy of the version in the path. private decides the new version’s visibility; without it the source setting is used.
Output
compare
apis.compare
Compare a definition against the stored version and list the differences
Risk: read
Posts a definition and answers a bare array of differences between it and the stored version, so the plugin returns
{ owner, api, version, changes }. method is a required query parameter on the route and takes FULL, LOGICAL or STRUCTURAL; the plugin sends FULL when you leave it out. A response that is not an array fails rather than reading as no changes.
Output
changes full type
changes full type
delete
apis.delete
Delete an API and every version of it. There is no undo and the comments go with it
Risk: destructive · Irreversible
Deletes the API and every version of it. The route answers 200 with no body, so the plugin reports
{ owner, api, deleted: true }.
Output
deleteVersion
apis.deleteVersion
Delete one version of an API. The other versions stay, and there is no undo
Risk: destructive · Irreversible
Deletes one version and leaves the others. The API itself stays.
Output
disableNotifications
apis.disableNotifications
Disable every notification the caller has on one API. Nothing else about the API changes
Risk: write
Turns off every notification the caller has on the API. The route answers 200 with no body, so the plugin reports an empty
{ enabled }.
Output
forkVersion
apis.forkVersion
Fork a version into another owner and name, including another organisation
Risk: write
Writes the version into
targetOwner under targetName and targetVersion, which can be another organisation. The name must be at least 3 characters and at most 60, and the version at most 128.
Output
getCapabilities
apis.getCapabilities
Read what the token may do with one API version, such as seeing standardization errors
Risk: read
Answers
{ canViewStandardizationErrors }, which says whether the token may read this version’s standardization findings.
Output
getDefaultVersion
apis.getDefaultVersion
Read which version the API shows by default. Null when none is set
Risk: read
Answers
{ version }, where version is null when the API has no default set.
Output
getDefinition
apis.getDefinition
Read the stored definition of one API version as text, optionally resolved or flattened
Risk: read
Answers
{ definition } as text. resolved follows $refs and flatten lifts inline schemas into named models; GraphQL definitions support neither. A JSON definition is re-serialized to a string, so the reply is always text.
Output
getNotifications
apis.getNotifications
Read which notification scopes are enabled for one API, and for the caller
Risk: read
Answers
{ enabled }, the notification scopes the caller has on the API. scope is a required query parameter, USER (the default) or ALL, and version narrows it to one version.
Output
list
apis.list
List the APIs under one owner, with paging, sorting and a filter for the token user own APIs
Risk: read
Answers an APIs.json object with an
apis array, one entry per API rather than per version. sort and order order the entries, and filter: 'user' narrows to the token’s own APIs.
Output
apis full type
apis full type
listVersions
apis.listVersions
List every version of one API, with its default version and metadata
Risk: read
Answers an APIs.json object with an
apis array, one entry per version, plus defaultVersion. This is how to find a version name before calling a route that needs one.
Output
apis full type
apis full type
rename
apis.rename
Rename an API. Its published URLs change, so anything pointing at the old name breaks
Risk: destructive
Sends
newName as a query parameter, with no body. The published URLs change, so anything pointing at the old name breaks. SwaggerHub emails the API’s designers and consumers about the rename, and the old name stays reserved, so a later save under it answers 403.
Output
save
apis.save
Save a definition to one API, creating the version or updating it. Answers 409 on a published version unless force is set
Risk: write
The definition is the request body, not a field inside an object. For OpenAPI and AsyncAPI the version comes from
info.version; pass version for GraphQL and MCP. Use format: 'graphql' for GraphQL SDL, which is sent as application/graphql. force overwrites a published version instead of answering 409. The route replies with no body, so the result reports the owner, the name and the version you passed. When the version comes from the definition’s info.version and you leave version out, the result has version: null. Core does not pass the status on, so whether the save created the version is not reported.
Output
setDefaultVersion
apis.setDefaultVersion
Change which version the API shows by default. The version has to exist
Risk: write
Writes the default version. The version has to exist, or the route answers 404.
Output
setNotifications
apis.setNotifications
Turn on notification scopes for one API. The body is the bare list of scopes
Risk: write
The body is the bare list of scopes, not an object around it. The route answers 200 with no body, so the plugin reports the scopes it sent as
{ enabled }.
Output
Api Settings
getLifecycle
apiSettings.getLifecycle
Read whether one API version is published
Risk: read
Answers
{ published } for one version.
Output
getVisibility
apiSettings.getVisibility
Read whether one API version is private
Risk: read
Answers
{ private } for one version.
Output
setLifecycle
apiSettings.setLifecycle
Publish or unpublish one API version. Publishing exposes it to everyone it is visible to
Risk: destructive
Publishes or unpublishes one version.
force matters when the version is already published, and a lifecycle change is what makes a spec visible in the portal. SwaggerHub emails the users the API is shared with when it is published or unpublished.
Output
setVisibility
apiSettings.setVisibility
Make one API version private or public. A private version leaves public view immediately
Risk: write
Makes one version private or public. A private version leaves public view immediately.
Output
Comments
create
comments.create
Post a comment on one API version, optionally anchored to a line range. Collaborators with notifications on are told about it
Risk: destructive
The route documents
replies as required, so the plugin always sends it, as an empty array. range anchors the comment to a line range and takes all six offsets. The API refuses a comment without one, so a comment with no range goes on line 1.
range full type
range full type
user full type
user full type
replies full type
replies full type
range full type
range full type
delete
comments.delete
Delete one comment and its replies. There is no undo
Risk: destructive · Irreversible
Deletes the comment and its replies. The route answers 200 with no body, so the plugin reports the ids.
Output
list
comments.list
List the comments on one API version with their replies and open or resolved status
Risk: read
Answers a bare array of comments. A 204 means the version has none, so the plugin reports
{ comments: [], empty: true } rather than failing.
Output
comments full type
comments full type
reply
comments.reply
Post a reply to an existing comment. Collaborators with notifications on are told about it
Risk: destructive
Adds a reply under the comment in the path, with a
body. Answers the reply as a plain comment.
Output
user full type
user full type
update
comments.update
Change the text of one comment
Risk: write
Sends PATCH with the new
body. Answers the updated comment.
Output
user full type
user full type
replies full type
replies full type
range full type
range full type
Domains
delete
domains.delete
Delete a domain and every version of it. There is no undo
Risk: destructive · Irreversible
Deletes the domain and every version.
force lets it through when another spec references it.
Output
deleteVersion
domains.deleteVersion
Delete one version of a domain. The other versions stay, and there is no undo
Risk: destructive · Irreversible
Deletes one domain version, leaving the others.
force behaves as on the domain delete.
Output
getDefinition
domains.getDefinition
Read the stored definition of one domain version as text
Risk: read
Answers
{ definition } as text, in whichever format the domain was stored as.
Output
getVersions
domains.getVersions
List every version of one domain
Risk: read
Answers an APIs.json object, one entry per domain version.
Output
apis full type
apis full type
list
domains.list
List the domains under one owner
Risk: read
Answers an APIs.json object with an
apis array, one entry per domain under the owner.
Output
apis full type
apis full type
save
domains.save
Save a definition to one domain, creating the version or updating it
Risk: write
The definition is the request body. The domain version comes from the definition when it carries one; pass
version otherwise.
Output
Integrations
execute
integrations.execute
Run one integration once, which pushes the stored definition to its target such as a repository or gateway
Risk: destructive
Runs the integration once, which pushes the stored definition to its target such as a repository or a gateway. A 205 means the API was updated as part of the run.
commitMessage sets the commit text on a source-control integration.
Output
list
integrations.list
List the integrations configured on one API version, with their ids and enabled state
Risk: read
Answers
{ integrations } with each integration’s id, name and enabled state. Use the id with integrations.execute.
Output
integrations full type
integrations full type
Projects
create
projects.create
Create a project from a list of API, domain and template names that already exist in the organisation
Risk: write
The route documents all three collections as required, so the plugin sends an empty array for any left out. Names have to exist in the organisation already.
Output
delete
projects.delete
Delete a project. The APIs, domains and templates it grouped stay on the account
Risk: destructive · Irreversible
Deletes the project. The specs it grouped stay on the account. The route answers 204.
Output
get
projects.get
Read one project with the APIs, domains and templates it groups
Risk: read
Answers one project with the
apis, domains and templates arrays it groups. Each entry is a name, not an id, and the specs must belong to the same organisation.
Output
list
projects.list
List the projects in one organisation
Risk: read
Answers
{ offset, totalCount, projects }. order takes ASC or DESC.
Output
projects full type
projects full type
update
projects.update
Replace a project definition. A collection left out is cleared, so send all three
Risk: write
Sends PUT, which replaces the project. A collection left out is cleared, so the plugin always sends all three. The PUT also needs
name; when you leave it out the plugin sends the project id, which is the project’s name.
Output
Specs
list
specs.list
List the specs visible to the account, filtered by type, owner, visibility, state or free text
Risk: read
Answers the APIs.json listing
{ offset, totalCount, apis }, one entry per spec. specType takes API, DOMAIN, TEMPLATE or ANY. visibility takes PUBLIC, PRIVATE or ANY, and sort takes NAME, UPDATED, CREATED, OWNER, BEST_MATCH or TITLE, with order of ASC or DESC. filter: 'user' narrows the result to the token’s own specs.
Output
apis full type
apis full type
validate
specs.validate
Validate an OpenAPI or AsyncAPI definition and get findings with line and column positions. Nothing is saved
Risk: read
Posts the definition and answers
{ valid, recognized, spec, summary, findings }. valid is true only when the definition was recognized and has no error-severity finding. maxProblems caps the findings at 100 by default and 1000 at most. Nothing is saved.
Output
spec full type
spec full type
summary full type
summary full type
findings full type
findings full type
Templates
delete
templates.delete
Delete one template version, or the whole template when no version is given. There is no undo
Risk: destructive · Irreversible
Deletes one template version, or the whole template when
version is left out (the API will not delete a template’s only version). The route answers 204, so the plugin reports the ids.
Output
get
templates.get
Read one template definition as text, optionally a built-in template
Risk: read
Answers
{ definition } as text. builtin: true reads a built-in template instead of one on the account, and flatten lifts inline schemas.
Output
list
templates.list
List the template catalog, optionally narrowed to one owner, including the built-in templates
Risk: read
Answers a bare array of template wrappers, including SwaggerHub’s built-in templates which carry
builtIn: true. owner narrows the catalog to one owner.
Output
templates full type
templates full type
save
templates.save
Create or update a template and its version
Risk: write
The definition is the request body.
version is optional where the definition carries one.
Output