Changelog

API Changelog

September 30, 2026

Added: Name the sender of an external authentication link

POST /api/v3/datasources/{datasource_name}/external-auth-links accepts an optional requested_by — the email of the user the links are sent on behalf of. Until now, links created through the API named an internal service address as their sender, and the confirmation that the connection was created went nowhere.

With requested_by, the link page and the invitation email show that user, and the user receives the confirmation email once the external user creates the connection.
requested_by must be an active user of your agency who is a member of the workspace or an owner of the agency. Any other value is rejected with 400, and no links are created.
Without requested_by, the link page and the invitation show your whitelabel title, and no confirmation email is sent.

September 22, 2026

Added: Recipes API v3.1

Automated recipes have a new version of their endpoints under /api/v3.1/, with the same four-call deployment flow and a response that says what a build actually delivered rather than only that it finished. Every v3.1 operation answers with one error envelope, {code, message, details}, and branches on code instead of on a message. The v3 operations still work — they are deprecated in the entry below, and Moving recipes to v3.1 walks through the move.

Templates. GET /api/v3.1/automated-recipe-templates/ and GET /api/v3.1/automated-recipe-templates/{template_id}/ now return origin (improvado or agency), categories and build_mode. build_mode tells you in advance what a data source that delivers nothing does to the build: progressive drops that source and builds the rest, atomic fails the whole recipe.
Recipes. GET /api/v3.1/automated-recipes/, GET /api/v3.1/automated-recipes/{recipe_id}/, POST /api/v3.1/automated-recipes/, PUT /api/v3.1/automated-recipes/{recipe_id}/ and DELETE /api/v3.1/automated-recipes/{recipe_id}/. POST answers 201 with the created recipe, PUT answers 200 with the configured one, so no follow-up GET is needed to learn the new state.
Builds. POST /api/v3.1/automated-recipes/{recipe_id}/build/ and POST /api/v3.1/automated-recipes/{recipe_id}/resetup/ answer 202 with the recipe, and GET /api/v3.1/automated-recipes/{recipe_id}/extractions/ reports the extraction tables the recipe reads.
A build that finished is not the same as a build that delivered everything. state is ready_to_work once the view is built; degraded says whether it was built from everything the recipe is configured for; sources[] breaks that down per data source with status, not_delivered_count and up to 100 not_delivered entries carrying an extraction_id, an account_id and a reason; not_delivered_reasons on the recipe is the set of those reasons, so a list request is enough to spot an incomplete fleet.
last_build_at is the time the last build started, wherever it was started from, and null when the recipe has never been built. In v3 the same field tracked the last change to the recipe record.
Errors. Every failure carries a documented code, and details is always an object. The catalogue of HTTP error codes and of build error codes is on the new Errors page; state: failed always comes with an error object. New values can be added to any enumeration, so treat an unknown code, reason or status as unhandled rather than as invalid.
state values are extracting_data, building_dependencies, ready_to_work and failed — snake_case, in the response and in the ?state= filter alike, so a v3 value such as Ready to work is answered with 400 instead of an empty page. The Deploying recipes guide covers the full flow against v3.1.

Added: List connection accounts in v3.1

GET /api/v3.1/connections/{connection_id}/accounts/ lists the accounts of a connection with the account id that PUT /api/v3.1/automated-recipes/{recipe_id}/ accepts in connections[].accounts[]. This is the only source of those ids: for some agencies the v3 accounts endpoint returns a different key, which the recipe PUT rejects with account_unavailable.

Each item carries id, title, connection_id, datasource_name, is_active, enabled_for_embedded_extraction, currency, additional_params and timestamps. Only accounts with is_active: true can be put into a recipe.
The path ends with a slash, like every v3.1 path; without it the request is answered with a 301 and a redirect that clients silently follow with the wrong method.
Paginated like the rest of the API, but with page_size 100 by default (maximum 100), ordered by id. search matches a case-insensitive substring of title, and an integer also matches an id exactly.

Deprecated: Recipes API v3

The ten automated recipe operations under /api/v3/ are deprecated in favour of their v3.1 counterparts. They keep working until they are switched off, and we will announce the date well before that; see Moving recipes to v3.1 for the field-by-field differences and the order to move in.

GET /api/v3/recipes/ and POST /api/v3/workspaces/{id}/recipes are not part of this: they are agency-level recipe operations, they use a different authentication scheme and they are not deprecated.

September 10, 2026

Changed: A recipe build waits for each extraction, and Ready to work is defined

A build used to start as soon as the first account's rows reached a shared extraction table, so a recipe could turn Ready to work with error: null while other accounts were still extracting. It now waits for each extraction of the build.

