> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Sets API

> Manage workspaces that group related documents

# Document Sets API

Document Sets (also referred to as Workspaces) organize multiple related documents into logical groups for collaborative work and batch processing.

## List Document Sets

Retrieve all document sets accessible to the authenticated user.

```bash theme={null}
GET /api/v1/document-sets/
```

Access rules:

* **Internal / Owner** roles: all document sets within their organization
* **All other roles**: only document sets where their user ID is in the `users` array

### Request Example

```bash theme={null}
curl -X GET "https://api.artosai.com/api/v1/document-sets/" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response

```json theme={null}
{
  "document_sets": [
    {
      "document_set_id": "ws-uuid-123",
      "document_set_name": "Q1 CSR Documents",
      "organization_id": "org-uuid-789",
      "details": "CSR submission documents for Q1 2024",
      "documents": ["doc-uuid-1", "doc-uuid-2"],
      "version": 1
    },
    {
      "document_set_id": "ws-uuid-456",
      "document_set_name": "Phase 3 Protocols",
      "organization_id": "org-uuid-789",
      "details": null,
      "documents": ["doc-uuid-3"],
      "version": 2
    }
  ]
}
```

### Response Fields

| Field                               | Type    | Description                      |
| ----------------------------------- | ------- | -------------------------------- |
| `document_sets`                     | array   | List of document sets            |
| `document_sets[].document_set_id`   | string  | Document set UUID                |
| `document_sets[].document_set_name` | string  | Set name                         |
| `document_sets[].organization_id`   | string  | Organization UUID                |
| `document_sets[].details`           | string  | Optional description             |
| `document_sets[].documents`         | array   | Array of associated document IDs |
| `document_sets[].version`           | integer | Set version                      |

### Status Codes

* **200 OK**: Document sets retrieved successfully
* **400 Bad Request**: Authentication failed

***

## Get Document Set

Retrieve a specific document set by ID, including associated documents and users.

```bash theme={null}
GET /api/v1/document-sets/{document_set_id}
```

### Path Parameters

| Parameter         | Type   | Required | Description              |
| ----------------- | ------ | -------- | ------------------------ |
| `document_set_id` | string | Yes      | UUID of the document set |

### Request Example

```bash theme={null}
curl -X GET "https://api.artosai.com/api/v1/document-sets/ws-uuid-123" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Response

```json theme={null}
{
  "users": [
    {
      "user_id": "user-uuid-1",
      "email": "alice@example.com"
    },
    {
      "user_id": "user-uuid-2",
      "email": "bob@example.com"
    }
  ],
  "document_set": [
    {
      "id": "doc-uuid-1",
      "document_set_name": "Q1 CSR Documents",
      "organization_id": "org-uuid-789",
      "user": "alice@example.com",
      "status": "Ready",
      "product_name": "DrugX",
      "document_name": "CSR_Final.docx",
      "document_type": "CSR",
      "created_at": "2024-01-25T12:00:00",
      "updated_at": "2024-01-25T12:45:00"
    }
  ]
}
```

### Response Fields

| Field                              | Type   | Description                            |
| ---------------------------------- | ------ | -------------------------------------- |
| `users`                            | array  | Users with access to this document set |
| `users[].user_id`                  | string | User UUID                              |
| `users[].email`                    | string | User email                             |
| `document_set`                     | array  | Documents in this set                  |
| `document_set[].id`                | string | Document UUID                          |
| `document_set[].document_set_name` | string | Parent set name                        |
| `document_set[].organization_id`   | string | Organization UUID                      |
| `document_set[].user`              | string | Owner email                            |
| `document_set[].status`            | string | Document status                        |
| `document_set[].product_name`      | string | Associated product name                |
| `document_set[].document_name`     | string | Document file name                     |
| `document_set[].document_type`     | string | Document type                          |
| `document_set[].created_at`        | string | Creation timestamp                     |
| `document_set[].updated_at`        | string | Last updated timestamp                 |

### Status Codes

* **200 OK**: Document set retrieved successfully
* **400 Bad Request**: Authentication failed or document set not found
* **403 Forbidden**: Not authorized to access this document set

***

## Create Document Set

Create a new document set for organizing documents.

```bash theme={null}
POST /api/v1/document-sets/
```

### Request Body

Both field names are accepted — `workspace_name` (alias) and `document_set_name` (internal) are interchangeable.

```json theme={null}
{
  "workspace_name": "Q1 CSR Documents"
}
```

or equivalently:

```json theme={null}
{
  "document_set_name": "Q1 CSR Documents"
}
```

### Request Parameters

| Parameter        | Alias               | Type   | Required | Description                   |
| ---------------- | ------------------- | ------ | -------- | ----------------------------- |
| `workspace_name` | `document_set_name` | string | Yes      | Name for the new document set |

### Request Example

```bash theme={null}
curl -X POST "https://api.artosai.com/api/v1/document-sets/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_name": "Q1 CSR Documents"
  }'
```

### Python Example

```python theme={null}
import requests

url = "https://api.artosai.com/api/v1/document-sets/"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

payload = {"workspace_name": "Q1 CSR Documents"}

response = requests.post(url, headers=headers, json=payload)
document_set = response.json()
print(f"Created set: {document_set['document_set_id']}")
```

### Response (201 Created)

```json theme={null}
{
  "document_set_id": "ws-uuid-123",
  "document_set_name": "Q1 CSR Documents",
  "organization_id": "org-uuid-789",
  "details": null,
  "documents": [],
  "version": 1
}
```

### Response Fields

| Field               | Type    | Description                                 |
| ------------------- | ------- | ------------------------------------------- |
| `document_set_id`   | string  | Auto-generated UUID                         |
| `document_set_name` | string  | Set name                                    |
| `organization_id`   | string  | Organization UUID                           |
| `details`           | string  | Optional description (null on creation)     |
| `documents`         | array   | Associated document IDs (empty on creation) |
| `version`           | integer | Set version (initialized to 1)              |

### Status Codes

* **201 Created**: Document set created successfully
* **400 Bad Request**: Authentication failed or missing token
* **500 Internal Server Error**: Database error

### Notes

* **Creator Automatically Added**: The user creating the set is automatically added to the `users` array
* **Organization-Scoped**: Set is automatically associated with the authenticated user's organization
* **Version Tracking**: Initial version is 1

***

## Typical Workflow

```bash theme={null}
TOKEN="your_bearer_token"
API="https://api.artosai.com"

# 1. List existing workspaces
curl -X GET "$API/api/v1/document-sets/" \
  -H "Authorization: Bearer $TOKEN"

# 2. Create a new workspace
SET_ID=$(curl -s -X POST "$API/api/v1/document-sets/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspace_name": "Phase 3 Study"}' | jq -r '.document_set_id')

echo "Created workspace: $SET_ID"

# 3. Generate documents into the workspace (documents are added via /documents/generate)

# 4. Retrieve the workspace with all documents
curl -X GET "$API/api/v1/document-sets/$SET_ID" \
  -H "Authorization: Bearer $TOKEN"
```