Collections

The /collections endpoint allows you to manage collections and their security permissions. Collections can be either static (with explicitly defined members) or dynamic (with members determined by a query).

Create Collection

Endpoint: /collections

Method: POST

Headers

Input Parameters

Example Request

{
    "name": "Project Documents",
    "description": "All project-related documents",
    "dynamic": false,
    "type": "<CONTENT_TYPE_ID>",
    "tags": ["project", "documents"],
    "properties": {
        "department": "Engineering",
        "year": "2024"
    }
}

Example Response

{
    "id": "<COLLECTION_ID>",
    "name": "Project Documents",
    "description": "All project-related documents",
    "dynamic": false,
    "status": "active",
    "type": {
        "id": "<CONTENT_TYPE_ID>",
        "name": "Document"
    },
    "tags": ["project", "documents"],
    "properties": {
        "department": "Engineering",
        "year": "2024"
    },
    "created_by": "user:<USER_ID>",
    "updated_by": "user:<USER_ID>",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
}

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Project Documents",
    "description": "All project-related documents",
    "dynamic": false,
    "type": "<CONTENT_TYPE_ID>",
    "tags": ["project", "documents"],
    "properties": {
        "department": "Engineering",
        "year": "2024"
    }
}'

Retrieve Collection

Endpoint: /collections/:collectionId

Method: GET

Headers

Path Parameters

Query Parameters

Example Response

{
    "id": "<COLLECTION_ID>",
    "name": "Project Documents",
    "description": "All project-related documents",
    "dynamic": false,
    "status": "active",
    "type": {
        "id": "<CONTENT_TYPE_ID>",
        "name": "Document"
    },
    "tags": ["project", "documents"],
    "properties": {
        "department": "Engineering",
        "year": "2024"
    },
    "created_by": "user:<USER_ID>",
    "updated_by": "user:<USER_ID>",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:30:00.000Z"
}

Code Example

curl -X GET \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID> \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Update Collection

Endpoint: /collections/:collectionId

Method: PUT

Headers

Path Parameters

Requirements: User must have content:write permission on the collection.

Input Parameters

Example Request

{
    "name": "Updated Project Documents",
    "description": "Updated description for project documents",
    "tags": ["project", "documents", "2024"]
}

Example Response

{
    "id": "<COLLECTION_ID>",
    "name": "Updated Project Documents",
    "description": "Updated description for project documents",
    "dynamic": false,
    "status": "active",
    "type": {
        "id": "<CONTENT_TYPE_ID>",
        "name": "Document"
    },
    "tags": ["project", "documents", "2024"],
    "created_by": "user:<USER_ID>",
    "updated_by": "user:<USER_ID>",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T11:00:00.000Z"
}

Code Example

curl -X PUT \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID> \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Updated Project Documents",
    "description": "Updated description for project documents",
    "tags": ["project", "documents", "2024"]
}'

Delete Collection

Endpoint: /collections/:collectionId

Method: DELETE

Headers

Path Parameters

Requirements: User must have content:delete permission on the collection.

Example Response

{
    "id": "<COLLECTION_ID>",
    "count": 1
}

Code Example

curl -X DELETE \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID> \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Search Collections

Endpoint: /collections/search

Method: POST

Headers

Requirements: User must have content:read permission. Returns only collections the user has access to.

ComplexCollectionSearchQuery Fields

The search query supports multiple filtering criteria:

Basic Filters

Pagination

Advanced Filters

Example Request

{
    "name": "project",
    "dynamic": false,
    "status": "active",
    "type": "<CONTENT_TYPE_ID>",
    "limit": 20,
    "offset": 0
}

Example Response

[
    {
        "id": "<COLLECTION_ID>",
        "name": "Project Documents",
        "description": "All project-related documents",
        "dynamic": false,
        "status": "active",
        "type": {
            "id": "<CONTENT_TYPE_ID>",
            "name": "Document"
        },
        "tags": ["project", "documents"],
        "created_by": "user:<USER_ID>",
        "updated_by": "user:<USER_ID>",
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
    }
]

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections/search \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "project",
    "dynamic": false,
    "status": "active",
    "type": "<CONTENT_TYPE_ID>",
    "limit": 20,
    "offset": 0
}'

Compute Facets

Endpoint: /collections/facets

Method: POST

Headers

Requirements: User must have content:read permission.

Description: Compute faceted aggregations on collections. Useful for building filter UIs and understanding collection distribution.

Input Parameters

FacetSpec Structure

Example Request

