Skip to main content

​
Document Sets API

Document Sets enable organizing multiple related documents into logical groups for collaborative work and batch processing.

​
Get Document Set

Retrieve a document set including all associated documents and users. 
GET /api/v1/document-sets/{document_set_id}

​
Path Parameters

ParameterTypeRequiredDescription
document_set_idstringYesUUID of document set

​
Request Example

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

​
Response

{
  "users": [
    {
      "user_id": "user-uuid",
      "email": "[email protected]",
      "role": "admin"
    }
  ],
  "document_set": [
    {
      "document_set_id": "set-uuid",
      "document_set_name": "Q1 CSR Documents",
      "organization_id": "org-uuid",
      "details": "CSR submission documents for Q1 2024",
      "documents": ["doc-1", "doc-2", "doc-3"],
      "version": 1,
      "created_at": "2024-01-20T10:00:00Z"
    }
  ]
}

​
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

{
  "document_set_name": "Q1 CSR Documents"
}

​
Request Parameters

ParameterTypeRequiredDescription
document_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 '{
    "document_set_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 = {"document_set_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": "set-uuid-123",
  "document_set_name": "Q1 CSR Documents",
  "organization_id": "org-uuid",
  "details": null,
  "documents": [],
  "version": 1
}

​
Response Fields

FieldTypeDescription
document_set_idstringAuto-generated UUID
document_set_namestringSet name
organization_idstringOrganization UUID
detailsstringOptional details/description
documentsarrayArray of document IDs
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

​
Features

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

​
Typical Workflow

# 1. Create document set
SET_ID=$(curl -X POST "https://api.artosai.com/api/v1/document-sets/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document_set_name": "Q1 Documents"}' | jq -r '.document_set_id')

# 2. Upload documents to set
# Documents are associated with sets during generation or management operations

# 3. Retrieve set with all documents
curl -X GET "https://api.artosai.com/api/v1/document-sets/$SET_ID" \
  -H "Authorization: Bearer $TOKEN"