> ## Documentation Index
> Fetch the complete documentation index at: https://r2r-patch-fix-ingestion.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Collection Management

> Manage collections in R2R

A collection in R2R is a logical grouping of users and documents that allows for efficient access control and organization. Collections enable you to manage permissions and access to documents at a collection level, rather than individually.

R2R provides a comprehensive set of collection features, allowing you to implement efficient access control and organization of users and documents in your applications.

<Note>
  Collection permissioning in R2R is still under development and as a result the API will likely evolve.
</Note>

## Collection creation and Management

### Create a Collection

Create a new collection with a name and optional description:

```python
create_collection_response = client.create_collection("Marketing Team", "Collection for marketing department")
collection_id = create_collection_response["results"]["collection_id] # '123e4567-e89b-12d3-a456-426614174000'
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': {
          'collection_id': '123e4567-e89b-12d3-a456-426614174000',
          'name': 'Marketing Team',
          'description': 'Collection for marketing department',
          'created_at': '2024-07-16T22:53:47.524794Z',
          'updated_at': '2024-07-16T22:53:47.524794Z'
        }
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### Get Collection details

Retrieve details about a specific collection:

```python
collection_details = client.get_collection(collection_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': {
          'collection_id': '123e4567-e89b-12d3-a456-426614174000',
          'name': 'Marketing Team',
          'description': 'Collection for marketing department',
          'created_at': '2024-07-16T22:53:47.524794Z',
          'updated_at': '2024-07-16T22:53:47.524794Z'
        }
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### Update a Collection

Update a collection's name or description:

```python
update_result = client.update_collection(
  collection_id,
  name="Updated Marketing Team",
  description="New description for marketing team"
)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': {
          'collection_id': '123e4567-e89b-12d3-a456-426614174000',
          'name': 'Updated Marketing Team',
          'description': 'New description for marketing team',
          'created_at': '2024-07-16T22:53:47.524794Z',
          'updated_at': '2024-07-16T23:15:30.123456Z'
        }
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### List Collections

Get a list of all collections:

```python
collections_list = client.list_collections()
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': [
          {
            'collection_id': '123e4567-e89b-12d3-a456-426614174000',
            'name': 'Updated Marketing Team',
            'description': 'New description for marketing team',
            'created_at': '2024-07-16T22:53:47.524794Z',
            'updated_at': '2024-07-16T23:15:30.123456Z'
          },
          # ... other collections ...
        ]
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

## User Management in Collections

### Add User to Collection

Add a user to a collection:

```python

user_id = '456e789f-g01h-34i5-j678-901234567890'  # This should be a valid user ID
add_user_result = client.add_user_to_collection(user_id, collection_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': {
          'message': 'User successfully added to the collection'
        }
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### Remove User from Collection

Remove a user from a collection:

```python
remove_user_result = client.remove_user_from_collection(user_id, collection_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': {
          'message': 'User successfully removed from the collection'
        }
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### List Users in Collection

Get a list of all users in a specific collection:

```python
users_in_collection = client.get_users_in_collection(collection_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': [
          {
            'user_id': '456e789f-g01h-34i5-j678-901234567890',
            'email': 'user@example.com',
            'name': 'John Doe',
            # ... other user details ...
          },
          # ... other users ...
        ]
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### Get User's Collections

Get all collections that a user is a member of:

```python
user_collections = client.user_collections(user_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': [
          {
            'collection_id': '123e4567-e89b-12d3-a456-426614174000',
            'name': 'Updated Marketing Team',
            # ... other Collection details ...
          },
          # ... other collections ...
        ]
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

## Document Management in Collections

### Assign Document to Collection

Assign a document to a collection:

```python
document_id = '789g012j-k34l-56m7-n890-123456789012' # must be a valid document id
assign_doc_result = client.assign_document_to_collection(document_id, collection_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': {
          'message': 'Document successfully assigned to the collection'
        }
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### Remove Document from Collection

Remove a document from a collection:

```python
remove_doc_result = client.remove_document_from_collection(document_id, collection_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': {
          'message': 'Document successfully removed from the collection'
        }
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### List Documents in Collection

Get a list of all documents in a specific collection:

```python
docs_in_collection = client.documents_in_collection(collection_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': [
          {
            'document_id': '789g012j-k34l-56m7-n890-123456789012',
            'title': 'Marketing Strategy 2024',
            # ... other document details ...
          },
          # ... other documents ...
        ]
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### Get Document's Collections

Get all collections that a document is assigned to:

```python
document_collections = client.document_collections(document_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': [
          {
            'collection_id': '123e4567-e89b-12d3-a456-426614174000',
            'name': 'Updated Marketing Team',
            # ... other Collection details ...
          },
          # ... other collections ...
        ]
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

## Advanced Collection Management

### Collection Overview

Get an overview of collections, including user and document counts:

```python
collections_overview = client.collections_overview()
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': [
          {
            'collection_id': '123e4567-e89b-12d3-a456-426614174000',
            'name': 'Updated Marketing Team',
            'description': 'New description for marketing team',
            'user_count': 5,
            'document_count': 10,
            'created_at': '2024-07-16T22:53:47.524794Z',
            'updated_at': '2024-07-16T23:15:30.123456Z'
          },
          # ... other collections ...
        ]
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

### Delete a Collection

Delete a collection:

```python
delete_result = client.delete_collection(collection_id)
```

<AccordionGroup>
  <Accordion title="Response">
    <ResponseField name="response" type="dict">
      ```python
      {
        'results': {
          'message': 'Collection successfully deleted'
        }
      }
      ```
    </ResponseField>
  </Accordion>
</AccordionGroup>

## Pagination and Filtering

Many collection-related methods support pagination and filtering:

```python
# List collections with pagination
paginated_collection = client.list_collections(offset=10, limit=20)

# Get users in a collection with pagination
paginated_users = client.get_users_in_collection(collection_id, offset=5, limit=10)

# Get documents in a collection with pagination
paginated_docs = client.documents_in_collection(collection_id, offset=0, limit=50)

# Get collections overview with specific collection IDs
specific_collections_overview = client.collections_overview(collection_ids=['id1', 'id2', 'id3'])
```

## Security Considerations

When implementing collection permissions, consider the following security best practices:

1. Always use HTTPS in production to encrypt data in transit.
2. Implement the principle of least privilege by assigning the minimum necessary permissions to users and collections.
3. Regularly audit collection memberships and document assignments.
4. Ensure that only authorized users (e.g., admins) can perform collection management operations.
5. Implement comprehensive logging for all collection-related actions.
6. Consider implementing additional access controls or custom roles within your application logic for more fine-grained permissions.

For more advanced use cases or custom implementations, refer to the R2R documentation or reach out to the community for support.