Skip to main content

​
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

FieldTypeDescription
document_setsarrayList of document sets
document_sets[].document_set_idstringDocument set UUID
document_sets[].document_set_namestringSet name
document_sets[].organization_idstringOrganization UUID
document_sets[].detailsstringOptional description
document_sets[].documentsarrayArray of associated document IDs
document_sets[].versionintegerSet 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

ParameterTypeRequiredDescription
document_set_idstringYesUUID 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

FieldTypeDescription
usersarrayUsers with access to this document set
users[].user_idstringUser UUID
users[].emailstringUser email
document_setarrayDocuments in this set
document_set[].idstringDocument UUID
document_set[].document_set_namestringParent set name
document_set[].organization_idstringOrganization UUID
document_set[].userstringOwner email
document_set[].statusstringDocument status
document_set[].product_namestringAssociated product name
document_set[].document_namestringDocument file name
document_set[].document_typestringDocument type
document_set[].created_atstringCreation timestamp
document_set[].updated_atstringLast 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

ParameterAliasTypeRequiredDescription
workspace_namedocument_set_namestringYesName 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

FieldTypeDescription
document_set_idstringAuto-generated UUID
document_set_namestringSet name
organization_idstringOrganization UUID
detailsstringOptional description (null on creation)
documentsarrayAssociated document IDs (empty on creation)
versionintegerSet 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"