With the configento.app API you maintain your components from other systems: read, create and change groups, characteristics, values, rules, tiered prices and price matrices – and publish your changes. Typical uses are a PIM or ERP that transfers values and prices, or a script that adjusts many components at once.
This article gets you started. All endpoints with every field are in the API reference.
What the API can do – and what it can't
The API works with the same data as the editor in the admin. Whatever you create there, you can also create via the API, and vice versa.
Not possible via the API:
- Managing API keys, buying AI tokens and reading or renewing the credentials of the shop integrations – these stay in the admin.
- Webhooks: configento.app does not notify your system about changes. If you want to detect changes, query the versions of a component (see Versions).
- Reading the published state: the API always returns the draft – what is currently in the editor. See Draft and publishing.
The reference also lists endpoints under /storefront/…, /plugin/… and /webhooks/…. These are used by the shop plugins and the Service Portal with their own credentials; you cannot call them with an API key.
Creating an API key
Every request needs an API key. You create it in the admin under Settings → API:
- Enter a Key name, e.g. "PIM" or "ERP sync".
- Choose the Permission – Read only or Read & write.
- With Read & write, optionally tick Publish and/or AI.
- Optionally set a date under Valid until (optional).
- Click Create. The key is shown only once – copy it right away and keep it safe.
Important:
- A key belongs to the service order you created it in and only works with that service order's components. The Active keys list only shows the keys of this service order.
- A key acts on your behalf. If you lose access to the service order – for example because you are removed from the team – your keys respond with
403. - With an expiry date, a key works until the end of that day (German time) and responds with
401afterwards. Use Change to move or remove the date – this also makes an expired key valid again. - Revoke blocks a key immediately.
- Ideally create one key per integration. Then you can revoke a single one without affecting the others.
More on the API tab: Global Settings.
Permissions
| Permission | Allows |
|---|---|
| Read only | Only GET requests. Everything else responds with 403 "This API key is read-only." |
| Read & write | Additionally create, change and delete drafts: components, groups, characteristics, values, rules, tiered prices, price matrices, tags |
| + Publish | Additionally publish components (POST /components/{id}/publish) and delete them (DELETE /components/{id}) – both take effect in the shop immediately |
| + AI | Additionally use the AI assistant via the API (/ai/…) – this consumes AI tokens |
Publish and AI are only available together with Read & write; both are off when you create a key. This way, for example, a PIM can maintain values and prices in the draft while a person checks and publishes in the admin. If you change a key's permissions, they apply from the next request.
Base URL and headers
https://admin.configento.app/api/v1Every request sends the key as a bearer token:
Authorization: Bearer YOUR_API_KEY
Accept: application/json
Content-Type: application/jsonThe first call
List components:
curl https://admin.configento.app/api/v1/components \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"The response only contains the key data of each component:
{
"data": [
{ "id": 123, "title": { "de_DE": "Carport" }, "edition": null, "requires_bundle": null, "tags": [] },
{ "id": -4, "title": { "de_DE": "Terrassendach (neu)" }, "edition": null, "requires_bundle": null, "tags": [] }
],
"sync_running": false
}Read a complete component – with groups, characteristics, values and rules:
curl https://admin.configento.app/api/v1/components/123 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"The data model
Component
├── groups[] Groups
│ └── characteristics[] Characteristics
│ └── values[] Values
├── rules[] Rules
└── rulesgroups[] Rule groups- Internal name: every characteristic has its internal name in
alt_title(letters, digits and_only). You use it to refer to the characteristic in formulas. - Texts per language: labels such as
titleare objects with one entry per language, e.g.{ "de_DE": "Farbe", "en_US": "Colour" }. The keys are the language codes of your component. - IDs: group and characteristic IDs are only unique within a component. That is why all paths are under
/components/{id}/….
Draft and publishing
- Everything goes into the draft. Every write request changes the draft – just like saving in the editor. Your shop sees none of it until the component is published.
- Reading returns the draft.
GET /components/{id}shows the current draft, not the state running in the shop. - Every change is a version. Every write request creates a new version. For many changes at once, use the bulk endpoints (e.g. all values of a characteristic in one request) instead of many single calls.
- Negative IDs: a component that has never been published has a negative ID (e.g.
-4). On its first publication it gets a positive ID. From then on only the new ID is valid – take it from the status query (final_component_id).
The most important endpoints
Components
GET /components # All components (key data)
GET /components/{id} # Component with groups, characteristics, values, rules
POST /components # Create a new empty component
PUT /components/{id} # Change the component's key data
POST /components/{id}/duplicate # Copy a component (as a new draft)
DELETE /components/{id} # Delete a component – in the shop too! Needs "Publish"POST /components expects title as text and optionally default_locale (default de_DE). The response contains the new, negative ID.
Groups and characteristics
POST /components/{id}/groups # Create a group
PUT /components/{id}/groups/{gid} # Change a group
DELETE /components/{id}/groups/{gid} # Delete a group
POST /components/{id}/groups/{gid}/characteristics # Create a characteristic
PUT /components/{id}/groups/{gid}/characteristics/{cid} # Change a characteristic
DELETE /components/{id}/groups/{gid}/characteristics/{cid} # Delete a characteristicValues
POST /components/{id}/characteristics/{cid}/values # Create one value
PUT /components/{id}/characteristics/{cid}/values # Replace all values at once
PUT /components/{id}/characteristics/{cid}/values/{vid} # Change one value
DELETE /components/{id}/characteristics/{cid}/values/{vid} # Delete one valuePrices
GET /components/{id}/characteristics/{cid}/pricelist # Read tiered prices
PUT /components/{id}/characteristics/{cid}/pricelist # Replace tiered prices
POST /components/{id}/characteristics/{cid}/matrix/upload # Append a table to a price matrix
DELETE /components/{id}/characteristics/{cid}/matrix/values # Delete all tables of a price matrixRules
GET /components/{id}/rules # Read rules
POST /components/{id}/rules # Create a rule
PUT /components/{id}/rules/{rid} # Change a rule
DELETE /components/{id}/rules/{rid} # Delete a rule
GET /components/{id}/rulesgroups # Read rule groupsThe rule type is set by validation_type: blacklist, predefine_values (predefined values) or error (error). More on rule types: Build a Rule Set.
Versions and publishing
GET /components/{id}/versions # Versions, newest first
POST /components/{id}/versions/{version}/restore # Restore a version as the draft
GET /components/{id}/validate # Check whether the draft can be published
POST /components/{id}/publish # Publish the draft – needs "Publish"
GET /components/{id}/publish/status # Progress of the publicationExample: creating a characteristic with values
Create the characteristic "Colour" in group 5 of component 123:
POST /components/123/groups/5/characteristics
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"alt_title": "farbe",
"title": { "de_DE": "Farbe", "en_US": "Colour" },
"type": "select",
"is_required": "1"
}The response is the new characteristic with its id (here 42). You then create new values one by one – each one gets its ID:
POST /components/123/characteristics/42/values
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{ "title": { "de_DE": "Anthrazit" }, "value": "anthrazit", "price": 15.00, "sku": "FARBE-ANT" }value is the value that formulas, rules and the cart see; price is the surcharge.
You can update existing values in one request, e.g. new prices from the PIM. Send the complete list with the id of every value:
PUT /components/123/characteristics/42/values
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"values": [
{ "id": 301, "title": { "de_DE": "Weiß" }, "value": "weiss", "price": 0 },
{ "id": 302, "title": { "de_DE": "Anthrazit" }, "value": "anthrazit", "price": 19.00 }
]
}Caution: this request replaces all values of the characteristic. Values missing from the list are deleted. Don't leave out the id – values without an ID cannot be addressed in rules and predefined values. Get the IDs beforehand with GET /components/123.
Example: uploading a price matrix
POST /components/123/characteristics/77/matrix/upload
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{
"name": "Preise 2026",
"csv": ";500;1000;1500\n500;89;119;149\n1000;129;169;209",
"delimiter": ";"
}The first row contains the values of the X axis, the first column the values of the Y axis. The characteristic must be of type price matrix (matrixvalue). Alternatively, upload a CSV file of up to 2 MB as multipart/form-data in the file field.
The upload appends another table – existing tables remain. To replace a table, first delete all of them with DELETE …/matrix/values and then upload again. More: Price Matrices from Excel/CSV.
Example: publishing
POST /components/123/publish
Authorization: Bearer YOUR_API_KEYThe server checks the draft first. If it has errors, you get 422 right away with the errors in message. Otherwise publishing runs in the background, and the 202 Accepted response contains the address for the status query in job_status_url:
curl https://admin.configento.app/api/v1/components/123/publish/status \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"The state field goes through queued, uploading and pushing and ends with done or failed. With done, final_component_id holds the ID of the published component – for a first publication this is the new, positive ID.
Error codes
Errors come as JSON with a message in message, e.g. {"message": "Unauthenticated."}. For invalid data, errors also names the affected fields.
| Status | Meaning |
|---|---|
401 |
Missing, invalid, revoked or expired key |
403 |
The key is not allowed to do this – e.g. "This API key is read-only.", "This API key may not publish or delete components." or an endpoint that only works in the admin. Also: you no longer have access to the key's service order |
404 |
The component, group, characteristic or value does not exist – or it belongs to another service order |
409 |
A publication is already running for this component |
422 |
Invalid data, or the draft has errors that prevent publishing |
429 |
Too many requests to the AI assistant (at most 20 per minute) |
The API reference
All endpoints with fields and examples are at admin.configento.app/docs/api – in the admin also via Settings → API → API Documentation. You can try requests there directly: open an endpoint, choose Send API Request on the right and paste your key in the Auth section.