Nexla Credentials API

openapi: 3.2.0
info:
  version: v1
  title: Nexla Rest Credentials 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: Credentials
  description: Operations for managing data credentials.
paths:
  /data_credentials:
    get:
      tags:
      - Credentials
      operationId: get_data_credentials
      summary: Get All Credentials
      description: 'Returns all data credentials accessible to the authenticated user.

        '
      parameters:
      - $ref: '#/components/parameters/access_roles'
      - $ref: '#/components/parameters/accept'
      - name: credentials_type
        in: query
        description: '(Optional) Set this to the type of credentials you want to filter by. Connection type or vendor name can be used there.

          '
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/data_credential_many'
        '403':
          description: Forbidden
        '404':
          description: Not found
    post:
      tags:
      - Credentials
      operationId: create_data_credential
      summary: Create a Credential
      description: 'Creates a Nexla data credential with the specified configuration in your Nexla account.


        > Note: `name`, `credentials_type`, and `credentials` are required.

        '
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/data_credential'
              - required:
                - name
                - credentials_type
                - credentials
      responses:
        '200':
          $ref: '#/components/responses/data_credential_one'
        '400':
          description: Unauthorized
  /data_credentials/{credential_id}:
    get:
      tags:
      - Credentials
      operationId: get_data_credential
      summary: Get Credential by ID
      description: 'Returns a credential object if a valid ID is provided.

        '
      parameters:
      - name: credential_id
        in: path
        description: The unique ID of the credential that needs to be fetched.
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/accept'
      responses:
        '200':
          $ref: '#/components/responses/data_credential_one'
        '403':
          description: Forbidden
        '404':
          description: Not found error
    put:
      tags:
      - Credentials
      operationId: update_data_credential
      summary: Update Credential
      description: "Updates a data credential in the authenticated user's account. \n\n> Note: This method does not perform partial updating of the `credentials` object. The entire `credentials` object will be updated if this is added to the payload.\n"
      parameters:
      - name: credential_id
        in: path
        description: The unique ID of the credential that needs to be fetched.
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/data_credential'
      responses:
        '200':
          $ref: '#/components/responses/data_credential_one'
        '403':
          description: Forbidden
        '404':
          description: Not found error
    delete:
      tags:
      - Credentials
      operationId: delete_data_credential
      summary: Delete a Credential
      description: Deletes a credential from your Nexla account.
      parameters:
      - name: credential_id
        in: path
        description: The unique ID of the credential that needs to be deleted.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/accept'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  code:
                    type: string
                    description: Response status code
                  message:
                    type: string
                    description: Response status text
        '404':
          description: Not found error
  /data_credentials/{credential_id}?expand=1:
    get:
      tags:
      - Credentials
      operationId: get_data_credential_expanded
      summary: Get Credential by ID with expanded references
      description: Returns a credential object along with advanced information about associated references if a valid ID is provided.
      parameters:
      - name: credential_id
        in: path
        description: The unique ID of the credential that needs to be fetched
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/expand'
      - $ref: '#/components/parameters/accept'
      responses:
        '200':
          $ref: '#/components/responses/data_credential_one'
        '403':
          description: Forbidden
        '404':
          description: Not found error
  /data_credentials/{credential_id}/probe:
    get:
      tags:
      - Credentials
      operationId: data_credential_probe
      summary: Test credential validity
      description: 'Use this endpoint to check whether or not a credential is valid.

        '
      parameters:
      - name: credential_id
        in: path
        description: The unique ID of the credential being used.
        required: true
        schema:
          type: integer
      - name: async
        in: query
        description: If set to 'true', request will be executed in a deferred way, and results will be provided later.
        required: false
        schema:
          type: boolean
      - name: request_id
        in: query
        description: The unique ID of the asynchronous request. In case it's provided, returns info about the deferred request.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/probe_response_with_async_results'
        '401':
          description: Unauthorized
        '403':
          description: Invalid credential
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    enum:
                    - 403
                  message:
                    type: string
                    description: 'Detailed reason for the credential authentication failure.

                      '
        '404':
          description: Not Found
  /data_credentials/{credential_id}/probe/tree:
    post:
      tags:
      - Credentials
      operationId: preview_storage_structure
      summary: Preview Storage Structure
      description: 'Use this endpoint to preview the structure/hierarchy of storage to which this credential grants access. For example, you can use this endpoint to see the folder and file structure of a file storage system or the table-column structure of a database.

        This can be used to inspect the directory hierarchy of file content storage or the database schema of a database/warehouse storage system. Note that this endpoint is only valid for credentials for storage systems wherein a storage structure needs to be reviewed.'
      parameters:
      - name: credential_id
        in: path
        description: The unique ID of the credential being used.
        required: true
        schema:
          type: integer
      - name: async
        in: query
        description: If set to 'true', request will be executed in a deferred way, and results will be provided later.
        required: false
        schema:
          type: boolean
      - name: request_id
        in: query
        description: The unique ID of the asynchronous request. In case it's provided, returns info about the deferred request.
        required: false
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                required:
                - depth
                properties:
                  depth:
                    type: integer
                    description: "Specify the hierarchy depth that should be scanned and returned in the response. \n\nIf no other payload properties are provided, the depth is relative to the storage root. If this request contains instructions about the slice of storage to be previewed (using the path/database/table properties), the depth will be applied relative to that storage slice.\n\nWe recommend using a depth = 1 to ensure that only small, relevant slices of the storage system are scanned.\n"
                  path:
                    type: string
                    description: 'Folder or subfolder path for which you wish to retrieve the content structure. The path string should be structured from the root of the location to the credential. For example, `demo-out.nexla.com/users/test` will return the folder tree for the contents of the `test` subfolder.


                      This is relevant for file-type connectors.

                      '
              - type: object
                required:
                - depth
                properties:
                  depth:
                    type: integer
                    description: "Specify the hierarchy depth that should be scanned and returned in the response. \n\nIf no other payload properties are provided, the depth is relative to the storage root. If this request contains instructions about the slice of storage to be previewed (using the path/database/table properties), the depth will be applied relative to that storage slice.\n\nWe recommend using a depth = 1 to ensure that only small, relevant slices of storage are scanned.\n"
                  database:
                    type: string
                    description: "Name of the database from which you wish to fetch table names or collections. \n\nRelevant for Database and NoSql document-type connectors. \n"
                  table:
                    type: string
                    description: "Name of the table of which you wish to fetch the column structure. \n\nRelevant for database-type connectors.\n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/probe_tree_with_async'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
  /data_credentials/{credential_id}/probe/sample:
    post:
      tags:
      - Credentials
      operationId: preview_connector_content
      summary: Preview Connector Content
      description: "Use this endpoint to preview the data content in a storage system.\n\n1. For file systems, this can be used to preview the file content of any specific file. \n2. For database systems, it can be used to preview sample rows from a table or query result. \n3. For the rest connector, it can be used to preview the results of any API request.\n4. For streaming connectors, it can be used to preview some records in a topic.\n\nFor most connectors, it can also be used to determine the type of records that might be detected in the resulting Nexset.\n"
      parameters:
      - name: credential_id
        in: path
        description: The unique ID of the credential being used.
        required: true
        schema:
          type: integer
      - name: async
        in: query
        description: If set to 'true', request will be executed in a deferred way, and results will be provided later.
        required: false
        schema:
          type: boolean
      - name: request_id
        in: query
        description: The unique ID of the asynchronous request. In case it's provided, returns info about the deferred request.
        required: false
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  path:
                    type: string
                    description: '__For file type connectors__: Set the path to the file from which you wish to preview content.

                      '
              - type: object
                additionalProperties:
                  type:
                  - string
                  - object
                  - number
                  - array
                  x-additionalPropertiesName: connector_source_config_property
                  description: "__For Rest, Database, Soap, and Stream Connectors__: Add all properties from the connector `source_config`.    \n"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/probe_sample_with_async'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
