VeristageDevelopers
Collections

Create a collection

POST/collections

Creates a collection owned by the api-key's linked user. Requires the write scope.

Visibility

Defaults to team — the publisher's other users (and other api-keys in the same usergroup) can see and list the collection. If the linked user may not create team collections, the default silently falls back to private; the response's visibility field reports what was applied. Requesting team explicitly when it isn't permitted returns 403 rather than downgrading.

private collections are visible only to the owning (linked) user — including in this API's own GET /collections for other keys.

Description

description is accepted and validated but not yet stored — the collection data model has no description field today. Send it for forward-compatibility only.

Idempotency

Pass an Idempotency-Key header (a unique random string per logical create, e.g. a UUID) to make retries safe. The first successful response with a given key is cached for 24 hours; replays return the same body byte-for-byte with Idempotent-Replayed: true. Reusing the key with a different request body returns 422 IDEMPOTENCY_KEY_CONFLICT.

Authorization

apiKey
X-Api-Key<token>

Issued to you when your integration is provisioned. Determines which catalogue resources are visible and which AI tools are available.

In: header

Header Parameters

Idempotency-Key?string

Optional client-supplied retry key. 1–255 printable-ASCII characters. Use a UUID or other high-entropy random string.

Match^[\x21-\x7E]+$
Lengthlength <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/collections" \  -H "Content-Type: application/json" \  -d '{    "name": "Spring catalogue"  }'
{  "success": true,  "status": "success",  "message": "Collection created",  "data": {    "ref": 55,    "name": "Spring catalogue",    "visibility": "team"  }}
{  "success": false,  "status": "fail",  "message": "string",  "error": {    "message": "API key is required",    "code": "NO_API_KEY"  }}

{  "success": false,  "status": "fail",  "message": "API key is required",  "error": {    "code": "NO_API_KEY",    "message": "API key is required"  }}

{  "success": false,  "status": "fail",  "message": "This API key does not have the 'write' scope",  "error": {    "code": "INSUFFICIENT_SCOPE",    "message": "This API key does not have the 'write' scope"  }}

{  "success": false,  "status": "fail",  "message": "string",  "error": {    "message": "API key is required",    "code": "NO_API_KEY"  }}

Add resources to a collection POST

Adds up to 100 resources per call. Requires the `write` scope and modify access to the collection (owner, or the collection allows changes). Each ref is validated for visibility to the api-key's linked user before adding; the response reports a per-ref status: - `added` — newly added to the collection. - `already_present` — was already in the collection (no-op). - `not_found` — the resource doesn't exist **or** isn't visible to the linked user (not distinguished). Adding is naturally idempotent: retrying the same request reports the previously added refs as `already_present`.

List distribution destinations GET

Distribution destinations available to the api-key's linked user (feed targets such as ONIX/metadata drops). FTP credentials are **never** returned. Destinations are server-wide — the data model has no per-usergroup destination — so every caller with distribution access sees the same set. Requires the `read` scope and the linked user's distribution permission (`dm` or `dv`).