{
    "facets": [
        {
            "name": "by_type",
            "field": "type"
        },
        {
            "name": "by_status",
            "field": "status"
        }
    ],
    "query": {
        "dynamic": false
    }
}

Example Response

{
    "by_type": [
        {
            "_id": "<TYPE_ID>",
            "count": 15
        },
        {
            "_id": null,
            "count": 5
        }
    ],
    "by_status": [
        {
            "_id": "active",
            "count": 18
        },
        {
            "_id": "archived",
            "count": 2
        }
    ],
    "total": 20
}

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections/facets \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "facets": [
        {
            "name": "by_type",
            "field": "type"
        },
        {
            "name": "by_status",
            "field": "status"
        }
    ],
    "query": {
        "dynamic": false
    }
}'

Update Collection Permissions

Endpoint: /collections/:collectionId/permissions

Method: PUT

Headers

Path Parameters

Requirements: User must have content:admin or content:superadmin permission.

Input Parameters

The request body should be an object with permission keys and arrays of principals:

Principal Format:

• user:<userId> - Individual user access
• group:<groupId> - Group access
• role:<roleId> - Role-based access
• project:* - Project-wide access (all project members)

Note: Dynamic collections cannot have permissions updated. For static collections, permissions automatically propagate to all member objects.

Example Request

{
    "content:read": ["user:507f1f77bcf86cd799439011", "group:507f191e810c19729de860ea", "project:*"],
    "content:write": ["user:507f1f77bcf86cd799439011", "project:*"],
    "content:delete": ["user:507f1f77bcf86cd799439011"]
}

Example Response

{
    "id": "<COLLECTION_ID>",
    "security": {
        "content:read": ["group:507f191e810c19729de860ea", "project:*", "user:507f1f77bcf86cd799439011"],
        "content:write": ["project:*", "user:507f1f77bcf86cd799439011"],
        "content:delete": ["user:507f1f77bcf86cd799439011"]
    },
    "objectsUpdated": 42
}

Code Example

curl -X PUT \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID>/permissions \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "content:read": ["user:507f1f77bcf86cd799439011", "group:507f191e810c19729de860ea", "project:*"],
    "content:write": ["user:507f1f77bcf86cd799439011", "project:*"],
    "content:delete": ["user:507f1f77bcf86cd799439011"]
}'

Propagate Permissions

Endpoint: /collections/:collectionId/propagate-permissions

Method: POST

Headers

Path Parameters

Requirements: User must have content:admin or content:superadmin permission.

Description: Manually triggers permission propagation from the collection to all its member objects. This is useful when permissions may be out of sync or need to be reapplied. Permissions are normally propagated automatically when changed, but this endpoint allows manual triggering.

Example Response

{
    "id": "<COLLECTION_ID>",
    "message": "Permissions propagated to 42 objects",
    "security": {
        "content:read": ["user:507f1f77bcf86cd799439011", "project:*"],
        "content:write": ["user:507f1f77bcf86cd799439011"],
        "content:delete": ["user:507f1f77bcf86cd799439011"]
    },
    "objectsUpdated": 42
}

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID>/propagate-permissions \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Add/Remove Collection Members

Endpoint: /collections/:collectionId/members

Method: POST

Headers

Path Parameters

Requirements: User must have content:write permission on the collection.

Input Parameters

Important Notes:

• Only works with static collections (where dynamic is false)
• Objects can belong to a maximum of 5 "secured" collections (collections with specific user/group permissions)
• Collections with only project:* permissions don't count toward this limit
• When adding members, the collection's permissions automatically propagate to the objects
• When an object is in multiple collections, it inherits permissions from ALL collections (additive model)

Example Request

{
    "action": "add",
    "members": ["507f1f77bcf86cd799439011", "507f191e810c19729de860ea", "507f191e810c19729de860eb"]
}

Example Response

{
    "id": "<COLLECTION_ID>",
    "objectsUpdated": 3
}

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID>/members \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "add",
    "members": ["507f1f77bcf86cd799439011", "507f191e810c19729de860ea", "507f191e810c19729de860eb"]
}'

Get Collection Members

Endpoint: /collections/:collectionId/members

Method: GET

Headers

Path Parameters

Requirements: User must have content:read permission on the collection.

Query Parameters

Description: Returns the objects that are members of this collection. For dynamic collections, returns objects matching the collection's query. For static collections, returns explicitly added members. Users with the content:superadmin permission can access all collection members regardless of object-level permissions.

Example Response

