Stoplight Versions API

openapi: 3.2.0
info:
  title: Stoplight Versions API
  version: api-v1
  contact:
    x-twitter: stoplightio
  x-apisguru-categories:
  - developer_tools
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_twitter.com_stoplightio_profile_image.png
  x-origin:
  - format: openapi
    url: https://api.stoplight.io/v1/versions/wDcMCTKXwn8X4ynL9/export/oas.json
    version: '3.0'
  x-providerName: stoplight.io
  description: 'Operations tagged Versions across 2 of this provider''s published API definitions: stoplight-openapi.json, stoplight-platform-v1-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.stoplight.io/v1
tags:
- name: Versions
paths:
  /versions/publish/anon:
    post:
      description: "Anonymously publish to API Docs.\n\nThis endpoint will take a JSON spec or a URL to a swagger or raml spec.\n\n```\n{\n  \"specData\": {...}\n}\n```\n\nor\n\n```\n{\n  \"url\": \"http://petstore.swagger.io/v2/swagger.json\"\n}\n```\n\nThe spec will be published to api-docs.io anonymously, which means you will not be able to update or remove this documentation.\n\nThe response will contain a url to the published documentation.\n\n```\n{\n  \"url\": \"https://swagger-petstore.api-docs.io/v1.0.0\"\n}\n```\n\n\nThe limitations of anonymous publishing\n* Cannot update/remove the documentation\n* Cannot choose the subdomain\n* Cannot choose the version\n* Cannot add theming"
      operationId: POST_versions-publish-anon
      requestBody:
        content:
          application/json:
            schema:
              properties:
                specData:
                  oneOf:
                  - type: object
                  - type: string
                url:
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              examples:
                response:
                  value:
                    url: https://stoplight.api-docs.io/api-v1
              schema:
                properties:
                  url:
                    type: string
                required:
                - url
                type: object
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standarderror'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standarderror'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standarderror'
          description: ''
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/standarderror'
          description: ''
      summary: Publish Anonymous
      tags:
      - Versions
    servers:
    - url: https://api.stoplight.io/v1
  /versions/{versionId}/export/{format}:
    parameters:
    - description: This is the unique identifier for the version.
      in: path
      name: versionId
      required: true
      schema:
        default: ''
        type: string
    - description: The specification / format that you want to export.
      in: path
      name: format
      required: true
      schema:
        default: oas.json
        enum:
        - oas.json
        - oas.yaml
        - raml08.yaml
        - raml10.yaml
        - stoplight.json
        - stoplight.yaml
        type: string
    get:
      description: 'Export a version to your choice of API specification.


        ### Allowed Formats:


        - oas.json

        - oas.yaml

        - raml08.yaml

        - raml10.yaml

        - stoplight.json

        - stoplight.yaml


        The stoplight format actually returns OAS (Swagger 2) with x-stoplight annotations. If you are exporting with the intent on importing back into Stoplight, this export format preserves the most information.


        ### Example URL:


        `https://api.stoplight.io/v1/versions/123/export/oas.json`'
      operationId: GET_versions-versionId-export-format
      responses:
        '200':
          content:
            application/json:
              examples:
                response:
                  value:
                    info:
                      title: Test API
                      version: '1.0'
                    paths: {}
                    swagger: '2.0'
            text/yaml:
              schema:
                description: The specification. Returned as a string when YAML, object when JSON.
                oneOf:
                - type: object
                - type: string
          description: ''
        '401':
          $ref: '#/components/responses/trait_standardErrors_401'
        '404':
          $ref: '#/components/responses/trait_standardErrors_404'
      summary: Export
      tags:
      - Versions
    servers:
    - url: https://api.stoplight.io/v1
  /versions/{versionId}/import:
    parameters:
    - description: This is the unique identifier for the version.
      in: path
      name: versionId
      required: true
      schema:
        type: string
    put:
      description: "Import the given specification into an existing version. \n\n**Warning, this is a destructive action! Any resources present in both the existing version, and the specification being imported, will be overwritten.**\n\nThis endpoint is particularly useful when you manage a specification file (Swagger or RAML) outside of Stoplight, and want to keep your Stoplight API version up to date as that specification changes.\n\nBy default, a \"merge\" is performed when importing. If a resource exists in the specification that you are importing, and in the Stoplight API, the resource will be overwritten. If a resource exists in the Stoplight API, but not in the spefication that you are importing, the resource will be left alone (and not deleted).\n\nYou can include an optional `options` property in the request body, to indicate if you would like to perform more of a replacement (instead of a merge). The options are documented in full in the response definition below these notes.\n\nTake this request + request body for example:\n\n`PUT https://api.stoplight.io/v1/versions/123/import`\n```json\n{\n  \"url\": \"http://petstore.swagger.io/v2/swagger.json\",\n  \"options\": {\n    \"removeExtraEndpoints\": true,\n    \"removeExtraSchemas\": true\n  }\n}\n```\n\nThis request will grab the swagger specification described at `http://petstore.swagger.io/v2/swagger.json`, and import it into the Stoplight API version with id `123`. Additionally, it will delete any existing endpoints or models that are not described in the petstore swagger being imported.\n\nInstead of a URL, you can provide the actual specification to be imported, either as a string (in the case of YAML) or an object (in the case of JSON). That request would look something like this:\n\n`PUT https://api.stoplight.io/v1/versions/123/import`\n```json\n{\n  \"specData\": {\n    \"swagger\": \"2.0\",\n    \"info\": {}\n    ... rest of spec\n  }\n}\n```"
      operationId: PUT_versions-versionId-import
      requestBody:
        content:
          application/json:
            schema:
              example:
                options:
                  removeExtraEndpoints: true
                  removeExtraModels: true
                url: http://petstore.swagger.io/v2/swagger.json
              properties:
                options:
                  properties:
                    removeExtraEndpoints:
                      default: ''
                      description: 'Default: false.'
                      type: boolean
                    removeExtraSchemas:
                      default: ''
                      description: 'Default: false.'
                      type: boolean
                    removeExtraTextSections:
                      default: ''
                      description: 'Default: false.'
                      type: boolean
                    removeExtraTraits:
                      default: ''
                      description: 'Default: false.'
                      type: boolean
                  type: object
                specData:
                  oneOf:
                  - type: object
                  - type: string
                url:
                  type: string
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      endpointCount:
                        type: number
                      format:
                        enum:
                        - RAML08
                        - RAML10
                        - SWAGGER
                        - STOPLIGHTX
                        type: string
                      projectId:
                        type: string
                      schemaCount:
                        type: number
                      testCount:
                        type: number
                      textSectionCount:
                        type: number
                      traitCount:
                        type: number
                      versionId:
                        type: string
                      workspaceId:
                        type: string
                    required:
                    - workspaceId
                    - projectId
                    - versionId
                    - schemaCount
                    - textSectionCount
                    - traitCount
                    - endpointCount
                    - testCount
                    - format
                    type: object
                required:
                - data
                type: object
          description: ''
        '401':
          $ref: '#/components/responses/trait_standardErrors_401'
        '404':
          $ref: '#/components/responses/trait_standardErrors_404'
      security:
      - Authorization: []
      summary: Import
      tags:
      - Versions
    servers:
    - url: https://api.stoplight.io/v1
  /versions/{versionId}/publish:
    parameters:
    - description: This is the unique identifier for the version.
      in: path
      name: versionId
      required: true
      schema:
        type: string
    post:
      description: 'Re-publish an API version in Stoplight. This will re-publish the given API version, with whatever publish settings have already been setup in the app.


        This will only work with APIs that have previously been published at least once.


        This works well with the #endpoint:957qEfc97BB5XGAeZ endpoint to augment your continuous integration processes, and automatically re-publish your documentation when certain events happen. Once such scenario is:


        1. Swagger is generated from your codebase, and pushed up to Github.

        2. A simple script that you write sends a request to the Stoplight API to import the new specification, passing in the URL to the swagger file on Github.

        3. After the import succeeds, and your API in Stoplight is up to date, the script sends a request to the Stoplight API (this endpoint) to re-publish your documentation.'
      operationId: POST_versions-versionId-publish
      responses:
        '200':
          content:
            application/json:
              examples:
                response:
                  value:
                    customDomain: https://help.stoplight.io/api-v1
                    url: https://stoplight.api-docs.io/api-v1
              schema:
                properties:
                  customDomain:
                    type: string
                  url:
                    type: string
                required:
                - url
                type: object
          description: ''
        '401':
          $ref: '#/components/responses/trait_standardErrors_401'
        '404':
          $ref: '#/components/responses/trait_standardErrors_404'
      security:
      - Authorization: []
      summary: Publish
      tags:
      - Versions
    servers:
    - url: https://api.stoplight.io/v1
  /versions/{versionId}/unpublish:
    parameters:
    - description: This is the unique identifier for the version.
      in: path
      name: versionId
      required: true
      schema:
        type: string
    put:
      description: Unpublish the documentation associated with the given API version.
      operationId: PUT_versions-versionId-unpublish
      responses:
        '200':
          content:
            application/json:
              examples:
                response:
                  value:
                    data: {}
              schema:
                properties:
                  data:
                    type: object
                type: object
          description: ''
        '401':
          $ref: '#/components/responses/trait_standardErrors_401'
        '404':
          $ref: '#/components/responses/trait_standardErrors_404'
      security:
      - Authorization: []
      summary: Unpublish
      tags:
      - Versions
    servers:
    - url: https://api.stoplight.io/v1
components:
  schemas:
    standarderror: {}
  responses:
    trait_standardErrors_404:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/standarderror'
      description: ''
    trait_standardErrors_401:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/standarderror'
      description: ''
  securitySchemes:
    Authorization:
      in: header
      name: Authorization
      type: apiKey
x-refined-from:
- stoplight-openapi.json
- stoplight-platform-v1-openapi.yml