Nexla GenAI Configurations API

openapi: 3.2.0
info:
  version: v1
  title: Nexla Rest GenAI Configurations 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: GenAI Configurations
  description: Operations for managing GenAI configurations.
paths:
  /gen_ai_integration_configs:
    get:
      tags:
      - GenAI Configurations
      operationId: get_gen_ai_configs
      summary: Get all GenAI configs in org
      description: Retrieves all GenAI configurations accessible to the authenticated user.
      parameters:
      - $ref: '#/components/parameters/accept'
      responses:
        '200':
          $ref: '#/components/responses/gen_ai_configs_many'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      tags:
      - GenAI Configurations
      operationId: create_gen_ai_config
      summary: Create a GenAI config
      description: 'Creates a GenAI configuration.

        '
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenAiConfigPayload'
      responses:
        '200':
          $ref: '#/components/responses/gen_ai_configs_one'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /gen_ai_integration_configs/{gen_ai_config_id}:
    get:
      tags:
      - GenAI Configurations
      operationId: get_gen_ai_integration_config
      summary: Get GenAI Integration Config
      description: 'Retrieves a GenAI integration configuration by ID.

        '
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: set_id
        in: path
        description: The unique ID of the GenAI config.
        required: true
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/gen_ai_configs_one'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /gen_ai_org_settings:
    get:
      tags:
      - GenAI Configurations
      operationId: get_gen_ai_org_settings
      summary: Get all bindings of GenAI configs of the org for specified usages.
      description: Retrieves all activated GenAI configurations for the org.
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: org_id
        in: query
        description: The ID of the org (super-admin access required).
        required: false
        schema:
          type: integer
      - name: all
        in: query
        description: Flag to fetch all config bindings in the system (super-admin access required).
        required: false
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/gen_ai_org_settings_many'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
    post:
      tags:
      - GenAI Configurations
      operationId: create_gen_ai_org_setting
      summary: Create a binding of GenAI config for the org for specific usage.
      description: Activates a GenAI configuration for specific usage. All other bindings for the same usage will be deactivated.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenAiOrgSettingPayload'
      parameters:
      - $ref: '#/components/parameters/accept'
      responses:
        '200':
          $ref: '#/components/responses/gen_ai_org_settings_one'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /gen_ai_org_settings/{gen_ai_org_setting_id}:
    delete:
      tags:
      - GenAI Configurations
      operationId: delete_gen_ai_org_setting
      summary: Delete GenAI Config binding for org.
      description: Delete GenAI config binding for an org (disables a GenAI configuration usage).
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: org_gen_ai_config_id
        in: path
        description: The unique ID of the GenAI config.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
  /gen_ai_org_settings/active_config:
    get:
      tags:
      - GenAI Configurations
      operationId: gen_ai_org_settings_show_active
      summary: Shows active GenAI Configuration for specific usage
      description: Shows active GenAI Configuration for specific usage
      parameters:
      - $ref: '#/components/parameters/accept'
      - name: gen_ai_usage
        in: query
        description: The usage of the GenAI configuration.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
components:
  schemas:
    GenAiOrgSettingPayload:
      type: object
      properties:
        org_id:
          type: integer
        gen_ai_config_id:
          type: integer
        gen_ai_usage:
          type: string
          enum:
          - all
          - gen_docs
          - check_code
    GenAiOrgSetting:
      type: object
      properties:
        id:
          type: integer
        org_id:
          type: integer
        gen_ai_usage:
          type: string
          enum:
          - gen_docs
          - check_code
          - all
        get_ai_config_id:
          type: integer
        gen_ai_config:
          description: GenAI configuration (only if accessible)
          $ref: '#/components/schemas/GenAiConfig'
    OrgSimplified:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email_domain:
          type: string
        email:
          type: string
        client_identifier:
          type: string
        org_webhook_host:
          type: string
    GenAiConfig:
      type: object
      properties:
        id:
          type: integer
          format: int32
        owner:
          $ref: '#/components/schemas/UserSimplified'
        org:
          $ref: '#/components/schemas/OrgSimplified'
        data_credentials:
          $ref: '#/components/schemas/DataCredential'
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - ACTIVE
          - PAUSED
        config:
          type: object
          additionalProperties: true
          properties:
            api_version:
              type: string
            openai_model:
              type: string
            google_ai_model:
              type: string
            enable_doc_recommendations:
              type: boolean
        type:
          type: string
          enum:
          - genai_openai
          - genai_googleai
    GenAiConfigPayload:
      type: object
      properties:
        name:
          type: string
        description:
          type:
          - string
          - 'null'
        status:
          anyOf:
          - type: string
            enum:
            - active
            - paused
          - type: 'null'
        config:
          type: object
          additionalProperties: true
          properties:
            api_version:
              type:
              - string
              - 'null'
            openai_model:
              type:
              - string
              - 'null'
            google_ai_model:
              type:
              - string
              - 'null'
            enable_doc_recommendations:
              type: boolean
        type:
          type: string
          enum:
          - genai_openai
          - genai_googleai
        data_credentials_id:
          type: integer
    DataCredential:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        owner:
          $ref: '#/components/schemas/UserSimplified'
        org:
          $ref: '#/components/schemas/OrgSimplified'
        access_roles:
          type: array
          items:
            type: string
        credentials_version:
          type: string
        managed:
          type: boolean
        credentials_type:
          type: string
        connector:
          type: object
          properties:
            id:
              type: integer
            type:
              type: string
            connection_type:
              type: string
            name:
              type: string
            description:
              type: string
            nexset_api_compatible:
              type: boolean
        api_keys:
          type: array
        credentials_non_secure_data:
          type: object
          additionalProperties:
            type:
            - string
            - object
            - integer
            x-additionalPropertiesName: credential_property
        verified_status:
          type: string
        verified_at:
          type: string
          format: date-time
        copied_from_id:
          type: integer
          format: nullable
        updated_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        tags:
          type: array
    UserSimplified:
      type: object
      properties:
        id:
          type: integer
        full_name:
          type: string
        email:
          type: string
        email_verified_at:
          type: string
          format: date-time
  responses:
    gen_ai_configs_many:
      description: Success
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/GenAiConfig'
    gen_ai_org_settings_many:
      description: Success
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/GenAiOrgSetting'
    gen_ai_org_settings_one:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenAiOrgSetting'
    gen_ai_configs_one:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenAiConfig'
  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