[
    {
        "id": "<OBJECT_ID>",
        "name": "Document 1",
        "status": "processed",
        "type": {
            "id": "<TYPE_ID>",
            "name": "Document"
        },
        "created_at": "2024-01-15T10:30:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
    }
]

Code Example

curl -X GET \
  'https://api.vertesia.io/api/v1/collections/<COLLECTION_ID>/members?limit=100&offset=0' \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Search Collection Members

Endpoint: /collections/:collectionId/search

Method: POST

Headers

Path Parameters

Requirements: User must have content:read permission on the collection.

Description: Performs advanced search on collection members with support for full-text search, vector similarity search, and complex filtering. The search is automatically scoped to the collection's members.

Input Parameters

The search accepts a ComplexSearchPayload with the following structure:

Example Request

{
    "query": {
        "name": "report",
        "status": "processed",
        "full_text": "quarterly financial",
        "vector": {
            "objectId": "<REFERENCE_OBJECT_ID>",
            "config": { "text": true }
        },
        "weights": {
            "text": 5,
            "full_text": 3
        }
    },
    "limit": 10,
    "offset": 0
}

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID>/search \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
        "name": "report",
        "status": "processed",
        "full_text": "quarterly financial"
    },
    "limit": 10,
    "offset": 0
}'

Compute Member Facets

Endpoint: /collections/:collectionId/facets

Method: POST

Headers

Path Parameters

Requirements: User must have content:read permission on the collection.

Description: Compute faceted aggregations on collection members. Useful for building filter UIs and understanding member distribution within a collection.

Input Parameters

Example Request

{
    "facets": [
        {
            "name": "by_status",
            "field": "status"
        },
        {
            "name": "by_type",
            "field": "type"
        }
    ]
}

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID>/facets \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "facets": [
        {
            "name": "by_status",
            "field": "status"
        },
        {
            "name": "by_type",
            "field": "type"
        }
    ]
}'

Search Child Collections

Endpoint: /collections/:collectionId/children/search

Method: POST

Headers

Path Parameters

Requirements: User must have content:read permission on the collection.

Description: Search for child collections of the specified parent collection. Collections can be organized hierarchically, and this endpoint returns direct children only.

Input Parameters

Accepts the same query parameters as Search Collections, with the parent field automatically set to the collection ID.

Example Request

{
    "name": "sub",
    "status": "active",
    "limit": 10,
    "offset": 0
}

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID>/children/search \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "sub",
    "status": "active",
    "limit": 10,
    "offset": 0
}'

Add/Remove Child Collections

Endpoint: /collections/:collectionId/children

Method: POST

Headers

Path Parameters

Requirements: User must have content:write permission on the collection.

Input Parameters

Note: A collection cannot be a child of itself. This validation is enforced by the API.

Example Request

{
    "action": "add",
    "children": ["507f1f77bcf86cd799439011", "507f191e810c19729de860ea"]
}

Example Response

{
    "count": 2
}

Code Example

curl -X POST \
  https://api.vertesia.io/api/v1/collections/<COLLECTION_ID>/children \
  -H 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "add",
    "children": ["507f1f77bcf86cd799439011", "507f191e810c19729de860ea"]
}'

Security Model

Additive Permission Model

When objects belong to multiple collections, they inherit permissions from ALL collections:

1. Permission Merging: Object permissions are the UNION of all collection permissions
2. Collection Limit: Maximum 5 secured collections per object (collections with specific user/group permissions)
3. Project-wide Access: Collections with only project:* don't count toward the limit
4. Revision Inheritance: All revisions inherit security from the root object
5. Automatic Propagation: Permission changes automatically propagate to all member objects

Permission Types

• content:read - View collection and its contents
• content:write - Modify collection and manage members
• content:delete - Delete collection
• content:admin - Manage collection permissions
• content:superadmin - Full access to all collections for management purposes

Access Control

• Users can only see collections they have at least content:read permission for
• Super admins can see all collections for management purposes
• Permission changes propagate automatically to all member objects
• Objects inherit the union of permissions from all their collections

Examples

Single Collection:

• Object A is in Collection 1 with ["user:123", "project:*"] read permission
• Object A inherits ["user:123", "project:*"] read permission

Multiple Collections:

• Object B is in Collection 1 with ["user:123"] read permission
• Object B is in Collection 2 with ["user:456", "project:*"] read permission
• Object B inherits ["user:123", "user:456", "project:*"] read permission (union of both)

Secured Collection Limit:

• Collections with only project:* permissions are not counted
• Objects can be in unlimited project:*-only collections
• Objects can be in maximum 5 collections with specific user/group permissions