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.

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

curl -X GET "https://api.artosai.com/api/v1/document-sets/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

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

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

curl -X GET "https://api.artosai.com/api/v1/document-sets/ws-uuid-123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

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

POST /api/v1/document-sets/

Request Body

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

{
  "workspace_name": "Q1 CSR Documents"
}

or equivalently:

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

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

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)

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

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"

Getting Started

API Reference

Core Concepts

Single-Tenant

Cookbooks

NPM SDK Reference

Integrations

Deployment

Document Sets API

Document Sets API

List Document Sets

Request Example

Response

Response Fields

Status Codes

Get Document Set

Path Parameters

Request Example

Response

Response Fields

Status Codes

Create Document Set

Request Body

Request Parameters

Request Example

Python Example

Response (201 Created)

Response Fields

Status Codes

Notes

Typical Workflow

​Document Sets API

​List Document Sets

​Request Example

​Response

​Response Fields

​Status Codes

​Get Document Set

​Path Parameters

​Request Example

​Response

​Response Fields

​Status Codes

​Create Document Set

​Request Body

​Request Parameters

​Request Example

​Python Example

​Response (201 Created)

​Response Fields

​Status Codes

​Notes

​Typical Workflow

Document Sets API

List Document Sets

Request Example

Response

Response Fields

Status Codes

Get Document Set

Path Parameters

Request Example

Response

Response Fields

Status Codes

Create Document Set

Request Body

Request Parameters

Request Example

Python Example

Response (201 Created)

Response Fields

Status Codes

Notes

Typical Workflow