nango.yaml
file, which lives in your code base.
Example
nango.yaml
Integrations fields
Integration configuration fields are underintegrations.<INTEGRATION-ID>
.
Lists the syncs for a given integration.
Lists the actions for a given integration.
Lists the events and functions executed when those events occur.
Sync fields
Sync configuration fields are underintegrations.<INTEGRATION-ID>.syncs.<SYNC-NAME>
.
Describes the sync.
Defines the schema of the data you want to sync. References a schema from the Models section of this configuration file.Each sync has a corresponding generated endpoint to fetch the data, configured in the
endpoint
field below.Syncs can have multiple output models. This is useful when there is some form of dependency between the two models, e.g.
- Fetching the data for a model from the external API requires fetching the data from another model first
- You want the records of one model to be persisted before the records of another model
Defines the endpoint to use to fetch the output model.Possible method values are:
GET
The method/endpoint combination can be shared across syncs to unify the communication with external APIs.
The group
is an optional value to group endpoints across functions.Legacy format: <METHOD> <URL-PATH>
. e.g.: GET /tasks
.Specifies whether each sync execution replaces all of the data (
full
) or upserts it (incremental
).Learn more about incremental vs. full refresh syncing.Defines the schema of the data required to run the sync. References a schema from the models.Sync inputs are passed from your app to the sync function via the connection metadata.
Lists the necessary scopes to execute the sync.This list is just indicative; it doesn’t trigger any automatic configuration (yet). List necessary scopes on the external API developer portal and your Nango UI integration settings.Defaults to no scope.
If
true
, automatically starts synchronizing between the external API and Nango when a new connection is created. Otherwise, it needs to be triggered via the API or Nango UI.Defaults to true
.When
track_deletes
is set to true
, Nango automatically detects deleted records during full syncs only and marks them as deleted in each record’s metadata (soft delete). These records remain stored in the cache.When set to false
, Nango does not mark missing records as deleted, even if they weren’t returned in the latest full sync—they simply remain in the cache unchanged.Defaults to false
.Follow this guide to add support for deletion detection to your syncs.This setting only applies if
sync_type: full
. For incremental syncs, this setting is ignored; instead, you must flag deleted records in the sync function using nango.batchDelete()
(reference).Lists the types of external webhooks the sync function will handle. Multiple syncs can listen to the same subscription. Learn more about handling external webhooks in syncs.
Action fields
Action configuration fields are underintegrations.<INTEGRATION-ID>.actions.<ACTION-NAME>
.
Describes the action.
Defines the schema of the data returned by the action. References a schema from the models section of this configuration file.Each action has a corresponding generated endpoint to trigger it, configured in the
endpoint
field below.Defines the endpoint to use to trigger the action.Possible method values are:
GET
, POST
, PUT
, PATCH
, DELETE
.The method/endpoint combination can be shared across actions to unify the communication with external APIs.
The group
is an optional value to group endpoints across functions.Legacy format: <METHOD> <URL-PATH>
. e.g.: POST /tasks
.Defines the schema of the data required to trigger the action. References a schema from the Models.Action inputs are passed as parameters when triggering the action.
Lists the necessary scopes to trigger the action.This list is just indicative; it doesn’t trigger any automatic configuration (yet). List necessary scopes on the external API developer portal and your Nango UI integration settings.Defaults to no scope.
On-events fields
on-events
configuration fields are under integrations.<INTEGRATION-ID>.on-events.<EVENT-NAME>
.
Nango currently supports the following events:
- post-connection-creation
- pre-connection-deletion
Lists the functions to execute after a new connection is created.Example:
Lists the functions to execute before a connection is deleted.Example:
Basic types
For each model, you must define its fields and data types. Data types are based on Typescript types, with some tweaks:nango.yaml type | Corresponding Typescript type |
---|---|
bool or boolean | boolean |
string | string |
char or varchar | string |
integer or int or number or bigint or float | number |
date | Date |
null | null |
undefined | undefined |
any | any |
array | any[] |
object | object |
true or false | true orfalse |
Arrays
Your can use array types like this:nango.yaml
Type & string unions
You can use union types such as:nango.yaml
nango.yaml
nango.yaml
When you use the
|
notation, we check each element against known Typescript types, to categorize it as type (if match) or string (if no match).Union array
Your can create a union array:nango.yaml
Reference other models
Your can use other models as types:nango.yaml
Extend types
You can have a model extend the properties of another base model:nango.yaml
Dynamic field keys
You can allow dynamic keys in models:nango.yaml
Optional property
You can set a property as optional:nango.yaml
Unsupported syntax
A non-exhaustive list of unsupported syntax:nango.yaml
Deploying your configuration
Changes to your integration configuration become active once you deploy them to a Nango environment using thenango deploy
CLI command.
These changes can have significant impacts, in particular, if you:
- Add a sync
- Remove a sync or an action
- Change a model or an integration script
Adding a sync
Unless you sync configuration specifiesautoStart: false
, the deployment will kick off the data synchronization between the external API and Nango, for all relevant connections.
This change will be reflected in the Nango UI in Integrations > select your integration > Endpoints tab.
Removing a sync
Removing a sync will erase all the cached data related to that sync, for all relevant connections. The synced records will no longer be accessive via the Nango API & SDKs. This change will be reflected in the Nango UI in Integrations > select your integration > Endpoints tab.Changing the integration ID in your configuration is the equivalent of deleting the sync with the old integration ID, and creating a new one. So, the data cached by the old sync will be deleted (for all relevant connections).
Removing an action
Removing an action will cause the failure of any request to trigger this action. This change will be reflected in the Nango UI in Integrations > select your integration > Endpoints tab.Changing a model or script
For full refresh syncs, as the data is replaced on each sync execution, the new model and script logic will apply to all records as soon as the sync executes following the deployment. For incremental syncs, you can end up with model disparities, as older records will have outdated content. You will still be able to fetch them from the Nango cache. In some cases, it’s better to trigger a full resync via the API or the Nango UI, so that all historical records are fetched again using the new script & model.Changing a model name in your configuration is the equivalent of deleting the model with the old name, and creating a new one.
Questions, problems, feedback? Please reach out in the Slack community.