> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/api/dataflows.md).
# Dataflows
## Create Dataflow Dataset
> Adds a custom SQL dataset to the dataflow.\
> \
> \`type\` is \`customSql\`. \`query\` is the SQL statement and is checked\
> before the dataset is saved. \`name\` is optional. An invalid query\
> returns 422. A failure while storing the query preview returns 502.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows/{dataflow_id}/datasets":{"post":{"summary":"Create Dataflow Dataset","tags":["Dataflows"],"description":"Adds a custom SQL dataset to the dataflow.\n\n`type` is `customSql`. `query` is the SQL statement and is checked\nbefore the dataset is saved. `name` is optional. An invalid query\nreturns 422. A failure while storing the query preview returns 502.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"dataflow_id","in":"path","required":true,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"responses":{"201":{"description":"dataset created","content":{"application/json":{}}},"400":{"description":"type must be customSql","content":{"application/json":{}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"422":{"description":"query is invalid","content":{"application/json":{}}},"502":{"description":"query preview could not be stored","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["customSql"],"description":"Dataset type. customSql is supported."},"query":{"type":"string","description":"SQL statement. Quote source table names from the dataflow."},"name":{"type":["string","null"],"description":"Dataset name. Omit it to use the default name."}},"required":["type","query"]}}}}}}}}
```
## Create Dataflow Destination
> Adds a destination to the dataflow.\
> \
> \`integration\_key\` is the destination integration, for example\
> \`google\_spreadsheet\`. Use a key from GET /v1/integrations/destinations.\
> \`credential\_id\` connects a credential the user can access. A credential\_id\
> that does not exist or does not match the integration returns 422. \`params\`\
> are the integration fields. Fields the integration does not list are\
> ignored.\
> \
> \`params\_configured\` is true when every required field is set.\
> \`params\_remaining\_errors\` lists fields that are still required.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows/{dataflow_id}/destinations":{"post":{"summary":"Create Dataflow Destination","tags":["Dataflows"],"description":"Adds a destination to the dataflow.\n\n`integration_key` is the destination integration, for example\n`google_spreadsheet`. Use a key from GET /v1/integrations/destinations.\n`credential_id` connects a credential the user can access. A credential_id\nthat does not exist or does not match the integration returns 422. `params`\nare the integration fields. Fields the integration does not list are\nignored.\n\n`params_configured` is true when every required field is set.\n`params_remaining_errors` lists fields that are still required.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"dataflow_id","in":"path","required":true,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"responses":{"201":{"description":"destination created","content":{"application/json":{}}},"400":{"description":"missing integration key","content":{"application/json":{}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataflow was not found","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"integration_key":{"type":"string","description":"Destination integration key."},"credential_id":{"type":"integer","description":"Id of a destination credential. Omit it to leave the destination unconnected."},"params":{"type":"object","description":"Integration fields, such as a sheet name."}},"required":["integration_key"]}}}}}}}}
```
## Create Dataflow Source
> Adds a source to the dataflow.\
> \
> \`integration\_key\` is the source integration, for example \`csv\` or\
> \`gsheet\`. Use a key from GET /v1/integrations/sources.\
> \`credential\_id\` connects a credential the user can access. A credential\_id\
> that does not exist or does not match the integration returns 422. \`params\` are\
> the integration fields. Fields the integration does not list are ignored.\
> Hidden fields are stored and omitted from the response.\
> \
> \`params\_configured\` is true when every required field is set.\
> \`params\_remaining\_errors\` lists fields that are still required.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows/{dataflow_id}/sources":{"post":{"summary":"Create Dataflow Source","tags":["Dataflows"],"description":"Adds a source to the dataflow.\n\n`integration_key` is the source integration, for example `csv` or\n`gsheet`. Use a key from GET /v1/integrations/sources.\n`credential_id` connects a credential the user can access. A credential_id\nthat does not exist or does not match the integration returns 422. `params` are\nthe integration fields. Fields the integration does not list are ignored.\nHidden fields are stored and omitted from the response.\n\n`params_configured` is true when every required field is set.\n`params_remaining_errors` lists fields that are still required.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"dataflow_id","in":"path","required":true,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"responses":{"201":{"description":"source created","content":{"application/json":{}}},"400":{"description":"missing integration key","content":{"application/json":{}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataflow was not found","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"integration_key":{"type":"string","description":"Source integration key."},"credential_id":{"type":"integer","description":"Id of a source credential. Omit it to create the source unconnected."},"params":{"type":"object","description":"Integration fields, such as a file URL."}},"required":["integration_key"]}}}}}}}}
```
## Get Dataflow
> Returns one dataflow.\
> \
> \`id\` is the dataflow id from GET /v1/workspaces/{workspace\_id}/dataflows.\
> \`schedule\` is the cron expression, or null when the dataflow is not\
> scheduled. \`sources\` lists each source on the dataflow.\
> \`last\_successful\_execution\_id\` is null when the dataflow has not run\
> successfully.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"dataflows.show.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the dataflow."},"name":{"type":"string","description":"Name of the dataflow."},"last_successful_execution_id":{"type":["string","null"],"description":"Id of the last successful execution. Null when the dataflow has not run successfully."},"schedule":{"type":["string","null"],"description":"Cron expression for the dataflow. Null when it is not scheduled."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/sources.item.response"}}},"required":["id","name","last_successful_execution_id","schedule","sources"]},"sources.item.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"type":{"type":"string"},"enabled":{"type":"boolean"},"lifecycle_state":{"type":"string","enum":["active","paused","disabled"]},"params_configured":{"type":"boolean"},"data_connections_count":{"type":"integer"},"last_success_run_at":{"type":["string","null"]},"error_details":{"type":["object","null"]}},"required":["id","name","type","enabled","lifecycle_state"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows/{id}":{"get":{"summary":"Get Dataflow","tags":["Dataflows"],"description":"Returns one dataflow.\n\n`id` is the dataflow id from GET /v1/workspaces/{workspace_id}/dataflows.\n`schedule` is the cron expression, or null when the dataflow is not\nscheduled. `sources` lists each source on the dataflow.\n`last_successful_execution_id` is null when the dataflow has not run\nsuccessfully.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"responses":{"200":{"description":"dataflow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dataflows.show.response"}}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataflow was not found","content":{"application/json":{}}}}}}}}
```
## Update Dataflow
> Updates the dataflow name, its schedule, or both.\
> \
> Send \`name\`, \`schedule\_config\`, or both. With no attributes, the\
> dataflow is returned unchanged. \`schedule\_config.interval\` sets the\
> cadence. Re-enabling a schedule without \`interval\` resumes the previous\
> cron. An interval the billing plan does not include returns 422 and\
> names the intervals the plan allows.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows/{id}":{"patch":{"summary":"Update Dataflow","tags":["Dataflows"],"description":"Updates the dataflow name, its schedule, or both.\n\nSend `name`, `schedule_config`, or both. With no attributes, the\ndataflow is returned unchanged. `schedule_config.interval` sets the\ncadence. Re-enabling a schedule without `interval` resumes the previous\ncron. An interval the billing plan does not include returns 422 and\nnames the intervals the plan allows.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"responses":{"200":{"description":"dataflow updated","content":{"application/json":{}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataflow was not found","content":{"application/json":{}}},"422":{"description":"schedule is not valid for the billing plan","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Provide a name and/or a schedule_config with at least one attribute.","properties":{"name":{"type":"string","description":"New name for the dataflow."},"schedule_config":{"type":"object","description":"Schedule configuration for the dataflow run.","properties":{"enabled":{"type":"boolean","description":"Turn the schedule on or off. With no `interval`, only toggles the existing schedule (re-enabling resumes the last cron)."},"interval":{"type":"string","description":"Schedule interval: quarterHourly, semiHourly, hourly, daily or monthly. Required to set or change the cron."},"week_days":{"type":"array","items":{"type":"integer"},"description":"Days the schedule runs, 0 (Monday) to 6 (Sunday). Used by daily, hourly, semiHourly and quarterHourly."},"month_day":{"type":"integer","description":"Day of month (1-28). Used by monthly."},"time":{"type":"string","description":"24h HH:MM start time. Used by daily and monthly."},"active_hours":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}},"description":"Hour window (0-23). Used by hourly, semiHourly and quarterHourly."},"timezone":{"type":"string","description":"IANA timezone name, e.g. 'America/New_York'. Only valid with a schedule."}}}}}}}}}}}}
```
## List Dataflows
> Lists dataflows in the workspace.\
> \
> Each item includes \`id\`, \`name\`, \`last\_success\_run\_at\`, and\
> \`last\_successful\_execution\_id\`. Pass \`id\` to other dataflow endpoints.\
> \`last\_success\_run\_at\` and \`last\_successful\_execution\_id\` are null when\
> the dataflow has not run successfully.\
> \
> The list contains at most 200 dataflows, most recently successful first.\
> Blank dataflows are omitted.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"public_api.dataflows.collection.response":{"type":"array","items":{"$ref":"#/components/schemas/dataflows.item.response"}},"dataflows.item.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the dataflow. Pass it to other dataflow endpoints."},"name":{"type":"string","description":"Name of the dataflow."},"last_success_run_at":{"type":["string","null"],"description":"Time of the last successful run. Null when the dataflow has not run successfully."},"last_successful_execution_id":{"type":["string","null"],"description":"Id of the last successful execution. Null when the dataflow has not run successfully."}},"required":["id","name","last_success_run_at","last_successful_execution_id"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows":{"get":{"summary":"List Dataflows","tags":["Dataflows"],"description":"Lists dataflows in the workspace.\n\nEach item includes `id`, `name`, `last_success_run_at`, and\n`last_successful_execution_id`. Pass `id` to other dataflow endpoints.\n`last_success_run_at` and `last_successful_execution_id` are null when\nthe dataflow has not run successfully.\n\nThe list contains at most 200 dataflows, most recently successful first.\nBlank dataflows are omitted.\n","responses":{"200":{"description":"dataflows in the workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/public_api.dataflows.collection.response"}}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"the billing plan does not include the public API","content":{"application/json":{}}}},"parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}}]}}}}
```
## Create Dataflow
> Creates a dataflow in the workspace.\
> \
> Send \`name\` to create an empty dataflow. Send \`template\_id\` to copy a\
> template from GET /v1/templates. \`name\` is then optional and, when sent,\
> replaces the template name.\
> \
> The response includes \`id\`, \`name\`, and \`url\`. \`url\` opens the dataflow\
> in Coupler.io. \`sources\` and \`destinations\` list what was copied from\
> the template, or are empty when the dataflow was created from a name.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"dataflows.create.response":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id of the new dataflow."},"name":{"type":"string","description":"Name of the dataflow."},"url":{"type":"string","description":"Coupler.io page where the user edits the dataflow."},"sources":{"type":"array","items":{"type":"object"},"description":"Sources on the dataflow. Empty when created from a name."},"destinations":{"type":"array","items":{"type":"object"},"description":"Destinations on the dataflow. Empty when created from a name."}},"required":["id","name","url","sources","destinations"]},"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows":{"post":{"summary":"Create Dataflow","tags":["Dataflows"],"description":"Creates a dataflow in the workspace.\n\nSend `name` to create an empty dataflow. Send `template_id` to copy a\ntemplate from GET /v1/templates. `name` is then optional and, when sent,\nreplaces the template name.\n\nThe response includes `id`, `name`, and `url`. `url` opens the dataflow\nin Coupler.io. `sources` and `destinations` list what was copied from\nthe template, or are empty when the dataflow was created from a name.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}}],"responses":{"201":{"description":"dataflow created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/dataflows.create.response"}}}},"400":{"description":"validation error when name is empty","content":{"application/json":{}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"forbidden when workflow limit exceeded","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name of the dataflow. Required unless `template_id` is sent."},"template_id":{"type":"string","description":"Id of a template from GET /v1/templates. When present, the dataflow is a copy of that template."}}}}}}}}}}
```
## Get Dataflow Setup
> Returns the setup state of one dataflow: schedule, sources,\
> destinations, and the views that can be shared.\
> \
> \`validation\_summary\` is null on this endpoint. A run that cannot start\
> returns that summary from POST /v1/workspaces/{workspace\_id}/dataflows/{dataflow\_id}/executions.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows/{id}/setup":{"get":{"summary":"Get Dataflow Setup","tags":["Dataflows"],"description":"Returns the setup state of one dataflow: schedule, sources,\ndestinations, and the views that can be shared.\n\n`validation_summary` is null on this endpoint. A run that cannot start\nreturns that summary from POST /v1/workspaces/{workspace_id}/dataflows/{dataflow_id}/executions.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"responses":{"200":{"description":"setup state of the dataflow","content":{"application/json":{}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataflow was not found","content":{"application/json":{}}}}}}}}
```
## Execute Dataflow
> Queues a run of the dataflow. The response has no body.\
> \
> \`run\_mode\` is required. \`full\` imports the data. \`preview\` runs a preview.\
> A dataflow that is not ready to run returns 422 with the same setup\
> payload as GET /v1/workspaces/{workspace\_id}/dataflows/{id}/setup, and\
> \`validation\_summary\` explains what is missing.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/dataflows/{dataflow_id}/executions":{"post":{"summary":"Execute Dataflow","tags":["Dataflows"],"description":"Queues a run of the dataflow. The response has no body.\n\n`run_mode` is required. `full` imports the data. `preview` runs a preview.\nA dataflow that is not ready to run returns 422 with the same setup\npayload as GET /v1/workspaces/{workspace_id}/dataflows/{id}/setup, and\n`validation_summary` explains what is missing.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"dataflow_id","in":"path","required":true,"description":"Id of the dataflow. Use an id from GET /v1/workspaces/{workspace_id}/dataflows.","schema":{"type":"string"}}],"responses":{"204":{"description":"dataflow run queued"},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"404":{"description":"dataflow was not found","content":{"application/json":{}}},"422":{"description":"dataflow is not ready to run","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"run_mode":{"type":"string","enum":["full","preview"],"description":"full imports the data. preview runs a preview."}},"required":["run_mode"]}}}}}}}}
```
## Update Destination
> Updates a destination. Only the fields sent are changed.\
> \
> \`params\` merges with the current values. Fields the integration does\
> not list are ignored. Pausing requires a successful run and a billing\
> plan that includes pausing. A destination that has never run\
> successfully cannot be paused.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/destinations/{id}":{"patch":{"summary":"Update Destination","tags":["Dataflows"],"description":"Updates a destination. Only the fields sent are changed.\n\n`params` merges with the current values. Fields the integration does\nnot list are ignored. Pausing requires a successful run and a billing\nplan that includes pausing. A destination that has never run\nsuccessfully cannot be paused.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the destination. Use an id from GET /v1/workspaces/{workspace_id}/dataflows/{id}/setup.","schema":{"type":"string"}}],"responses":{"200":{"description":"destination updated","content":{"application/json":{}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"the user cannot update this dataflow, or the billing plan does not allow pausing","content":{"application/json":{}}},"404":{"description":"destination not found","content":{"application/json":{}}},"422":{"description":"destination params are invalid, or the destination cannot be paused before its first successful run","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Destination name."},"credential_id":{"type":"integer","description":"Id of a destination credential the user can access. An unknown or incompatible id is rejected."},"params":{"type":"object","description":"Integration fields to merge into the current params."},"lifecycle_state":{"type":"string","enum":["active","paused","disabled"],"description":"Refresh state of the destination. 'active' refreshes on the dataflow schedule. 'paused' stops refreshing but keeps the data already collected; it requires at least one successful run and is not available on every billing plan. 'disabled' turns the destination off. Prefer 'paused' over 'disabled' when the user wants to keep the collected data. While a destination stays paused its configuration is read-only, because the stored data is served exactly as it was collected. To change any other field, send 'active' in the same request and both are applied together."}}}}}}}}}}
```
## Update Source
> Updates a source. Only the fields sent are changed. A disabled source\
> stays disabled unless \`enabled\` or \`lifecycle\_state\` is sent.\
> \
> \`params\` merges with the current values. Fields the integration does\
> not list are ignored. Hidden fields are omitted from the response.\
> Pausing requires a successful run and a billing plan that includes\
> pausing. A source that has never run successfully cannot be paused.
```json
{"openapi":"3.1.0","info":{"title":"Coupler.io Public API","version":"v1"},"servers":[{"url":"https://api.coupler.io"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Bearer token: a personal API token or an OAuth access token."}},"schemas":{"error_response":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["error"]}}},"paths":{"/v1/workspaces/{workspace_id}/sources/{id}":{"patch":{"summary":"Update Source","tags":["Dataflows"],"description":"Updates a source. Only the fields sent are changed. A disabled source\nstays disabled unless `enabled` or `lifecycle_state` is sent.\n\n`params` merges with the current values. Fields the integration does\nnot list are ignored. Hidden fields are omitted from the response.\nPausing requires a successful run and a billing plan that includes\npausing. A source that has never run successfully cannot be paused.\n","parameters":[{"name":"workspace_id","in":"path","required":true,"description":"Id of the workspace. Use an id returned by GET /v1/workspaces.","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Id of the source. Use an id from GET /v1/workspaces/{workspace_id}/dataflows/{id}/setup.","schema":{"type":"string"}}],"responses":{"200":{"description":"source updated","content":{"application/json":{}}},"401":{"description":"missing or invalid API token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error_response"}}}},"403":{"description":"the user cannot update this dataflow, or the billing plan does not allow pausing","content":{"application/json":{}}},"404":{"description":"source not found","content":{"application/json":{}}},"422":{"description":"source params are invalid, or the source cannot be paused before its first successful run","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Source name."},"credential_id":{"type":"integer","description":"Id of a source credential the user can access."},"params":{"type":"object","description":"Integration fields to merge into the current params."},"enabled":{"type":"boolean","description":"Whether the source runs."},"lifecycle_state":{"type":"string","enum":["active","paused","disabled"],"description":"Refresh state of the source. 'active' refreshes on the dataflow schedule. 'paused' stops refreshing but keeps the data already collected; it requires at least one successful run and is not available on every billing plan. 'disabled' turns the source off. Prefer 'paused' over 'disabled' when the user wants to keep the collected data. While a source stays paused its configuration is read-only, because the stored data is served exactly as it was collected. To change any other field, send 'active' in the same request and both are applied together."}}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/api/dataflows.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.