# Tools reference

!!!danger Private beta: access through the IAMP platform only
The Quable MCP server is a **private beta** and **not a public API**. Access is only authorized through the **IAMP platform**: any other access is not authorized. **Any tool, prompt, resource, parameter or behavior can change or be removed at any time, without notice.**
!!!

At the time of writing, the Quable MCP server exposes **35 tools**, **2 prompts** and a few **resources**. Your AI assistant reads the description of each tool and chooses which one to call: you normally don't call tools yourself, but knowing them helps you write precise requests and understand what the assistant does.

!!!info Conventions
- **Codes, not labels.** Every identifier parameter expects the exact code (`fr_FR`, `reference_color`, `completeness_e_commerce`), never a display label. The `list_*` and `search_*` tools resolve labels to codes.
- **`locale`** on most tools sets the `X-Quable-Locale` header: the language of translated labels in the response and the locale in which filters are evaluated. It does not select which data languages are written or returned.
- **JSON parameters.** Parameters described as *JSON string* expect a serialized JSON object or array, e.g. `'{"fr_FR": "Rouge"}'`.
- :icon-pencil: marks a **write tool**. Each one tells the assistant to confirm with you before calling it, and fails with a *Read access* token.
!!!

---

## Overview

| Domain | Tools |
| --- | --- |
| [Session and server](#session-and-server) | `test_credentials`, `get_user_info`, `server_time`, `get_pim_url`, `skill_word_count` |
| [Catalog structure](#catalog-structure) | `list_locales`, `list_document_types`, `list_completenesses`, `list_attributes`, `search_classification`, `search_attribute-sets`, `update_attribute-set` |
| [Products](#products) | `get_product`, `search_products`, `create_product`, `update_product` |
| [Variants](#variants) | `get_variant`, `search_variants`, `create_variant`, `update_variant` |
| [Assets](#assets) | `get_asset`, `get_asset_file`, `search_asset`, `update_asset` |
| [Select options](#select-options) | `list_predefined-values`, `update_predefined-value` |
| [Links](#links) | `add_asset_to_product`, `remove_asset_from_product`, `add_link`, `remove_link` |
| [Exports](#exports) | `list_export_profiles`, `get_export_options`, `trigger_export`, `get_export_status`, `get_export_file` |

---

## Session and server

### test_credentials

Checks that the instance name and token sent in the headers are valid. Use it to test a new connection.

**Parameters:** none.
**Returns:** `{"status": "valid credential"}`, or an authentication error.

### get_user_info

Returns the profile of the token's user. Call it at the start of a session so the assistant knows which locale to use by default.

**Parameters:** none.
**Returns:** `localesAvailable` (active data locales), `localeDefault`, `localeI18nDefault` (interface language), permissions (`permissionFeatures`, `permissionField`, `permissionCatalog`, `damPermissionCatalog`), `admin`, `active`, `timezone`, `username`, `email`, `firstName`, `lastName`, `dateLogged`.

### server_time

Returns the current UTC time of the server. Does not call your instance and needs no authentication.

**Returns:** `{"utc_now": "2026-11-19T10:42:00+00:00"}`

### get_pim_url

Builds a clickable link to a product or asset page in the Quable PIM interface.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `entity_type` | `product` \| `asset` | yes | Kind of page. |
| `legacy_id` | string or number | yes | The numeric `legacy_id` found in tool results. **Not** the product or asset code. |

**Returns:** `{"url": "https://your-instance.quable.com/#classification/product-new/12345/edit"}`. A missing or non-numeric `legacy_id` returns an error: the tool never guesses a link.

### skill_word_count

Counts the visible words of a text. HTML tags, comments and scripts are removed and entities decoded first, so a rich-text value counts only what a reader sees. Useful to check the length of a generated description. Needs no authentication.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | yes | Text or HTML to count. |

**Returns:** `{"word_count": 128}`

---

## Catalog structure

These tools tell the assistant how your PIM is configured. Most of them are called by the [`pim-bootstrap`](#prompts) prompt.

### list_locales

Lists the active data locales of the instance.

**Parameters:** none.
**Returns:** a list of `{id, label, fallback?}`. `id` is the code to use in other tools (e.g. `fr_FR`). `fallback` is the locale used when a value is missing.

### list_document_types

Lists document types (product types) and link types.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `locale` | string | no | Language of the `name` field (e.g. `fr-FR`). Default `en-US`. |

**Returns:** `{document_types: [{id, name, object_type, has_variant}], link_types: [{id, name}]}`. `has_variant` tells whether the type accepts variants. Link type `id`s are used by `add_link` and `remove_link`.

### list_completenesses

Lists the completeness rules configured on the instance. It does **not** return scores: read them on a product with `get_product` (view `completeness`) or filter with `search_products`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `locale` | string | no | Language of the `name` field. Default `en-US`. |

**Returns:** a list of `{id, name, document_type, required_attributes, required_links: [{id, minimum}]}`.

### list_attributes

Finds attribute codes, for example from an approximate name.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | no | Case-insensitive filter on code and name. |
| `document_type_id` | string | no | Restrict to one document type. Without it, attributes of all types are returned. |
| `locale` | string | no | Language of the `name` field. Default `en-US`. |

**Returns:** a list of `{id, name, type, documentTypeId, group}`. Types `simple_select` and `multi_select` are select attributes (also called *combo* and *multicombo*): use [`list_predefined-values`](#list_predefined-values) to get their options.

!!!
`list_attributes` works on document types only, not on link types.
!!!

### search_classification

Resolves classification (category) ids from a name or id.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | no | Matched on id and labels in every locale, ignoring case, accents, `-` and `_`. |
| `classification_id` | string | no | One id, or several comma-separated. Unknown ids are returned in `missing_ids`. |
| `catalog_id` | string | no | Restrict to one catalog, e.g. `PIM` for product classifications. Other catalogs are channels or DAM folders. |
| `locale` | string | no | Language of `label` and `path`. |
| `limit` | integer | no | Page size, default 30, max 50. |
| `offset` | integer | no | Start position, default 0. |

**Returns:** `{items: [{id, label, path, parent_id, catalog_id, active, legacy_id}], total, returned, offset, missing_ids}`. Labels are not unique: the same name can exist under several parents, so check `path`.

### search_attribute-sets

Lists attribute sets, i.e. which attributes apply to the products of a document type and count for completeness.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | Filter on the set id (case-insensitive). |
| `search` | string | no | Partial match on id and name. |
| `document_type_id` | string | no | Restrict to one document type. |
| `locale` | string | no | Language of the `name` field. |
| `limit` | integer | no | Max rows, default 50. |

**Returns:** `{items: [{id, code, name, document_type_id, attributes}], total, returned}`. `attributes` lists the attribute codes of the set.

### update_attribute-set :icon-pencil:

Creates or updates an attribute set. Idempotent by `code`.

!!!danger Data model change
An attribute set controls which attributes are visible on every product of a type, cascades to variants and changes completeness scores. Inspect the current state with `search_attribute-sets` first.
!!!

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | Attribute set id. |
| `labels` | JSON string | on create | Locale → label, e.g. `{"en-US": "Jacket attributes", "fr-FR": "Attributs veste"}`. Merged with existing labels on update. |
| `document_type_id` | string | on create | Document type of the set. Cannot be changed afterwards. |
| `attributes` | JSON string | no | Array of attribute codes, e.g. `["attr_color", "attr_size"]`. **Replaces** the composition. Omit it to keep the current one. An empty array is rejected. |

---

## Products

### get_product

Reads one product (document) by its exact id. To read several known products, the assistant calls it once per id rather than searching.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `product_id` | string | yes | Exact document id. |
| `views` | array | no | Sections to return: `basic`, `attributes`, `classifications`, `tags`, `completeness`, `links`, `assets`, `variants`, `workflow`. `basic` is always included. |
| `output_locales` | string | no | Comma-separated data locales to keep, e.g. `fr_FR,en_US`. Default: all active locales. |
| `attributes` | string | no | Comma-separated attribute codes to keep. Requires `attributes` in `views`. |
| `locale` | string | no | Interface locale for translated labels. |

**Returns:** the `basic` view (`id`, `documentType`, `active`, `attributeSet`, `dateCreated`, `dateModified`, `mainAssetThumbnailUrl`, `legacy_id`) plus the requested sections, and a `_meta` block:

```json
{
  "id": "REF-001",
  "attributes": { "product_name": { "fr_FR": "Veste", "en_GB": "Jacket" } },
  "completenesses": { "completeness_e_commerce": { "fr_FR": 85, "en_GB": 100 } },
  "_meta": {
    "views": { "used": ["basic", "attributes", "completeness"], "omitted": ["links", "assets", "..."] },
    "output_locales": { "used": ["fr_FR", "en_GB"], "omitted": [] }
  }
}
```

Section keys in the result: `completeness` → `completenesses`, `links` → `documentLinks`, `assets` → `assetLinks`, `workflow` → `workflows`. In `_meta`, *omitted* means *not requested*, not *does not exist*.

### search_products

Searches and filters products when their ids are not known.

| Parameter | Type | Description |
| --- | --- | --- |
| `search` | string or array | A string runs a full-text search. A list of up to 8 filename tokens (e.g. `["tshirt_red", "4568"]`) runs *orphan matching*: it returns scored `matches` (with `matched_on`, `score`, `legacy_id`) and `no_match` instead of `items`. |
| `include_variants` | boolean | With a token list, also match variant codes. |
| `document_type_id` | string | Filter on document type. |
| `classification_id` | string | Filter on one classification. |
| `classification_ids` | string | Several classifications, as `["id1","id2"]` or `id1,id2`. |
| `completeness_id` | string | Completeness rule to filter on. Requires `completeness_locale` and `completeness_value`. |
| `completeness_locale` | string | Locale the completeness filter is evaluated in, e.g. `fr_FR`. |
| `completeness_value` | string | Score, e.g. `100`. Exact match unless `completeness_operator` is set. |
| `completeness_operator` | `gt` \| `gte` \| `lt` \| `lte` | Turns `completeness_value` into a threshold. |
| `attribute_filters` | JSON object or string | See [Attribute filters](#attribute-filters). |
| `attribute_filter_string` | string | Raw REST API query string. Takes precedence over `attribute_filters`. |
| `sort_by` | `dateCreated` \| `dateModified` \| `id` \| `documentType` | Sort on a document field. |
| `sort_by_completeness` | string | Sort on a completeness rule's score, in the locale given by `locale`. |
| `sort_by_attribute` | string | Sort on an attribute value. |
| `order_direction` | `asc` \| `desc` | Default `desc`. |
| `limit` / `offset` | integer | Pagination, default 20 / 0. `limit` is capped at 50. |
| `locale` | string | Locale in which filters and sorts are evaluated when the field has no locale of its own. |
| `views`, `output_locales`, `attributes` | | Same as [`get_product`](#get_product), applied to each item. |

Set at most **one** of `sort_by`, `sort_by_completeness` and `sort_by_attribute`.

**Returns:** `{items, total, limit, offset, _meta}`.

**Example:** the 10 products with the best Spanish e-commerce score, without filtering:

```json
{
  "sort_by_completeness": "completeness_e_commerce",
  "order_direction": "desc",
  "locale": "es_ES",
  "limit": 10
}
```

#### Attribute filters

Used by `search_products`, `search_asset` and `search_variants`:

| Filter | Meaning |
| --- | --- |
| `{"color": "red"}` | Exact value |
| `{"color": ""}` | Value is missing |
| `{"color": ["red", "blue"]}` | Any of the values |
| `{"date_expiration": {"before": "2026-08-31"}}` | Before a date (also `"now"`) |
| `{"date_launch": {"after": "now"}}` | After a date |
| `{"name": {"contains": "jacket"}}` | Contains a text, `search_variants` only |

### create_product :icon-pencil:

Creates a product with its classification, attribute set and values.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document_code` | string | yes | New unique code. Refused if already used. |
| `document_type_id` | string | yes | Document type, from `list_document_types`. |
| `document_name` | string | yes | Product name, written to the `<document_type_id>_name` attribute. |
| `classification` | string | yes | Classification id, from `search_classification`. |
| `attribute_set` | string | yes | Attribute set of that type, from `search_attribute-sets`. |
| `attributes` | JSON string | no | Attribute values, same [formats](#attribute-value-formats) as `update_product`. Each attribute must belong to the type and to the attribute set. |
| `locale` | string | no | Locale of `document_name`. Default: the user's locale. |

Invalid input is refused before anything is created.
**Returns:** `{status, message, document, missing_required, not_persisted}`. `missing_required` lists required attributes still empty. `not_persisted` lists values the PIM did not store: retry them with `update_product`.

### update_product :icon-pencil:

Partially updates a product: only the keys you send change. If the PIM does not persist a value (for example a character limit is exceeded), the tool returns an error instead of reporting success.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document_id` | string | yes | Exact document id. |
| `attributes` | JSON string | yes | Payload, see below. |
| `locale` | string | no | Interface locale of the returned document. Does not choose which locale is written. |

Top-level keys of the payload:

| Key | Description |
| --- | --- |
| `attributes` | Attribute code → value, see [formats](#attribute-value-formats). |
| `active` | Boolean. |
| `classification` | `{"id": "classification-id"}`, a single classification. |
| `attributeSet` | `{"id": "attribute-set-id"}` |
| `id` | Optional. Omit it or set it to `document_id`. **A different value renames the product code.** |

The document type cannot be changed after creation.

```json
{
  "attributes": {
    "product_description": { "fr_FR": "Nouvelle description", "en_GB": "New description" },
    "product_color": [{ "id": "red" }],
    "product_weight": 1.2
  }
}
```

**Returns:** `{status, message, document}`, where `document` has the same shape as `get_product`.

#### Attribute value formats

| Attribute type | Format | Example |
| --- | --- | --- |
| Text, translatable (`textfield`, `textarea`, `htmlEditor`) | Locale → value | `{"fr_FR": "Rouge", "en_GB": "Red"}` |
| Text, not translatable | String | `"ABC-123"` |
| Number | Number | `42.5` |
| Checkbox | Boolean or string | `true`, `"1"`, `"false"` |
| Date / time | String | `"2026-11-19 00:00:00"` / `"14:30"` |
| Single select (combo) | Array of exactly one option code | `[{"id": "red"}]` |
| Multi select (multicombo) | Array of option codes | `[{"id": "red"}, {"id": "blue"}]` |
| Raw (`brut`) | JSON string | `"[{\"key\": \"value\"}]"` |

To clear a value, send `null` or an empty string.

---

## Variants

### get_variant

Reads one variant (SKU) with every attribute of the variant type.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `variant_code` | string | yes | Variant code. Case and trailing spaces are ignored. |
| `locale` | string | no | Keep only this locale in translated values. Default: all locales. |

**Returns:** `{found, variant_code, legacy_id, product_code, name, active, sequence, date_created, date_modified, attributes, missing_required, assets: [{asset_id, link_type, sequence}]}`. `attributes` lists every attribute allowed by the parent's attribute set, `null` when never set. An unknown code returns `found: false` instead of an error.

### search_variants

Lists the variants of a product, or searches variants across the catalog.

| Parameter | Type | Description |
| --- | --- | --- |
| `product_code` | string | Parent product. Its variants are returned in sequence order. Omitted: all variants, by code. |
| `attribute_filters` | JSON object or string | See [Attribute filters](#attribute-filters). A select matches its option code or label. Unknown attributes are refused. |
| `fields` | array or string | Attribute codes to return. |
| `locale` | string | Locale in which text filters are evaluated. Default: the user's locale. |
| `limit` / `offset` | integer | Default 20 / 0, `limit` max 50. |

**Returns:** `{items: [{variant_code, legacy_id, product_code, name, active, sequence, attributes}], total, limit, offset}`.

### create_variant :icon-pencil:

Creates a variant under an existing product. The product's type must accept variants (`has_variant` in `list_document_types`).

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `product_code` | string | yes | Parent product code. |
| `variant_code` | string | yes | New unique code, max 150 characters. |
| `attributes` | JSON string | no | Variant attributes, same [formats](#attribute-value-formats) as `update_product`, e.g. `{"quable_sku_name": {"fr_FR": "Veste M"}, "sku_ean": 3700000000001}`. |

A variant follows its parent's attribute set: values of attributes outside that set are refused.
**Returns:** `{status, message, variant: {id, legacy_id, product_code, name, sequence, active}, missing_required, not_persisted}`.

### update_variant :icon-pencil:

Changes attribute values of a variant. The code, parent and status are never changed.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `variant_code` | string | yes | Variant code. |
| `attributes` | JSON object or string | yes | Attribute code → value. |
| `locale` | string | no | Lets a translatable text be sent as a plain string for this locale. |

- A select is **replaced** by the full list sent, never merged. `[]` or `null` clears it.
- A translatable text only changes the locales sent.
- Values the PIM would drop or garble are refused before writing, and the result is read back.

**Returns:** `{status: "updated" | "partially_updated", message, variant_code, product_code, attributes, not_persisted, missing_required}`.

---

## Assets

### get_asset

Reads an asset's metadata: name, original filename, size, thumbnail and preview URLs, attributes, classifications and links. No file content.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_id` | string | yes | Asset code. |
| `locale` | string | no | Interface locale. |

### get_asset_file

Downloads an asset's content so the assistant can read it.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_id` | string | yes | Asset code. |
| `rendition` | `thumbnail` \| `original` | no | Default: `original` for PDF, CSV and spreadsheets, `thumbnail` otherwise. |
| `mode` | `auto` \| `text` \| `document` | no | PDF handling, default `auto`. |
| `locale` | string | no | Interface locale. |

What you get, by file type:

| Type | Result |
| --- | --- |
| **Image** | A native image block: the model sees the picture. The thumbnail is enough for recognition and tagging. |
| **PDF**, `mode: auto` or `text` | The text layer of the PDF, up to 75,000 characters (`truncated: true` beyond). `auto` returns an error for a scanned PDF with no text layer. |
| **PDF**, `mode: document` | The PDF itself as a document block. Keeps the layout (tables, columns) and works for scans, but costs more context. |
| **CSV, XLS, XLSX, XLSB, ODS** | `{mode: "table", format, sheets: [{name, rows, total_rows, total_columns}]}`. Formula cells hold their last computed value; dates are ISO 8601. |

Other file types are rejected: use `get_asset` for their metadata and URLs. See [size limits](/mcp-server/limits-and-troubleshooting/#size-limits).

### search_asset

Searches DAM assets.

| Parameter | Type | Description |
| --- | --- | --- |
| `query` | string | Full-text search. |
| `classification` | string | DAM folder (classification) id, or several comma-separated. |
| `tags` | string | Tag id, or several comma-separated. |
| `original_filename` | string | Filter on the uploaded filename. |
| `linked_to_document` | object | Assets linked to a product: `{"link_type": "article_images", "document_code": "SKU-1"}`. Both keys are required. |
| `orphans_only` | boolean | Only assets linked to no product or variant. |
| `created_after` / `created_before` | string | Creation date range. |
| `modified_after` / `modified_before` | string | Modification date range. |
| `attribute_filters` | JSON object or string | See [Attribute filters](#attribute-filters), e.g. `{"date_expiration": {"before": "now"}}` for expired assets. |
| `attribute_filter_string` | string | Raw REST API query string. Takes precedence over `attribute_filters`. |
| `sort_by` | `dateCreated` \| `dateModified` \| `id` \| `name` | Sort field. |
| `sort_order` | `asc` \| `desc` | Default `desc`. |
| `limit` / `offset` | integer | Pagination, default 20 / 0. |
| `locale` | string | Interface locale. |

**Returns:** a compact paginated list. Each item has a `legacy_id` for `get_pim_url`.

### update_asset :icon-pencil:

Partially updates an asset's attributes.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_code` | string | yes | Asset code, e.g. `800488-1_I_P.jpg`. |
| `attributes` | JSON string | yes | Attribute code → value, same [formats](#attribute-value-formats) as products. |
| `locale` | string | no | Interface locale. |

For select attributes on assets, prefer the shape returned by `get_asset`: an array of `{id, labels}`, where `id` is the option code.

```json
{
  "qua_asset_non_translatable_text": "Label",
  "qua_asset_textfield": { "fr_FR": "texte", "en_GB": null },
  "qua_asset_multicombo": [{ "id": "season_winter", "labels": { "en_GB": "Winter", "fr_FR": "Hiver" } }]
}
```

**Returns:** `{status, message, asset}`.

---

## Select options

### list_predefined-values

Lists the options of a select attribute (types `simple_select` / `multi_select`). Use it to find the code behind a label before filtering or updating, or to check that a code is free.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `attribute_id` | string | yes | Select attribute code, from `list_attributes`. |
| `search` | string | no | Case-insensitive filter on code or label. |
| `locale` | string | no | Locale used to fill `label`. All translations are always in `labels`. |

**Returns:** a list of `{code, attribute_id, labels, label, description, legacy_id}`.

### update_predefined-value :icon-pencil:

Creates or updates an option of a select attribute. Idempotent: creates the option when the code is new, updates its labels otherwise.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `attribute_id` | string | yes | Select attribute code. |
| `code` | string | yes | Option code. |
| `labels` | JSON string | yes | Locale → label, e.g. `{"en_GB": "Red tag", "fr_FR": "Tag rouge"}`. Merged with existing labels. |
| `description` | JSON string | no | Locale → description. |

**Returns:** `{status, message, predefined_value}`, where `status` says whether the option was created or updated.

---

## Links

### add_asset_to_product :icon-pencil:

Links an asset to a product. The product is the link origin, the asset the target.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_code` | string | yes | Asset code. |
| `document_code` | string | yes | Product code. |
| `link_type` | string | no | Link type id. Resolved automatically when only one product → asset link type exists. |
| `sequence` | integer | no | Position in the gallery, default 1. |
| `force` | boolean | no | Link even if the asset is already linked elsewhere. Default `false`. |
| `locale` | string | no | Interface locale. |

### remove_asset_from_product :icon-pencil:

Removes the link between an asset and a product.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `asset_code` | string | yes | Asset code. |
| `document_code` | string | yes | Product code. |
| `link_type` | string | no | Required only when several links exist between the two. |
| `locale` | string | no | Interface locale. |

### add_link :icon-pencil:

Creates a link of any type between two objects: product → product (cross-sell, upsell, replacement), product → asset, etc. One link per call.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `origin` | string | yes | Origin object code. |
| `target` | string | yes | Target object code. |
| `link_type` | string | yes | Link type **id** from `list_document_types` (`link_types`), never a label. |
| `locale` | string | no | Interface locale. |

If the link already exists, returns `already_linked: true` without creating a duplicate.

### remove_link :icon-pencil:

Removes a link of any type. One link per call. Give either `link_code`, or `origin` + `target` + `link_type`.

| Parameter | Type | Description |
| --- | --- | --- |
| `link_code` | string | Link id, for a direct deletion. |
| `origin` / `target` / `link_type` | string | Identify the link when its id is not known. |
| `locale` | string | Interface locale. |

If the link no longer exists, returns `already_removed: true` without an error.

---

## Exports

Exports are asynchronous and follow four steps. See the [export workflow](/mcp-server/workflows/#export-your-catalog).

### list_export_profiles

Lists the export profiles saved in the PIM, with their UUID for `trigger_export`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `search` | string | no | Search term passed to the export profiles API. |
| `locale` | string | no | Interface locale. |

### get_export_options

Step 1: discovers what can be exported.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `model` | string | no | Returns the exportable columns of this model. Must be qualified as `<base>.<type_id>`, e.g. `document.qua_document` or `link.<link_type_id>`. A bare `document` returns HTTP 400. |
| `extension` | `csv` \| `xlsx` | no | Returns the formatting options of this format. |
| `locale` | string | no | Interface locale. |

**Returns:** the allowed export models, plus columns and format options when requested.

### trigger_export

Step 2: starts an export and returns a `process_id` immediately. Give **exactly one** of `export_profile_id` or `export_profile`.

| Parameter | Type | Description |
| --- | --- | --- |
| `export_profile_id` | string | UUID of a saved profile, from `list_export_profiles`. |
| `export_profile` | JSON string | Inline profile, see below. |
| `locale` | string | Locale override. |
| `upload_location` | string | Remote delivery, e.g. `sftp://host/path` or `ftp://host/path`. The file is then not downloadable inline. |
| `callback` | JSON string | Webhook called when the export ends, e.g. `{"url": "https://example.com/hook", "headers": {"X-Token": "..."}}`. |
| `portal_id` | string | Portal to export from, if not the default one. |

Inline profile, all columns (default):

```json
{ "model": "document.qua_document", "extension": "csv", "locales": ["en_GB", "fr_FR"] }
```

Inline profile with a column selection (only when you ask for specific columns or headers):

```json
{
  "model": "document.qua_document",
  "extension": "csv",
  "locales": ["fr_FR"],
  "mappings": [
    { "attributeCode": "document_code", "attributeType": "unlocalized_text", "name": "document", "position": 0 }
  ]
}
```

For localized attributes in `mappings`, add the locale in parentheses after the code, e.g. `"qua_textfield (fr_FR)"`. Use `get_export_options` with `model` to get the exact column codes and types.

### get_export_status

Step 3: polls an export.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `process_id` | string | yes | From `trigger_export`. |
| `locale` | string | no | Interface locale. |

**Returns:** `{process_id, status, files: [{id, status}], startDate, endDate, hint}`. `status` is `pending`, `running`, `finished`, `failed` or `canceled`. `hint` tells the assistant what to do next: poll again in about 10 seconds, download the file, or report that the file was delivered to the remote location or that the export failed.

### get_export_file

Step 4: downloads the exported file.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `file_id` | string | yes | From `files[].id` in `get_export_status`. |
| `locale` | string | no | Interface locale. |

Quable delivers exports as a zip archive: the tool unzips it and returns the CSV or XLSX file itself (`filename`, `mimetype`, base64 content). Files above 250 KB return metadata only, with `too_large: true`. In that case, reduce the scope (fewer columns, locales or products), download the file from the Quable interface, or use `upload_location`.

---

## Prompts

Prompts are ready-made instructions the agent can load.

| Prompt | Description |
| --- | --- |
| `pim-bootstrap` | **Start here.** Tells the assistant to load your PIM structure (`get_user_info`, `list_locales`, `list_document_types`, `list_completenesses`) and to always use exact codes, never labels. |
| `server_status_prompt` | Asks the assistant to check the server's health and metadata. |

---

## Resources

| URI | Description |
| --- | --- |
| `server://info` | Server name, version and website. |
| `skill://pim-links/SKILL.md` | Guidance for the assistant on giving links to PIM pages with `get_pim_url`. |
| `skill://mcp-basics/SKILL.md` | Basic operational checks. |
