Nexla Marketplace API

openapi: 3.2.0
info:
  version: v1
  title: Nexla Rest Marketplace API
  termsOfService: https://nexla.com/terms-of-service/
  contact:
    name: Nexla Support
    url: https://docs.nexla.com
    email: support@nexla.com
  license:
    name: Nexla
    url: https://nexla.com
  x-logo:
    url: https://cdn.nexla.io/ui/assets/brand/v2/nexla-logo-color-portrait.svg
    backgroundColor: '#ffffff'
  description: '# Introduction


    The Nexla API is a REST-ful API used to easily create and manage resources in Nexla in ways that best fit any use case. It can be used to configure and monitor data flows for different data-integration use cases and to perform all aspects of data engineering automation offered by the Nexla platform.


    The Nexla API supports all data flow-creation and -management actions in the platform, as well as administrative user- and organization-level account-management tasks. Note that all other client packages, such as the Nexla CLI and Nexla UI, also connect to the overall Nexla infrastructure through the Nexla API.


    The API references in this document lists all API endpoints and the corresponding payloads.


    Check out the [API Developer Guides](https://developers.nexla.com/docs/nexla-api) to view guides and tutorials for recommended use cases for different endpoints.


    # API Data Format and Versions


    The API uses JSON for all data exchanges.


    You __should__ specify the API version that should be used in the Accept header of each request. For example, to access Version 1 of the API, the Accept header should be the following:

    ```

    Accept: application/vnd.nexla.api.v1+json

    ```


    The Nexla API also supports a generic version header, which will default your access to the latest version of the data source/destination API.



    ```

    Accept: application/json

    ```


    # Authentication


    Most Nexla API endpoints require `Bearer Token` authentication mechanism for making an authenticated request to the API. While this token can be generated programmatically outside Nexla UI by starting a session with an `api_key`, unless unavoidable, we recommend starting your session from the Nexla UI and using the `Nexla Session Token` from the Nexla UI as the Authorization header for calls to the Nexla API.


    <SecurityDefinitions />'
servers:
- url: https://{nexla-api-host}
  variables:
    nexla-api-host:
      default: dataops.nexla.io/nexla-api
      description: Nexla API URL your Nexla instance
security:
- NexlaSessionToken: []
tags:
- name: Marketplace
  description: Operations for managing the marketplace domains and items.
paths:
  /marketplace/domains:
    get:
      tags:
      - Marketplace
      operationId: get_domains
      summary: Get marketplace domains.
      description: 'Use this endpoint to fetch marketplace domains. You need a read permission for the org.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      responses:
        '200':
          $ref: '#/components/responses/domains_many'
        '403':
          description: Forbidden
    post:
      tags:
      - Marketplace
      operationId: create_domains
      summary: Create marketplace domains.
      description: 'Use this endpoint to create marketplace domains. You need a manage permission for the org.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      requestBody:
        content:
          application/vnd.nexla.api.v1+json:
            schema:
              $ref: '#/components/schemas/MarketplaceDomainCreate'
      responses:
        '200':
          $ref: '#/components/responses/domains_many'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /marketplace/domains/for_org:
    get:
      tags:
      - Marketplace
      operationId: get_domains_for_org
      summary: Get marketplace domains for organization.
      description: 'Use this endpoint to fetch marketplace domains for a specific organization. You need a read permission for the org.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: org_id
        in: query
        description: The organization ID to filter domains by
        required: true
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/domains_many'
        '403':
          description: Forbidden
  /marketplace/domains/{domain_id}:
    get:
      tags:
      - Marketplace
      operationId: get_domain
      summary: Get a single marketplace domain.
      description: 'Use this endpoint to fetch a marketplace domain. You need a read permission for the domain.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain that needs to be fetched.
        required: true
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/domains_one'
        '403':
          description: Forbidden
    put:
      tags:
      - Marketplace
      operationId: update_domain
      summary: Update a single marketplace domain.
      description: 'Use this endpoint to update a marketplace domain. You need a manage permission for the domain.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain that needs to be updated.
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/vnd.nexla.api.v1+json:
            schema:
              $ref: '#/components/schemas/MarketplaceDomainCreate'
      responses:
        '200':
          $ref: '#/components/responses/domains_one'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      tags:
      - Marketplace
      operationId: create_domain
      summary: Create a single marketplace domain.
      description: 'Use this endpoint to create a marketplace domain. You need a manage permission for the org.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      requestBody:
        content:
          application/vnd.nexla.api.v1+json:
            schema:
              $ref: '#/components/schemas/MarketplaceDomainCreate'
      responses:
        '200':
          $ref: '#/components/responses/domains_one'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    delete:
      tags:
      - Marketplace
      operationId: delete_domain
      summary: Delete a single marketplace domain.
      description: 'Use this endpoint to delete a marketplace domain. You need a manage permission for the domain to delete it.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain that needs to be deleted.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successfully deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /marketplace/domains/{domain_id}/items:
    get:
      tags:
      - Marketplace
      operationId: get_domain_items
      summary: Get marketplace items for a domain.
      description: 'Use this endpoint to fetch marketplace items for a domain. You need a read permission for the domain.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain.
        required: true
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/domain_items_many'
        '403':
          description: Forbidden
    post:
      tags:
      - Marketplace
      operationId: create_domain_item
      summary: Create a marketplace item for a domain.
      description: 'Use this endpoint to create a marketplace item for a domain. You need a manage permission for the domain.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain.
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/vnd.nexla.api.v1+json:
            schema:
              $ref: '#/components/schemas/MarketplaceDomainsItemCreate'
      responses:
        '200':
          $ref: '#/components/responses/domain_items_many'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /marketplace/domains/{domain_id}/custodians:
    get:
      tags:
      - Marketplace
      operationId: get_domain_custodians
      summary: Get custodians for a marketplace domain.
      description: 'Use this endpoint to fetch custodians for a marketplace domain. You need a read permission for the domain.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain.
        required: true
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/custodians_many'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    put:
      tags:
      - Marketplace
      operationId: update_domain_custodians
      summary: Update custodians for a marketplace domain.
      description: 'Use this endpoint to update custodians for a marketplace domain. You need a manage permission for the domain.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain.
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/vnd.nexla.api.v1+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CustodiansPayload'
      responses:
        '200':
          $ref: '#/components/responses/custodians_many'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      tags:
      - Marketplace
      operationId: add_domain_custodians
      summary: Add custodians to a marketplace domain.
      description: 'Use this endpoint to add custodians to a marketplace domain. You need a manage permission for the domain.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain.
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/vnd.nexla.api.v1+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CustodiansPayload'
      responses:
        '200':
          $ref: '#/components/responses/custodians_many'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    delete:
      tags:
      - Marketplace
      operationId: remove_domain_custodians
      summary: Remove custodians from a marketplace domain.
      description: 'Use this endpoint to remove custodians from a marketplace domain. You need a manage permission for the domain.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: domain_id
        in: path
        description: The unique ID of the domain that needs to be deleted.
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/vnd.nexla.api.v1+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CustodiansPayload'
      responses:
        '200':
          description: Successfully deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    MarketplaceDomain:
      type: object
      properties:
        id:
          type: integer
        org_id:
          type:
          - 'null'
          - integer
        owner_id:
          type:
          - 'null'
          - integer
        name:
          type: string
        description:
          type: string
        parent_id:
          type: integer
          description: ID of the parent domain. Domains may build a hierarchy.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    MarketplaceDomainsItem:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type:
          - 'null'
          - string
        data_samples:
          type: array
          items:
            type: object
            additionalProperties: true
          description: Data samples coming from data sets that the marketplace item presents.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    MarketplaceDomainsItemCreate:
      type: object
      properties:
        name:
          type: string
        description:
          type:
          - 'null'
          - string
        data_set_id:
          type: integer
          description: ID of the org's dataset that marketplace item should present. User should have a `read` permission for the dataset.
    CustodiansPayload:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
          email:
            type: string
    MarketplaceDomainCreate:
      type: object
      properties:
        org_id:
          type:
          - 'null'
          - integer
        owner_id:
          type:
          - 'null'
          - integer
        name:
          type: string
        description:
          type: string
        parent_id:
          type: integer
          description: ID of the parent domain. Domains may build a hierarchy.
        custodians:
          $ref: '#/components/schemas/CustodiansPayload'
    CustodiansResponse:
      type: array
      items:
        type: object
        properties:
          id:
            type: integer
          email:
            type: string
          full_name:
            type: string
  responses:
    custodians_many:
      description: List of custodians
      content:
        application/vnd.nexla.api.v1+json:
          schema:
            $ref: '#/components/schemas/CustodiansResponse'
    domains_many:
      description: List of marketplace domains
      content:
        application/vnd.nexla.api.v1+json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/MarketplaceDomain'
    domain_items_many:
      description: List of marketplace domain items
      content:
        application/vnd.nexla.api.v1+json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/MarketplaceDomainsItem'
    domains_one:
      description: Single marketplace domain
      content:
        application/vnd.nexla.api.v1+json:
          schema:
            $ref: '#/components/schemas/MarketplaceDomain'
  parameters:
    accept:
      name: Accept
      in: header
      schema:
        type: string
        enum:
        - application/vnd.nexla.api.v1+json
        - application/json
        description: 'Setting to `application/vnd.nexla.api.v1+json` is recommended.

          '
  securitySchemes:
    NexlaSessionToken:
      type: http
      scheme: Bearer
      bearerFormat: JWT
      description: "The first step in calling the Nexla API or Nexla CLI is to fetch a Session access token by logging on to your Nexla UI instance. This ensures that your authentication is performed through your organization's preferred Identity Provider.\n\nTo fetch an access token from the Nexla UI, simply go to your Nexla UI instance, and try the route `/token`. For example, if your Nexla UI instance is at `https://dataops.nexla.io`, open `https://dataops.nexla.io/token` in the browser. \n\nThis will automatically route you to a login page, ask you to authenticate using your preferred Identity Provider, and, upon successful authentication, route you to a page where you can copy the Access Token.\n\nUsage format: `Bearer <JWT>`.\n"
    NexlaApiKeyQuery:
      type: apiKey
      name: api_key
      in: query
      description: '> **Important:** Never share your API keys. Keep them guarded and secure. If you think the key has been compromised, you can rotate the API key by calling relevant API Key management endpoints.


        The platform generates a unique API key for this resource. Add the API key as a query parameter to authenticate this request.

        Usage: `?api_key=<api-key>`

        '
    NexlaApiKeyHeader:
      type: http
      scheme: Basic
      description: '> **Important:** Never share your API keys. Keep them guarded and secure. If you think the key has been compromised, you can rotate the API key by calling relevant API Key management endpoints.


        The platform generates a unique API key for this resource. Add the API key as an authorization header to authenticate this request.

        Usage format: `Basic <api-key>`

        '
    basicAuth:
      type: http
      scheme: basic
    GoogleSSOToken:
      type: http
      scheme: Bearer
      bearerFormat: JWT
      description: 'The token that is used when logging into Nexla via Google SSO.

        '
x-tagGroups:
- name: Session
  tags:
  - Session Management
- name: Integrate
  tags:
  - Flows
  - Sources
  - Destinations (Data Sinks)
  - Nexsets (Data Sets)
  - Credentials
  - Data Maps
  - Code Containers
  - Transforms
  - Projects
- name: Monitor
  tags:
  - Notifications
  - Metrics
  - Audit Logs
  - Quarantine Settings
- name: Collaborate
  tags:
  - Access Control
- name: Account Management
  tags:
  - Organizations
  - Users
  - User Settings
  - Teams
  - Gen AI Configs
- name: Real-Time Events
  tags:
  - Webhooks
- name: Rate Limiting
  tags:
  - Limits
- name: Marketplace
  tags:
  - Marketplace
- name: Self Sign-Up
  tags:
  - Self Sign-Up
  - Self Sign-Up Admin
- name: Async Tasks
  tags:
  - Async Tasks