# Improvado API v3

> Complete documentation for Large Language Models


---

## Document: System Fields

URL: /system-fields


# System Fields

System fields are platform-level fields that Improvado automatically adds to every data table. These fields provide essential metadata for identifying accounts and tracking data freshness.

## Available System Fields

| Field | Description |
|-------|-------------|
| `account_id` | Unique identifier of the connected account |
| `account_name` | Display name of the connected account |
| `__insert_date` | Timestamp when the row was inserted into the table |

These fields are guaranteed to be present in all data tables, regardless of the data source or extract template.

## Where System Fields Appear

**Data Tables API** — The [Get data table details](/api/data-tables#get-data-table-details) endpoint (`/api/v3/data-tables/{id}`) returns the complete table schema, including all system fields.

**CSV exports** — All CSV files generated via load orders include system fields as columns.

## Where System Fields Do NOT Appear

**Extract Template metadata** — Endpoints like [Get extract template details](/api/extracts#get-extract-template-details) (`/api/v3/datasources/{datasource_name}/extract-templates/{template_id}`) return only provider fields — the fields that come directly from the data source API.

**Recipe metadata** — Similarly, recipe endpoints return only the fields defined in the recipe configuration, not system fields.

## Why This Design?

The API separates two distinct concepts:

- **Provider fields** — Fields that come from the data source (e.g., Facebook, Google Ads). These define the extract template or recipe structure and vary by data source.

- **System fields** — Platform-level fields added by Improvado. These are consistent across all data sources and provide account context and data lineage.

Extract template and recipe endpoints describe the data structure from the provider's perspective. The Data Tables API provides the complete schema as it exists in your destination, including both provider fields and system fields.

## Guarantees

- `account_id` and `account_name` are present in every table
- These fields can be safely used in queries and integrations without hard-coding assumptions
- Use the Data Tables API to discover the full schema of any table



---

## Document: Rate limits

URL: /rate-limits


# Rate limits

All API methods enforce rate limits (maximum number of requests per period of time).

Exact mechanism (including rate limit values, informational headers and errors) will be described later.


---

## Document: Pagination

URL: /pagination


# Pagination

All endpoints with pagination enabled implement same pagination scheme.

Paginated response will contain special pagination attributes. Example:

```json
{
    "count": 1023,
    "next": "https://api.example.org/accounts/?page=5",
    "previous": "https://api.example.org/accounts/?page=3",
    "results": [
       ...
    ],
}
```

You can customize pagination settings using query parameters:

`page_size` - set the number of items per page (default is 100)

`page` - set the page number to get in response (default is 1)

Paginated responses are sorted by `id` value.


---

## Document: Getting started

URL: /introduction


# Getting started

## Basic concepts

### Onboarding

Improvado provides credentials to access the embedded API for its customers. After credentials are created customer should change password and use this login and password combination as credentials for [Basic authentication](/auth#basic-authentication).

### Base URL

API endpoints should use this base URL: `https://embedded.improvado.io`

### API errors

Special HTTP status code will be returned in case of an error.

Response Content-Type will be `application/json`.

**Body structure**

```json
{
	"details": "error description"
}
```

Possible errors are described in the documentation for each API endpoint.


---

## Document: /changelog

A chronological log of changes to the Improvado Embedded API v3.

URL: /changelog



# API Changelog

## 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`](/api/iframe#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}`](/api/data-tables#update-a-data-table) 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}`](/api/data-tables#get-a-data-table), 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`](/api/data-source-connections#generate-external-authentication-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`](/api/data-source-connections#list-external-authentication-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`](/api/data-source-connections#revoke-an-external-authentication-link) — 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/`](/api/extraction-templates#validate-extraction-template-settings) 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}/`](/api/extraction-templates#get-an-extraction-template-by-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`](/api/extracts#list-extracts), [`GET /api/v3/extracts/{id}`](/api/extracts#get-an-extract), 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`](/api/extracts#migrate-a-wide-report-extract) — 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/`](/api/extraction-templates#validate-extraction-template-settings) — 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`](/api/extracts#list-extracts), [`GET /api/v3/extracts/{id}`](/api/extracts#get-an-extract), 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/`](/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



---

## Document: Authorization

URL: /auth


# Authorization

- [Basic authentication](#basic-authentication) is required for workspaces management, and obtaining access token for operating against workspaces resources.
- [Token authentication](#token-authentication) is required when accessing workspace specific resources (Connection, Account, Extraction etc.)

## Basic authentication

Basic authentication is required for workspaces management, and obtaining access token for operating against workspaces resources.

*When Basic auth is required, use credentials provided by Improvado for Embedded API access.*

It is common implementation of Basic auth, as described in the [RFC 7616](https://datatracker.ietf.org/doc/html/rfc7617):

Credentials value is base64 encoded string composed from username and password separated by `:` .

Requests requiring this type of authentication must contain following header

`Authorization: 'Basic <credentials value>'`

Implementation example (Python):
```python
import requests

username = 'username@email.com'
password = 'password'

response = requests.get(
    'https://embedded.improvado.io/api/v3/workspaces',
    auth=requests.auth.HTTPBasicAuth(
        username=username,
        password=password,
    )
)
```

Authenticating with invalid credentials will return `401 Unauthorized`

## Token authentication

Token authentication is required when accessing workspace specific resources (Connection, Account, Extraction etc.)

Token value is obtained from [Create a token](/api/auth#create-a-token) endpoint.

Requests requiring this type of authentication must contain the following header:

`Authorization: 'Bearer <token value>'`

Token expiration time is 30 minutes.

The expiration time is renewed when the token is used to authorize a request.

New token acquisition is required if the token has expired.

Authenticating with an invalid or expired token will return `401 Unauthorized`

Implementation example (Python):
```python
import requests

username = 'username@email.com'
password = 'password'

# response {token: <token value>}
response = requests.post(
    'https://embedded.improvado.io/api/v3/token',
    auth=requests.auth.HTTPBasicAuth(
        username=username,
        password=password,
    ),
    json={'workspace_id': <int>}
)
token_value = response.json()['token']

auth_header = 'Authorization'
auth_value = 'Bearer {token_value}'.format(token_value=token_value)
headers = {auth_header: auth_value}

response = requests.get(
    'https://embedded.improvado.io/api/v3/datasources',
    headers=headers
)
```




# API Reference

## Improvado Embedded API v3

### POST /api/v3/token
**Create a token**
URL: https://embedded.improvado.io/api/v3/token
Tags: Authentication

Creates and returns new access token for operating against workspace resources.

Request body:
- Content-Type: application/json
  - `workspace_id` (integer) — Workspace ID

Responses:
- 200: Create a Token
- 400: Bad Request
- 401: Forbidden

### GET /api/v3/workspaces
**List workspaces**
URL: https://embedded.improvado.io/api/v3/workspaces
Tags: Workspaces

Get a list of workspaces

Responses:
- 200: Get a list of Workspaces
- 401: Forbidden

### POST /api/v3/workspaces
**Create a workspace**
URL: https://embedded.improvado.io/api/v3/workspaces
Tags: Workspaces

Create a workspace

Request body:
- Content-Type: application/json
  - `title` (string) — Workspace title

Responses:
- 201: Create a Workspace
- 401: Forbidden

### GET /api/v3/workspaces/{id}
**Get a workspace**
URL: https://embedded.improvado.io/api/v3/workspaces/{id}
Tags: Workspaces

Get a workspace

Parameters:
- `id` (path) (required) — Workspace ID

Responses:
- 200: Get a Workspace
- 401: Forbidden

### PUT /api/v3/workspaces/{id}
**Update a workspace**
URL: https://embedded.improvado.io/api/v3/workspaces/{id}
Tags: Workspaces

Update a workspace

Parameters:
- `id` (path) (required) — Workspace ID

Request body:
- Content-Type: application/json
  - `title` (string) — Workspace title

Responses:
- 200: Update a Workspace
- 400: Bad Request
- 401: Forbidden

### GET /api/v3/workspaces/{id}/dashboards
**List workspace dashboards**
URL: https://embedded.improvado.io/api/v3/workspaces/{id}/dashboards
Tags: Workspaces

Get a list of available dashboards for a given workspace. Only returns dashboards with TYPE=DATA. Only includes dashboards with enabled recipes for the specified workspace.

Parameters:
- `id` (path) (required) — Workspace ID

Responses:
- 200: Get a list of available dashboards for a given workspace
- 401: Forbidden
- 404: Workspace Not Found

### POST /api/v3/workspaces/{id}/recipes
**Enable recipe in a workspace**
URL: https://embedded.improvado.io/api/v3/workspaces/{id}/recipes
Tags: Recipes

Enables a specific recipe for a given workspace

Parameters:
- `id` (path) (required) — Workspace ID

Request body:
- Content-Type: application/json
  - `recipe_id` (integer) — Recipe ID

Responses:
- 204: Recipe is enabled
- 401: Forbidden
- 403: Recipe pipeline is disabled for agency
- 404: Workspace or Recipe Not Found

### POST /api/v3/get_iframe_url
**Get iframe URL**
URL: https://embedded.improvado.io/api/v3/get_iframe_url
Tags: iframe

Iframe allows to embed Improvado’s mechanism of creating datasource and destination connections in a safe way (including credentials passing). Datasources and destinations have different connection flows and attributes, Improvado handles this and has embedded all supported flows into iframe. In order to create a new connection within Improvado; call Get iframe url API, embed the iframe into your website so your customers can sign in to a datasource or setup destination connection parameters. After that you will be able to extract and load data using created connections.

### Account selection

By default the iframe creates the connection as soon as the user authorizes, and that connection syncs every account the credentials give access to.

Append `show_account_selection=True` to the returned URL to split the flow into two steps instead:

1. **Authorization** — the user signs in to the data source. No connection is created yet.
2. **Account selection** — the accounts reachable with those credentials are listed, and the user either syncs all of them or picks specific ones. The connection is created from that choice.

The `ConnectionCreated` message is posted to the parent window only after the second step, so the connection always exists by the time your page is notified.

Add the parameter yourself — this endpoint does not emit it:

```
https://embedded.improvado.io/api/v3/iframe/?code=<str>&type=datasource&name=jira&show_account_selection=True
```

Not every data source can list accounts before the connection exists. Where it cannot, the iframe falls back to the default single-step flow and the parameter has no effect.

Parameters:
- `show_connectors_list` (query) — Shows list of connected connections in iframe (optional parameter)
- `show_datasources` (query) — Shows list of all available data sources for connection (optional parameter)
- `show_accounts` (query) — Allows to open page for each connection and enable/disable accounts within (optional parameter)
- `show_accounts_only_on_auth` (query) — Automatically opens page for a connection after authorization. Only works if `show_accounts=False`. (optional parameter)

Request body:
- Content-Type: application/json
  - `workspace_id` (integer) — Workspace ID
  - `type` (string) — defines whether you want to create a destination connection or datasource connection. Allowed values are destination or datasource (optional parameter)
  - `name` (string) — string identifier of datasource or destination you want to connect to (optional parameter)

Responses:
- 200: Get iframe URL
- 400: Bad Request
- 401: Forbidden

### GET /api/v3/recipes
**List agency recipes**
URL: https://embedded.improvado.io/api/v3/recipes
Tags: Recipes

Get list of recipes available for agency

Responses:
- 200: Get list of recipes available for agency
- 401: Forbidden

### GET /api/v3/datasources
**List data sources**
URL: https://embedded.improvado.io/api/v3/datasources
Tags: Data sources

Returns list of datasources available to connect to

Responses:
- 200: Get a list of DataSources
- 401: Forbidden

### GET /api/v3/datasources/{datasource_name}/connections
**List data source connections**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/connections
Tags: Data source connections

Returns list of connections within workspace by data source

Parameters:
- `datasource_name` (path) (required) — Data source name

Responses:
- 200: Get a list of Connections
- 400: Bad Request
- 401: Forbidden

### DELETE /api/v3/datasources/{datasource_name}/connections/{id}
**Delete a connection**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/connections/{id}
Tags: Data source connections

Delete specified connection. Also related accounts are marked as inactive (is_active property becomes false) and related extractions are paused.

Parameters:
- `datasource_name` (path) (required) — Datasource name
- `id` (path) (required) — Connection ID

Responses:
- 204: Delete a Connection
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### POST /api/v3/datasources/{datasource_name}/external-auth-links
**Generate external authentication links**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/external-auth-links
Tags: Data source connections

Generates one-time links that let an external user (for example, the end client of an agency)
authenticate a data source connection with their own credentials and select which accounts to
grant — without having access to the workspace. This is the API equivalent of the platform UI
action "Request credentials from another user".

One link is generated per email in `to_emails`; the email identifies the external user.
Links are single-use, expire after 14 days, and can be revoked.

> **Important:** Requires the agency feature flag for external authentication links
> (contact Improvado to enable it). The endpoint returns `403` when the flag is disabled.

Parameters:
- `datasource_name` (path) (required) — Data source name

Request body:
- Content-Type: application/json
  - Schema: ExternalAuthLinksCreateRequest

Responses:
- 201: External authentication links generated
- 400: Validation error
- 401: Forbidden
- 403: External authentication links are not enabled for this agency. Contact Improvado to enable the feature.

### GET /api/v3/datasources/{datasource_name}/external-auth-links
**List external authentication links**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/external-auth-links
Tags: Data source connections

Lists the external authentication links generated for this data source in the current
workspace, newest first. Each link carries its current status: `not_used`, `used`,
`expired`, or `revoked_manually`. An unknown `datasource_name` yields an empty list.

Parameters:
- `datasource_name` (path) (required) — Data source name
- `page` (query) — Page number
- `page_size` (query) — Number of items per page (max 1000)

Responses:
- 200: External authentication links
- 401: Forbidden

### POST /api/v3/datasources/{datasource_name}/external-auth-links/{id}/revoke
**Revoke an external authentication link**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/external-auth-links/{id}/revoke
Tags: Data source connections

Revokes a not-yet-used external authentication link so it can no longer be used to
authenticate. Idempotent — revoking an already-revoked link returns `200` with the
existing revocation data. Returns `400` if the link was already used or has expired.

Parameters:
- `datasource_name` (path) (required) — Data source name
- `id` (path) (required) — External authentication link ID

Responses:
- 200: Link revoked
- 400: Link already used or expired
- 401: Forbidden
- 404: Link not found — the ID does not exist within this data source and workspace (including an unknown `datasource_name`).

### DELETE /api/v3/connections/{connection_id}
**Delete a connection**
URL: https://embedded.improvado.io/api/v3/connections/{connection_id}
Tags: Data source connections

Delete specified connection. Also related accounts are marked as inactive (is_active property becomes false) and related extractions are paused.

Parameters:
- `connection_id` (path) (required) — Connection ID

Responses:
- 204: Delete a Connection
- 401: Forbidden
- 404: Not Found

### GET /api/v3/connections/{connection_id}/accounts
**List accounts for connection**
URL: https://embedded.improvado.io/api/v3/connections/{connection_id}/accounts
Tags: Accounts

List accounts for connection

Parameters:
- `connection_id` (path) (required) — Connection ID

Responses:
- 200: Get a list of Accounts
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### PATCH /api/v3/connections/{connection_id}/accounts
**Update accounts**
URL: https://embedded.improvado.io/api/v3/connections/{connection_id}/accounts
Tags: Accounts

Update accounts

Parameters:
- `connection_id` (path) (required) — Connection ID

Request body:
- Content-Type: application/json

Responses:
- 200: Update Accounts
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### PATCH /api/v3/connections/{connection_id}/accounts/{account_id}
**Update an account**
URL: https://embedded.improvado.io/api/v3/connections/{connection_id}/accounts/{account_id}
Tags: Accounts

Update an account

Parameters:
- `connection_id` (path) (required) — Connection ID
- `account_id` (path) (required) — Account ID

Request body:
- Content-Type: application/json
  - `enabled_for_embedded_extraction` (boolean) — Enabled for embedded extraction

Responses:
- 200: Update an Account
- 401: Forbidden
- 404: Not Found

### GET /api/v3/datasources/{datasource_name}/extract-templates
**List extraction templates for a datasource**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/extract-templates
Tags: Extraction templates

List extraction templates available for datasource

Parameters:
- `datasource_name` (path) (required) — Datasource name

Responses:
- 200: Get a list of extraction templates
- 400: Not Found
- 401: Forbidden

### POST /api/v3/datasources/{datasource_name}/extract-templates
**Create an extraction template**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/extract-templates
Tags: Extraction templates

Create a custom (agency-level) extraction template based on a parent global template.

For wide report templates (parent has `allow_to_select_dimensions` or `is_created_from_wide`),
a `connection_id` is required and the selected fields are validated against the DSAS API.

Required RBAC permission: `EXTRACT.CREATE`.

Parameters:
- `datasource_name` (path) (required) — Datasource name

Request body:
- Content-Type: application/json
  - Schema: ExtractTemplateCreateRequest

Responses:
- 201: Template created successfully
- 400: Bad Request
- 401: Forbidden

### GET /api/v3/datasources/{datasource_name}/extract-templates/{id}
**Get an extraction template**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/extract-templates/{id}
Tags: Extraction templates

Returns detailed info about extraction template

Parameters:
- `datasource_name` (path) (required) — Datasource name
- `id` (path) (required) — Extract Template ID

Responses:
- 200: Get an extraction template
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### GET /api/v3/extract-template/{template_id}/
**Get an extraction template by id**
URL: https://embedded.improvado.io/api/v3/extract-template/{template_id}/
Tags: Extraction templates

Returns a compact representation of an extraction template, including whether it is a wide report template. Useful for deciding which extract flow to use before creating or migrating an extract.

Parameters:
- `template_id` (path) (required) — A unique integer value identifying this Extraction template.

Responses:
- 200: Extraction template
- 403: Forbidden
- 404: Not found

### POST /api/v3/extract-template/{template_id}/preview/
**Preview extraction template data**
URL: https://embedded.improvado.io/api/v3/extract-template/{template_id}/preview/
Tags: Extraction templates

Returns a preview of data that would be extracted using the given template configuration. The response includes both the data rows and column metadata.

Parameters:
- `template_id` (path) (required) — A unique integer value identifying this Extraction template.

Request body:
- Content-Type: application/json
  - Schema: ExtractTemplatePreviewRequest

Responses:
- 200: Preview data with rows and column metadata
- 400: Bad request
- 403: Forbidden
- 404: Not found

### POST /api/v3/extract-template/{template_id}/validation/
**Validate extraction template settings**
URL: https://embedded.improvado.io/api/v3/extract-template/{template_id}/validation/
Tags: Extraction templates

Validates the proposed combination of fields, custom settings and accounts against the given extraction template before creating or migrating an extract. Use this endpoint as a pre-flight check — for example, before creating an extract or calling the migrate-wide endpoint.

Accounts are referenced by their embedded account IDs and must all belong to a single connection. The connection is resolved automatically from the provided accounts.

Parameters:
- `template_id` (path) (required) — A unique integer value identifying this Extraction template.

Request body:
- Content-Type: application/json
  - Schema: ExtractTemplateValidationRequest

Responses:
- 200: Validation result. An empty `detail` and empty `incompatible` mean the settings are valid. Incompatible field combinations are returned in `incompatible`; other validation errors (e.g. bad custom settings) are returned in `detail`.

- 400: Bad Request
- 403: Forbidden
- 404: Not found

### POST /api/v3/datasources/{datasource_name}/custom_setting_options/
**Load custom setting options**
URL: https://embedded.improvado.io/api/v3/datasources/{datasource_name}/custom_setting_options/
Tags: Extraction templates

Returns selectable options for a custom extraction setting that is backed by source entities. Use this endpoint when an extraction template exposes a `select` custom setting with dynamic `source` metadata and the UI needs to populate its choices for one or more accounts.
Account IDs in the request are remote account IDs from the source platform (the same string IDs used by extraction template preview), scoped by the provided `connection_id`. Search and pagination are applied over the loaded option list by Improvado, so source APIs do not need to support filtering or paging.

Parameters:
- `datasource_name` (path) (required) — Data source name.

Request body:
- Content-Type: application/json
  - Schema: CustomSettingOptionsRequest

Responses:
- 200: Custom setting options grouped by account.
- 400: Bad request
- 403: Forbidden
- 408: Request timeout

### GET /api/v3/extracts
**List extracts**
URL: https://embedded.improvado.io/api/v3/extracts
Tags: Extracts

List extracts

Parameters:
- `extraction_ids` (query) — Extraction IDs
- `connection_id` (query) — Filter extracts by connection ID. Accepts a single ID or a comma-separated list (e.g. `123` or `123,456`).
- `datasource_name` (query) — Filter extracts by datasource name (e.g. `reddit`, `facebook`). Accepts a single value or a comma-separated list.
- `data_table_id` (query) — Filter extracts by data table ID. Accepts a single ID or a comma-separated list.

Responses:
- 200: Get a list of Extracts
- 401: Forbidden

### POST /api/v3.1/extracts/
**Create extract**
URL: https://embedded.improvado.io/api/v3.1/extracts/
Tags: Extracts

Request to this endpoint setups a new extracts. New extract creation request is composed of Connection, Account and Extract Template data.

Request body:
- Content-Type: application/json
  - `data_table_title` (string) — Data Table Title
  - `template_id` (integer) — Template ID
  - `template_settings` (object) — Template settings
  - `accounts` (array)

Responses:
- 201: Create an Extract
- 401: Forbidden

### GET /api/v3/extracts/{id}
**Get an extract**
URL: https://embedded.improvado.io/api/v3/extracts/{id}
Tags: Extracts

Get detailed info about extract

Parameters:
- `id` (path) (required) — Extract ID

Responses:
- 200: Get an Extract
- 401: Forbidden
- 404: Not Found

### PUT /api/v3/extracts/{id}
**Update an extract**
URL: https://embedded.improvado.io/api/v3/extracts/{id}
Tags: Extracts

Allows to update scheduling, fields, additional parameters and sync_historical_data attributes values for existing extraction.

Parameters:
- `id` (path) (required) — Extract ID

Request body:
- Content-Type: application/json
  - `scheduling` (array)
  - `fields` (array)
  - `additional_params` (object)
  - `sync_historical_data` (string)

Responses:
- 200: Update an Extract
- 400: Bad Request
- 401: Forbidden

### PATCH /api/v3/extracts/{id}
**Update an extract partially**
URL: https://embedded.improvado.io/api/v3/extracts/{id}
Tags: Extracts

Allows to partially update scheduling, fields, additional parameters and sync_historical_data attributes values for existing extraction. Only provided fields will be updated, omitted fields will remain unchanged.

Parameters:
- `id` (path) (required) — Extract ID

Request body:
- Content-Type: application/json
  - `scheduling` (array)
  - `fields` (array)
  - `additional_params` (object)
  - `sync_historical_data` (string)

Responses:
- 200: Partially Update an Extract
- 400: Bad Request
- 401: Forbidden

### POST /api/v3/extracts/{id}/run
**Run an extract**
URL: https://embedded.improvado.io/api/v3/extracts/{id}/run
Tags: Extracts

Manual run an extract with custom date range

Parameters:
- `id` (path) (required) — Extract ID

Request body:
- Content-Type: application/json
  - `date_from` (string) — Start date for the extract run
  - `date_to` (string) — End date for the extract run

Responses:
- 200: Run an Extract
- 400: Bad Request
- 401: Forbidden

### POST /api/v3/extracts/{extract_id}/pause
**Pause an extract**
URL: https://embedded.improvado.io/api/v3/extracts/{extract_id}/pause
Tags: Extracts

Pauses extract so it wont download data from datasource until it’s unpaused

Parameters:
- `extract_id` (path) (required) — Extract ID

Responses:
- 204: Pause an Extract
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### POST /api/v3/extracts/{extract_id}/unpause
**Unpause an extract**
URL: https://embedded.improvado.io/api/v3/extracts/{extract_id}/unpause
Tags: Extracts

Unpauses extract so it starts to download data from datasource

Parameters:
- `extract_id` (path) (required) — Extract ID

Responses:
- 204: Unpause an Extract
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### POST /api/v3/extracts/migrate-wide
**Migrate a wide report extract**
URL: https://embedded.improvado.io/api/v3/extracts/migrate-wide
Tags: Extracts

Migrates a wide report extract with changed dimensions to a new extract with a new data table. The new extract is linked to the source extract and the source extract is paused; its data and data table remain queryable. Every omitted `template_settings` field is pre-filled from the source extract, so only the settings being changed need to be passed. `template_id` and `account` are resolved from the source extract when omitted; a data table title is generated when `data_table_title` is empty.

Request body:
- Content-Type: application/json
  - Schema: MigrateWideExtractRequest

Responses:
- 200: The newly created extract detail
- 400: Bad Request - Invalid request parameters, the source extract is not a wide report or dimensions were not changed.
- 401: Forbidden
- 404: Not Found

### GET /api/v3/destinations
**List of destinations**
URL: https://embedded.improvado.io/api/v3/destinations
Tags: Destinations

List destinations with short info. Paginated response is ordered by the name field.

Responses:
- 200: Get a list of Destinations
- 401: Forbidden

### GET /api/v3/destinations/{destination_name}/connections
**List destination connections**
URL: https://embedded.improvado.io/api/v3/destinations/{destination_name}/connections
Tags: Destination connections

List destination connections

Parameters:
- `destination_name` (path) (required) — Destination name

Responses:
- 200: List of destination connections
- 400: Bad Request
- 401: Forbidden

### POST /api/v3/destinations/{destination_name}/connections
**Create a connection**
URL: https://embedded.improvado.io/api/v3/destinations/{destination_name}/connections
Tags: Destination connections

Create a destination connection of a given type

Parameters:
- `destination_name` (path) (required) — Destination name

Request body:
- Content-Type: application/json
  - `title` (string) — Connection title
  - `create_load_for_new_tables` (boolean) — Create load for new tables
  - `destination_name` (string) — Destination name
  - `conenctions_params` (object) — Connection params

Responses:
- 201: Create a Connection
- 400: Bad Request
- 401: Forbidden

### GET /api/v3/destinations/{destination_name}/connections/{id}
**Get a connection**
URL: https://embedded.improvado.io/api/v3/destinations/{destination_name}/connections/{id}
Tags: Destination connections

Get detailed info about destination connection

Parameters:
- `destination_name` (path) (required) — Destination name
- `id` (path) (required) — Destination Connection ID

Responses:
- 200: Get a Connection
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### PATCH /api/v3/destinations/{destination_name}/connections/{id}
**Update a connection**
URL: https://embedded.improvado.io/api/v3/destinations/{destination_name}/connections/{id}
Tags: Destination connections

Allows to update create_load_for_new_tables value for destination connection

Parameters:
- `destination_name` (path) (required) — Destination name
- `id` (path) (required) — Destination Connection ID

Request body:
- Content-Type: application/json
  - `create_load_for_new_tables` (boolean)

Responses:
- 200: Update a Connection
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### PUT /api/v3/destinations/{destination_name}/connections/{id}
**Reauthorize a connection**
URL: https://embedded.improvado.io/api/v3/destinations/{destination_name}/connections/{id}
Tags: Destination connections

Reauthorize an existing destination connection

Parameters:
- `destination_name` (path) (required) — Destination name
- `id` (path) (required) — Destination Connection ID

Request body:
- Content-Type: application/json
  - `title` (string) — Connection title
  - `connection_params` (object) — Connection params

Responses:
- 200: Reauthorize a Connection
- 400: Bad Request
- 401: Forbidden

### PUT /api/v3/destinations/{destination_name}/connections/{destination_connection_id}/recheck
**Check connection status**
URL: https://embedded.improvado.io/api/v3/destinations/{destination_name}/connections/{destination_connection_id}/recheck
Tags: Destination connections

Starts a manual status check of a destination connection. If a destination connection has invalid or staled connection credentials – the system will mark this destination connection as invalid for future loads.

Parameters:
- `destination_name` (path) (required) — Destination name
- `destination_connection_id` (path) (required) — Destination Connection ID

Responses:
- 200: Recheck a Connection
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### GET /api/v3/data-tables
**List data tables**
URL: https://embedded.improvado.io/api/v3/data-tables
Tags: Data tables

List data tables

Responses:
- 200: Get a list of data tables
- 401: Forbidden

### GET /api/v3/data-tables/{data_table_id}
**Get a data table**
URL: https://embedded.improvado.io/api/v3/data-tables/{data_table_id}
Tags: Data tables

Get detailed info about data table

Parameters:
- `data_table_id` (path) (required) — Data Table ID

Responses:
- 200: Get a Data Table
- 401: Forbidden
- 404: Not Found

### PUT /api/v3/data-tables/{data_table_id}
**Update a data table**
URL: https://embedded.improvado.io/api/v3/data-tables/{data_table_id}
Tags: Data tables

Updates which fields (columns) of the data table are selected for delivery. `selected_fields` must contain 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 — omitting a dimension field from `selected_fields` returns `400`. Fields the detail endpoint returns with `can_edit: false` are not meant to be toggled and should always be included in `selected_fields`.

Parameters:
- `data_table_id` (path) (required) — Data Table ID

Request body:
- Content-Type: application/json
  - `selected_fields` (array) — Full list of field `name` values that should be selected. Any field of the data table not listed becomes deselected.

Responses:
- 200: Update a Data Table
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### GET /api/v3/loads
**List loads**
URL: https://embedded.improvado.io/api/v3/loads
Tags: Loads

List all loads

Parameters:
- `data_table_id` (query) — Data Table ID
- `destination_connection_id` (query) — Destination Connection ID
- `destination_name` (query) — Destination Name

Responses:
- 200: Get a list of Loads

### POST /api/v3/loads
**Create a load**
URL: https://embedded.improvado.io/api/v3/loads
Tags: Loads

Creates a new load. A load creation request is composed of Data Table and Destination Connection data.

**Validation rules:**
- When `run_policy` is `"schedule"`, `schedules` must contain at least one entry.
- When `run_policy` is `"after extraction"`, `schedules` must be empty or omitted.

Request body:
- Content-Type: application/json
  - `data_table_id` (integer) — Data Table ID
  - `destination_connection_id` (string) — Destination Connection ID (UUID)
  - `destination_table` (string) — Destination Table
  - `run_policy` (string) — When the load runs:
- `after extraction` — runs automatically after the related extract finishes.
- `schedule` — runs on the recurring schedule(s) defined in `schedules`.

  - `schedules` (array) — Required when `run_policy` is `schedule`. Must be empty or omitted when `run_policy` is `after extraction`.
  - `load_historical_data` (boolean) — When `true`, the initial load run will backfill historical data for the data table.

Responses:
- 200: Create a Load
- 401: Forbidden

### GET /api/v3/loads/{load_id}
**Get a load**
URL: https://embedded.improvado.io/api/v3/loads/{load_id}
Tags: Loads

Get detailed info about load

Parameters:
- `load_id` (path) (required) — Load ID

Responses:
- 200: Get a Load
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### PUT /api/v3/loads/{load_id}
**Update a load**
URL: https://embedded.improvado.io/api/v3/loads/{load_id}
Tags: Loads

Allows to update load run policy or scheduling

Parameters:
- `load_id` (path) (required) — Load ID

Request body:
- Content-Type: application/json
  - `run_policy` (string) — When the load runs:
- `after extraction` — runs automatically after the related extract finishes.
- `schedule` — runs on the recurring schedule(s) defined in `schedules`.

  - `schedules` (array) — Required when `run_policy` is `schedule`. Must be empty or omitted when `run_policy` is `after extraction`.

Responses:
- 200: Update a Load
- 400: Bad Request
- 401: Forbidden

### DELETE /api/v3/loads/{load_id}
**Delete a load**
URL: https://embedded.improvado.io/api/v3/loads/{load_id}
Tags: Loads

Allows to delete load. Already loaded data will remain in customer’s destination.

Parameters:
- `load_id` (path) (required) — Load ID

Responses:
- 204: Delete a Load
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### PUT /api/v3/loads/{id}/pause
**Pause a load**
URL: https://embedded.improvado.io/api/v3/loads/{id}/pause
Tags: Loads

Allows to pause load so it will not load data to customer’s destination until it is unpaused.

Parameters:
- `id` (path) (required) — Load ID

Responses:
- 204: Pause a Load
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### PUT /api/v3/loads/{id}/unpause
**Unpause a load**
URL: https://embedded.improvado.io/api/v3/loads/{id}/unpause
Tags: Loads

Allows to unpaused load so it will continue to load data to customer’s destination.

Parameters:
- `id` (path) (required) — Load ID

Responses:
- 204: Unpause a Load
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### PUT /api/v3/loads/{id}/run
**Run a load**
URL: https://embedded.improvado.io/api/v3/loads/{id}/run
Tags: Loads

Allows to manually run data load into customer’s destination.
Optionally provide `date_from` and `date_to` in the request body to run the load
for a specific date range. Both fields must be provided together.
Date range is ignored for loads by accounts.

Parameters:
- `id` (path) (required) — Load ID

Request body:
- Content-Type: application/json
  - `date_from` (string) — Start date for the load run (YYYY-MM-DD). Must be used together with date_to.
  - `date_to` (string) — End date for the load run (YYYY-MM-DD). Must be used together with date_from.

Responses:
- 204: Run a Load
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### GET /api/v3/automated-recipe-templates
**List automated recipe templates**
URL: https://embedded.improvado.io/api/v3/automated-recipe-templates
Tags: Recipes

Returns a paginated list of available automated recipe templates that can be used to create automated recipes.

Parameters:
- `page` (query) — Page number for pagination
- `page_size` (query) — Number of results per page (max 100)
- `search` (query) — Search templates by name
- `data_sources` (query) — Filter by data sources (comma-separated list, e.g., "google_analytics,facebook_ads")

Responses:
- 200: List of automated recipe templates
- 401: Forbidden

### GET /api/v3/automated-recipe-templates/{template_id}
**Get automated recipe template detail**
URL: https://embedded.improvado.io/api/v3/automated-recipe-templates/{template_id}
Tags: Recipes

Returns detailed information about a specific automated recipe template, including its tree structure and dependencies.

Parameters:
- `template_id` (path) (required) — Automated recipe template ID

Responses:
- 200: Automated recipe template details
- 401: Forbidden
- 404: Not Found

### GET /api/v3/automated-recipes
**List automated recipes**
URL: https://embedded.improvado.io/api/v3/automated-recipes
Tags: Recipes

Returns a paginated list of automated recipes in the workspace.

Parameters:
- `template_id` (query) — Filter by template ID
- `state` (query) — Filter by recipe state
- `page` (query) — Page number for pagination
- `page_size` (query) — Number of results per page (max 100)

Responses:
- 200: List of automated recipes
- 401: Forbidden

### POST /api/v3/automated-recipes
**Create automated recipe**
URL: https://embedded.improvado.io/api/v3/automated-recipes
Tags: Recipes

Creates a new automated recipe from a template.

Request body:
- Content-Type: application/json
  - `template_id` (integer) — ID of the automated recipe template
  - `title` (string) — Recipe name. If not specified, template name is used

Responses:
- 201: Automated recipe created successfully
- 400: Bad Request
- 401: Forbidden
- 403: Forbidden

### GET /api/v3/automated-recipes/{recipe_id}
**Get automated recipe detail**
URL: https://embedded.improvado.io/api/v3/automated-recipes/{recipe_id}
Tags: Recipes

Returns detailed information about a specific automated recipe, including its configuration and connections.

Parameters:
- `recipe_id` (path) (required) — Automated recipe ID (numeric string)

Responses:
- 200: Automated recipe details
- 401: Forbidden
- 404: Not Found

### PUT /api/v3/automated-recipes/{recipe_id}
**Update automated recipe configuration**
URL: https://embedded.improvado.io/api/v3/automated-recipes/{recipe_id}
Tags: Recipes

Updates the configuration of an automated recipe, including data sources, connections, and sync settings.

Parameters:
- `recipe_id` (path) (required) — Automated recipe ID (numeric string)

Request body:
- Content-Type: application/json
  - Schema: AutomatedRecipeUpdateRequest

Responses:
- 200: Recipe configuration updated successfully (empty body)
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### POST /api/v3/automated-recipes/{recipe_id}/build
**Build automated recipe**
URL: https://embedded.improvado.io/api/v3/automated-recipes/{recipe_id}/build
Tags: Recipes

Triggers the build process for an automated recipe. The recipe will transition through states (Extracting Data -> Building Dependencies -> Ready To Work or Failed).

Parameters:
- `recipe_id` (path) (required) — Automated recipe ID (numeric string)

Responses:
- 200: Build started successfully
- 400: Bad Request
- 401: Forbidden
- 404: Not Found

### GET /api/v3/webhook_endpoints/
**List webhook endpoints**
URL: https://embedded.improvado.io/api/v3/webhook_endpoints/
Tags: Webhooks

List webhook endpoints registered in the current workspace.

Responses:
- 200: A paginated list of webhook endpoints
- 401: Authentication credentials were not provided.
- 403: Embedded API is not enabled for this agency, or workspace header is missing.

### POST /api/v3/webhook_endpoints/
**Create a webhook endpoint**
URL: https://embedded.improvado.io/api/v3/webhook_endpoints/
Tags: Webhooks

Register a new webhook endpoint and subscribe it to one or more event types. The endpoint is created
in `unverified` status and a fresh `secret` is returned in the response. Use the `verify` action to
activate the endpoint.

> **Important:** `event_types` must contain identifiers returned by `GET /api/v3/webhook_event_types/`
> (e.g. `load_completed`, `transformation_completed`). Unknown event names are accepted by the
> request but no deliveries will be sent for them — always source the names from the event types
> endpoint rather than hard-coding them.

Request body:
- Content-Type: application/json
  - Schema: WebhookEndpointCreateRequest

Responses:
- 201: Webhook endpoint created
- 400: Validation error
- 401: Authentication credentials were not provided.
- 403: Embedded API is not enabled for this agency, or workspace header is missing.

### GET /api/v3/webhook_endpoints/{id}/
**Get a webhook endpoint**
URL: https://embedded.improvado.io/api/v3/webhook_endpoints/{id}/
Tags: Webhooks

Retrieve detailed information about a webhook endpoint, including its current subscriptions and signing secret.

Parameters:
- `id` (path) (required) — Webhook endpoint ID

Responses:
- 200: Webhook endpoint detail
- 401: Authentication credentials were not provided.
- 404: Webhook endpoint not found

### PATCH /api/v3/webhook_endpoints/{id}/
**Update a webhook endpoint**
URL: https://embedded.improvado.io/api/v3/webhook_endpoints/{id}/
Tags: Webhooks

Partially update a webhook endpoint. Either field may be omitted.

- Setting `event_types` **replaces** the full list of subscriptions for this endpoint.
- Updating either field resets the endpoint status to `unverified`; you must call `verify` again before the endpoint will receive events.

Parameters:
- `id` (path) (required) — Webhook endpoint ID

Request body:
- Content-Type: application/json
  - Schema: WebhookEndpointUpdateRequest

Responses:
- 200: Webhook endpoint updated
- 400: Validation error
- 401: Authentication credentials were not provided.
- 404: Webhook endpoint not found

### DELETE /api/v3/webhook_endpoints/{id}/
**Delete a webhook endpoint**
URL: https://embedded.improvado.io/api/v3/webhook_endpoints/{id}/
Tags: Webhooks

Permanently delete a webhook endpoint and all of its subscriptions. Pending and in-flight deliveries for this endpoint are abandoned.

Parameters:
- `id` (path) (required) — Webhook endpoint ID

Responses:
- 204: Deleted
- 401: Authentication credentials were not provided.
- 404: Webhook endpoint not found

### POST /api/v3/webhook_endpoints/{id}/verify/
**Verify a webhook endpoint**
URL: https://embedded.improvado.io/api/v3/webhook_endpoints/{id}/verify/
Tags: Webhooks

Trigger ownership verification of the endpoint URL.

Improvado sends a `GET` request to the endpoint URL with the headers:

- `X-Improvado-Verify-Token` — the endpoint's signing secret
- `X-Improvado-Challenge` — a one-time random token

The receiver must respond with HTTP 200 and the value of `X-Improvado-Challenge` as the response body.
On success, the endpoint transitions to `active`. On failure (non-200 status, mismatching body, or
connection error), the endpoint remains `unverified` and a 400 is returned.

Parameters:
- `id` (path) (required) — Webhook endpoint ID

Responses:
- 200: Endpoint verified successfully (status is now `active`)
- 400: Verification failed (unreachable URL, non-200 response, or challenge mismatch)
- 401: Authentication credentials were not provided.
- 404: Webhook endpoint not found

### POST /api/v3/webhook_endpoints/{id}/regenerate_secret/
**Rotate the signing secret**
URL: https://embedded.improvado.io/api/v3/webhook_endpoints/{id}/regenerate_secret/
Tags: Webhooks

Generate a new signing secret for the endpoint. The previous secret is invalidated immediately and
the endpoint is reset to `unverified` status, so the endpoint must be re-verified before it will
receive further events. Update your receiver to use the new secret before re-verification.

Parameters:
- `id` (path) (required) — Webhook endpoint ID

Responses:
- 200: Secret rotated; the new secret is in the response body.
- 401: Authentication credentials were not provided.
- 404: Webhook endpoint not found

### GET /api/v3/webhook_event_types/
**List available webhook event types**
URL: https://embedded.improvado.io/api/v3/webhook_event_types/
Tags: Webhooks

List event types that can be subscribed to via `event_types` when creating or updating a webhook endpoint.

Responses:
- 200: List of supported event types
- 401: Authentication credentials were not provided.

### GET /api/v3/roles/
**List roles**
URL: https://embedded.improvado.io/api/v3/roles/
Tags: Roles

Returns every role visible to the agency: non-internal system roles
(Workspace Admin, Editor, Viewer, etc.) plus all agency-scoped custom roles.
Each entry carries `user_count` — the number of users currently assigned to that role.

Responses:
- 200: List of roles
- 401: Authentication credentials were not provided.
- 403: Agency does not have embedded API enabled, or caller is not an agency chief.

### POST /api/v3/roles/
**Create a custom role**
URL: https://embedded.improvado.io/api/v3/roles/
Tags: Roles

Creates a new agency-scoped custom role. The role's title must be unique within the agency
and every `(layer, permission)` pair must come from the catalog (`GET /api/v3/roles/permissions`).

Request body:
- Content-Type: application/json
  - Schema: RoleWriteRequest

Responses:
- 201: Role created
- 400: Invalid payload (empty title, unknown layer/permission, etc.)
- 409: A role with the same title already exists in this agency.

### GET /api/v3/roles/permissions
**Permissions catalog**
URL: https://embedded.improvado.io/api/v3/roles/permissions
Tags: Roles

Curated catalog of product layers and the permissions that can be granted on each.
Stable display order; `title`/`description` are human-readable and safe to render directly.

Responses:
- 200: Catalog of layers and permissions.
- 401: Authentication credentials were not provided.

### GET /api/v3/roles/{role_id}
**Get a role**
URL: https://embedded.improvado.io/api/v3/roles/{role_id}
Tags: Roles

Returns one role. Visible to the agency only if it's a non-internal system role
or an agency-scoped custom role belonging to the calling agency.

Parameters:
- `role_id` (path) (required) — Role ID

Responses:
- 200: Role detail
- 404: Role not found.

### PATCH /api/v3/roles/{role_id}
**Update a custom role**
URL: https://embedded.improvado.io/api/v3/roles/{role_id}
Tags: Roles

Update an agency-scoped custom role's title, description, and permission set.
System roles are read-only and cannot be modified.

Parameters:
- `role_id` (path) (required)

Request body:
- Content-Type: application/json
  - Schema: RoleWriteRequest

Responses:
- 200: Updated role
- 400: Invalid payload.
- 403: System roles cannot be modified.
- 404: Role not found.
- 409: Another role in this agency already uses this title.

### DELETE /api/v3/roles/{role_id}
**Delete a custom role**
URL: https://embedded.improvado.io/api/v3/roles/{role_id}
Tags: Roles

Delete an agency-scoped custom role. **Users currently assigned to it are atomically
reassigned to the system Viewer role**; the response returns how many were moved.
System roles cannot be deleted.

Parameters:
- `role_id` (path) (required)

Responses:
- 200: Role deleted; affected users reassigned to Viewer.
- 403: System roles cannot be deleted.
- 404: Role not found.

### GET /api/v3/roles/{role_id}/users
**List users assigned to a role**
URL: https://embedded.improvado.io/api/v3/roles/{role_id}/users
Tags: Roles

Returns the users currently holding the role, with their workspace assignment.
Useful for impact preview before editing or deleting the role.

Parameters:
- `role_id` (path) (required)

Responses:
- 200: Users assigned to the role.
- 404: Role not found.