Asset Collections API

Collections are the organising unit for files in the Runnit asset library. Every asset belongs to exactly one collection, and a collection can be linked to projects, client organisations, and brief jobs so its files appear in the right places in the app.

Authentication: every endpoint requires an API key. See API Keys & Authentication.

Permissions: read endpoints need asset view access and write endpoints need asset upload access. Every role from member up has both by default; freelancer accounts have neither.

Unlike most /api/v1 resources, collection endpoints return the resource directly (for example { "collection": { ... } }) without a success flag, except for deletes, which return { "success": true }.

The collection object

{
  "id": "d5df4edc-...",
  "ownerOrganizationId": "ddf75d91-...",
  "name": "Brand Guidelines",
  "slug": "brand-guidelines",
  "collectionType": "reference",
  "description": "Research, analysis, and reference materials",
  "metadata": {},
  "createdAt": "2026-07-08T02:31:49.136Z",
  "updatedAt": "2026-07-08T02:31:49.136Z",
  "deletedAt": null
}

collectionType is one of brand_strategy, creative, reference, job_output, project, custom, agent_knowledge, brief_templates, component_source, or agent_docs.

Entity links attach a collection to something else in Runnit:

{
  "id": "9f2c1e77-...",
  "collectionId": "d5df4edc-...",
  "entityType": "project",
  "entityId": "1f0e9a52-...",
  "createdAt": "2026-07-08T02:31:49.201Z"
}

entityType is organization, project, or job.

GET /api/v1/collections

List collections, either everything owned by an organisation or the collections linked to a specific entity. Provide organizationId, or both entityType and entityId.

Needs asset view access.

Query parameters

Name	Type	Required	Description
organizationId	UUID	One of the two filters	Lists every collection the organisation owns.
entityType	string	With entityId	organization, project, or job.
entityId	UUID	With entityType	Lists collections linked to this entity.

Example request

curl "https://api.runnit.io/api/v1/collections?organizationId=<org-id>" \
  -H 'Authorization: Bearer rnk_your_key'

Response

{ "collections": [ { "id": "d5df4edc-...", "name": "Brand Guidelines", "collectionType": "reference" } ] }

Errors

• 400 if you supply neither organizationId nor the entityType and entityId pair.

GET /api/v1/collections/by-name

Look up a single collection by its exact name within an organisation. Useful when your integration works with well-known collection names rather than IDs.

Needs asset view access.

Query parameters

Name	Type	Required	Description
name	string	Yes	Exact collection name.
organizationId	UUID	Yes	Owning organisation.

Example request

curl "https://api.runnit.io/api/v1/collections/by-name?name=Brand%20Guidelines&organizationId=<org-id>" \
  -H 'Authorization: Bearer rnk_your_key'

Response

{ "collection": { "id": "d5df4edc-...", "name": "Brand Guidelines" } }

Errors

• 400 if name or organizationId is missing.
• 404 if no collection has that name in the organisation.

POST /api/v1/collections

Create a collection, optionally linking it to entities in the same request.

Needs asset upload access.

Request body

Name	Type	Required	Description
ownerOrganizationId	UUID	Yes	Organisation that owns the collection.
name	string	Yes	Collection name.
slug	string	No	URL-safe identifier. Generated from the name when omitted.
collectionType	string	No	One of the types listed above. Defaults to custom.
description	string	No	What the collection holds.
metadata	object	No	Free-form metadata.
entityLinks	array	No	Objects with entityType and entityId to link on creation.

Example request

curl -X POST https://api.runnit.io/api/v1/collections \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "ownerOrganizationId": "<org-id>",
    "name": "Winter Campaign Assets",
    "collectionType": "creative",
    "description": "Final creative for the winter launch.",
    "entityLinks": [ { "entityType": "project", "entityId": "<project-id>" } ]
  }'

Response

Returns 201 with the new collection:

{ "collection": { "id": "d5df4edc-...", "name": "Winter Campaign Assets", "slug": "winter-campaign-assets" } }

Errors

• 400 if ownerOrganizationId or name is missing.

GET /api/v1/collections/:collectionId

Get one collection by ID.

Needs asset view access.

Path parameters

Name	Type	Required	Description
collectionId	UUID	Yes	Collection ID.

Query parameters

Name	Type	Required	Description
includeLinks	boolean	No	When true, the collection includes its entityLinks array.

Example request

curl "https://api.runnit.io/api/v1/collections/<collection-id>?includeLinks=true" \
  -H 'Authorization: Bearer rnk_your_key'

Response

{ "collection": { "id": "d5df4edc-...", "name": "Winter Campaign Assets", "entityLinks": [ { "entityType": "project", "entityId": "1f0e9a52-..." } ] } }