An extraction counts as delivered once one of its runs has completed; the historical backfill may still be loading, as before.
Extractions that cannot deliver on their own are not waited for: ones paused because a connection was deleted or invalidated, an account was disabled, permissions were lost or someone paused them, and existing extractions a rebuild reuses that have nothing running. The others are waited for up to a limit, and any still missing then are left out of the build. A paused extraction no longer counts as ready.
A build with nothing to build from - no extraction delivered, or none for one of the template's extract templates - fails. Depending on the template, a data source whose extractions all failed to deliver either fails the recipe or is dropped while the other sources are built.
GET /api/v3/automated-recipes/{recipe_id}/extractions/: extraction_ids lists every extraction the last build used, created or reused. ready still reports only that the tables exist, so it can be true while the recipe is Extracting Data.
The Deploying recipes guide explains what Ready to work guarantees and how to confirm account coverage.

September 8, 2026

Changed: The connection iframe lets the end user choose the authentication method

When a data source offers several authentication methods, for example OAuth through Improvado's app and OAuth through your own app ("Bring Your Own App"), the iframe returned by POST /api/v3/get_iframe_url now shows a chooser above the authorization form. Previously only the data source's default method was reachable.

The default method is preselected, so a user who does not touch the chooser gets the same flow as before.
Each method has its own form fields and OAuth flow; the chosen method is used for the whole authorization.
Append use_default_auth=True to the iframe URL to hide the chooser and keep the previous behaviour. Add the parameter yourself — the endpoint does not emit it.
Data sources with a single method are unaffected.

Added: Per-extraction status, template resetup and recipe deletion

Three Recipes endpoints that the service already implements are now reachable and documented. Nothing about the recipe model changed - these are operations that existed behind the API and were not exposed through it.

GET /api/v3/automated-recipes/{recipe_id}/extractions/ reports the extraction tables the recipe reads and whether each exists in the workspace destination, with the extractions the last build created. ready turns true when every table is there, which is the signal that repeating a build that failed for missing data is worth it. Answers 501 when the destination cannot be asked whether a table exists, and 503 when it cannot be queried - a failure is never reported as table_exists: false.
POST /api/v3/automated-recipes/{recipe_id}/resetup/ recreates a deployed recipe from the current version of its template and starts the build. Configuration - data sources, connections, accounts, sync_from_date - is preserved. This is how a template fix reaches recipes already deployed from it.
DELETE /api/v3/automated-recipes/{recipe_id}/ permanently deletes a recipe: SQL views dropped, configuration and cells removed, data tables cleaned up, and the intermediate recipes it was built on deleted with it — a recipe built on top of this one is left in place and will break. It frees the template slot, so the same template can be deployed again - the way to retire a failed deployment.
The PUT description no longer claims a recipe cannot be deleted or redeployed from the same template, and the Deploying recipes guide covers all three calls.

September 2, 2026

Changed: The Recipes reference now matches the API, and deployment is documented end to end

Every Recipes path is documented with its required trailing slash, the template detail response is corrected, and the deployment flow is published as a guide. Nothing in the API changed - this closes the gap between the reference and the running service.

Recipes paths end in a slash. /api/v3/automated-recipes and friends answer 301 without it, and clients that follow the redirect downgrade POST to GET and drop the body. The documented URLs now carry the slash — this includes GET /api/v3/recipes/. The one exception is POST /api/v3/workspaces/{id}/recipes, which is genuinely registered without a trailing slash and is documented that way.
Template detail returns level, children (nested recursively) and dependencies_count - not the tree_structure wrapper that was documented. It also returns output_columns, now documented: the schema of the table the template produces, available before you deploy.
accounts[] items are objects {id, account_id}. id is Improvado's internal account id and is scoped to the workspace, as is connection_id; only the external account_id is stable across workspaces. Deploying one template to many workspaces requires resolving both per workspace.
PUT /api/v3/automated-recipes/{recipe_id}/ is a required deployment step and is append-only. A recipe created by POST is empty. The payload is the complete configuration, and removing a data source, connection or account returns 400 - the three messages are now shown as examples.
Recipe detail documents error, the object carrying why the last build failed, and states that last_build_at tracks the last configuration change rather than a build.
Output table naming: the name comes from the template's title, not from the title you pass on create, and uniqueness is scoped to (agency, workspace). Resolve the physical name through datatable_id and GET /api/v3/data-tables/{data_table_id}.
New Deploying recipes guide with the four-call happy path, authenticated curl samples and the per-workspace deployment loop.

August 28, 2026

Changed: Create automated recipe documents both "already exists" responses, and the recipe state enum is corrected

