AimableDocs
DocsAPI ReferenceRelease Notes

Collections

Updated 9 July 2026

Collections API

The Collections domain in the Aimable Platform API allows users to organize and manage groups of related content, such as media assets, documents, or user-generated items. Collections act as labeled containers that help structure data for easier navigation, sharing, and curation. This is especially useful for content management, digital asset libraries, or collaborative workspaces.

Managing collections requires appropriate permissions — specifically the collections.manage permission for updates and the curator role for deletion. All endpoints are versioned under /v1/collections and require authentication.

Key Concepts

  • Collection: A logical group of items identified by a unique collection_id (UUID). Each collection has metadata such as name and description.
  • Soft-delete: When a collection is deleted via the API, it is not permanently removed but marked as inactive (soft-delete), preserving data integrity and enabling potential recovery.
  • Permissions:
    • collections.manage: Required to update collection metadata.
    • Curator role: Required to delete a collection.

Updating a Collection

Use the PATCH /v1/collections/{collection_id} endpoint to update a collection’s name or description.

Request Example

bash
curl -X PATCH 'https://api.aimable.com/api/v1/collections/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Project Phoenix Assets",
    "description": "All design files and videos for the Phoenix campaign launch."
  }'

Request Parameters

ParameterTypeLocationRequiredDescription
collection_idstringpathYesUUID of the collection
AuthorizationstringheaderYesBearer token
X-API-KeystringheaderNoOptional API key

Success Response (200 OK)

json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Project Phoenix Assets",
  "description": "All design files and videos for the Phoenix campaign launch.",
  "created_at": "2023-04-10T12:00:00Z",
  "updated_at": "2023-05-15T08:30:00Z"
}

Only provided fields are updated. Omitting name or description leaves them unchanged.

Deleting a Collection

Use the DELETE /v1/collections/{collection_id} endpoint to soft-delete a collection. This action is irreversible via API and requires curator privileges.

Request Example

bash
curl -X DELETE 'https://api.aimable.com/api/v1/collections/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'Authorization: Bearer <your-access-token>'

Success Response (200 OK)

json
{
  "message": "Collection successfully deleted",
  "collection_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Soft-delete means the collection is no longer accessible via normal queries but may still exist in backups or audit logs.

Common Workflows

1. Update and Archive a Collection

  1. Update the collection to reflect its archived status:
bash
curl -X PATCH '/api/v1/collections/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'Authorization: Bearer <token>' \
  -d '{"description": "Archived on 2023-10-01. No further updates planned."}'
  1. Delete the collection if no longer needed (requires curator role):
bash
curl -X DELETE '/api/v1/collections/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'Authorization: Bearer <token>'

See Authentication & errors for request authentication and the standard error responses.

With the Collections API, you can dynamically maintain structured content groups — keeping your data organized, up-to-date, and accessible to the right users.

Related Endpoints

See also