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.

Organisation access: you can only work with collections owned by your own organisation or by an active client of your organisation. Requests that name another organisation return 403. Requests for a collection ID you cannot access return 404, the same as a collection that does not exist.

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. The type is a stable identifier and does not always match the display name: brand_strategy collections are shown as Brand Guidelines in the app.

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.
• 403 if the organisation, or the organisation that owns the entity, is not yours or an active client of yours.
• 404 if the entityType and entityId pair names a job or project that does not exist.

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.
• 403 if the organisation is not yours or an active client of yours.
• 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, or if an entity link is missing entityType or entityId.
• 403 if ownerOrganizationId is not yours or an active client of yours, or if an entity link targets a job, project, or organisation you cannot access. Nothing is created when a link is rejected.
• 404 if an entity link names a job or project that does not exist.

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, was deleted, or belongs to an organisation you cannot access.

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 or belongs to an organisation you cannot access.

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, was already deleted, or belongs to an organisation you cannot access.

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. This list does not include file content; fetch a single asset with the Assets API when you need its content.

Errors

• 404 if the collection does not exist or belongs to an organisation you cannot access.

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.
• 403 if the entity belongs to a job, project, or organisation you cannot access.
• 404 if the collection or the named job or project does not exist, or the collection belongs to an organisation you cannot access.

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, or the collection does not exist or belongs to an organisation you cannot access.

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 Guidelines", "collectionType": "brand_strategy" }, { "name": "Creative", "collectionType": "creative" } ] }

Errors

• 400 if ownerOrganizationId or clientOrganizationId is missing.
• 403 if ownerOrganizationId is not yours or an active client of yours, or if clientOrganizationId is not an active client of the owner organisation.

Next steps

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