# yaml-language-server: $schema=https://spec.openapis.org/oas/3.1/schema/2025-02-13 openapi: 3.1.0 externalDocs: url: https://nango.dev/docs/reference/backend/http-api/authentication 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 security: - bearerAuth: [] paths: /providers: get: summary: List all providers 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: summary: Get a provider 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' /providers/{provider}/templates: get: summary: List provider templates description: Returns the template functions available in the catalog for a provider. Requires a valid API key (no specific scope). parameters: - name: provider in: path required: true schema: type: string description: The provider name. responses: '200': description: Successfully returned the provider's template functions content: application/json: schema: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ProviderTemplateFunction' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /integrations: get: summary: List integrations 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' post: summary: Create an integration description: Create an integration requestBody: required: true content: application/json: schema: type: object required: - unique_key - provider properties: unique_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 provider unique name. display_name: type: string description: The integration display name. forward_webhooks: type: boolean description: Whether to forward webhooks received for this integration. Defaults to true. credentials: $ref: '#/components/schemas/IntegrationCredentialsInput' description: > Developer app credentials for the integration. Omit them to create the integration without credentials and provide them later, either with an update request or per connection at connection time. integration_config: type: object additionalProperties: type: string description: > Provider-specific configuration for providers that declare an `integration_config` schema (e.g. `private-api-generic`, `aws-sigv4`). Keys and required fields depend on the provider; values are validated against the provider schema. responses: '200': description: Successfully created an integration content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Integration' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /integrations/quickstart: post: summary: Create a quickstart integration description: Create an integration using a Nango-provided developer app for providers that require a developer app. requestBody: required: true content: application/json: schema: type: object required: - unique_key - provider properties: unique_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 provider unique name. display_name: type: string description: The integration display name. forward_webhooks: type: boolean description: Whether to forward webhooks for this integration. responses: '200': description: Successfully created 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' /integrations/{uniqueKey}: get: summary: Get an integration 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' patch: summary: Edit an integration description: Edit an integration parameters: - name: uniqueKey in: path required: true schema: type: string description: The integration ID (unique_key) that you created in Nango. requestBody: required: true content: application/json: schema: type: object properties: unique_key: type: string description: A unique integration ID, which you will use in the other API calls to reference this integration. display_name: type: string description: The integration display name. forward_webhooks: type: boolean description: Whether to forward webhooks received for this integration. credentials: $ref: '#/components/schemas/IntegrationCredentialsInput' description: > Developer app credentials for the integration. Only the fields you pass are updated; the ones you leave out keep their current value. integration_config: type: object additionalProperties: type: string description: > Provider-specific configuration for providers that declare an `integration_config` schema (e.g. `private-api-generic`, `aws-sigv4`). Only the fields you pass are updated. responses: '200': description: Successfully updated an integration content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Integration' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: summary: Delete an integration description: Deletes a specific integration. parameters: - name: uniqueKey in: path required: true schema: type: string description: The integration ID (unique_key) that you created in Nango. responses: '200': description: Successfully deleted an integration content: application/json: schema: type: object required: - success properties: success: type: boolean '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /integrations/{uniqueKey}/functions: get: summary: List functions description: Returns the functions available to an integration, including Nango catalog actions when available. Requires an API key with the `environment:functions:list` scope. parameters: - name: uniqueKey in: path required: true schema: type: string description: The integration ID (unique_key) that you created in Nango. - name: type in: query required: false schema: type: string enum: [sync, action, on-event] description: Filter by function type. - name: search in: query required: false schema: type: string minLength: 1 maxLength: 255 description: Case-insensitive filter on the function name. - name: page in: query required: false schema: type: integer minimum: 0 default: 0 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: Successfully returned the integration's functions content: application/json: schema: type: object required: - data - pagination properties: data: type: array items: $ref: '#/components/schemas/ListedNangoFunction' pagination: type: object required: - total - page - limit properties: total: type: integer page: type: integer limit: type: integer '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /integrations/{uniqueKey}/functions/{name}: get: summary: Get a function description: Returns a single function available to an integration. This can be a deployed function or a Nango catalog action. Requires an API key with the `environment:functions:read` scope. parameters: - name: uniqueKey in: path required: true schema: type: string description: The integration ID (unique_key) that you created in Nango. - name: name in: path required: true schema: type: string description: The name of the function. - name: type in: query required: false schema: type: string enum: [sync, action, on-event] description: Disambiguates when multiple functions share the same name. responses: '200': description: Successfully returned the function content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/ListedNangoFunction' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: summary: Delete a function description: Deletes a deployed function and enqueues its async teardown. Functions managed by `nango deploy` (repo source) cannot be deleted through this endpoint. Requires an API key with the `environment:functions:delete` scope. parameters: - name: uniqueKey in: path required: true schema: type: string description: The integration ID (unique_key) that you created in Nango. - name: name in: path required: true schema: type: string description: The name of the function. - name: type in: query required: true schema: type: string enum: [sync, action] description: Required to disambiguate a sync and an action that share a name. On-event functions are not yet supported. responses: '200': description: Successfully enqueued the function deletion content: application/json: schema: type: object required: - data properties: data: type: object required: - success properties: success: type: boolean '400': description: Invalid request, or the function is managed by `nango deploy`. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: [function_managed_by_deploy] message: type: string '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /integrations/{uniqueKey}/functions/{name}/code: get: summary: Get a function's source code description: Returns the TypeScript source code of a function for a given integration. Requires an API key with the `environment:functions:read` scope. parameters: - name: uniqueKey in: path required: true schema: type: string description: The integration ID (unique_key) that you created in Nango. - name: name in: path required: true schema: type: string description: The name of the function. - name: type in: query required: false schema: type: string enum: [sync, action, on-event] description: The function type. Required to disambiguate when multiple functions share the same name. responses: '200': description: Successfully returned the function source code content: application/json: schema: type: object required: - type - code properties: type: type: string enum: [sync, action, on-event] description: The function type. code: type: string description: The TypeScript source code of the function. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: Multiple functions share the same name. Specify a `type` to disambiguate. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: [ambiguous_function] message: type: string payload: type: object properties: matches: type: array items: type: object required: - type - name properties: type: type: string enum: [sync, action, on-event] name: type: string /connection: get: summary: List connections (deprecated) description: Returns a list of connections without credentials. This endpoint is deprecated, use the /connections endpoint instead. 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: Will partially match connection IDs or end user profiles. - name: endUserId in: query deprecated: true schema: type: string description: Deprecated. Prefer filtering connections by tag (e.g. `tags[end_user_id]=...`). - name: endUserOrganizationId in: query deprecated: true schema: type: string description: Deprecated. Prefer filtering connections by tag (e.g. `tags[organization_id]=...`). - name: tags in: query description: Filter the list of connections based on connection tags. All provided tags must match. style: deepObject explode: true schema: $ref: '#/components/schemas/Tags' - name: limit in: query schema: type: integer description: Limit the number of connections returned - name: page in: query schema: type: integer description: Page number for paginated results responses: '200': description: Successfully returned a list of connections content: application/json: schema: type: object required: - connections properties: connections: type: array items: type: object required: - id - connection_id - provider - provider_config_key - created - metadata - tags - 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: anyOf: - type: object - type: 'null' description: Custom metadata attached to the connection tags: $ref: '#/components/schemas/Tags' errors: type: array items: $ref: '#/components/schemas/ConnectionError' description: | List of connection errors. Ex: - Connection credentials are invalid (type=auth) - Last sync for the connection has failed (type=sync) end_user: deprecated: true anyOf: - $ref: '#/components/schemas/ConnectionEndUser' - type: 'null' post: summary: Add a connection (deprecated) description: Adds a connection for which you already have credentials. This endpoint is deprecated, use the /connections endpoint instead. 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: summary: Get a connection (deprecated) description: Returns a specific connection with credentials. This endpoint is deprecated, use the /connections/{connectionId} endpoint instead. 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 content: application/json: schema: $ref: '#/components/schemas/ConnectionFull' '400': description: Invalid request content: application/json: schema: type: object properties: message: type: string '424': description: Connection refresh exhausted content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: The error code message: type: string description: A human-readable error message '404': description: Unknown Connection content: application/json: schema: type: object properties: message: type: string delete: summary: Delete a connection (deprecated) description: Deletes a specific connection. This endpoint is deprecated, use the /connections/{connectionId} endpoint instead. 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: summary: Set connection metadata (deprecated) description: Set custom metadata for the connection or connections. If updating multiple connections pass in an array of connection ids instead of a string. This endpoint is deprecated, use the /connections/metadata endpoint instead. 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: summary: Edit connection metadata (deprecated) 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. This endpoint is deprecated, use the /connections/metadata endpoint instead. 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': $ref: '#/components/responses/BadRequest' /connection/{connectionId}/metadata: post: summary: Set connection metadata (deprecated) description: Set custom metadata for the connection. deprecated: true 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': $ref: '#/components/responses/BadRequest' patch: summary: Edit connection metadata (deprecated) description: Edit custom metadata for the connection (only overrides specified properties, not the entire metadata). deprecated: true 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': $ref: '#/components/responses/BadRequest' /connections: get: summary: List connections 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 deprecated: true schema: type: string description: Deprecated. No direct replacement for partial matching; prefer exact filtering via `connectionId` or connection tags (e.g. `tags[end_user_id]=...`). - name: endUserId in: query deprecated: true schema: type: string description: Deprecated. Prefer filtering connections by tag (e.g. `tags[end_user_id]=...`). - name: endUserOrganizationId in: query deprecated: true schema: type: string description: Deprecated. Prefer filtering connections by tag (e.g. `tags[organization_id]=...`). - name: tags in: query description: Filter the list of connections based on connection tags. All provided tags must match. style: deepObject explode: true schema: $ref: '#/components/schemas/Tags' - name: limit in: query schema: type: integer description: Limit the number of connections returned - name: page in: query schema: type: integer description: Page number for paginated results responses: '200': description: Successfully returned a list of connections content: application/json: schema: type: object required: - connections properties: connections: type: array items: type: object required: - id - connection_id - provider - provider_config_key - created - metadata - tags - 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: anyOf: - type: object - type: 'null' description: Custom metadata attached to the connection tags: $ref: '#/components/schemas/Tags' errors: type: array items: $ref: '#/components/schemas/ConnectionError' description: | List of connection errors. Ex: - Connection credentials are invalid (type=auth) - Last sync for the connection has failed (type=sync) end_user: deprecated: true anyOf: - $ref: '#/components/schemas/ConnectionEndUser' - type: 'null' '400': $ref: '#/components/responses/BadRequest' post: summary: Upsert a connection description: Upserts a connection for which you already have credentials. requestBody: required: true content: application/json: schema: type: object required: - provider_config_key - credentials properties: provider_config_key: type: string description: The integration ID that you created on Nango. metadata: type: object description: (OAuth, required for some APIs) Metadata to be attached to the connection. connection_id: type: string description: The connection ID used to create the connection. connection_config: type: object description: (OAuth, required for some APIs) Additional configuration to be attached to the connection. credentials: type: object description: The credentials to be attached to the connection. anyOf: - $ref: '#/components/schemas/OAuth1Credentials' - $ref: '#/components/schemas/OAuth2Credentials' - $ref: '#/components/schemas/BasicApiCredentials' - $ref: '#/components/schemas/ApiKeyCredentials' - $ref: '#/components/schemas/OAuth2ClientCredentials' - $ref: '#/components/schemas/UnauthCredentialsWithType' - $ref: '#/components/schemas/TbaCredentials' - type: object title: GitHub App additionalProperties: false required: - type - app_id - installation_id properties: type: type: string enum: [APP] app_id: type: string installation_id: type: string tags: $ref: '#/components/schemas/Tags' end_user: allOf: - $ref: '#/components/schemas/EndUser' deprecated: true description: Deprecated, use tags instead responses: '200': description: Successfully created an integrations content: application/json: schema: $ref: '#/components/schemas/ConnectionFull' '400': $ref: '#/components/responses/BadRequest' /connections/{connectionId}: get: summary: Get a connection 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 - name: refresh_github_app_jwt_token in: query description: If true, this will refresh the JWT token for GitHub App / Github App OAuth connections schema: type: boolean responses: '200': description: Successfully returned a connection content: application/json: schema: $ref: '#/components/schemas/ConnectionFull' '400': $ref: '#/components/responses/BadRequest' '424': description: Connection refresh exhausted content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: The error code message: type: string description: A human-readable error message '404': $ref: '#/components/responses/NotFound' patch: summary: Edit a connection description: Edit a 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 requestBody: required: true content: application/json: schema: type: object properties: tags: $ref: '#/components/schemas/Tags' webhook_url_override: type: string description: > Override the environment's webhook URLs for this connection. When set, this connection's webhooks are sent only to this URL. Pass an empty string to clear the override. end_user: allOf: - $ref: '#/components/schemas/EndUser' deprecated: true description: Deprecated, use tags instead responses: '200': description: Successfully updated the connection content: application/json: schema: type: object properties: success: type: boolean '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' delete: summary: Delete a connection 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': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' /connections/metadata: post: summary: Set connection metadata 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: summary: Edit connection metadata 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 /scripts/config: get: summary: Get scripts configuration description: Return the configuration for all integration functions. parameters: - name: format in: query required: false schema: type: string enum: [nango, openai] description: The output type of the script configuration responses: '200': description: Successfully returned integration functions config content: application/json: schema: type: object properties: providerConfigKey: type: string syncs: type: array items: type: object properties: id: type: number name: type: string example: 'github-issues' enabled: type: boolean type: type: string example: 'sync' json_schema: type: object 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: 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 models: type: array items: type: object properties: name: type: string fields: type: array required: - name actions: type: array items: type: object properties: id: type: number name: type: string example: 'github-issues' type: type: string example: 'action' 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: doesn't track deletes, metadata is not required.\n" scopes: type: array items: type: string example: 'public_repo' endpoints: type: array items: type: object models: type: array items: type: object properties: name: type: string fields: type: array required: - name on-events: type: array items: type: string provider: type: string example: 'github' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /functions/compile: post: operationId: compileFunction summary: Compile a function description: Compiles TypeScript function source code and returns the bundled JavaScript. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FunctionCompileRequest' responses: '200': description: Successfully compiled the function. content: application/json: schema: $ref: '#/components/schemas/FunctionCompileResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' /functions/dryruns: post: operationId: createFunctionDryrun summary: Dry run a function description: Starts an asynchronous dry run for TypeScript function source code against a connection without deploying it. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FunctionDryrunRequest' responses: '202': description: Successfully started the dry run. content: application/json: schema: $ref: '#/components/schemas/FunctionDryrunCreateResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' /functions/dryruns/{id}: get: operationId: getFunctionDryrun summary: Get dry run results description: Returns the status and result of an asynchronous function dry run. parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Successfully retrieved the dry run. content: application/json: schema: $ref: '#/components/schemas/FunctionDryrunResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /functions/deployments: post: operationId: createFunctionDeployment summary: Create a function deployment description: | Deploys a function to an existing integration. Use `type: function` to deploy submitted TypeScript source code, or `type: template` to deploy a template from the provider catalog. Requires an API key with the `environment:deploy` scope. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FunctionDeploymentRequest' responses: '202': description: | Deployment record. `status` may be any of `waiting`, `running`, `success`, or `failed`. If it is not `success`, poll `GET /functions/deployments/{id}` for the final status and details. content: application/json: schema: $ref: '#/components/schemas/FunctionDeploymentResponse' '409': description: The template is already deployed, or the template name is ambiguous and `function_type` is required. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: [template_already_deployed, ambiguous_function] message: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' /functions/deployments/{id}: get: operationId: getFunctionDeployment summary: Get a function deployment description: Returns the status and result of an asynchronous function deployment. parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Successfully retrieved the deployment. content: application/json: schema: $ref: '#/components/schemas/FunctionDeploymentResultResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /records: get: summary: Get synced records 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. A response may contain fewer records than `limit` when records have a large size. Always check `next_cursor` and continue paginating until it is `null`. - 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 format: date-time 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: ids in: query required: false description: An array of string containing a list of your records IDs. The list will be filtered to include only the records with a matching ID. schema: type: array items: type: string maxItems: 100 - name: variant in: query required: false schema: type: string description: The variant of the model to fetch - 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 script' _nango_metadata: type: object properties: deleted_at: anyOf: - type: string format: date-time - type: 'null' 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' format: date-time 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' format: date-time cursor: type: string description: The current cursor of the record. Use this to fetch records updated after this record example: 'MjAyNC0wMy0wNFQwNjo1OTo1MS40NzE0NDEtMDU6MDB8fDE1Y2NjODA1LTY0ZDUtNDk0MC1hN2UwLTQ1ZmM3MDQ5OTdhMQ==' pruned_at: anyOf: - type: string format: date-time - type: 'null' description: The timestamp at which the record payload was pruned (emptied) next_cursor: type: string description: The base64-encoded cursor for pagination example: 'MjAyMy0xMS0xN1QxMTo0NzoxNC40NDcrMDI6MDB8fDAzZTA1NzIxLWNiZmQtNGYxNS1iYTNhLWFlNjM2Y2MwNmEw==' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /records/prune: patch: summary: Prune records description: |- Prunes synced records for a given connection and model using cursor-based pagination. **What is pruning:** Pruning empties the record payload while preserving the record metadata. **Cursor behavior:** Records are pruned up to and including the specified cursor. 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: - model - until_cursor properties: model: type: string description: The data model to prune records from variant: type: string description: The variant of the model until_cursor: type: string description: Prune all records up to and including this cursor. Use the cursor value from _nango_metadata.cursor of the record you want to prune up to. limit: type: integer minimum: 1 maximum: 10000 description: The maximum number of records to prune in this request. Defaults to 1000. responses: '200': description: Successfully pruned records content: application/json: schema: type: object required: - count - has_more properties: count: type: integer description: The number of records pruned in this request example: 150 has_more: type: boolean description: |- Indicates if there are potentially more records to prune. - `true`: There may be more records that need pruning - `false`: All records up to the cursor have been pruned example: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /sync/trigger: post: summary: Trigger a sync 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: oneOf: - type: array description: A list of sync names that you wish to pause. If empty, all syncs are triggered items: type: string description: Sync name example: 'github-issues' - type: array description: A list of sync object (with a name and variant properties) that you wish to trigger. If empty, all syncs are triggered items: type: object required: - name properties: name: type: string description: The name of the sync variant: type: string description: The variant name example: { 'name': 'github-issues', 'variant': 'custom-variant' } opts: type: object description: Options for triggering the sync. properties: reset: type: boolean description: If true, clears the checkpoint and lastSyncDate before triggering the sync, causing it to start fresh. emptyCache: type: boolean description: If true, deletes all cached records associated with the sync before triggering. Must be used with reset=true. responses: '200': description: Successfully triggered the sync content: application/json: schema: type: object required: - success properties: success: type: boolean '400': description: Invalid request content: application/json: schema: type: object properties: message: type: string /sync/start: post: summary: Start a sync 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: oneOf: - type: array description: A list of sync names that you wish to start. If empty, all syncs are triggered items: type: string description: Sync name example: 'github-issues' - type: array description: A list of sync object (with a name and variant properties) that you wish to start. items: type: object required: - name properties: name: type: string description: The name of the sync variant: type: string description: The variant name example: { 'name': 'github-issues', 'variant': 'custom-variant' } responses: '200': description: Successfully started the sync content: application/json: schema: type: object required: - success properties: success: type: boolean '400': description: Invalid request content: application/json: schema: type: object properties: message: type: string /sync/pause: post: summary: Pause a sync 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: oneOf: - type: array description: A list of sync names that you wish to pause. If empty, all syncs are triggered items: type: string description: Sync name example: 'github-issues' - type: array description: A list of sync object (with a name and variant properties) that you wish to start. items: type: object required: - name properties: name: type: string description: The name of the sync variant: type: string description: The variant name example: { 'name': 'github-issues', 'variant': 'custom-variant' } responses: '200': description: Successfully paused the sync content: application/json: schema: type: object required: - success properties: success: type: boolean '400': description: Invalid request content: application/json: schema: type: object properties: message: type: string /sync/status: get: summary: Get sync status 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, as a comma-separated list. Pass in "*" to return all syncs for the integration. For variants, use the format "syncName::variantName". - 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. connection_id: type: string description: The ID of the connection name: type: string description: The name of the sync. variant: type: string description: The variant of the sync. status: type: string enum: ['RUNNING', 'PAUSED', 'STOPPED', 'SUCCESS', 'ERROR'] description: The current status of the sync. type: deprecated: true 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 checkpoint: anyOf: - type: object - type: 'null' description: Last checkpoint saved during sync execution. Null if no checkpoint exists. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /sync/{name}/variant/{variant}: post: summary: Create sync variant description: Creates a new sync variant for a specific connection parameters: - name: name in: path required: true schema: type: string description: The name of the sync - name: variant in: path required: true schema: type: string description: The name of the variant to create. Cannot be "base" (protected name). requestBody: required: true content: application/json: schema: type: object required: - provider_config_key - connection_id properties: provider_config_key: type: string description: The integration ID used when creating the connection connection_id: type: string description: The ID of the connection to create the sync variant for responses: '200': description: Successfully created the sync variant content: application/json: schema: type: object required: - id - name - variant properties: id: type: string description: The unique identifier for the created sync variant name: type: string description: The name of the sync variant: type: string description: The name of the variant '400': description: Invalid request content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: [ invalid_body, invalid_uri_params, invalid_query_params, invalid_variant, unknown_connection, unknown_provider_config, unknown_sync, sync_variant_already_exists, resource_capped, feature_disabled ] message: type: string errors: type: array items: type: object '500': description: Server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: [failed_sync_variant_creation] message: type: string delete: summary: Delete sync variant description: Deletes a sync variant for a specific connection parameters: - name: name in: path required: true schema: type: string description: The name of the sync - name: variant in: path required: true schema: type: string description: The name of the variant to delete. Cannot be "base" (protected name). requestBody: required: true content: application/json: schema: type: object required: - provider_config_key - connection_id properties: provider_config_key: type: string description: The integration ID used when creating the connection connection_id: type: string description: The ID of the connection the sync variant belongs to responses: '200': description: Successfully deleted the sync variant content: application/json: schema: type: object required: - success properties: success: type: boolean description: Indicates if the deletion was successful '400': description: Invalid request content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: [invalid_body, invalid_uri_params, invalid_query_params, invalid_variant, unknown_connection] message: type: string errors: type: array items: type: object '404': description: Sync variant not found content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: [not_found] '500': description: Server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: [failed_sync_variant_deletion] message: type: string /action/{actionId}: get: summary: Get action result description: Retrieves the result of an asynchronous action. See [Asynchronous action documentation](/guides/functions/action-functions#trigger-asynchronously) for more details. parameters: - name: actionId in: path required: true schema: type: string description: The ID of the asynchronous action (returned from triggering an action with X-Async header) responses: '200': description: The action has completed successfully (output cannot exceed 2MB) content: application/json: schema: type: object description: The data returned by the action properties: your-properties: type: string description: The data returned by the action example: 'The data returned by the action' '404': description: No results. The action has not completed yet content: application/json: schema: type: object properties: error: type: object properties: message: type: string example: 'Action not completed yet' '500': description: The action has completed with an error content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string payload: type: object /sync/update-connection-frequency: put: summary: Update sync frequency 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 sync_variant: type: string description: The variant of the sync you want to update frequency: anyOf: - type: string - type: 'null' 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: 30 seconds." 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: summary: Trigger an action 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 - name: X-Async in: header required: false schema: type: boolean description: Set to true to trigger the action asynchronously. When true, the response will include a status URL and ID for retrieving the action result later. See [Asynchronous action documentation](/guides/functions/action-functions#trigger-asynchronously) for more details. - name: X-Max-Retries in: header required: false schema: type: integer minimum: 0 maximum: 5 default: 0 description: The maximum number of retries in case of failure (between 0 and 5). Only applicable when X-Async is true. Default to 0 if not specified. 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 'exec' function. responses: '200': description: The result of the action. content: application/json: schema: oneOf: - type: object description: The result of the action when triggered synchronously. (cannot exceed 10MB) properties: your-properties: type: object description: The data returned by the action example: 'The data returned by the action' - type: object description: The ID and the status URL of the action to poll for the result when triggered asynchronously. required: - statusUrl - id properties: statusUrl: type: string description: URL to poll for the action result example: '/action/35f461d4-e681-4957-ab14-c0ae1609431d' id: type: string description: Unique identifier for the asynchronous action example: '35f461d4-e681-4957-ab14-c0ae1609431d' '400': description: Invalid request content: application/json: schema: type: object properties: message: type: string '424': description: Action http error content: application/json: schema: type: object required: - error properties: error: type: object required: - message - code - payload properties: message: type: string code: type: string payload: type: object upstream: type: object properties: status: type: integer headers: type: object properties: content-type: type: string patternProperties: '^x-rate': type: string body: type: object additionalProperties: true '500': description: Action error content: application/json: schema: type: object required: - error properties: error: type: object required: - message - code - payload properties: message: type: string code: type: string payload: type: object /environments: get: summary: List environments description: List environments in the authenticated account. Optionally filter by an exact environment name. parameters: - name: name in: query required: false description: Exact environment name to find. schema: type: string pattern: '^[a-z0-9_-]+$' maxLength: 255 example: staging responses: '200': description: Successfully listed environments content: application/json: schema: type: object required: - data properties: data: type: array items: type: object required: - id - uuid - name - is_production properties: id: type: integer description: Numeric environment ID. example: 123 uuid: type: string format: uuid description: Environment UUID. Use this in account-level API calls for this environment. example: 123e4567-e89b-12d3-a456-426614174000 name: type: string description: The environment name. example: staging is_production: type: boolean description: Whether the environment is production. '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' post: summary: Create an environment description: Create a new environment requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - name properties: name: type: string description: Environment name. Lowercase letters, digits, hyphens, and underscores only. Max 255 characters. The reserved name `prod` is always treated as production. pattern: '^[a-z0-9_-]+$' maxLength: 255 example: staging is_production: type: boolean description: Whether to mark the environment as production. Defaults to false, except for the reserved name `prod`. callback_url: type: string format: uri description: Custom OAuth callback URL for this environment. hmac_key: type: string description: HMAC key used by the legacy public-key authorization flow. maxLength: 1000 hmac_enabled: type: boolean description: Whether HMAC verification is enabled for the legacy public-key authorization flow. slack_notifications: type: boolean description: Whether Slack notifications are enabled for this environment. otlp_endpoint: type: string description: OpenTelemetry collector endpoint. Requires a plan with OpenTelemetry export. Pass an empty string to set an empty endpoint. otlp_headers: type: array description: Headers sent with OpenTelemetry export requests. Requires a plan with OpenTelemetry export. Maximum 100 headers. maxItems: 100 items: type: object additionalProperties: false required: - name - value properties: name: type: string minLength: 1 maxLength: 256 value: type: string minLength: 1 maxLength: 4000 responses: '200': description: Successfully created an environment content: application/json: schema: type: object required: - data properties: data: type: object required: - id - uuid - name properties: id: type: integer description: Numeric environment ID. example: 123 uuid: type: string format: uuid description: Environment UUID. Use this in later account-level API calls. example: 123e4567-e89b-12d3-a456-426614174000 name: type: string description: The environment name. example: staging '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: An environment with this name already exists. content: application/json: schema: $ref: '#/components/schemas/StdError' '500': $ref: '#/components/responses/ServerError' /environments/{environmentUuid}: delete: summary: Delete an environment description: Delete an environment parameters: - name: environmentUuid in: path required: true schema: type: string format: uuid description: Environment UUID returned when the environment was created. responses: '204': description: Successfully deleted the environment '400': description: Cannot delete the reserved `prod` environment. content: application/json: schema: $ref: '#/components/schemas/StdError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /environments/{environmentUuid}/api-keys: get: summary: List environment API keys description: Returns a list of Environment API keys in an environment. parameters: - name: environmentUuid in: path required: true description: Environment UUID that owns the keys. schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 - name: display_name in: query required: false description: Exact API-key display name to find. schema: type: string minLength: 1 maxLength: 255 example: provisioned-ci responses: '200': description: Successfully listed Environment API keys content: application/json: schema: type: object required: - data properties: data: type: array items: type: object required: - id - uuid - display_name - scopes - last_used_at - created_at properties: id: type: integer description: Numeric API-key ID. example: 456 uuid: type: string format: uuid description: API-key UUID. example: 123e4567-e89b-12d3-a456-426614174001 display_name: type: string example: provisioned-ci scopes: type: array items: type: string last_used_at: type: [string, 'null'] format: date-time created_at: type: string format: date-time '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' post: summary: Create an environment API key description: Create a new environment API key parameters: - name: environmentUuid in: path required: true description: Environment UUID that will own the key. schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - display_name properties: display_name: type: string description: Display name for the key. Must be unique within the environment. minLength: 1 maxLength: 255 example: provisioned-ci scopes: type: array minItems: 1 items: type: string description: Environment scopes to grant the key, such as `environment:deploy` or `environment:*`. Defaults to `environment:*` (full access). example: - environment:deploy responses: '200': description: Successfully created an Environment API key content: application/json: schema: type: object required: - data properties: data: type: object required: - id - uuid - display_name - scopes - secret - created_at properties: id: type: integer description: Numeric key ID. example: 456 uuid: type: string format: uuid description: API key UUID. Use this to delete the key later. example: 123e4567-e89b-12d3-a456-426614174001 display_name: type: string example: provisioned-ci scopes: type: array items: type: string description: Scopes granted to the key. `environment:*` when no scopes were specified. example: - environment:deploy secret: type: string description: The API key secret. Store it now; it is not returned again. created_at: type: string format: date-time '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: A key with this display name already exists in the environment. content: application/json: schema: $ref: '#/components/schemas/StdError' '500': $ref: '#/components/responses/ServerError' /environments/{environmentUuid}/api-keys/{keyUuid}: get: summary: Get an environment API key description: Retrieve an Environment API key, including its secret. parameters: - name: environmentUuid in: path required: true description: Environment UUID that owns the key. schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 - name: keyUuid in: path required: true description: API-key UUID. schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174001 responses: '200': description: Successfully retrieved the Environment API key content: application/json: schema: type: object required: - data properties: data: type: object required: - id - uuid - display_name - scopes - secret - last_used_at - created_at properties: id: type: integer example: 456 uuid: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174001 display_name: type: string example: provisioned-ci scopes: type: array items: type: string secret: type: string description: The Environment API-key secret. last_used_at: type: [string, 'null'] format: date-time created_at: type: string format: date-time '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' patch: summary: Update an environment API key description: Change the display name and/or scopes of an Environment API key. Requires an Account API key with the `account:environments:api_keys:update` scope. parameters: - name: environmentUuid in: path required: true description: Environment UUID that owns the key. schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 - name: keyUuid in: path required: true description: API-key UUID. schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174001 requestBody: required: true content: application/json: schema: type: object additionalProperties: false minProperties: 1 properties: display_name: type: string description: New display name for the key. Must be unique within the environment. minLength: 1 maxLength: 255 example: provisioned-ci scopes: type: array minItems: 1 items: type: string description: Environment scopes that replace the key's current scopes, such as `environment:deploy` or `environment:*`. example: - environment:deploy responses: '200': description: Successfully updated the Environment API key content: application/json: schema: type: object required: - data properties: data: type: object required: - id - uuid - display_name - scopes - last_used_at - created_at properties: id: type: integer example: 456 uuid: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174001 display_name: type: string example: provisioned-ci scopes: type: array items: type: string example: - environment:deploy last_used_at: type: [string, 'null'] format: date-time created_at: type: string format: date-time '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: A key with this display name already exists in the environment. content: application/json: schema: $ref: '#/components/schemas/StdError' '500': $ref: '#/components/responses/ServerError' delete: summary: Delete an environment API key description: Delete an environment API key parameters: - name: environmentUuid in: path required: true description: Environment UUID that owns the key. schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 - name: keyUuid in: path required: true description: API key UUID returned when the key was created. schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174001 responses: '200': description: Successfully deleted the Environment API key content: application/json: schema: type: object required: - success properties: success: type: boolean example: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/ServerError' /environment-variables: get: summary: Get environment variables 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...' /environment/webhook-signing-key/rotate: post: summary: Rotate the webhook signing key description: | Replace the key Nango signs its webhooks with. The previous key stops being used within 5 minutes, so verify against both during that window. Requires the `environment:webhook_signing_key:rotate` scope. responses: '200': description: The new webhook signing key content: application/json: schema: type: object required: - data properties: data: type: object required: - webhook_signing_key properties: webhook_signing_key: type: string description: The new webhook signing key example: '5f1c0d2e-6a1b-4f3c-9d8e-7b6a5c4d3e2f' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: The environment has more than one webhook signing key and cannot be rotated automatically. content: application/json: schema: $ref: '#/components/schemas/StdError' '500': $ref: '#/components/responses/ServerError' /proxy/{anyPath}: get: summary: Proxy GET request 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: summary: Proxy POST request 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: summary: Proxy PUT request 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: summary: Proxy PATCH request 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: summary: Proxy DELETE request 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: summary: Create connect session description: Create a new connect session requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectSessionInput' responses: '201': description: Successfully created 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' /connect/sessions/reconnect: post: summary: Reconnect with connect session description: | Create a new connect session to reconnect to a specific integration. The token is used like a standard connect session. Only connections created with a connect session are compatible with this endpoint. Use this method when a user needs to input new credentials or to manually refresh token. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConnectSessionReconnectInput' responses: '201': description: Successfully created 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' /connect/session: get: summary: Get connect session 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: summary: Delete connect session 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: securitySchemes: bearerAuth: type: http scheme: bearer description: An Environment API key from your Nango environment, or an Account API key for account-level endpoints. 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' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/StdError' ServerError: description: Server error content: application/json: schema: $ref: '#/components/schemas/StdError' ServiceUnavailable: description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/StdError' GatewayTimeout: description: Gateway timeout 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 RunnableFunctionType: type: string enum: [action, sync] FunctionAvailability: type: object description: 'Availability metadata attached to a listed function. Catalog actions have `id: null`, `last_deployed: null`, `enabled: true`, and `source: tools-catalog`. Deployed functions have an id and a `last_deployed` timestamp.' required: - id - enabled - last_deployed - source properties: id: type: [number, 'null'] description: Sync-config id. `null` for a Nango catalog action. enabled: type: boolean description: Whether the function is enabled. Always `true` for actions, including a deployed action whose stored configuration is disabled. Syncs and on-event functions report the stored value. last_deployed: type: [string, 'null'] format: date-time description: ISO-8601 timestamp. `null` for a Nango catalog action. source: type: string enum: [catalog, standalone, repo, tools-catalog] description: '`tools-catalog` is a Nango catalog action that has not been deployed. `catalog`, `standalone`, and `repo` are deployed functions.' NangoSyncFunction: type: object required: - name - type - returns - json_schema - runs - auto_start - track_deletes properties: name: type: string description: type: string scopes: type: array items: type: string type: type: string enum: [sync] input: type: string returns: type: array items: type: string json_schema: type: [object, 'null'] runs: type: [string, 'null'] description: Schedule expression, e.g. `every day`. auto_start: type: boolean track_deletes: type: boolean NangoActionFunction: type: object required: - name - type - returns - json_schema properties: name: type: string description: type: string scopes: type: array items: type: string type: type: string enum: [action] input: type: string returns: type: array items: type: string json_schema: type: [object, 'null'] NangoOnEventFunction: type: object required: - name - type - event properties: name: type: string description: type: string scopes: type: array items: type: string type: type: string enum: [on-event] event: type: string enum: [post-connection-creation, pre-connection-deletion, validate-connection] ProviderTemplateFunction: description: A sync or action template function from the provider catalog (no deployment metadata). oneOf: - $ref: '#/components/schemas/NangoSyncFunction' - $ref: '#/components/schemas/NangoActionFunction' ListedNangoFunction: description: A listed function (sync, action, or on-event) merged with its availability metadata. oneOf: - allOf: - $ref: '#/components/schemas/NangoSyncFunction' - $ref: '#/components/schemas/FunctionAvailability' - allOf: - $ref: '#/components/schemas/NangoActionFunction' - $ref: '#/components/schemas/FunctionAvailability' - allOf: - $ref: '#/components/schemas/NangoOnEventFunction' - $ref: '#/components/schemas/FunctionAvailability' FunctionCompileRequest: type: object additionalProperties: false required: - code properties: code: type: string minLength: 1 description: The TypeScript source code for the function. FunctionCompileResponse: type: object additionalProperties: false required: - bundle_size_bytes - bundled_js - compiled_at properties: bundle_size_bytes: type: integer minimum: 0 bundled_js: type: string description: The bundled JavaScript output. compiled_at: type: string format: date-time FunctionDryrunRequest: type: object additionalProperties: false required: - integration_id - function_type - code - connection_id properties: integration_id: type: string description: The integration ID (unique_key) that you created in Nango. function_type: $ref: '#/components/schemas/RunnableFunctionType' code: type: string minLength: 1 description: The TypeScript source code for the function. connection_id: type: string description: The connection ID to use for the dry run. input: description: Optional JSON input payload passed to the function. metadata: type: object additionalProperties: true description: Optional metadata available to the function during the dry run. checkpoint: type: object additionalProperties: true description: Optional checkpoint payload available to sync functions during the dry run. last_sync_date: type: string format: date-time description: Optional last sync date available to sync functions during the dry run. FunctionDryrunStatus: type: string enum: [waiting, running, success, failed] FunctionDryrunCreateResponse: type: object additionalProperties: false required: - id - status - created_at properties: id: type: string format: uuid status: type: string enum: [waiting, running] created_at: type: string format: date-time FunctionDryrunResponse: type: object additionalProperties: false required: - id - status - integration_id - function_type - created_at - updated_at properties: id: type: string format: uuid status: $ref: '#/components/schemas/FunctionDryrunStatus' integration_id: type: string function_type: $ref: '#/components/schemas/RunnableFunctionType' created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: string format: date-time completed_at: type: string format: date-time duration_ms: type: integer minimum: 0 output: type: string description: Dry run command output. result: description: The function result, when the dry run emits one. error: type: object additionalProperties: false required: - code - message properties: code: type: string message: type: string payload: description: Optional error payload. FunctionDeploymentRequest: oneOf: - $ref: '#/components/schemas/FunctionDeploymentCodeRequest' - $ref: '#/components/schemas/FunctionDeploymentTemplateRequest' discriminator: propertyName: type mapping: function: '#/components/schemas/FunctionDeploymentCodeRequest' template: '#/components/schemas/FunctionDeploymentTemplateRequest' FunctionDeploymentCodeRequest: type: object additionalProperties: false required: - type - integration_id - function_name - function_type - code properties: type: type: string enum: [function] description: Deploy submitted function source code. integration_id: type: string description: The integration ID (unique_key) that you created in Nango. function_name: type: string description: The sync or action function name. function_type: $ref: '#/components/schemas/RunnableFunctionType' code: type: string minLength: 1 description: The TypeScript source code for the function. version: type: string description: Optional version tag for this deployment. allow_destructive: type: boolean description: Allow overwriting an existing standalone function with the same name. FunctionDeploymentTemplateRequest: type: object additionalProperties: false required: - type - integration_id - template properties: type: type: string enum: [template] description: Deploy a template from the provider catalog onto the integration. integration_id: type: string description: The integration ID (unique_key) that you created in Nango. template: type: string description: The template name to deploy, as listed by `GET /providers/{provider}/templates`. function_type: $ref: '#/components/schemas/RunnableFunctionType' FunctionDeploymentResponse: type: object additionalProperties: false required: - id - status - created_at properties: id: type: string status: type: string enum: [waiting, running, success, failed] description: The status of the function deployment. Poll `GET /functions/deployments/{id}` to get the final status. created_at: type: string format: date-time FunctionDeploymentResultResponse: type: object additionalProperties: false required: - id - status - integration_id - function_name - function_type - created_at - updated_at properties: id: type: string format: uuid status: type: string enum: [waiting, running, success, failed] description: The status of the function deployment. integration_id: type: string description: The integration ID (unique_key) that you created in Nango. function_name: type: string description: The sync or action function name. function_type: $ref: '#/components/schemas/RunnableFunctionType' created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: string format: date-time completed_at: type: string format: date-time duration_ms: type: integer minimum: 0 deployed: type: boolean description: Whether the deployment updated any functions. deployed_functions: type: array items: type: object additionalProperties: false required: - name - version properties: name: type: string version: type: string description: Functions updated by the deployment. output: type: string description: Deployment command output. error: type: object additionalProperties: false required: - code - message properties: code: type: string message: type: string payload: description: Optional error payload. FunctionDeployResponse: type: object additionalProperties: false required: - integration_id - function_name - function_type - deployed - deployed_functions - output properties: integration_id: type: string function_name: type: string function_type: $ref: '#/components/schemas/RunnableFunctionType' deployed: type: boolean deployed_functions: type: array items: type: object additionalProperties: false required: - name - version properties: name: type: string version: type: string output: type: string description: Deployment command output. 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', 'JWT', 'BILL', 'TWO_STEP', 'SIGNATURE', 'INSTALL_PLUGIN' ] 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 pre_connection_deletion_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-time description: When it was created updated_at: type: string format: date-time description: Last time it was updated forward_webhooks: type: boolean description: Whether webhooks received from this integration's provider are forwarded to your backend. missing_fields: type: array items: type: string description: > Credential fields the integration is missing, e.g. `oauth_client_id`. Empty when the integration is fully configured, when it uses Nango-provided credentials, or when the auth mode collects everything at connection time. Field names only, never values. IntegrationFull: allOf: - $ref: '#/components/schemas/Integration' - type: object additionalProperties: false properties: webhook_url: anyOf: - type: string - type: 'null' description: Configure your integration webhooks to point to this URL credentials: anyOf: - $ref: '#/components/schemas/IntegrationCredentialsWithConfig' - type: 'null' ConnectSessionInput: type: object properties: tags: $ref: '#/components/schemas/Tags' end_user: allOf: - $ref: '#/components/schemas/EndUser' deprecated: true description: Deprecated, use tags instead organization: type: object deprecated: true description: Deprecated, use tags instead required: - id 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) authorization_params: type: object description: Query params passed to the OAuth flow (for OAuth2 only) additionalProperties: true connection_config: type: object additionalProperties: true properties: oauth_scopes_override: type: string description: Override oauth scopes oauth_client_id_override: type: string description: Set to empty string to allow end-users to provide their own OAuth client ID in Connect UI oauth_client_secret_override: type: string description: Set to empty string to allow end-users to provide their own OAuth client secret in Connect UI overrides: type: object additionalProperties: type: object description: The unique name of an integration additionalProperties: false properties: docs_connect: type: string description: Override the url of the docs we point to in the connect flow webhook_url_override: type: string description: Override the environment's webhook URLs for the connection created by this session. When set, that connection's webhooks are sent only to this URL (the environment's primary and secondary URLs are bypassed). ConnectSessionReconnectInput: type: object required: - connection_id - integration_id properties: connection_id: type: string integration_id: type: string tags: $ref: '#/components/schemas/ConnectSessionInput/properties/tags' end_user: $ref: '#/components/schemas/ConnectSessionInput/properties/end_user' organization: $ref: '#/components/schemas/ConnectSessionInput/properties/organization' integrations_config_defaults: $ref: '#/components/schemas/ConnectSessionInput/properties/integrations_config_defaults' overrides: $ref: '#/components/schemas/ConnectSessionInput/properties/overrides' webhook_url_override: $ref: '#/components/schemas/ConnectSessionInput/properties/webhook_url_override' ConnectSession: type: object required: - token - expires_at properties: token: type: string description: The connect session token connect_link: type: string description: The URL to directly connect the user to the integration. This can be used as a magic link. expires_at: type: string description: When the token expires format: date-time AllAuthCredentials: anyOf: - $ref: '#/components/schemas/OAuth1CredentialsWithRaw' - $ref: '#/components/schemas/OAuth2CredentialsWithRaw' - $ref: '#/components/schemas/BasicApiCredentials' - $ref: '#/components/schemas/ApiKeyCredentials' - $ref: '#/components/schemas/AppCredentials' - $ref: '#/components/schemas/JwtCredentials' - $ref: '#/components/schemas/OAuth2ClientCredentialsWithRaw' - $ref: '#/components/schemas/AppStoreCredentialsWithRaw' - $ref: '#/components/schemas/UnauthCredentials' - $ref: '#/components/schemas/CustomCredentials' - $ref: '#/components/schemas/TbaCredentials' - $ref: '#/components/schemas/BillCredentialsWithRaw' - $ref: '#/components/schemas/TwoStepCredentials' - $ref: '#/components/schemas/SignatureCredentials' ## ---------------------- Credentials ApiKeyCredentials: type: object title: Api Key additionalProperties: false properties: apiKey: type: string type: type: string enum: [API_KEY] required: - type - apiKey AppCredentials: type: object title: GitHub App additionalProperties: false properties: access_token: type: string expires_at: format: date-time type: string raw: type: object type: type: string enum: [APP] required: - type - access_token - raw AppStoreCredentials: type: object title: App Store additionalProperties: false properties: access_token: type: string expires_at: type: string format: date-time private_key: type: string type: type: string enum: [APP_STORE] required: - access_token - private_key AppStoreCredentialsWithRaw: title: App Store allOf: - $ref: '#/components/schemas/AppStoreCredentials' - type: object additionalProperties: false required: - raw properties: raw: type: object BasicApiCredentials: type: object title: Basic Auth additionalProperties: false properties: password: type: string type: enum: [BASIC] type: string username: type: string required: - type - username - password BillCredentials: type: object title: Bill additionalProperties: false properties: dev_key: type: string expires_at: type: string format: date-time organization_id: type: string password: type: string session_id: type: string type: type: string enum: [BILL] user_id: type: string username: type: string required: - dev_key - organization_id - password - raw - type - username BillCredentialsWithRaw: title: Bill allOf: - $ref: '#/components/schemas/BillCredentials' - type: object additionalProperties: false required: - raw properties: raw: type: object CustomCredentials: type: object title: Custom additionalProperties: false properties: raw: type: object type: type: string enum: [CUSTOM] required: - raw - type JwtCredentials: type: object title: JWT additionalProperties: false properties: expires_at: format: date-time type: string issuerId: type: string privateKey: anyOf: - additionalProperties: false properties: id: type: string secret: type: string required: - id - secret type: object - type: string privateKeyId: type: string token: type: string type: type: string enum: [JWT] required: - type - privateKey OAuth1Credentials: type: object title: OAuth1 additionalProperties: false properties: oauth_token: type: string oauth_token_secret: type: string type: type: string enum: [OAUTH1] required: - oauth_token - oauth_token_secret - type OAuth1CredentialsWithRaw: title: OAuth1 allOf: - $ref: '#/components/schemas/OAuth1Credentials' - type: object additionalProperties: false required: - raw properties: raw: type: object OAuth2ClientCredentials: type: object title: OAuth2 Client additionalProperties: false properties: client_id: type: string client_secret: type: string expires_at: type: string format: date-time token: type: string type: type: string enum: [OAUTH2_CC] required: - client_id - client_secret - token - type OAuth2ClientCredentialsWithRaw: title: OAuth2 Client allOf: - $ref: '#/components/schemas/OAuth2ClientCredentials' - type: object additionalProperties: false required: - raw properties: raw: type: object OAuth2Credentials: type: object title: OAuth2 additionalProperties: false properties: access_token: type: string config_override: additionalProperties: false properties: client_id: type: string client_secret: type: string type: object expires_at: format: date-time type: string refresh_token: type: string type: enum: [OAUTH2] type: string required: - access_token - type OAuth2CredentialsWithRaw: title: OAuth2 allOf: - $ref: '#/components/schemas/OAuth2Credentials' - type: object additionalProperties: false required: - raw properties: raw: type: object SignatureCredentials: type: object title: Signature additionalProperties: false properties: expires_at: type: string format: date-time password: type: string token: type: string type: type: string enum: [SIGNATURE] username: type: string required: - type - username - password TbaCredentials: type: object title: TBA additionalProperties: false properties: config_override: additionalProperties: false properties: client_id: type: string client_secret: type: string type: object token_id: type: string token_secret: type: string type: type: string enum: [TBA] required: - type - token_id - token_secret - config_override TwoStepCredentials: type: object title: Two Step additionalProperties: false properties: expires_at: format: date-time type: string raw: type: object token: type: string type: type: string enum: [TWO_STEP] required: - raw - type UnauthCredentials: type: object title: Unauthenticated additionalProperties: false UnauthCredentialsWithType: type: object title: Unauthenticated additionalProperties: false required: - type properties: type: type: string enum: [NONE] ## ---------------------- Connection Tags: type: object description: Connection tags (key/value strings). Keys are normalized to lowercase. maxProperties: 10 additionalProperties: type: string maxLength: 255 ConnectionEndUser: type: object deprecated: true required: - id properties: id: type: string description: Uniquely identifies the end user. deprecated: true email: anyOf: - type: string - type: 'null' deprecated: true display_name: anyOf: - type: string - type: 'null' deprecated: true tags: type: object additionalProperties: true description: Tags associated with the end user. Only accepts strings values, up to 64 keys. deprecated: true organization: deprecated: true anyOf: - type: object required: - id properties: id: type: string description: Uniquely identifies the organization the end user belongs to display_name: anyOf: - type: string - type: 'null' - type: 'null' EndUser: type: object deprecated: true required: - id properties: id: type: string description: Uniquely identifies the end user. deprecated: true email: type: string deprecated: true display_name: type: string deprecated: true tags: type: object additionalProperties: type: string maxLength: 64 description: Tags associated with the end user. Only accepts strings values, up to 64 keys. deprecated: true ConnectionError: type: object required: - type - log_id properties: type: type: string enum: [auth, sync] example: auth log_id: type: string example: VrnbtykXJFckCm3HP93t ConnectionFull: type: object required: - id - connection_id - provider_config_key - provider - errors - metadata - connection_config - tags - created_at - updated_at - last_fetched_at - credentials properties: id: type: integer connection_id: type: string provider_config_key: type: string provider: type: string errors: type: array items: $ref: '#/components/schemas/ConnectionError' end_user: deprecated: true anyOf: - $ref: '#/components/schemas/ConnectionEndUser' - type: 'null' metadata: type: object additionalProperties: true connection_config: type: object additionalProperties: true tags: $ref: '#/components/schemas/Tags' created_at: type: string updated_at: type: string last_fetched_at: type: string credentials: $ref: '#/components/schemas/AllAuthCredentials' ## -------- Yaml NangoModel: type: object additionalProperties: false properties: fields: type: array items: $ref: '#/components/schemas/NangoModelField' isAnon: type: boolean name: type: string required: - name - fields NangoModelField: type: object additionalProperties: false required: - name - value properties: array: type: boolean dynamic: type: boolean model: type: boolean name: type: string optional: type: boolean tsType: type: boolean union: type: boolean value: anyOf: - type: string - type: number - type: boolean - items: type: array $ref: '#/components/schemas/NangoModelField' IntegrationCredentials: description: Integration credentials schema for different authentication types, as returned in API responses (fields may be null). oneOf: - type: object required: - type - client_id - client_secret properties: type: type: string enum: - OAUTH1 - OAUTH2 - TBA client_id: type: string minLength: 1 maxLength: 255 client_secret: type: string minLength: 1 scopes: anyOf: - type: string pattern: '^[0-9a-zA-Z:/_.-]+(,[0-9a-zA-Z:/_.-]+)*$' - type: 'null' webhook_secret: anyOf: - type: string maxLength: 255 - type: 'null' - type: object required: - type - app_id - app_link - private_key properties: type: type: string enum: - APP app_id: type: string minLength: 1 maxLength: 255 app_link: type: string minLength: 1 private_key: type: string pattern: '^-----BEGIN RSA PRIVATE KEY----.*-----END RSA PRIVATE KEY-----$' - type: object required: - type - client_id - client_secret - app_id - app_link - private_key properties: type: type: string enum: - CUSTOM client_id: type: string minLength: 1 maxLength: 255 client_secret: type: string minLength: 1 app_id: type: string minLength: 1 maxLength: 255 app_link: type: string minLength: 1 private_key: type: string pattern: '^-----BEGIN RSA PRIVATE KEY----.*-----END RSA PRIVATE KEY-----$' - type: object required: - type properties: type: type: string enum: - MCP_OAUTH2_GENERIC client_name: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' client_uri: anyOf: - type: string maxLength: 255 - type: 'null' client_logo_uri: anyOf: - type: string maxLength: 255 - type: 'null' - type: object required: - type properties: type: type: string enum: - MCP_OAUTH2 client_id: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' client_secret: anyOf: - type: string minLength: 1 - type: 'null' scopes: anyOf: - type: string pattern: '^(?:[0-9a-zA-Z:/_.*-]+([, ]+[0-9a-zA-Z:/_.*-]+)*)?$' - type: 'null' IntegrationCredentialsWithConfig: description: > Same as IntegrationCredentials, plus the shape returned for providers that declare an `integration_config` schema (e.g. aws-sigv4, epic, private-api-generic), alongside or instead of fixed credential fields. This variant is response-only -- it can't be submitted on create or update. oneOf: - $ref: '#/components/schemas/IntegrationCredentials' - type: object required: - type - auth_mode - integration_config properties: type: type: string enum: - INTEGRATION_CONFIG auth_mode: type: string description: The provider's actual auth mode (e.g. AWS_SIGV4, TWO_STEP, API_KEY). integration_config: type: object additionalProperties: type: string description: The provider's `integration_config` values, keyed by the fields it declares. IntegrationCredentialsInput: description: > Integration credentials schema accepted in create/update request bodies. Only `type` is required: developer app credentials can be omitted at creation and supplied later, either with an update request or per connection at connection time. Fields left out of an update are kept as-is rather than cleared. MCP_OAUTH2 is the exception — static creation requires both client_id and client_secret, while dynamic and CIMD providers reject those fields because Nango manages them. Optional fields must not be null. oneOf: - type: object required: - type properties: type: type: string enum: - OAUTH1 - OAUTH2 - TBA client_id: type: string minLength: 1 maxLength: 255 client_secret: type: string minLength: 1 scopes: type: string pattern: '^[0-9a-zA-Z:/_.-]+(,[0-9a-zA-Z:/_.-]+)*$' webhook_secret: type: string maxLength: 255 - type: object required: - type properties: type: type: string enum: - APP app_id: type: string minLength: 1 maxLength: 255 app_link: type: string minLength: 1 private_key: type: string pattern: '^-----BEGIN RSA PRIVATE KEY----.*-----END RSA PRIVATE KEY-----$' - type: object required: - type properties: type: type: string enum: - CUSTOM client_id: type: string minLength: 1 maxLength: 255 client_secret: type: string minLength: 1 app_id: type: string minLength: 1 maxLength: 255 app_link: type: string minLength: 1 private_key: type: string pattern: '^-----BEGIN RSA PRIVATE KEY----.*-----END RSA PRIVATE KEY-----$' - type: object required: - type properties: type: type: string enum: - MCP_OAUTH2_GENERIC client_name: type: string minLength: 1 maxLength: 255 client_uri: type: string maxLength: 255 client_logo_uri: type: string maxLength: 255 - type: object required: - type properties: type: type: string enum: - MCP_OAUTH2 client_id: type: string minLength: 1 maxLength: 255 client_secret: type: string minLength: 1 scopes: type: string pattern: '^(?:[0-9a-zA-Z:/_.*-]+([, ]+[0-9a-zA-Z:/_.*-]+)*)?$'