components:
  parameters:
    access_roles:
      name: access_role
      in: query
      schema:
        type: string
        enum:
        - collaborator
        - operator
        - admin
        - owner
        description: "Add this query parameter to a request to view resources for which the authenticated user has permission. \n\n1. `collaborator`: Resources to which the user has access via the collaborator or higher permissions.\n2. `operator`: Resources to which the user has access via the operator or higher permissions.\n3. `admin`: Resources to which the user has access via the administrator or owner permissions.\n4. `owner`: Resources created by the user.\nNote that the absence of this property in the request is treated as `owner`, so you do not need to set `access_role=owner` in the query.\n"
        externalDocs:
          description: Nexla API access roles
          url: https://developers.nexla.com/docs/access-modes
    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.

          '
    expand:
      name: expand
      in: query
      schema:
        type: integer
        enum:
        - 1
        description: 'Add this parameter to a resource fetch request to receive details about related resources in the response.

          '
  schemas:
    probe_sample_with_async:
      oneOf:
      - $ref: '#/components/schemas/AsyncResponse'
      - $ref: '#/components/schemas/probe_sample'
    probe_sample:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
          description: 'Response status code from the third-party storage system to which this credential connects. `Ok` indicates that the request resulted in a valid response from the storage system.

            '
        message:
          type: string
          enum:
          - Ok
          description: 'Message string indicating response validity from the underlying storage system. `Ok` indicates that the request resulted in a valid response from the storage system.

            Errors are returned as relevant message strings indicating the failure reasons.

            '
        connection_type:
          allOf:
          - $ref: '#/components/schemas/ConnectorTypeFile'
          - $ref: '#/components/schemas/ConnectorTypeDatabase'
          - $ref: '#/components/schemas/ConnectorTypeNoSql'
          - $ref: '#/components/schemas/ConnectorTypeKafka'
          - $ref: '#/components/schemas/ConnectorTypeVectorDB'
          - type: string
            enum:
            - rest
          - type: string
            enum:
            - soap
        output:
          oneOf:
          - type: object
            description: 'Response structure of sample file content from a file-type store.

              '
            properties:
              contentType:
                type: string
                description: 'File content type. Usually, this is `application/json`, `text/plain`, or `application/binary`.

                  '
              statusCode:
                type: integer
                description: 'Storage system status code for the sample request. Usually, this is 200 for a successful sample attempt and other status codes for unsuccessful sample attempts.

                  '
              response:
                type: string
                description: 'Sample lines from the file.

                  '
          - type: object
            description: 'Response structure of sample rows from a database-type store.

              '
            properties:
              contentType:
                type: string
                description: 'Response content type. Usually, this is `application/json`.

                  '
              statusCode:
                type: integer
                description: 'Storage system status code for the sample request. Usually, this is 200 for a successful sample attempt and other status codes for unsuccessful sample attempts.

                  '
              response:
                type: object
                properties:
                  columns:
                    type: array
                    description: 'An array of column names in the sample response.

                      '
                    items:
                      type: string
                  data:
                    type: array
                    description: 'An array of data rows in the sample response.

                      '
                    items:
                      type: object
                      additionalProperties:
                        type:
                        - integer
                        - string
                        - object
                        x-additionalPropertiesName: column_name
                        description: 'Value of the column in this row of data.

                          '
          - type: object
            description: 'The response structure for sample documents from a NoSQL document store.

              '
            properties:
              contentType:
                type: string
                enum:
                - application/json
                description: 'Response content type. Usually, this is `application/json`.

                  '
              statusCode:
                type: integer
                description: 'Storage system status code for the sample request. Usually, this is 200 for a successful sample attempt and other status codes for unsuccessful sample attempts.

                  '
              response:
                type: string
                description: 'JSON string in which each key is a document name and the value of each key is the content of the corresponding document.

                  '
          - type: object
            description: 'The response structure for the API response from a rest/soap connector.

              '
            properties:
              contentType:
                type: string
                description: 'Connector response content type. Usually, this is `application/json`, `text/plain`, or `application/binary`.

                  '
              statusCode:
                type: integer
                description: 'Storage system status code for the sample request. Usually, this is 200 for a successful sample attempt and other status codes for unsuccessful sample attempts.

                  '
              response:
                type: string
                description: "API response from the 3rd party (connector) API.                  \n\n  \n                 \n"
    ConnectorTypeKafka:
      type: string
      enum:
      - confluent_kafka
      - google_pubsub
      - jms
      - kafka
      - tibco
    org:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email_domain:
          type: string
        email:
          type: 'null'
        client_identifier:
          type: 'null'
    ConnectorTypeNoSql:
      type: string
      enum:
      - dynamodb
      - firebase
      - mongo
    owner:
      type: object
      properties:
        id:
          type: integer
        full_name:
          type: string
        email:
          type: string
          format: email
    probe_tree_with_async:
      oneOf:
      - $ref: '#/components/schemas/probe_tree_common'
      - $ref: '#/components/schemas/AsyncResponse'
    probe_tree_common:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
          description: 'Response status code from the third-party storage system to which this credential connects. `Ok` indicates that the request resulted in a valid response from the storage system.

            '
        message:
          type: string
          enum:
          - Ok
          description: 'Message string indicating response validity from the underlying storage system. `Ok` indicates that the request resulted in a valid response from the storage system.

            Errors are returned as relevant message strings indicating the failure reasons.

            '
        connection_type:
          type: string
          description: '__Connector Type__: Connector codename.

            '
      discriminator:
        propertyName: connection_type
        mapping:
          azure_blb: '#/components/schemas/file_probe_tree'
          azure_data_lake: '#/components/schemas/file_probe_tree'
          box: '#/components/schemas/file_probe_tree'
          delta_lake_azure_blb: '#/components/schemas/file_probe_tree'
          delta_lake_azure_data_lake: '#/components/schemas/file_probe_tree'
          delta_lake_s3: '#/components/schemas/file_probe_tree'
          dropbox: '#/components/schemas/file_probe_tree'
          ftp: '#/components/schemas/file_probe_tree'
          gcs: '#/components/schemas/file_probe_tree'
          gdrive: '#/components/schemas/file_probe_tree'
          min_io_s3: '#/components/schemas/file_probe_tree'
          s3: '#/components/schemas/file_probe_tree'
          s3_iceberg: '#/components/schemas/file_probe_tree'
          sharepoint: '#/components/schemas/file_probe_tree'
          webdav: '#/components/schemas/file_probe_tree'
          as400: '#/components/schemas/database_probe_tree'
          aws_athena: '#/components/schemas/database_probe_tree'
          azure_synapse: '#/components/schemas/database_probe_tree'
          bigquery: '#/components/schemas/database_probe_tree'
          databricks: '#/components/schemas/database_probe_tree'
          db2: '#/components/schemas/database_probe_tree'
          firebolt: '#/components/schemas/database_probe_tree'
          gcp_alloydb: '#/components/schemas/database_probe_tree'
          gcp_spanner: '#/components/schemas/database_probe_tree'
          hana_jdbc: '#/components/schemas/database_probe_tree'
          hive: '#/components/schemas/database_probe_tree'
          mysql: '#/components/schemas/database_probe_tree'
          netsuite_jdbc: '#/components/schemas/database_probe_tree'
          oracle: '#/components/schemas/database_probe_tree'
          oracle_autonomous: '#/components/schemas/database_probe_tree'
          postgres: '#/components/schemas/database_probe_tree'
          redshift: '#/components/schemas/database_probe_tree'
          snowflake: '#/components/schemas/database_probe_tree'
          sqlserver: '#/components/schemas/database_probe_tree'
          sybase: '#/components/schemas/database_probe_tree'
          teradata: '#/components/schemas/database_probe_tree'
          dynamodb: '#/components/schemas/nosql_probe_tree'
          firebase: '#/components/schemas/nosql_probe_tree'
          mongo: '#/components/schemas/nosql_probe_tree'
    AsyncResponse:
      type: object
      description: 'This object represents the response of an asynchronous operation. The response can be a dictionary or an array of dictionaries. The format of the response depends on the operation that was executed.

        '
      properties:
        request_id:
          type: integer
          description: 'The unique ID of the request that was executed. This ID can be used to track the status of the request.

            '
        status:
          type: string
          enum:
          - pending
          - running
          - completed
          - failed
          - cancelled
        request_started_at:
          type: string
          format: date-time
          description: 'The date and time when the request was started.

            '
        progress:
          type: integer
          description: 'The progress of the request (value from 0 to 100). This value is a percentage of the total progress of the request. Applicable only to certain types of async operations.

            '
        result:
          type: object
          description: 'The result of the async operation. Format depends on the task type.

            '
          additionalProperties: true
        request_stopped_at:
          type: string
          format: date-time
          description: 'The date and time when the request was stopped. This field is only present if the request has been stopped (due to cancellation or error).

            '
        request_completed_at:
          type: string
          format: date-time
          description: 'The date and time when the request was completed. This field is only present if the request has been completed successfully.

            '
    ConnectorTypeFile:
      type: string
      enum:
      - azure_blb
      - azure_data_lake
      - box
      - delta_lake_azure_blb
      - delta_lake_azure_data_lake
      - delta_lake_s3
      - dropbox
      - ftp
      - gcs
      - gdrive
      - min_io_s3
      - s3
      - s3_iceberg
      - sharepoint
      - webdav
    ConnectorTypeVectorDB:
      type: string
      enum:
      - pinecone
    ConnectorTypeDatabase:
      type: string
      enum:
      - as400
      - aws_athena
      - azure_synapse
      - bigquery
      - cloudsql_mysql
      - cloudsql_postgres
      - cloudsql_sqlserver
      - databricks
      - db2
      - firebolt
      - gcp_alloydb
      - gcp_spanner
      - hana_jdbc
      - hive
      - mysql
      - netsuite_jdbc
      - oracle
      - oracle_autonomous
      - postgres
      - redshift
      - snowflake
      - snowflake_dcr
      - sqlserver
      - sybase
      - teradata
    AccessRoles:
      type: array
      description: "This property reflects all the permissions the user/team/organization has to this resource. \n\n1. `collaborator`: The user/team/organization can view the resource but not make any modifications to it.\n2. `operator`: The user/team/organization can view the resource and can activate/pause it, but not make any other modifications to it.\n3. `administrator`: The user/team/organization has complete administrative rights to this resource.\n4. `owner`: This user created the resource and so has complete administrative rights to it. \n"
      items:
        type: string
        enum:
        - owner
        - collaborator
        - operator
        - admin
    data_credential:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        credentials_type:
          type: string
      discriminator:
        propertyName: credentials_type
        mapping:
          as400: '#/components/schemas/as400_data_credential'
          aws_athena: '#/components/schemas/aws_athena_data_credential'
          azure_blb: '#/components/schemas/azure_blb_data_credential'
          azure_data_lake: '#/components/schemas/azure_data_lake_data_credential'
          azure_synapse: '#/components/schemas/azure_synapse_data_credential'
          bigquery: '#/components/schemas/bigquery_data_credential'
          box: '#/components/schemas/box_data_credential'
          cloudsql_mysql: '#/components/schemas/cloudsql_mysql_data_credential'
          cloudsql_postgres: '#/components/schemas/cloudsql_postgres_data_credential'
          cloudsql_sqlserver: '#/components/schemas/cloudsql_sqlserver_data_credential'
          confluent_kafka: '#/components/schemas/confluent_kafka_data_credential'
          databricks: '#/components/schemas/databricks_data_credential'
          db2: '#/components/schemas/db2_data_credential'
          delta_lake_azure_blb: '#/components/schemas/delta_lake_azure_blb_data_credential'
          delta_lake_azure_data_lake: '#/components/schemas/delta_lake_azure_data_lake_data_credential'
          delta_lake_s3: '#/components/schemas/delta_lake_s3_data_credential'
          dropbox: '#/components/schemas/dropbox_data_credential'
          dynamodb: '#/components/schemas/dynamodb_data_credential'
          firebase: '#/components/schemas/firebase_data_credential'
          firebolt: '#/components/schemas/firebolt_data_credential'
          ftp: '#/components/schemas/ftp_data_credential'
          gcp_alloydb: '#/components/schemas/gcp_alloydb_data_credential'
          gcp_spanner: '#/components/schemas/gcp_spanner_data_credential'
          gcs: '#/components/schemas/gcs_data_credential'
          gdrive: '#/components/schemas/gdrive_data_credential'
          google_pubsub: '#/components/schemas/google_pubsub_data_credential'
          hana_jdbc: '#/components/schemas/hana_jdbc_data_credential'
          hive: '#/components/schemas/hive_data_credential'
          jms: '#/components/schemas/jms_data_credential'
          kafka: '#/components/schemas/kafka_data_credential'
          min_io_s3: '#/components/schemas/min_io_s3_data_credential'
          mongo: '#/components/schemas/mongo_data_credential'
          mysql: '#/components/schemas/mysql_data_credential'
          netsuite_jdbc: '#/components/schemas/netsuite_jdbc_data_credential'
          nexla_monitor: '#/components/schemas/nexla_monitor_data_credential'
   

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nexla/refs/heads/main/openapi/nexla-credentials-api-openapi.yml