AimableDocs
DocsAPI Reference

Collections

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

curl -X PATCH 'https://api.aimable.com/api-proxy/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

| Parameter | Type | Location | Required | Description | |-----------------|--------|----------|----------|-------------| | collection_id | string | path | Yes | UUID of the collection | | Authorization | string | header | Yes | Bearer token | | X-API-Key | string | header | No | Optional API key |

Success Response (200 OK)

{
  "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

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

Success Response (200 OK)

{
  "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:
curl -X PATCH '/api-proxy/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):
curl -X DELETE '/api-proxy/v1/collections/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H 'Authorization: Bearer <token>'

Authentication & Error Handling

All endpoints require a valid access token:

Authorization: Bearer <your-access-token>

Optional: Include an API key for tracking or rate-limiting purposes:

X-API-Key: your_api_key_123

Common Errors

| Status | Meaning | |-------|--------| | 401 Unauthorized | Missing or invalid access token | | 403 Forbidden | Insufficient permissions (e.g., missing collections.manage or curator role) | | 422 Unprocessable Entity | Invalid input format |

Example 422 Response
{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "String should have at least 1 character",
      "type": "value_error",
      "input": ""
    }
  ]
}

💡 Always validate input length and type before sending requests.

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