--- name: gc2-configurations description: Use when creating, listing, editing, publishing or deleting Vidi configurations (what the GC2 Dashboard calls "Configurations") in GC2 BaaS, or handing Vidi a published configuration URL — /api/v4/configurations endpoints, the getConfiguration/postConfiguration/patchConfiguration/deleteConfiguration/getPublicConfiguration tools, the Configurations SDK class, configuration_* keys, the body-as-JSON-text rule, the anonymous .json form, or CONFIGURATION_NOT_FOUND / SUPER_USER_ONLY errors. --- # Vidi Configurations Use this skill for the v4 Configurations API (`/api/v4/configurations`): managing Vidi configurations with a token and reading published ones anonymously. v4 reads and writes **the same rows** as the legacy `/api/v2/configuration`, so a configuration made in the Dashboard is editable through v4 and the other way round. ## Availability Implemented on the GeoCloud2 branch `feat/configurations-v4` (commit `d74dd38e`). As of 2026-11 it is **not merged, not released and not on production `api.gc2.io`** — assume dev-only and expect `404`/`406` elsewhere. MCP tools ship in `@mapcentia/gc2-mcp-server` 1.2.0+; the SDK `Configurations` class in the `@mapcentia/gc2-sdk` release after 0.3.1. ## Resource ```json { "key": "configuration_my_map_673211a0b1c2d312345678", "name": "My map", "description": "Configuration for the public map", "published": true, "body": "{\"brandName\": \"My map\"}" } ``` - `body` is a **string holding JSON text**, not an object — send `JSON.stringify(config)`, parse it yourself on read. It must parse to a JSON **object or array** (scalars and broken JSON → `400 INVALID_REQUEST`). It is stored and returned unchanged. - `key` is generated by the server (`configuration__`), is **never accepted in a body**, and does not change when the configuration is renamed. - `null` is rejected in every field. Missing or unknown fields → `400 INPUT_VALIDATION_ERROR`. ## Management (token from the database owner) | Operation | Route / MCP tool | Result | |---|---|---| | List all, published or not | `GET /api/v4/configurations` / `getConfiguration` (no key) | `200`, plain JSON array | | Get by key(s) | `GET .../{key[,key...]}` / `getConfiguration` | `200`: **object** for one key, **array** for several; any missing key → `404 CONFIGURATION_NOT_FOUND` | | Create | `POST /api/v4/configurations` / `postConfiguration` | `201` + `Location: /api/v4/configurations/`; body is one object or an array; `name` (non-empty), `description` (may be `""`), `published`, `body` are **all required** | | Update | `PATCH .../{key}` / `patchConfiguration` | `303 See Other` + `Location`; **one key only**; any non-empty subset of the four fields | | Delete | `DELETE .../{key[,key...]}` / `deleteConfiguration` | `204`; every key is checked first — if one is missing, nothing is deleted (`404`) | - Sub-user tokens get `403 SUPER_USER_ONLY` on all four. A missing token is `400` (not `401`). - The `201`/`303` bodies are empty: read the generated key from `Location`, then GET it. - Delete is destructive — follow the confirmation policy in `gc2-rules` before calling `deleteConfiguration`. ## Public read (no token) `getPublicConfiguration` — a token sent along is ignored; the route always behaves anonymously. | Route | Result | |---|---| | `GET /api/v4/configurations/database/{database}` | Array of the **published** configurations | | `GET .../database/{database}/{key}` | The object, if published | | `GET .../database/{database}/{key}.json` | The raw `body` as `application/json` (attachment) — **the URL to give Vidi** | - One key only (no comma lists). Unpublished and unknown keys both answer `404 CONFIGURATION_NOT_FOUND`, so keys cannot be probed. - Unknown database → `404 DATABASE_NOT_FOUND`. A method the route does not offer → `406`. - With the MCP tool, append `.json` to the `key` argument to get the body itself. ## Keys in URLs Keys match `^configuration_[A-Za-z0-9_@+\-]+$`. v4 only generates `[A-Za-z0-9_]`, but Dashboard-made keys can contain `@`, `+` and `-`, so **URL-encode every key** (`+` must travel as `%2B`). The MCP tools and the SDK do this for you; with raw HTTP, encode each key and join with a literal comma. ## OpenAPI gaps - The PATCH body is described with the `Configuration` schema, which marks all four fields required. They are optional on PATCH (the `patchConfiguration` tool already offers them as optional). - The `getPublicConfiguration` response is described only as `Configuration`/array; the `.json` form (raw body) appears only in the description text. ## SDK Standalone class, explicit-client pattern: `new Configurations(client.http)`. ```ts const configurations = new Configurations(http) const { keys } = await configurations.postConfiguration({ name: 'My map', description: '', published: true, body: JSON.stringify({ brandName: 'My map' }), }) await configurations.patchConfiguration(keys[0], { published: false }) const url = configurations.publicConfigurationUrl('mydb', keys[0]) // .json URL for Vidi, no request made ``` Methods: `getConfiguration()` / `(key)` / `(keys[])`, `postConfiguration(one | many)` → `{location, keys}`, `patchConfiguration(key, partial)`, `deleteConfiguration(key | keys[])`, and the anonymous `getPublicConfiguration(database, key?)`, `getPublicConfigurationBody(database, key)` (parsed body), `publicConfigurationUrl(database, key)`. Errors are `CentiaApiError` (`.status`/`.code`). Types: `Configuration`, `CreateConfigurationRequest`, `PatchConfigurationRequest`. ## Common mistakes | Mistake | Reality | |---|---| | Sending `body` as an object | It is JSON **text**; stringify it. Objects fail validation | | Sending `key` on POST or PATCH | Server-generated; an unknown field → `400 INPUT_VALIDATION_ERROR` | | Managing configurations through `/api/v4/keyvalue` | Rows written there get an owner and are **invisible** to the configurations API (and never served as published). Use this API only | | Treating unpublished configurations as secret | `configuration_*` rows are readable through `/api/v4/keyvalue` by every user of the database, sub-users included. `published: false` only hides them from anonymous callers | | Giving Vidi the object URL | Vidi needs the `{key}.json` form, which returns the body itself | | Expecting `200` from PATCH or a body from POST | `303` / `201` with `Location` only — disable auto-redirect | | Comma lists on PATCH or the public route | Single key only there; lists work on management GET and DELETE | | Expecting the key to follow a rename | The key is fixed at creation | | Assuming production availability | Branch-only as of 2026-11; verify against the target host's OpenAPI first |