Errors

• 404 if the collection does not exist or was deleted.

PATCH /api/v1/collections/:collectionId

Update a collection’s details. Send only the fields you want to change.

Needs asset upload access.

Request body (all optional)

Name	Type	Required	Description
name	string	No	New name.
slug	string	No	New slug.
collectionType	string	No	One of the types listed above.
description	string	No	New description.
metadata	object	No	Replaces the stored metadata.

Example request

curl -X PATCH https://api.runnit.io/api/v1/collections/<collection-id> \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{ "description": "Approved creative only." }'

Response

{ "collection": { "id": "d5df4edc-...", "description": "Approved creative only." } }

Errors

• 404 if the collection does not exist.

DELETE /api/v1/collections/:collectionId

Delete a collection. By default this is a soft delete: the collection is hidden but recoverable by support. Pass hard=true to remove it permanently.

Needs asset upload access.

Query parameters

Name	Type	Required	Description
hard	boolean	No	true deletes the collection permanently. Defaults to a soft delete.

Example request

curl -X DELETE "https://api.runnit.io/api/v1/collections/<collection-id>" \
  -H 'Authorization: Bearer rnk_your_key'

Response

{ "success": true }

Errors

• 404 if the collection does not exist or was already deleted.

GET /api/v1/collections/:collectionId/assets

List every asset in a collection, together with the collection itself and a count.

Needs asset view access.

Example request

curl https://api.runnit.io/api/v1/collections/<collection-id>/assets \
  -H 'Authorization: Bearer rnk_your_key'

Response

{
  "collection": { "id": "d5df4edc-...", "name": "Winter Campaign Assets" },
  "assets": [ { "id": "5595c819-...", "fileName": "style-guide", "fileType": "markdown" } ],
  "count": 1
}

Asset objects use the shape described on the Assets API page.

Errors

• 404 if the collection does not exist.

GET /api/v1/collections/:collectionId/links

List a collection’s entity links.

Needs asset view access.

Example request

curl https://api.runnit.io/api/v1/collections/<collection-id>/links \
  -H 'Authorization: Bearer rnk_your_key'

Response

{ "links": [ { "id": "9f2c1e77-...", "entityType": "project", "entityId": "1f0e9a52-..." } ] }

POST /api/v1/collections/:collectionId/links

Link a collection to an entity. Adding a link that already exists is safe and returns the existing link.

Needs asset upload access.

Request body

Name	Type	Required	Description
entityType	string	Yes	organization, project, or job.
entityId	UUID	Yes	Entity to link.

Example request

curl -X POST https://api.runnit.io/api/v1/collections/<collection-id>/links \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{ "entityType": "project", "entityId": "<project-id>" }'

Response

Returns 201 with the link:

{ "link": { "id": "9f2c1e77-...", "collectionId": "d5df4edc-...", "entityType": "project", "entityId": "1f0e9a52-..." } }

Errors

• 400 if entityType or entityId is missing.

DELETE /api/v1/collections/:collectionId/links

Remove an entity link from a collection. The link to remove is identified by query parameters, not a body.

Needs asset upload access.

Query parameters

Name	Type	Required	Description
entityType	string	Yes	organization, project, or job.
entityId	UUID	Yes	Entity to unlink.

Example request

curl -X DELETE "https://api.runnit.io/api/v1/collections/<collection-id>/links?entityType=project&entityId=<project-id>" \
  -H 'Authorization: Bearer rnk_your_key'

Response

{ "success": true }

Errors

• 400 if entityType or entityId is missing.
• 404 if no matching link exists.

POST /api/v1/collections/default

Create the standard set of collections for a client organisation: Brand Strategy, Creative, Reference Docs, and Brief Templates, each linked to the client. Safe to call repeatedly; existing collections are not duplicated.

Needs asset upload access.

Request body

Name	Type	Required	Description
ownerOrganizationId	UUID	Yes	Your organisation (the collections’ owner).
clientOrganizationId	UUID	Yes	The client organisation the collections are for.

Example request

curl -X POST https://api.runnit.io/api/v1/collections/default \
  -H 'Authorization: Bearer rnk_your_key' \
  -H 'Content-Type: application/json' \
  -d '{ "ownerOrganizationId": "<org-id>", "clientOrganizationId": "<client-org-id>" }'

Response

Returns 201 with the full set:

{ "collections": [ { "name": "Brand Strategy", "collectionType": "brand_strategy" }, { "name": "Creative", "collectionType": "creative" } ] }

Errors

• 400 if ownerOrganizationId or clientOrganizationId is missing.

Next steps

Upload and manage the files inside your collections with the Assets API.