Yext Connectors API

openapi: 3.0.0
info:
  title: Yext Admin Account Settings Connectors API
  version: '2.0'
servers:
- url: https://api.yextapis.com/v2
security:
- api_key: []
- api-key: []
tags:
- name: Connectors
paths:
  /accounts/{accountId}/connectors/{connectorId}/pushData:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/v'
    post:
      operationId: pushData
      requestBody:
        description: The data to be saved for and processed by the Connector.
        required: true
        content:
          text/plain:
            schema:
              type: string
      parameters:
      - name: connectorId
        in: path
        required: true
        schema:
          type: string
        description: ID of the Connector.
      - name: runMode
        in: query
        schema:
          type: string
          default: DEFAULT
          enum:
          - DEFAULT
          - COMPREHENSIVE
          - DELETION
        description: The run mode of the Connector.
      - name: dryRun
        in: query
        schema:
          type: boolean
          default: 'false'
        description: Whether the run should include a dry run.
      tags:
      - Connectors
      summary: 'Connectors: Push Data'
      description: 'Pushes data to be saved for and processed by a specified Connector.

        A run will be initiated with the data provided.

        '
      responses:
        '200':
          $ref: '#/components/responses/PushDataEndpointResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/connectors/{connectorId}/trigger:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/v'
    post:
      operationId: triggerConnector
      parameters:
      - name: connectorId
        in: path
        required: true
        schema:
          type: string
        description: ID of the Connector.
      - name: runMode
        in: query
        schema:
          type: string
          default: DEFAULT
          enum:
          - DEFAULT
          - COMPREHENSIVE
          - DELETION
        description: The run mode of the Connector.
      - name: dryRun
        in: query
        schema:
          type: boolean
          default: 'false'
        description: Whether the run should include a dry run.
      tags:
      - Connectors
      summary: 'Connectors: Trigger'
      description: Triggers a run of the specified Connector.
      responses:
        '200':
          $ref: '#/components/responses/TriggerConnectorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/connectors/{connectorId}/runs/{runUid}:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/v'
    get:
      operationId: getConnectorRun
      parameters:
      - name: connectorId
        in: path
        required: true
        schema:
          type: string
        description: ID of the Connector.
      - name: runUid
        in: path
        required: true
        schema:
          type: string
        description: UID of the Run.
      tags:
      - Connectors
      summary: 'Connectors: Get Run'
      description: Retrieve information for a Run with a given ID and Connector ID.
      responses:
        '200':
          $ref: '#/components/responses/GetConnectorRunResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/connectors/{connectorId}/runs/{runUid}/approve:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/v'
    post:
      operationId: approveRun
      parameters:
      - name: connectorId
        in: path
        required: true
        schema:
          type: string
        description: ID of the Connector.
      - name: runUid
        in: path
        schema:
          type: string
        description: UID of the run to be approved.
      tags:
      - Connectors
      summary: 'Connectors: Approve Run'
      description: 'Approves a dry run that is ready for review.

        The changes from the dry run will be applied once the run is approved.

        '
      responses:
        '200':
          $ref: '#/components/responses/ApproveRunResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /accounts/{accountId}/connectors/{connectorId}/runs/{runUid}/cancel:
    parameters:
    - $ref: '#/components/parameters/accountId'
    - $ref: '#/components/parameters/v'
    post:
      operationId: cancelRun
      parameters:
      - name: connectorId
        in: path
        required: true
        schema:
          type: string
        description: ID of the Connector.
      - name: runUid
        in: path
        schema:
          type: string
        description: UID of the run to be cancelled.
      tags:
      - Connectors
      summary: 'Connectors: Cancel Run'
      description: Cancels a non-terminal run.
      responses:
        '200':
          $ref: '#/components/responses/CancelRunResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  responses:
    GetConnectorRunResponse:
      description: Get Connector Run Response
      content:
        application/json:
          schema:
            title: GetConnectorRunResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  runUid:
                    type: integer
                    description: UID of the Run.
                  status:
                    type: string
                    enum:
                    - CREATED
                    - IN_PROGRESS
                    - COMPLETED
                    - COMPLETED_WITH_ERRORS
                    - FAILED
                    - CANCELED
                    description: Status of the Run.
                  runMode:
                    type: string
                    enum:
                    - DEFAULT
                    - COMPREHENSIVE
                    - DELETION
                    description: Mode of the Run.
                  triggerType:
                    type: string
                    enum:
                    - AUTO
                    - MANUAL
                    description: How the Run was triggered.
                  createdTimestamp:
                    type: number
                    description: The official time the run started (milliseconds since epoch).
                  completedTimestamp:
                    type: number
                    description: The official time the run has been completed (milliseconds since epoch).
                  createdCount:
                    type: integer
                    description: 'The number of successfully created entities.


                      If the v param is after `20231114`, the returned value will appear under the `results` property.

                      '
                  updatedCount:
                    type: integer
                    description: 'The number of successfully updated entities.


                      If the v param is after `20231114`, the returned value will appear under the `results` property.

                      '
                  deletedCount:
                    type: integer
                    description: 'The number of successfully deleted entities.


                      If the v param is after `20231114`, the returned value will appear under the `results` property.

                      '
                  failedCount:
                    type: integer
                    description: 'The number of entities that failed to be created or updated.


                      If the v param is after `20231114`, the returned value will appear under the `results` property.

                      '
                  unchangedCount:
                    type: integer
                    description: 'The number of entities that weren''t updated.


                      If the v param is after `20231114`, the returned value will appear under the `results` property.

                      '
                  results:
                    $ref: '#/components/schemas/ConnectorRunResults'
                  dryRunResults:
                    $ref: '#/components/schemas/ConnectorRunResults'
    TriggerConnectorResponse:
      description: Trigger Connector Response
      content:
        application/json:
          schema:
            title: TriggerConnectorResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  id:
                    type: string
                    description: 'ID of the Connector.


                      If the v param is after `20230215`, the returned value will appear under the `connectorId` property.

                      '
                  connectorId:
                    type: string
                    description: 'ID of the Connector.


                      If the v param is before `20230215`, the returned value will appear under the `id` property.

                      '
                  runUid:
                    type: integer
                    description: UID of the Run.
    PushDataEndpointResponse:
      description: Get Connector Push Data Response
      content:
        application/json:
          schema:
            title: GetConnectorPushDataResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  id:
                    type: string
                    description: ID of the Connector.
                  runUid:
                    type: integer
                    description: UID of the Run.
    ErrorResponse:
      description: Error Response
      content:
        application/json:
          schema:
            title: ErrorResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMetaWithError'
              response:
                type: object
    CancelRunResponse:
      description: Cancel Run Response
      content:
        application/json:
          schema:
            title: CancelRunResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  connectorId:
                    type: string
                    description: ID of the Connector.
                  runUid:
                    type: integer
                    description: UID of the cancelled Run.
    ApproveRunResponse:
      description: Approve Run Response
      content:
        application/json:
          schema:
            title: ApproveRunResponse
            type: object
            properties:
              meta:
                $ref: '#/components/schemas/ResponseMeta'
              response:
                type: object
                properties:
                  connectorId:
                    type: string
                    description: ID of the Connector.
                  runUid:
                    type: integer
                    description: UID of the approved Run.
  schemas:
    ResponseMetaWithError:
      allOf:
      - $ref: '#/components/schemas/ResponseMeta'
      - type: object
        properties:
          errors:
            type: array
            description: List of errors and warnings.
            items:
              $ref: '#/components/schemas/ResponseError'
    ResponseMeta:
      type: object
      properties:
        uuid:
          type: string
          example: 4f72b877-e2d0-4de4-9324-b9cf2c03e1a0
          description: Unique ID for this request / response.
    ResponseError:
      type: object
      properties:
        name:
          type: string
        code:
          type: integer
          description: 'Code that uniquely identifies the error or warning.

            '
        type:
          type: string
          enum:
          - FATAL_ERROR
          - NON_FATAL_ERROR
          - WARNING
        message:
          type: string
          description: Message explaining the problem.
    ConnectorRunResults:
      type: object
      required:
      - createdCount
      - updatedCount
      - deletedCount
      - failedCount
      - unchangedCount
      properties:
        createdCount:
          type: integer
          description: The number of successfully created entities.
        updatedCount:
          type: integer
          description: The number of successfully updated entities.
        deletedCount:
          type: integer
          description: The number of successfully deleted entities.
        failedCount:
          type: integer
          description: The number of entities that failed to be created or updated.
        unchangedCount:
          type: integer
          description: The number of entities that weren't updated.
  parameters:
    v:
      name: v
      in: query
      required: true
      schema:
        type: string
      description: A date in `YYYYMMDD` format.
    accountId:
      name: accountId
      in: path
      required: true
      schema:
        type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: query
    api-key:
      type: apiKey
      name: api-key
      in: header