# API Changelog ## May 21, 2026 **Added: Roles & Permissions API** New endpoints for managing custom workspace roles and inspecting the available permission catalog: - [`GET /api/v3/roles/`](/api/roles#list-roles) — list system + agency-custom roles (each carries `user_count`) - [`GET /api/v3/roles/permissions`](/api/roles#permissions-catalog) — ordered catalog of product layers and permissions, each with human-readable `title` and `description` - [`GET /api/v3/roles/{role_id}`](/api/roles#get-a-role) — retrieve a role - [`GET /api/v3/roles/{role_id}/users`](/api/roles#list-users-assigned-to-a-role) — list users assigned to a role (with workspace), useful for impact preview - [`POST /api/v3/roles/`](/api/roles#create-a-custom-role) — create a custom role - [`PATCH /api/v3/roles/{role_id}`](/api/roles#update-a-custom-role) — update title, description, or permissions of a custom role - [`DELETE /api/v3/roles/{role_id}`](/api/roles#delete-a-custom-role) — 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`](/api/data-source-connections#list-data-source-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/`](/api/extraction-templates#load-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`](/api/extracts#list-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/`](/api/extraction-templates#preview-extraction-template-data) --- ## 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/` --- ## 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 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 --- ## 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 --- ## 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