spec.yaml

openapi: 3.1.0
info:
    title: 'Nango API'
    description: 'Nango API specs used to authorize & sync data with external APIs.'
    version: '1.0.0'
servers:
    - url: https://api.nango.dev
      description: Production server
    - url: http://localhost:3003
      description: Local server
paths:
    /providers:
        get:
            description: Returns a list of all available providers
            responses:
                '200':
                    description: Successfully returned a list of available providers
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - data
                                properties:
                                    data:
                                        type: array
                                        items:
                                            $ref: '#/components/schemas/Provider'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'
    /providers/{provider}:
        get:
            description: Returns a specific provider
            parameters:
                - name: provider
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The provider name
            responses:
                '200':
                    description: Successfully returned a specific provider
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - data
                                properties:
                                    data:
                                        $ref: '#/components/schemas/Provider'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'
                '404':
                    $ref: '#/components/responses/NotFound'
    /config:
        get:
            deprecated: true
            description: Returns a list of integrations. Deprecated, please use `GET /integrations`
            responses:
                '200':
                    description: Successfully returned a list of integrations
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - configs
                                properties:
                                    configs:
                                        type: array
                                        items:
                                            $ref: '#/components/schemas/Integration'
        post:
            description: Create a new integration
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - provider_config_key
                                - provider
                            properties:
                                provider_config_key:
                                    type: string
                                    description: A unique integration ID, which you will use in the other API calls to reference this integration.
                                provider:
                                    type: string
                                    description: The Nango API Configuration.
                                oauth_client_id:
                                    type: string
                                    description: The ID of your OAuth app (registered with the external API). Required for OAuth APIs.
                                oauth_client_secret:
                                    type: string
                                    description: The secret of your OAuth app (registered with the external API). Required for OAuth APIs.
                                oauth_scopes:
                                    type: string
                                    description: Comma separated list of scopes.
            responses:
                '200':
                    description: Successfully created an integration
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - config
                                properties:
                                    config:
                                        type: object
                                        required:
                                            - unique_key
                                            - provider
                                        properties:
                                            unique_key:
                                                type: string
                                                description: The integration ID that you created in Nango.
                                            provider:
                                                type: string
                                                description: The Nango API Configuration.
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
        put:
            description: Edits an integration (only for OAuth APIs)
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - provider_config_key
                                - provider
                                - oauth_client_id
                                - oauth_client_secret
                            properties:
                                provider_config_key:
                                    type: string
                                    description: The integration ID that you created on Nango.
                                provider:
                                    type: string
                                    description: The Nango API Configuration.
                                oauth_client_id:
                                    type: string
                                    description: The ID of your OAuth app (registered with the external API).
                                oauth_client_secret:
                                    type: string
                                    description: The secret of your OAuth app (registered with the external API).
                                oauth_scopes:
                                    type: string
                                    description: Comma separated list of scopes.
            responses:
                '200':
                    description: Successfully edit an integration
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - config
                                properties:
                                    config:
                                        type: object
                                        required:
                                            - unique_key
                                            - provider
                                        properties:
                                            unique_key:
                                                type: string
                                                description: The integration ID that you created in Nango.
                                            provider:
                                                type: string
                                                description: The Nango API Configuration.
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                '404':
                    description: Unknown integration
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /config/{providerConfigKey}:
        get:
            deprecated: true
            description: Returns a specific integration. Deprecated, please use `GET /integrations/{uniqueKey}`
            parameters:
                - name: providerConfigKey
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The integration ID that you created in Nango.
                - name: include_creds
                  in: query
                  required: false
                  description: If true, the response will contain the client ID, secret, scopes, auth_mode and app link - if applicable. include_creds is false by default.
                  schema:
                      type: boolean
            responses:
                '200':
                    description: Successfully returned an integration
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - config
                                properties:
                                    config:
                                        type: object
                                        required:
                                            - unique_key
                                            - provider
                                        properties:
                                            unique_key:
                                                type: string
                                                description: The integration ID that you created in Nango.
                                            provider:
                                                type: string
                                                description: The Nango API Configuration.
                                            actions:
                                                type: array
                                                items:
                                                    type: object
                                                    properties:
                                                        name:
                                                            type: string
                                                            description: The name of the action.
                                                        created_at:
                                                            type: string
                                                            description: The creation timestamp of the sync.
                                                        updated_at:
                                                            type: string
                                                            description: The last updated timestamp of the sync.
                                            syncs:
                                                type: array
                                                items:
                                                    type: object
                                                    properties:
                                                        name:
                                                            type: string
                                                            description: The name of the sync.
                                                        created_at:
                                                            type: string
                                                            description: The creation timestamp of the sync.
                                                        updated_at:
                                                            type: string
                                                            description: The last updated timestamp of the sync.
                                                        description:
                                                            type: string
                                                            description: Description of what the sync does and details about it
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                '404':
                    description: Unknown integration
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
        delete:
            description: Deletes a specific integration
            parameters:
                - name: providerConfigKey
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The integration ID that you created in Nango.
            responses:
                '200':
                    description: Successfully deleted an integration
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success:
                                        type: boolean
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                '404':
                    description: Unknown integration
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
    /integrations:
        get:
            description: Returns a list of integrations
            responses:
                '200':
                    description: Successfully returned an integration
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - data
                                properties:
                                    data:
                                        type: array
                                        items:
                                            $ref: '#/components/schemas/Integration'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'
                '404':
                    $ref: '#/components/responses/NotFound'
    /integrations/{uniqueKey}:
        get:
            description: Returns a specific integration
            parameters:
                - name: uniqueKey
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The integration ID (unique_key) that you created in Nango.
                - name: include
                  in: query
                  schema:
                      type: array
                      items:
                          type: string
                          enum: [webhook, credentials]
                  description: Include additional sensitive data
            responses:
                '200':
                    description: Successfully returned an integration
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - data
                                properties:
                                    data:
                                        $ref: '#/components/schemas/IntegrationFull'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'
                '404':
                    $ref: '#/components/responses/NotFound'

    /connection:
        get:
            description: Returns a list of connections without credentials
            parameters:
                - name: connectionId
                  in: query
                  schema:
                      type: string
                  description: Will exactly match a given connectionId. Can return multiple connections with the same ID across integrations
                - name: search
                  in: query
                  schema:
                      type: string
                  description: Search connections. Will search in connection ID or end user profile.
            responses:
                '200':
                    description: Successfully returned a list of connections
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - configs
                                properties:
                                    configs:
                                        type: array
                                        items:
                                            type: object
                                            required:
                                                - id
                                                - connection_id
                                                - provider
                                                - provider_config_key
                                                - created
                                                - metadata
                                                - errors
                                            properties:
                                                id:
                                                    type: integer
                                                    description: The internal Nango ID used for the connection.
                                                connection_id:
                                                    type: string
                                                    description: The connection ID used to create the connection.
                                                provider:
                                                    type: string
                                                    description: The Nango API Configuration.
                                                provider_config_key:
                                                    type: string
                                                    description: The integration ID used to create the connection (aka Unique Key, Provider Config Key).
                                                created:
                                                    type: string
                                                    description: Connection creation date.
                                                metadata:
                                                    type: object
                                                    description: Custom metadata attached to the connection
                                                    nullable: true
                                                errors:
                                                    type: array
                                                    items:
                                                        type: object
                                                        properties:
                                                            type:
                                                                type: string
                                                                example: "'auth' or 'sync'"
                                                            log_id:
                                                                type: string
                                                                example: 'VrnbtykXJFckCm3HP93t'
                                                    description: |
                                                        List of connection errors. Ex:
                                                        - Connection credentials are invalid (type=auth)
                                                        - Last sync for the connnection has failed (type=sync)

        post:
            description: Adds a connection for which you already have credentials.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - provider_config_key
                            properties:
                                connection_id:
                                    type: string
                                    description: The connection ID used to create the connection.
                                provider_config_key:
                                    type: string
                                    description: The integration ID that you created on Nango.
                                access_token:
                                    type: string
                                    description: (OAuth 2, required) Existing access token.
                                refresh_token:
                                    type: string
                                    description: (OAuth 2, optional) Pass the refresh token if you have it.
                                expires_at:
                                    type: string
                                    format: date
                                    description: (OAuth 2, optional) Safer and preferred.
                                expires_in:
                                    type: integer
                                    description: (OAuth 2, optional) In seconds.
                                no_expiration:
                                    type: boolean
                                    description: (OAuth2, optional) If the provider gives access tokens that don't expire, pass in `true` to avoid an import validation error.
                                oauth_client_id_override:
                                    type: string
                                    description: (OAuth2, optional) Override the integration's OAuth client id
                                oauth_client_secret_override:
                                    type: string
                                    description: (OAuth2, optional) Override the integration's OAuth client secret
                                oauth_token:
                                    type: string
                                    description: (OAuth 1, required) The client token to be attached to the connection.
                                oauth_token_secret:
                                    type: string
                                    description: (OAuth 1, required) The client token secret to be attached to the connection.
                                metadata:
                                    type: object
                                    description: (OAuth, required for some APIs) Metadata to be attached to the connection.
                                connection_config:
                                    type: object
                                    description: (OAuth, required for some APIs) Additional configuration to be attached to the connection.
                                username:
                                    type: string
                                    description: (Basic, required) username to be attached to the connection.
                                password:
                                    type: string
                                    description: (Basic, required) password to be attached to the connection.
                                api_key:
                                    type: string
                                    description: (API Key, required) API key to be attached to the connection.
            responses:
                '200':
                    description: Successfully created an integrations
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /connection/{connectionId}:
        get:
            description: Returns a specific connection with credentials
            parameters:
                - name: connectionId
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - name: provider_config_key
                  in: query
                  required: true
                  description: The integration ID used to create the connection (aka Unique Key).
                  schema:
                      type: string
                - name: force_refresh
                  in: query
                  description: If true, Nango will attempt to refresh the access access token regardless of its expiration status (false by default).
                  schema:
                      type: boolean
                - name: refresh_token
                  in: query
                  description: If true, return the refresh token as part of the response (false by default).
                  schema:
                      type: boolean
            responses:
                '200':
                    description: Successfully returned a connection
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                '404':
                    description: Unknown Connection
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
        delete:
            description: Deletes a specific connection
            parameters:
                - name: connectionId
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - name: provider_config_key
                  in: query
                  required: true
                  description: The integration ID used to create the connection (aka Unique Key).
                  schema:
                      type: string
            responses:
                '200':
                    description: Successfully deleted an connection
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    success:
                                        type: boolean
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
                '404':
                    description: Unknown connection
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
    /connection/metadata:
        post:
            description: Set custom metadata for the connection or connections. If updating multiple connections pass in an array of connection ids instead of a string.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - metadata
                                - connection_id
                                - provider_config_key
                            properties:
                                connection_id:
                                    oneOf:
                                        - type: string
                                          example: 'connection-123'
                                          description: The connection ID used to set the metadata on.
                                        - type: array
                                          items:
                                              type: string
                                              example: 'connection-123'
                                          description: The connection IDs used to set the metadata on. If one connection id is invalid in the array the entire operation is aborted with no changes made.
                                provider_config_key:
                                    type: string
                                    description: The integration ID used to create the connection (aka Unique Key).
                                metadata:
                                    type: object

            responses:
                '201':
                    description: Successfully set the metadata for the connections
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    connection_id:
                                        oneOf:
                                            - type: string
                                              example: 'connection-123'
                                              description: The connection ID used to set the metadata on. Returns an array of connection ids if an array is passed in.
                                            - type: array
                                              items:
                                                  type: string
                                                  example: 'connection-123'
                                              description: The connection IDs used to set the metadata on. If one connection id is invalid in the array the entire operation is aborted with no changes made.
                                    provider_config_key:
                                        type: string
                                        description: The integration ID used to create the connection (aka Unique Key).
                                    metadata:
                                        type: object
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
        patch:
            description: Edit custom metadata for the connection or connections (only overrides specified properties, not the entire metadata). If updating multiple connections pass in an array of connection ids instead of a string.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - metadata
                                - connection_id
                                - provider_config_key
                            properties:
                                connection_id:
                                    oneOf:
                                        - type: string
                                          example: 'connection-123'
                                          description: The connection ID used to update the metadata on. Accepts an array of connection ids as well
                                        - type: array
                                          items:
                                              type: string
                                              example: 'connection-123'
                                          description: The connection IDs used to update the metadata on. If one connection id is invalid in the array the entire operation is aborted with no changes made.
                                provider_config_key:
                                    type: string
                                    description: The integration ID used to create the connection (aka Unique Key).
                                metadata:
                                    type: object

            responses:
                '200':
                    description: Successfully updated the metadata for the connections
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    connection_id:
                                        oneOf:
                                            - type: string
                                              example: 'connection-123'
                                              description: The connection ID used to update the metadata on. Returns an array of connection ids if an array is passed in.
                                            - type: array
                                              items:
                                                  type: string
                                                  example: 'connection-123'
                                              description: The connection IDs used to update the metadata on. If one connection id is invalid in the array the entire operation is aborted with no changes made.
                                    provider_config_key:
                                        type: string
                                        description: The integration ID used to create the connection (aka Unique Key).
                                    metadata:
                                        type: object
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /connection/{connectionId}/metadata:
        post:
            description: Set custom metadata for the connection.
            parameters:
                - name: connectionId
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - name: Provider-Config-Key
                  in: header
                  required: true
                  description: The integration ID used to create the connection (aka Unique Key).
                  schema:
                      type: string
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object

            responses:
                '201':
                    description: Successfully created an integrations
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

        patch:
            description: Edit custom metadata for the connection (only overrides specified properties, not the entire metadata).
            parameters:
                - name: connectionId
                  in: path
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - name: Provider-Config-Key
                  in: header
                  required: true
                  description: The integration ID used to create the connection (aka Unique Key).
                  schema:
                      type: string
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
            responses:
                '200':
                    description: Successfully updated the metadata
                    content:
                        application/json:
                            schema:
                                type: object
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /scripts/config:
        get:
            description: Return the configuration for all integration scripts
            responses:
                '200':
                    description: Successfully returned integration scripts config
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    providerConfigKey:
                                        type: string
                                    syncs:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                name:
                                                    type: string
                                                    example: 'github-issues'
                                                type:
                                                    type: string
                                                    example: 'sync'
                                                models:
                                                    type: array
                                                    items:
                                                        type: object
                                                        properties:
                                                            name:
                                                                type: string
                                                                example: 'GithubIssue'
                                                            fields:
                                                                type: array
                                                                items:
                                                                    type: object
                                                                    properties:
                                                                        name:
                                                                            type: string
                                                                            example: 'title'
                                                                        type:
                                                                            type: string
                                                                            example: 'string'
                                                sync_type:
                                                    type: string
                                                    example: 'INCREMENTAL'
                                                runs:
                                                    type: string
                                                    example: 'every 30 minutes'
                                                track_deletes:
                                                    type: boolean
                                                auto_start:
                                                    type: boolean
                                                last_deployed:
                                                    type: string
                                                    example: '2024-02-01T09:09:03.502Z'
                                                is_public:
                                                    type: boolean
                                                pre_built:
                                                    type: boolean
                                                version:
                                                    type: string
                                                    example: '0.0.3'
                                                attributes:
                                                    type: object
                                                input:
                                                    type: object
                                                returns:
                                                    type: array
                                                    items:
                                                        type: string
                                                        example: 'GithubIssue'
                                                description:
                                                    type: string
                                                    example: "Fetches the Github issues from all a user's repositories.\nDetails: full sync, doesn't track deletes, metadata is not required.\n"
                                                scopes:
                                                    type: array
                                                    items:
                                                        type: string
                                                        example: 'public_repo'
                                                endpoints:
                                                    type: array
                                                    items:
                                                        type: object
                                                webhookSubscriptions:
                                                    type: array
                                                    items:
                                                        type: string
                                    actions:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                name:
                                                    type: string
                                                    example: 'github-issues'
                                                type:
                                                    type: string
                                                    example: 'sync'
                                                models:
                                                    type: array
                                                    items:
                                                        type: object
                                                        properties:
                                                            name:
                                                                type: string
                                                                example: 'GithubIssue'
                                                            fields:
                                                                type: array
                                                                items:
                                                                    type: object
                                                                    properties:
                                                                        name:
                                                                            type: string
                                                                            example: 'id'
                                                                        type:
                                                                            type: string
                                                                            example: 'integer'
                                                last_deployed:
                                                    type: string
                                                    example: '2024-02-28T20:16:38.052Z'
                                                is_public:
                                                    type: boolean
                                                    example: false
                                                pre_built:
                                                    type: boolean
                                                    example: false
                                                version:
                                                    type: string
                                                    example: '4'
                                                attributes:
                                                    type: object
                                                input:
                                                    type: object
                                                returns:
                                                    type: object
                                                description:
                                                    type: string
                                                    example: "Fetches the Github issues from all a user's repositories.\nDetails: full sync, doesn't track deletes, metadata is not required.\n"
                                                scopes:
                                                    type: array
                                                    items:
                                                        type: string
                                                        example: 'public_repo'
                                                endpoints:
                                                    type: array
                                                    items:
                                                        type: object
                                    postConnectionScripts:
                                        type: array
                                        items:
                                            type: string
                                    provider:
                                        type: string
                                        example: 'github'
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /records:
        get:
            description: Returns data synced with Nango Sync
            parameters:
                - name: model
                  in: query
                  required: true
                  schema:
                      type: string
                  description: The data model to fetch
                - name: cursor
                  in: query
                  required: false
                  schema:
                      type: string
                  description: |
                      A marker used to fetch records modified after a specific point in time. If not provided, all records are returned. Each record includes a cursor value found in _nango_metadata.cursor. Save the cursor from the last record retrieved to track your sync progress. Use the cursor parameter together with the limit parameter to paginate through records. The cursor is more precise than modified_after, as it can differentiate between records with the same modification timestamp.
                - name: limit
                  in: query
                  required: false
                  schema:
                      type: integer
                  description: The maximum number of records to return. Defaults to 100.
                - name: filter
                  in: query
                  required: false
                  schema:
                      type: string
                      enum: [added, updated, deleted]
                  description: Filter to only show results that have been added or updated or deleted.
                - name: modified_after
                  in: query
                  required: false
                  schema:
                      type: string
                  description: A timestamp (e.g., 2023-05-31T11:46:13.390Z) used to fetch records modified after this date and time. If not provided, all records are returned. The modified_after parameter is less precise than cursor, as multiple records may share the same modification timestamp.
                - name: delta
                  in: query
                  required: false
                  deprecated: true
                  schema:
                      type: string
                  description: DEPRECATED (use modified_after) Timestamp, e.g. 2023-05-31T11:46:13.390Z. If passed, only records modified after this timestamp are returned, otherwise all records are returned.
                - name: Connection-Id
                  in: header
                  required: true
                  description: The connection ID used to create the connection.
                  schema:
                      type: string
                - name: Provider-Config-Key
                  in: header
                  required: true
                  description: The integration ID used to create the connection (aka Unique Key).
                  schema:
                      type: string

            responses:
                '200':
                    description: Successfully returned records
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    records:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                your-properties:
                                                    type: string
                                                    description: The data Nango synced in for you
                                                    example: 'Your synced data, in the schema you (or Nango) defined in nango.yaml'
                                                _nango_metadata:
                                                    type: object
                                                    properties:
                                                        deleted_at:
                                                            type: string
                                                            nullable: true
                                                            description: The timestamp at which Nango detected the record as deleted
                                                        last_action:
                                                            type: string
                                                            description: The last action seen on this record
                                                            enum: ['ADDED', 'UPDATED', 'DELETED']
                                                        first_seen_at:
                                                            type: string
                                                            description: The timestamp at which Nango first saw this record
                                                            example: '2023-09-18T15:20:35.941305+00:00'
                                                        last_modified_at:
                                                            type: string
                                                            description: The timestamp at which Nango last detected a change to this record
                                                            example: '2023-09-18T15:20:35.941305+00:00'
                                                        cursor:
                                                            type: string
                                                            description: The current cursor of the record. Use this to fetch records updated after this record
                                                            example: 'MjAyNC0wMy0wNFQwNjo1OTo1MS40NzE0NDEtMDU6MDB8fDE1Y2NjODA1LTY0ZDUtNDk0MC1hN2UwLTQ1ZmM3MDQ5OTdhMQ=='
                                    next_cursor:
                                        type: string
                                        description: The base64-encoded cursor for pagination
                                        example: 'MjAyMy0xMS0xN1QxMTo0NzoxNC40NDcrMDI6MDB8fDAzZTA1NzIxLWNiZmQtNGYxNS1iYTNhLWFlNjM2Y2MwNmEw=='
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /sync/trigger:
        post:
            description: Triggers an additional, one-off execution of specified sync(s) (for a given connection or all applicable connections if no connection is specified).
            requestBody:
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - provider_config_key
                                - syncs
                            properties:
                                provider_config_key:
                                    type: string
                                    description: The ID of the integration that you established within Nango.
                                connection_id:
                                    type: string
                                    description: The ID of the connection. If omitted, the syncs will be triggered for all relevant connections.
                                syncs:
                                    type: array
                                    description: An array of sync names to trigger. If the array is empty, all syncs are triggered.
                                    items:
                                        type: string
                                full_resync:
                                    type: boolean
                                    description: Clear the records and reset the "lastSyncDate" associated with the sync before triggering a new sync job.

            responses:
                '200':
                    description: Successfully triggered the sync
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /sync/start:
        post:
            description: Starts the schedule of specified sync(s) for a given connection or all applicable connections if no connection is specified. Upon starting the schedule, the sync will execute immediately and then continue to run at the specified frequency. If the schedule was already started, this will have no effect.
            requestBody:
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - provider_config_key
                                - syncs
                            properties:
                                provider_config_key:
                                    type: string
                                    description: The ID of the integration that you established within Nango.
                                connection_id:
                                    type: string
                                    description: The ID of the connection. If omitted, the syncs will be started for all relevant connections.
                                syncs:
                                    type: array
                                    description: A list of sync names that you wish to start.
                                    items:
                                        type: string
            responses:
                '200':
                    description: Successfully started the sync
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
    /sync/pause:
        post:
            description: Pauses the schedule of specified sync(s) for a given connection or all applicable connections if no connection is specified.
            requestBody:
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - provider_config_key
                                - syncs
                            properties:
                                provider_config_key:
                                    type: string
                                    description: The ID of the integration that you established within Nango.
                                connection_id:
                                    type: string
                                    description: The ID of the connection. If omitted, the syncs will be paused for all relevant connections.
                                syncs:
                                    type: array
                                    description: A list of sync names that you wish to pause.
                                    items:
                                        type: string
            responses:
                '200':
                    description: Successfully paused the sync
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /sync/status:
        get:
            description: Get the status of specified sync(s) (for a given connection or all applicable connections if no connection is specified)
            parameters:
                - name: provider_config_key
                  in: query
                  required: true
                  schema:
                      type: string
                  description: The ID of the integration you established within Nango
                - name: syncs
                  in: query
                  required: true
                  schema:
                      type: string
                  description: The name of the syncs you want to fetch a status for. Pass in "*" to return all syncs per the integration
                - name: connection_id
                  in: query
                  required: false
                  schema:
                      type: string
                  description: The ID of the connection. If omitted, all connections will be surfaced.
            responses:
                '200':
                    description: Successfully returned a list of syncs and their status
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    syncs:
                                        type: array
                                        items:
                                            type: object
                                            properties:
                                                id:
                                                    type: string
                                                    description: The unique identifier for the sync.
                                                name:
                                                    type: string
                                                    description: The name of the sync.
                                                status:
                                                    type: string
                                                    enum: ['RUNNING', 'PAUSED', 'STOPPED', 'SUCCESS', 'ERROR']
                                                    description: The current status of the sync.
                                                type:
                                                    type: string
                                                    description: The most recent sync type completed
                                                    enum: ['INCREMENTAL', 'INITIAL']
                                                finishedAt:
                                                    type: string
                                                    description: ISO string of the most recently completed sync
                                                nextScheduledSyncAt:
                                                    type: string
                                                    description: ISO string of the next scheduled sync time
                                                frequency:
                                                    type: string
                                                    description: The execution frequency of the sync
                                                latestResult:
                                                    type: object
                                                    description: Additional information regarding the latest result of the sync. Contains a model name with added, updated and deleted records
                                                recordCount:
                                                    type: object
                                                    description: Total count of records for each model synced by the sync
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /sync/update-connection-frequency:
        put:
            description: Override a sync's default frequency for a specific connection, or revert to the default frequency.
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - provider_config_key
                                - connection_id
                                - sync_name
                                - frequency
                            properties:
                                provider_config_key:
                                    type: string
                                    description: The ID of the integration you established within Nango
                                connection_id:
                                    type: string
                                    description: The ID of the connection
                                sync_name:
                                    type: string
                                    description: The name of the sync you want to update
                                frequency:
                                    type: string
                                    nullable: true
                                    description: "The frequency you want to set (ex: 'every hour'). Set null to revert to the default frequency. Uses the https://github.com/vercel/ms notations. Min frequency: 5 minutes."
            responses:
                '200':
                    description: Successfully updated the frequency
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    frequency:
                                        type: string
                                        description: The updated frequency value
                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string
    /action/trigger:
        post:
            description: Triggers an action for a connection
            parameters:
                - name: Connection-Id
                  in: header
                  required: true
                  description: The connection ID used to create the connection.
                  schema:
                      type: string
                - name: Provider-Config-Key
                  in: header
                  required: true
                  description: The integration ID used to create the connection (aka Unique Key).
                  schema:
                      type: string
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            type: object
                            required:
                                - action_name
                            properties:
                                action_name:
                                    type: string
                                    description: The name of the action to trigger.
                                input:
                                    type: object
                                    description: The necessary input for your action's 'runAction' function.

            responses:
                '200':
                    description: Returns the result of the action
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    your-properties:
                                        type: string
                                        description: The data returned by the action
                                        example: 'The data returned by the action'

                '400':
                    description: Invalid request
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    message:
                                        type: string

    /environment-variables:
        get:
            description: Retrieve the environment variables as added in the Nango dashboard
            responses:
                '200':
                    description: Retrieve the environment variables as added in the Nango dashboard
                    content:
                        application/json:
                            schema:
                                type: array
                                items:
                                    type: object
                                    properties:
                                        name:
                                            type: string
                                            description: The name of the environment variable
                                            example: 'MY_SECRET_KEY'
                                        value:
                                            type: string
                                            description: The value of the environment variable
                                            example: 'SK_373892NSHFNCOWFO...'

    /proxy/{anyPath}:
        get:
            description: Make a GET request with the Proxy.
            parameters:
                - name: anyPath
                  in: path
                  required: true
                  schema:
                      type: string
                - name: $ANY_QUERY_PARAMS
                  in: query
                  required: true
                  schema:
                      type: string
                - in: header
                  name: Connection-Id
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - in: header
                  name: Provider-Config-Key
                  required: true
                  schema:
                      type: string
                  description: The integration ID used to create the connection (aka Unique Key).
                - in: header
                  name: Retries
                  schema:
                      type: string
                  description: The number of retries in case of failure (with exponential back-off). Optional, default 0.
                - in: header
                  name: Retry On
                  schema:
                      type: string
                  description: Comma separated status codes to explicitly retry on in addition to the default 5xx and 429.
                - in: header
                  name: Base-Url-Override
                  schema:
                      type: string
                  description: Provide an API base URL when the base API is not listed in the providers.yaml or it needs to be overridden. Optional
                - in: header
                  name: Decompress
                  schema:
                      type: string
                  description: Override the decompress option when making requests. Optional, defaults to false
                - in: header
                  name: nango-proxy-$ANY_HEADER
                  schema:
                      type: string
                  description: Any other headers you send are passed on to the external API
            responses:
                '200':
                    description: The response exactly as returned by the external API
        post:
            description: Make a POST request with the Proxy.
            parameters:
                - name: anyPath
                  in: path
                  required: true
                  schema:
                      type: string
                - in: header
                  name: Connection-Id
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - in: header
                  name: Provider-Config-Key
                  required: true
                  schema:
                      type: string
                  description: The integration ID used to create the connection (aka Unique Key).
                - in: header
                  name: Retries
                  schema:
                      type: string
                  description: The number of retries in case of failure (with exponential back-off). Optional, default 0.
                - in: header
                  name: Base-Url-Override
                  schema:
                      type: string
                  description: Provide an API base URL when the base API is not listed in the providers.yaml or it needs to be overridden. Optional
                - in: header
                  name: Decompress
                  schema:
                      type: string
                  description: Override the decompress option when making requests. Optional, defaults to false
                - in: header
                  name: nango-proxy-$ANY_HEADER
                  schema:
                      type: string
                  description: Any other headers you send are passed on to the external API
            requestBody:
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                $ANY_BODY_PARAMS:
                                    type: string
            responses:
                '200':
                    description: The response exactly as returned by the external API
        put:
            description: Make a PUT request with the Proxy.
            parameters:
                - name: anyPath
                  in: path
                  required: true
                  schema:
                      type: string
                - in: header
                  name: Connection-Id
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - in: header
                  name: Provider-Config-Key
                  required: true
                  schema:
                      type: string
                  description: The integration ID used to create the connection (aka Unique Key).
                - in: header
                  name: Retries
                  schema:
                      type: string
                  description: The number of retries in case of failure (with exponential back-off). Optional, default 0.
                - in: header
                  name: Base-Url-Override
                  schema:
                      type: string
                  description: Provide an API base URL when the base API is not listed in the providers.yaml or it needs to be overridden. Optional
                - in: header
                  name: Decompress
                  schema:
                      type: string
                  description: Override the decompress option when making requests. Optional, defaults to false
                - in: header
                  name: nango-proxy-$ANY_HEADER
                  schema:
                      type: string
                  description: Any other headers you send are passed on to the external API
            requestBody:
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                $ANY_BODY_PARAMS:
                                    type: string
            responses:
                '200':
                    description: The response exactly as returned by the external API
        patch:
            description: Make a PATCH request with the Proxy.
            parameters:
                - name: anyPath
                  in: path
                  required: true
                  schema:
                      type: string
                - in: header
                  name: Connection-Id
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - in: header
                  name: Provider-Config-Key
                  required: true
                  schema:
                      type: string
                  description: The integration ID used to create the connection (aka Unique Key).
                - in: header
                  name: Retries
                  schema:
                      type: string
                  description: The number of retries in case of failure (with exponential back-off). Optional, default 0.
                - in: header
                  name: Base-Url-Override
                  schema:
                      type: string
                  description: Provide an API base URL when the base API is not listed in the providers.yaml or it needs to be overridden. Optional
                - in: header
                  name: Decompress
                  schema:
                      type: string
                  description: Override the decompress option when making requests. Optional, defaults to false
                - in: header
                  name: nango-proxy-$ANY_HEADER
                  schema:
                      type: string
                  description: Any other headers you send are passed on to the external API
            requestBody:
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                $ANY_BODY_PARAMS:
                                    type: string
            responses:
                '200':
                    description: The response exactly as returned by the external API
        delete:
            description: Make a DELETE request with the Proxy.
            parameters:
                - name: anyPath
                  in: path
                  required: true
                  schema:
                      type: string
                - name: $ANY_QUERY_PARAMS
                  in: query
                  required: true
                  schema:
                      type: string
                - in: header
                  name: Connection-Id
                  required: true
                  schema:
                      type: string
                  description: The connection ID used to create the connection.
                - in: header
                  name: Provider-Config-Key
                  required: true
                  schema:
                      type: string
                  description: The integration ID used to create the connection (aka Unique Key).
                - in: header
                  name: Retries
                  schema:
                      type: string
                  description: The number of retries in case of failure (with exponential back-off). Optional, default 0.
                - in: header
                  name: Base-Url-Override
                  schema:
                      type: string
                  description: Provide an API base URL when the base API is not listed in the providers.yaml or it needs to be overridden. Optional
                - in: header
                  name: Decompress
                  schema:
                      type: string
                  description: Override the decompress option when making requests. Optional, defaults to false
                - in: header
                  name: nango-proxy-$ANY_HEADER
                  schema:
                      type: string
                  description: Any other headers you send are passed on to the external API
            responses:
                '200':
                    description: The response exactly as returned by the external API
    /connect/sessions:
        post:
            description: Create a new connect session
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ConnectSession'
            responses:
                '201':
                    description: Successfully created a connect session
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - data
                                properties:
                                    data:
                                        type: object
                                        required:
                                            - token
                                            - expires_at
                                        properties:
                                            token:
                                                type: string
                                                description: The connect session token
                                            expires_at:
                                                type: string
                                                description: When the token expires
                                                format: date
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'
    /connect/session:
        get:
            description: Retrieve a connect session
            responses:
                '200':
                    description: Successfully retrieved a connect session
                    content:
                        application/json:
                            schema:
                                type: object
                                required:
                                    - data
                                properties:
                                    data:
                                        $ref: '#/components/schemas/ConnectSession'
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'
                '404':
                    $ref: '#/components/responses/NotFound'
        delete:
            description: Delete a connect session
            responses:
                '204':
                    description: Successfully deleted a connect session
                '400':
                    $ref: '#/components/responses/BadRequest'
                '401':
                    $ref: '#/components/responses/Unauthorized'
                '404':
                    $ref: '#/components/responses/NotFound'

