IMimprovado
Automated Recipes

Create a recipe

Creates a recipe from a template in the workspace the request is authenticated for. The recipe is created empty - no data sources, no connections, no accounts - so the next call has to be PUT /api/v3.1/automated-recipes/{recipe_id}/. Starting a build before that answers 409 recipe_not_configured.

One recipe per template per workspace. A second create from the same template answers 409 recipe_already_exists and names the recipes that already exist. Do not create recipes from one template in one workspace in parallel: the second call loses the race and gets the same answer.

title names the recipe and nothing else. It is optional and at most 255 characters; if it is missing, null, empty or only spaces, the template supplies the default name. The name of the output table is derived from the title of the template at the moment the recipe is created, never from title in this body, and the recipe keeps that name for good: renaming the template later changes the table name only for recipes deployed after the rename. To read the physical name, take datatable_id from this response and call GET /api/v3/data-tables/{data_table_id}, then read sql_name.

post/api/v3.1/automated-recipes/

Request

Request body

template_idinteger required

Identifier of the template to deploy, as returned by the template list. It has to belong to your agency and be deployable through the API; anything else answers 400 template_not_found.

titlestring nullable

Name of the recipe, at most 255 characters. Omit it, or send null, an empty string or only spaces, to let the template name the recipe. It has no effect on the name of the output table.

Response

The recipe was created. It holds no configuration yet, so data_sources, connections and sources are empty and last_build_at is null.

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.