IMimprovado
Automated Recipes

Configure a recipe

Gives a recipe the data sources, connections and accounts it builds from. This step is mandatory: a recipe created through the API holds no configuration, and a build started before it answers 409 recipe_not_configured.

The body is the full set, not a delta: send every data source, connection and account the recipe should have, including the ones it already has. Take connection_id from GET /api/v3/datasources/{datasource_name}/connections and every account id from GET /api/v3.1/connections/{connection_id}/accounts/ of this same workspace, and use only accounts with is_active: true - anything else is rejected with 400 account_unavailable.

Configuration only grows. Data sources, connections and accounts can be added, and none of them can be taken away: a body that leaves one out is rejected with 409 and the matching *_removal_not_allowed code. An account cannot be removed from a recipe at all, by this operation or by any other, and deleting the recipe does not remove it either. If the data of an account has to be taken out of a result, contact support.

A successful call answers 200 with the recipe as it now stands, so the response can be compared with what was sent. It changes neither state nor error and starts no build; POST .../build/ does that.

put/api/v3.1/automated-recipes/{recipe_id}/

Request

Path parameters

recipe_idstring required

Recipe identifier, as returned when the recipe was created. A string of digits.

Request body

data_sourcesstring[] required

Every data source the recipe reads, by name. Cannot be empty, and every name has to be one of the recipe's allowed_data_sources. A data source already configured has to stay in the list.

sync_from_datestring date nullable

The first date the recipe collects data from. Omit it or send null to leave the date the recipe already has unchanged.

Response

The recipe as it now stands, with the configuration this call saved

recipe_idstring

Recipe identifier. A string, even though it is made of digits.

template_idinteger

The template this recipe was created from.

template_titlestring

Current name of that template.

titlestring

Recipe name. When you create a recipe without a title, the template supplies the default.

workspace_idinteger

The workspace this recipe lives in.

state'extracting_data' | 'building_dependencies' | 'ready_to_work' | 'failed'

Where the recipe stands. extracting_data - data is being collected; building_dependencies - the tables are being built; ready_to_work - the last build finished and the output table can be queried; failed - the last build failed, see error. ready_to_work means built, not built completely: it is built from the extractions that delivered, and how complete that is shown by degraded and sources. New values can be added, so tolerate unknown ones.

degradedboolean nullable

Whether the last build was incomplete. Only meaningful while state is ready_to_work: in every other state, a failed recipe and a running build included, it is false. true - the build left something out, either a whole data source or some extractions; see not_delivered_reasons and sources. false - everything in the build delivered. null - the completeness of the last build is unknown because that build ran before version 3.1.

not_delivered_reasonsstring[]

The distinct reasons behind an incomplete last build, sorted and deduplicated across all data sources. Empty when degraded is false or null.

datatable_idinteger nullable

The recipe's output data table, or null while none is registered. Resolve the physical table name with GET /api/v3/data-tables/{data_table_id} instead of deriving it from a title.

last_build_atstring date-time nullable

When the last build of this recipe was started, no matter what started it. null means the recipe has never been built. For recipes last built before version 3.1 this is an approximation: the time the recipe record last changed, which is often the end of that build rather than its start.

created_atstring date-time

When the recipe was created.

updated_atstring date-time

When the recipe itself last changed. It says nothing about builds - for those use last_build_at and state.

data_sourcesstring[]

Data source names the recipe is configured for, sorted. Empty on a recipe that has been created but not configured yet.

allowed_data_sourcesstring[]

Data source names the template allows, sorted. Everything in data_sources has to come from this list.

sync_from_datestring date

The date the recipe collects data from. Always set in a response, even though it may be omitted from a configuration request.

Changes

No recorded changes to this operation across all 1 revision of this API.