POST /api/v3/automated-recipes/ returns more than detail when the slot is already taken, and the state values were documented with the wrong casing.

The 400 response now has its own schema. When a recipe from the same template already exists in the workspace, the body carries existing_recipe_ids next to detail - a list, which can hold more than one id. Treat that response as "already deployed" and reuse one of the returned recipes instead of failing.
When the output table name derived from the template is already taken in the workspace, the body carries conflicting_recipe_ids.
The 201 response documents datatable_id, which the endpoint has always returned. Resolve the physical table name with GET /api/v3/data-tables/{data_table_id} rather than deriving it from the recipe title.
Recipe state is Ready to work, not Ready To Work. The state filter on GET /api/v3/automated-recipes/ matches exactly and is case-sensitive, so a filter written with the previously documented casing returned 200 with an empty page and no error.

No behaviour changed - this documents what the API already returns.

August 19, 2026

Documented: the full webhook event catalog

All 90 event types that GET /api/v3/webhook_event_types/ can return are now enumerated in the spec, and each one is documented with the payload you actually receive on the new Webhook Events page.

event_types (when creating or updating an endpoint) and event_name (in the event-type response) now carry the full enum, so the reference lists valid values and generated clients validate them.
The delivered data object is shaped by the event's aggregate class, not by the event type — 12 shapes cover all 90 events. Match on the shape rather than on each event name.
All payload values are strings. A field documented as empty is empty in production for that event type; it is not an omission. Notably extraction_completed carries no status or error, and transformation_completed never carries mcdm_recipe_title.
17 event types are marked silent: valid to subscribe to, but they produced no events in a 30-day production sample. Do not build a flow that waits on one.

No behaviour changed — this documents what the API already sends.

August 12, 2026

Added: Account selection in the connection iframe

Append show_account_selection=True to the URL returned by POST /api/v3/get_iframe_url to let the end user choose which accounts a connection syncs, instead of creating a connection that syncs all of them.

The flow becomes two steps: the user authorizes first, then either syncs all accounts or picks specific ones, and the connection is created from that choice.
ConnectionCreated is posted to the parent window only after the account step, so the connection already exists when your page receives it.
Add the parameter to the returned URL yourself — get_iframe_url does not emit it.
Data sources that cannot list accounts before the connection exists keep the single-step flow, and the parameter has no effect there.

Existing embeds are unaffected: without the parameter the iframe behaves exactly as before.

July 14, 2026

Added: Update a data table (field selection)

New PUT /api/v3/data-tables/{data_table_id} operation that controls which fields (columns) of a data table are delivered by its loads to the destination.

