Apidog

openapi: 3.1.0
info:
  title: Apidog API
  description: >-
    Apidog provides a public REST API that lets developers programmatically
    interact with Apidog projects for importing and exporting API specifications.
    All API URLs begin with the base URL https://api.apidog.com. The API is
    versioned via the `X-Apidog-Api-Version` request header (current version:
    `2024-03-28`). Authentication uses a personal API access token passed as a
    Bearer Token in the `Authorization` header.
  version: 2024-03-28
  contact:
    name: Apidog
    url: https://apidog.com/
  termsOfService: https://legal.apidog.com/
externalDocs:
  description: Apidog OpenAPI Reference
  url: https://openapi.apidog.io/
servers:
- url: https://api.apidog.com
  description: Apidog Production API
security:
- bearerAuth: []
tags:
- name: Import And Export
  description: Import and export API specification data in OpenAPI, Swagger, and Postman Collection formats.
paths:
  /v1/projects/{projectId}/import-openapi:
    post:
      operationId: importOpenApiData
      summary: Import OpenAPI Or Swagger Data
      description: >-
        Import API specification data in OpenAPI 3 or Swagger 2 format into the
        specified Apidog project. The specification can be provided as a JSON
        or YAML string, or fetched from a URL. Advanced options control target
        folder, branch, module, overwrite behavior, and whether unmatched
        resources are deleted.
      tags:
      - Import And Export
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/apidogApiVersion'
      - $ref: '#/components/parameters/locale'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - input
              properties:
                input:
                  oneOf:
                  - type: string
                    description: The OpenAPI/Swagger specification as a JSON or YAML string.
                  - type: object
                    required:
                    - url
                    properties:
                      url:
                        type: string
                        format: uri
                        description: URL pointing to the OpenAPI/Swagger specification file.
                      basicAuth:
                        type: object
                        properties:
                          username:
                            type: string
                          password:
                            type: string
                options:
                  type: object
                  description: Advanced import options.
                  properties:
                    targetEndpointFolderId:
                      type: integer
                      description: Folder ID where endpoints will be stored. Defaults to the root folder.
                    targetSchemaFolderId:
                      type: integer
                      description: Folder ID where schemas will be stored. Defaults to the root folder.
                    endpointOverwriteBehavior:
                      type: string
                      description: How to handle endpoints whose path and method already exist.
                      enum:
                      - OVERWRITE_EXISTING
                      - AUTO_MERGE
                      - KEEP_EXISTING
                      - CREATE_NEW
                    schemaOverwriteBehavior:
                      type: string
                      enum:
                      - OVERWRITE_EXISTING
                      - AUTO_MERGE
                      - KEEP_EXISTING
                      - CREATE_NEW
                    deleteUnmatchedResources:
                      type: boolean
                      description: If true, resources not present in the imported spec are deleted.
                    targetBranchId:
                      type: integer
                      description: Optional sprint branch to import into.
                    moduleId:
                      type: integer
                      description: Optional module ID to import into.
                    importServersAsEnvironments:
                      type: boolean
                      description: If true, server definitions in the spec are imported as environments.
            examples:
              ImportOpenApiDataRequestExample:
                summary: Default importOpenApiData request
                x-microcks-default: true
                value:
                  input: "openapi: 3.0.0\ninfo:\n  title: Example API\n  version: 1.0.0\npaths: {}"
                  options:
                    endpointOverwriteBehavior: AUTO_MERGE
                    importServersAsEnvironments: true
      responses:
        '200':
          description: Import completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResult'
              examples:
                ImportOpenApiData200Example:
                  summary: Default importOpenApiData 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    data:
                      endpoint:
                        created: 5
                        updated: 0
                        failed: 0
                        ignored: 0
                      schema:
                        created: 3
                        updated: 0
                        failed: 0
                        ignored: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/projects/{projectId}/export-openapi:
    post:
      operationId: exportOpenApiData
      summary: Export Data In OpenAPI Or Swagger Format
      description: >-
        Export the API specification data from the specified Apidog project in
        OpenAPI 2.0, 3.0, or 3.1 format. Output is delivered as a fully-formed
        OpenAPI document containing info, paths, components, tags, and servers.
      tags:
      - Import And Export
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/apidogApiVersion'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                scope:
                  type: string
                  description: Defines the export range.
                  enum:
                  - ALL
                  - SELECTED_ENDPOINTS
                  - SELECTED_TAGS
                  - SELECTED_FOLDERS
                  default: ALL
                oasVersion:
                  type: string
                  description: Target OpenAPI version.
                  enum:
                  - '2.0'
                  - '3.0'
                  - '3.1'
                  default: '3.0'
                exportFormat:
                  type: string
                  description: Output file format.
                  enum:
                  - JSON
                  - YAML
                  default: JSON
                environmentIds:
                  type: array
                  description: Optional list of environment IDs to include as servers.
                  items:
                    type: integer
                branchId:
                  type: integer
                  description: Optional sprint branch to export from.
                moduleId:
                  type: integer
                  description: Optional module ID to export from.
                endpointIds:
                  type: array
                  description: Optional list of specific endpoint IDs to export.
                  items:
                    type: integer
                tags:
                  type: array
                  description: Optional list of tags to filter which endpoints to export.
                  items:
                    type: string
                options:
                  type: object
                  properties:
                    includeApidogExtensionProperties:
                      type: boolean
                      description: Include Apidog OpenAPI x-apidog-* extensions in the export.
                    includeFolderNamesAsTags:
                      type: boolean
                      description: Use folder names as tags in the exported spec.
            examples:
              ExportOpenApiDataRequestExample:
                summary: Default exportOpenApiData request
                x-microcks-default: true
                value:
                  scope: ALL
                  oasVersion: '3.0'
                  exportFormat: JSON
      responses:
        '200':
          description: Export completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResult'
              examples:
                ExportOpenApiData200Example:
                  summary: Default exportOpenApiData 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    data:
                      openapi: '3.0.0'
                      info:
                        title: My API
                        version: 1.0.0
                      paths: {}
                      components: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v1/projects/{projectId}/import-postman-collection:
    post:
      operationId: importPostmanCollectionData
      summary: Import Postman Collection Data
      description: >-
        Import API data from a Postman Collection (v2 format) into the specified
        Apidog project. The collection should be provided as a stringified JSON
        string exported from Postman.
      tags:
      - Import And Export
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/apidogApiVersion'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - input
              properties:
                input:
                  type: string
                  description: The Postman Collection v2 data as a stringified JSON string.
                options:
                  type: object
                  description: Advanced import options.
                  properties:
                    targetEndpointFolderId:
                      type: integer
                      description: Destination folder. Defaults to the project root folder.
                    endpointOverwriteBehavior:
                      type: string
                      enum:
                      - OVERWRITE_EXISTING
                      - AUTO_MERGE
                      - KEEP_EXISTING
                      - CREATE_NEW
                    endpointCaseOverwriteBehavior:
                      type: string
                      enum:
                      - OVERWRITE_EXISTING
                      - AUTO_MERGE
                      - KEEP_EXISTING
                      - CREATE_NEW
                    updateFolderOfChangedEndpoint:
                      type: boolean
                    targetBranchId:
                      type: integer
                    moduleId:
                      type: integer
            examples:
              ImportPostmanCollectionDataRequestExample:
                summary: Default importPostmanCollectionData request
                x-microcks-default: true
                value:
                  input: '{"info":{"name":"Example Collection","schema":"https://schema.getpostman.com/json/collection/v2.1.0/collection.json"},"item":[]}'
      responses:
        '200':
          description: Import completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResult'
              examples:
                ImportPostmanCollectionData200Example:
                  summary: Default importPostmanCollectionData 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    data:
                      endpoint:
                        created: 5
                        updated: 0
                        failed: 0
                        ignored: 0
                      endpointFolder:
                        created: 2
                        updated: 0
                        failed: 0
                        ignored: 0
                      endpointCase:
                        created: 4
                        updated: 0
                        failed: 0
                        ignored: 0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Apidog API uses Bearer Token authorization. Include your personal API
        access token in the Authorization header as "Bearer {token}". Tokens
        are generated under Avatar -> Account Settings -> API Access Token.
  parameters:
    projectId:
      name: projectId
      in: path
      required: true
      description: The unique identifier of the Apidog project.
      schema:
        type: integer
    apidogApiVersion:
      name: X-Apidog-Api-Version
      in: header
      required: true
      description: >-
        The Apidog API version. Required for all requests. Current supported
        version is `2024-03-28`. Apidog supports previous versions for at
        least three months after a newer version launches.
      schema:
        type: string
        example: '2024-03-28'
    locale:
      name: locale
      in: query
      required: false
      description: Locale for response messages, e.g. `en-US`.
      schema:
        type: string
        example: en-US
  schemas:
    ResourceCounters:
      type: object
      description: Counters returned for each resource type after an import operation.
      properties:
        created:
          type: integer
          description: Number of resources created.
        updated:
          type: integer
          description: Number of resources updated.
        failed:
          type: integer
          description: Number of resources that failed to import.
        ignored:
          type: integer
          description: Number of resources ignored (e.g. due to keep-existing policy).
    ImportError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message.
    ImportResult:
      type: object
      description: Result of an import operation.
      properties:
        success:
          type: boolean
          description: Whether the import was successful.
        data:
          type: object
          properties:
            endpoint:
              $ref: '#/components/schemas/ResourceCounters'
            schema:
              $ref: '#/components/schemas/ResourceCounters'
            endpointFolder:
              $ref: '#/components/schemas/ResourceCounters'
            schemaFolder:
              $ref: '#/components/schemas/ResourceCounters'
            endpointCase:
              $ref: '#/components/schemas/ResourceCounters'
            errors:
              type: array
              items:
                $ref: '#/components/schemas/ImportError'
    ExportResult:
      type: object
      description: Result of an export operation. The `data` field contains a fully-formed OpenAPI document.
      properties:
        success:
          type: boolean
          description: Whether the export was successful.
        data:
          description: The exported OpenAPI/Swagger document, either as a string (when exportFormat is YAML) or as an object (when exportFormat is JSON).
          oneOf:
          - type: string
          - type: object
    Error:
      type: object
      description: Standard error response.
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
            message:
              type: string
              description: Human-readable error message.
  responses:
    Unauthorized:
      description: >-
        Authentication failed. The Bearer Token is missing, invalid, or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The specified project was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The API version header is missing or unsupported.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'