openapi: 3.1.0
info:
  title: Port Action Runs Migrations API
  version: '1.0'
tags:
- name: Migrations
paths:
  /v1/migrations:
    get:
      summary: Get all migrations
      tags:
      - Migrations
      description: This route allows you to fetch all migrations (both past and present) in your Port organization.<br/><br/>The call will perform a logical `AND` operation on the query parameters below, and return all migrations that match the criteria.
      parameters:
      - schema:
          type: array
          items:
            type: string
            enum:
            - COMPLETED
            - RUNNING
            - PENDING
            - INITIALIZING
            - FAILURE
            - CANCELLED
            - PENDING_CANCELLATION
        in: query
        name: status
        required: false
      - schema:
          type: string
        in: query
        name: actor
        required: false
        description: The identifier of the user who initiated the migration. You can use the [Get user](https://docs.port.io/api-reference/get-a-user/) route to get a user's identifier.
      - schema:
          type: string
        in: query
        name: blueprint
        required: false
        description: The identifier of the blueprint associated with the migration.
      security:
      - bearer:
        - read:blueprints
      responses:
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                additionalProperties: false
        '404':
          description: A resource with the provided identifier was not found
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                - message
                additionalProperties: false
                description: A resource with the provided identifier was not found
    post:
      summary: Create a migration
      tags:
      - Migrations
      description: This route allows you to create a migration in your Port organization. You can use this to migrate data from one blueprint to another.<br/><br/>**Note** that it is not possible to directly change the data type of an existing property via the UI or the API. The type field setting of a property (**number**, **string**, etc.) is permanent and cannot be changed after creation.<br/><br/>However, you can create a new property with the desired type and migrate the old values to it. Refer to the [documentation](https://docs.port.io/build-your-software-catalog/customize-integrations/configure-data-model/setup-blueprint/properties/#change-a-property-type) for more information on how to change a property's type.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceBlueprint:
                  type: string
                  description: The identifier of the blueprint from which the migration will be performed.
                mapping:
                  type: object
                  description: The definition used to map the data from the source blueprint into the target blueprint.
                  properties:
                    blueprint:
                      type: string
                      description: The identifier of the target blueprint.
                    filter:
                      type: string
                      description: An optional set of [conditions](https://docs.port.io/scorecards/concepts-and-structure/#conditions) to filter the entities that will be migrated.
                    itemsToParse:
                      type: string
                      description: A `jq` query that evaluates to an array of items, used to create multiple entities at once. See more information [here](https://docs.port.io/build-your-software-catalog/customize-integrations/configure-mapping/#create-multiple-entities-from-an-array-api-object).
                    entity:
                      type: object
                      properties:
                        identifier:
                          type: string
                          description: A `jq` expression used to get data from the source blueprint, to be used as an identifier for the entity.
                        title:
                          type: string
                          description: A `jq` expression used to get data from the source blueprint, to be used as the title of the entity.
                        icon:
                          type: string
                          description: The icon of the entity.
                        team:
                          type: string
                          description: The team the entity belongs to.
                        properties:
                          type: object
                          description: An object containing the properties of the entity and their values, in `"key":"value"` pairs where the `key` is the property's identifier, and the `value` is its value.
                          additionalProperties:
                            type: string
                        relations:
                          type: object
                          description: An object containing the relations of the entity and their values, in `"key":"value"` pairs where the `key` is the relation's identifier, and the `value` is the related entity's identifier for single-relations, or an array of identifiers for many-relations.<br/>You can also use a [search query](https://docs.port.io/build-your-software-catalog/customize-integrations/configure-mapping#mapping-relations-using-search-queries) to define relations based on a property of the related entity.
                          additionalProperties:
                            type: string
                  required:
                  - entity
              required:
              - sourceBlueprint
              - mapping
              additionalProperties: false
        required: true
      security:
      - bearer: []
      responses:
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                additionalProperties: false
        '404':
          description: A resource with the provided identifier was not found
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                - message
                additionalProperties: false
                description: A resource with the provided identifier was not found
        '413':
          description: Request body is too large (limit is 1MiB)
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                additionalProperties: false
                description: Request body is too large (limit is 1MiB)
        '422':
          description: The json provided does not match the route's schema
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                - message
                additionalProperties: false
                description: The json provided does not match the route's schema
  /v1/migrations/{migration_id}:
    get:
      summary: Get a migration
      tags:
      - Migrations
      description: This route allows you to fetch a specific migration in your Port organization.
      parameters:
      - schema:
          type: string
        in: path
        name: migration_id
        required: true
        description: The identifier of the migration you want to fetch.
      security:
      - bearer:
        - read:blueprints
      responses:
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                additionalProperties: false
        '404':
          description: A resource with the provided identifier was not found
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                - message
                additionalProperties: false
                description: A resource with the provided identifier was not found
  /v1/migrations/{migration_id}/cancel:
    post:
      summary: Cancel a migration
      tags:
      - Migrations
      description: This route allows you to cancel a running migration in your Port organization.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: The reason for cancelling the migration.
              additionalProperties: false
      parameters:
      - schema:
          type: string
        in: path
        name: migration_id
        required: true
        description: The identifier of the migration you want to cancel.
      security:
      - bearer: []
      responses:
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                additionalProperties: false
        '404':
          description: A resource with the provided identifier was not found
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                - message
                additionalProperties: false
                description: A resource with the provided identifier was not found
        '413':
          description: Request body is too large (limit is 1MiB)
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                additionalProperties: false
                description: Request body is too large (limit is 1MiB)
        '422':
          description: The json provided does not match the route's schema
          content:
            application/json:
              schema:
                properties:
                  ok:
                    const: false
                  error:
                    type: string
                  message:
                    type: string
                required:
                - ok
                - error
                - message
                additionalProperties: false
                description: The json provided does not match the route's schema
components:
  securitySchemes:
    bearer:
      type: apiKey
      name: Authorization
      in: header