Request body takes selected_fields — the full list of field name values (as returned by the detail endpoint's fields[].name) that should be selected; any field not listed becomes deselected.
Field selection is set at the data table level and affects all loads delivering this data table. Unknown field names are ignored; dimension fields cannot be deselected (returns 400).
Returns the same DataTableDetail payload as GET /api/v3/data-tables/{data_table_id}, so clients can confirm the resulting selection without a follow-up read.

Added: External authentication links

New endpoints that let you request data source credentials from an external user — the API equivalent of the platform UI action "Request credentials from another user":

POST /api/v3/datasources/{datasource_name}/external-auth-links — generates one-time links (one per email in to_emails) that let an external user, such as the end client of an agency, authenticate a connection with their own credentials and select which accounts to grant, without having access to the workspace. Links are single-use, expire after 14 days, and can be revoked; set send_email: false to deliver the links yourself instead of having Improvado email them.
GET /api/v3/datasources/{datasource_name}/external-auth-links — lists the generated links with their current status (not_used, used, expired, revoked_manually).
POST /api/v3/datasources/{datasource_name}/external-auth-links/{id}/revoke — revokes a not-yet-used link.

Requires the agency feature flag for external authentication links (contact Improvado to enable it); the endpoint returns 403 otherwise.

June 15, 2026

Changed: Extraction template validation request format

POST /api/v3/extract-template/{template_id}/validation/ now takes a new request body shaped around embedded accounts:

accounts is now a non-empty list of embedded account IDs (integers) instead of remote account ID strings. The connection is resolved automatically from the accounts, which must all belong to a single connection.
Field, custom-setting, dynamic-field, custom-filter and historical-backfill inputs now live under an optional template_settings object (fields, additional_params, dynamic_fields, custom_filters, sync_historical_data).
The top-level connection_id, fields, custom_settings and string accounts fields have been removed.
Returns 400 when accounts span multiple connections or reference accounts that do not exist.

Added: Get extraction template by id

GET /api/v3/extract-template/{template_id}/ — returns a compact template representation (id, datasource_name, is_wide_template), useful for choosing the right extract flow before creating or migrating an extract.

Added: Account identifiers on extract objects

Extract responses (GET /api/v3/extracts, GET /api/v3/extracts/{id}, and create / PUT / PATCH responses) now include:

account_entity_id — internal Improvado account entity ID
account_embedded_id — embedded account ID (nullable when the account is not linked to an embedded account)

June 5, 2026

Added: Wide report extract migration

New endpoints supporting non-destructive dimension changes on wide report extracts. Changing dimensions on a wide report requires a data table with a new schema, so instead of editing the extract in place, the API creates a new extract with a new data table and pauses the original — its data stays queryable.

POST /api/v3/extracts/migrate-wide — migrate a wide report extract with changed dimensions to a new extract. Only migrated_from_extraction_id and template_settings are required; every omitted setting is pre-filled from the source extract, and the response returns the new extract's detail.
POST /api/v3/extract-template/{template_id}/validation/ — pre-flight validation of the proposed fields / custom_settings / accounts combination against a template before creating or migrating an extract.

Changed: is_wide_template flag on extract template objects

The template object in extract responses (GET /api/v3/extracts, GET /api/v3/extracts/{id}, and PUT / PATCH responses) now includes a boolean is_wide_template field, so clients can detect wide report extracts and route dimension changes through the migrate-wide flow.

May 21, 2026

Added: Roles & Permissions API

New endpoints for managing custom workspace roles and inspecting the available permission catalog:

GET /api/v3/roles/ — list system + agency-custom roles (each carries user_count)
GET /api/v3/roles/permissions — ordered catalog of product layers and permissions, each with human-readable title and description
GET /api/v3/roles/{role_id} — retrieve a role
GET /api/v3/roles/{role_id}/users — list users assigned to a role (with workspace), useful for impact preview
POST /api/v3/roles/ — create a custom role
PATCH /api/v3/roles/{role_id} — update title, description, or permissions of a custom role
DELETE /api/v3/roles/{role_id} — delete a custom role; users assigned to it are atomically reassigned to the system Viewer role, response includes reassigned_users_count

System roles are read-only. All endpoints require Basic Auth as an agency chief, and the agency must have the embedded API enabled.

May 5, 2026

Added: enabled_for_extraction_accounts_number on List Connections

New response field on GET /api/v3/datasources/{datasource_name}/connections that returns the number of accounts on each connection that are selected for extraction.

Pairs with the existing accounts_number (total accounts) — clients can detect connections with enabled_for_extraction_accounts_number == 0 and prompt the user to select accounts before setting up extractions or loads.
Removes the need to fan out a per-connection GET /accounts call to compute this client-side.

April 28, 2026

Added: Custom Setting Options endpoint

New endpoint for loading dynamic options for select-based extraction custom settings:

POST /api/v3/datasources/{datasource_name}/custom_setting_options/
Resolves options for one or more source accounts using connection_id
Accepts remote account ID strings in account_ids, matching extraction template preview
Supports server-side search and pagination over loaded option lists
Returns options grouped by account using the standard paginated-response shape (count, next, previous, results)

April 27, 2026

Added: Webhooks API

New endpoints for managing webhook endpoints that receive event notifications from Improvado:

GET / POST /api/v3/webhook_endpoints/ — list and register webhook endpoints
GET / PATCH / DELETE /api/v3/webhook_endpoints/{id}/ — retrieve, update, and delete an endpoint
POST /api/v3/webhook_endpoints/{id}/verify/ — verify endpoint ownership via challenge-response
POST /api/v3/webhook_endpoints/{id}/regenerate_secret/ — rotate the signing secret
GET /api/v3/webhook_event_types/ — list available event types

Each endpoint is workspace-scoped, signs deliveries with HMAC-SHA256 in the X-Improvado-Signature header, and supports automatic retries with backoff on failed deliveries.

April 15, 2026

Added: Filter parameters for List Extracts endpoint

New optional query parameters on GET /api/v3/extracts to narrow results on the server side:

connection_id — filter by connection ID (single value or comma-separated list)
datasource_name — filter by datasource name, e.g. reddit or reddit,facebook
data_table_id — filter by data table ID (single value or comma-separated list)

Lets clients avoid paginating the full list and filtering locally.

April 2, 2026

Added: Create Extract Template endpoint

New endpoint for creating extraction templates programmatically.

POST /api/v3/datasources/{datasource_name}/extract-templates/
Supports standard and wide report template creation
Wide report templates require connection_id and validate fields against the DSAS API
Includes detailed error response examples for common validation failures

March 31, 2026

Added: Preview Data endpoint

New endpoint for previewing extracted data before committing to a full load.

POST /api/v3/extract-template/{template_id}/preview/

March 27, 2026

Added: Date range parameters to Run Load endpoint

Added optional date_from and date_to request body parameters to PUT /api/v3/loads/{id}/run
Allows running a load for a specific date range instead of the default schedule window

March 12, 2026

Added: sync_historical_data field to Extract responses

New read-only field sync_historical_data (nullable ISO date string) added to Extract detail and list response schemas
Indicates when the extract last synced historical data

Affected endpoints: GET /api/v3/extracts/{id}, GET /api/v3/extracts/

February 3, 2026

Added: max_file_size_mb for S3 destination connections

New optional max_file_size_mb connection parameter (45–100000) on POST /api/v3/destinations/{destination_name}/connections and PUT /api/v3/destinations/{destination_name}/connections/{id} that splits delivered files into chunks of the given size
Requires {{chunk_id}} in the filename template and file_format: parquet

Changed: Destination connection update is documented as a partial update

PUT /api/v3/destinations/{destination_name}/connections/{id} is renamed from "Reauthorize a connection" to "Update connection parameters" and now documents its actual semantics:

connection_params is merged at field level — omitted fields keep their current values, so a payload like {"connection_params": {"partition_by": "by_month"}} is a complete, valid request.
Secret fields must be sent all together if any one of them is included; omit them entirely to keep the stored values.
Unknown field names are rejected with 400, and a successful update triggers a connection re-check.

Heads-up for generated SDKs: the spec's operationId for this operation changed from api_v3_destination_connection_reathorize to api_v3_destination_connection_update_params, and the create request schema's misspelled conenctions_params property is corrected to connection_params (matching what the API has always accepted) — regenerating a client from this spec renames the corresponding method and request field.

No API behaviour changed — this documents what the API already does.

January 13, 2026

Added: Automated Recipes endpoints

New endpoints for managing automated recipe execution:

Create, read, update, and delete automated recipes
Configure recipe triggers and scheduling
Monitor recipe execution status

November 20, 2025

Added: Data source category field

New category field added to the GET /api/v3/datasources response
Allows filtering and grouping data sources by their category

July 28, 2025

Added: Extract Partial Update endpoint

New PATCH endpoint for partially updating extract configurations
Allows modifying individual fields without sending the full extract payload

July 23, 2025

Added: Cross-account IAM role chaining for S3 destination connections

New authentication method for S3 destination connections that needs no long-lived AWS keys:

connection_option now accepts role_chaining
New assume_role_arn connection parameter — the customer IAM role Improvado assumes
Read-only improvado_assume_role_arn and improvado_assume_role_externalid parameters are returned on GET /api/v3/destinations/{destination_name}/connections/{id} for building the trust policy on the customer side
aws_access_key_id / aws_secret_access_key are not used with role_chaining

July 7, 2025

Added: DTS Session Authentication

New authentication flow using DTS session tokens
Alternative to API key authentication for embedded use cases

March 27, 2025

Added: DataTable detail endpoint

New GET /api/v3/data-tables/{id} endpoint for retrieving detailed information about a specific data table

Added: format, user_type and is_dynamic on field objects

Each entry of a fields list gained three attributes, in extraction template, extract and data table responses alike.

format — how the value is meant to be rendered: string, float, integer, iso_8601_date, currency, percent, duration, url or image_url. A hint, not a storage contract: metrics fall back to float when a data source declares no format explicitly, and no decimal precision is guaranteed.
user_type — broad data type of the field
is_dynamic — whether the field comes from a dynamic, per-connection schema

March 18, 2025

Added: sql_name to Extract Template detail

New sql_name field added to the extract template detail response
Useful for referencing templates in SQL-based workflows

August 30, 2024

Added: Recipes endpoints

New set of endpoints for managing data transformation recipes:

List, create, read, update, and delete recipes
Manage recipe steps and transformations
Activate and deactivate recipes

August 14, 2024

Added: connection_option for S3 destination connections

New connection_option connection parameter on POST /api/v3/destinations/{destination_name}/connections selecting the authentication method: aws_credentials (default) or bucket_policy
AWS keys are required only for the aws_credentials option

June 20, 2024

Initial release: Embedded API v3

The first public release of the Improvado Embedded API v3 specification, including:

Authentication: API key-based authentication
Data Sources: List available data sources and their configurations
Extracts: Full CRUD for data extraction configurations
Extract Templates: Browse and use pre-built extraction templates
Loads: Configure and manage data loading to destinations
Destinations: List available destination connections
Data Tables: Access workspace data tables

Last modified on October 2, 2026