components:
    responses:
        BadRequest:
            description: Bad request
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/StdError'
        Unauthorized:
            description: Unauthorized
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/StdError'
        NotFound:
            description: Not Found
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/StdError'

    schemas:
        StdError:
            type: object
            additionalProperties: false
            properties:
                error:
                    type: object
                    additionalProperties: false
                    required:
                        - code
                    properties:
                        code:
                            type: string
                        message:
                            type: string
                        errors:
                            type: array
                            items:
                                type: object

        TokenUrlObject:
            properties:
                OAUTH1:
                    type: string
                OAUTH2:
                    type: string
                OAUTH2CC:
                    type: string
                BASIC:
                    type: string
                API_KEY:
                    type: string
                APP_STORE:
                    type: string
                CUSTOM:
                    type: string
                APP:
                    type: string
                NONE:
                    type: string
            additionalProperties: false
            type: object

        SimplifiedJSONSchema:
            type: object
            additionalProperties: false
            required: ['type', 'title', 'description']
            properties:
                type:
                    type: string
                    enum: [string]
                title:
                    type: string
                description:
                    type: string
                example:
                    type: string
                pattern:
                    type: string
                format:
                    type: string
        BaseProvider:
            properties:
                name:
                    type: string
                display_name:
                    type: string
                auth_mode:
                    type: string
                    enum:
                        [
                            'OAUTH1',
                            'OAUTH2',
                            'OAUTH2_CC',
                            'BASIC',
                            'API_KEY',
                            'APP_STORE',
                            'CUSTOM',
                            'APP',
                            'NONE',
                            'TBA',
                            'TABLEAU',
                            'JWT',
                            'BILL',
                            'TWO_STEP',
                            'SIGNATURE'
                        ]
                proxy:
                    properties:
                        base_url:
                            type: string
                        headers:
                            type: object
                        query:
                            properties:
                                api_key:
                                    type: string
                            required:
                                - api_key
                            additionalProperties: false
                            type: object
                        retry:
                            type: object
                            properties:
                                at:
                                    type: string
                                after:
                                    type: string
                        decompress:
                            type: boolean
                        paginate:
                            anyOf: []
                        verification:
                            properties:
                                method:
                                    type: string
                                endpoint:
                                    type: string
                                base_url_override:
                                    type: string
                                headers:
                                    type: object
                            required:
                                - method
                                - endpoint
                            additionalProperties: false
                            type: object
                    required:
                        - base_url
                    additionalProperties: false
                    type: object
                authorization_url:
                    type: string
                authorization_url_encode:
                    type: boolean
                access_token_url:
                    type: string
                token_url_encode:
                    type: boolean
                authorization_params:
                    type: object
                scope_separator:
                    type: string
                default_scopes:
                    items:
                        type: string
                    type: array
                token_url:
                    anyOf:
                        - type: string
                        - $ref: '#/components/schemas/TokenUrlObject'
                token_params:
                    type: object
                authorization_url_replacements:
                    type: object
                authorization_url_fragment:
                    type: string
                redirect_uri_metadata:
                    items:
                        type: string
                    type: array
                token_response_metadata:
                    items:
                        type: string
                    type: array
                docs:
                    type: string
                token_expiration_buffer:
                    type: number
                webhook_routing_script:
                    type: string
                webhook_user_defined_secret:
                    type: boolean
                post_connection_script:
                    type: string
                categories:
                    items:
                        type: string
                    type: array
                connection_configuration:
                    items:
                        type: string
                    type: array
                connection_config:
                    $ref: '#/components/schemas/SimplifiedJSONSchema'
                credentials:
                    type: object
                    properties:
                        apiKey:
                            $ref: '#/components/schemas/SimplifiedJSONSchema'

            required:
                - auth_mode
                - name
                - display_name
                - docs
            additionalProperties: false
            type: object
        ProviderOAuth2:
            properties:
                auth_mode:
                    enum:
                        - OAUTH2
                        - CUSTOM
                    type: string
                token_params:
                    properties:
                        grant_type:
                            enum:
                                - authorization_code
                                - client_credentials
                            type: string
                    additionalProperties: false
                    type: object
                disable_pkce:
                    type: boolean
                refresh_params:
                    properties:
                        grant_type:
                            enum:
                                - refresh_token
                            type: string
                    required:
                        - grant_type
                    additionalProperties: false
                    type: object
                authorization_method:
                    type: string
                    enum:
                        - body
                        - header
                body_format:
                    type: string
                    enum:
                        - form
                        - json
                refresh_url:
                    type: string
                expires_in_unit:
                    enum:
                        - milliseconds
                    type: string
                token_request_auth_method:
                    enum:
                        - basic
                        - custom
                    type: string
            required:
                - auth_mode
            additionalProperties: false
            type: object
        ProviderOAuth1:
            properties:
                auth_mode:
                    enum:
                        - OAUTH1
                    type: string
                request_url:
                    type: string
                request_params:
                    type: object
                request_http_method:
                    enum:
                        - GET
                        - PUT
                        - POST
                    type: string
                token_http_method:
                    enum:
                        - GET
                        - PUT
                        - POST
                    type: string
                signature_method:
                    enum:
                        - HMAC-SHA1
                        - RSA-SHA1
                        - PLAINTEXT
                    type: string
            required:
                - auth_mode
                - request_url
                - signature_method
            additionalProperties: false
            type: object

        Provider:
            anyOf:
                - $ref: '#/components/schemas/BaseProvider'
                  title: 'Default'
                - $ref: '#/components/schemas/ProviderOAuth1'
                  title: 'Oauth1'
                - $ref: '#/components/schemas/ProviderOAuth2'
                  title: 'Oauth2'

        Integration:
            type: object
            additionalProperties: false
            required:
                - unique_key
                - display_name
                - provider
                - created_at
                - updated_at
            properties:
                unique_key:
                    type: string
                    description: The integration ID that you created in Nango.
                display_name:
                    type: string
                    description: The provider display name.
                provider:
                    type: string
                    description: The Nango API Configuration.
                logo:
                    type: string
                    description: Absolute path to the logo of this integration (svg)
                created_at:
                    type: string
                    format: date
                    description: When it was created
                updated_at:
                    type: string
                    format: date
                    description: Last time it was updated
        IntegrationFull:
            allOf:
                - $ref: '#/components/schemas/Integration'
                - type: object
                  additionalProperties: false
                  properties:
                      webhook_url:
                          type: string
                          description: Configure your integration webhooks to point to this URL
                          nullable: true
                      credentials:
                          nullable: true
                          oneOf:
                              - type: object
                                additionalProperties: false
                                properties:
                                    type:
                                        type: string
                                        enum: ['OAUTH2', 'OAUTH1', 'TBA']
                                    client_id:
                                        type: string
                                        nullable: true
                                    client_secret:
                                        type: string
                                        nullable: true
                                    scopes:
                                        type: string
                                        nullable: true

                              - type: object
                                additionalProperties: false
                                properties:
                                    type:
                                        type: string
                                        enum: ['APP']
                                    app_id:
                                        type: string
                                        nullable: true
                                    private_key:
                                        type: string
                                        nullable: true
                                    app_link:
                                        type: string
                                        nullable: true

        ConnectSession:
            type: object
            required:
                - end_user
            properties:
                end_user:
                    type: object
                    required:
                        - id
                        - email
                    properties:
                        id:
                            type: string
                            description: Uniquely identifies the end user.
                        email:
                            type: string
                        display_name:
                            type: string
                organization:
                    type: object
                    properties:
                        id:
                            type: string
                            description: Uniquely identifies the organization the end user belongs to
                        display_name:
                            type: string
                allowed_integrations:
                    type: array
                    description: Filters which integrations the end user can interact with
                    items:
                        type: string
                integrations_config_defaults:
                    type: object
                    additionalProperties:
                        type: object
                        description: the unique name of an integration
                        additionalProperties: false
                        properties:
                            user_scopes:
                                type: string
                                description: User scopes (for Slack only)
                            connection_config:
                                type: object
                                additionalProperties: true
                                properties:
                                    oauth_scopes_override:
                                        type: string
                                        description: Override oauth scopes