VeristageDevelopers
Collections

Add resources to a collection

POST/collections/{ref}/resources

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.

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

Path Parameters

ref*integer

Collection id.

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/0/resources" \  -H "Content-Type: application/json" \  -d '{    "resourceRefs": [      101,      102,      103    ]  }'
{  "success": true,  "status": "success",  "message": "Resources processed",  "data": {    "collectionRef": 55,    "results": [      {        "ref": 101,        "status": "added"      },      {        "ref": 102,        "status": "added"      },      {        "ref": 103,        "status": "not_found"      }    ],    "addedCount": 2,    "alreadyPresentCount": 0,    "notFoundCount": 1  }}
{  "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"  }}

List collections visible to the api-key GET

Collections the linked user can see: their own, public ones, and those shared with them or their usergroup. Ordered by name. Requires the `read` scope.

Create a collection POST

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`.