Skip to main content

Get Documents API

The get-documents endpoint allows you to retrieve a list of all documents for a specific collection. The response includes document information along with processing progress.

Endpoint​

POST /get-documents

Authentication​

This endpoint requires authentication using the access token obtained from generate-client-auth-token.

Include the token in the Authorization header:

Authorization: Bearer {access_token}

Request Headers​

HeaderRequiredDescription
AuthorizationYesBearer access_token from generate-client-auth-token
Content-TypeYesMust be application/json

Request Body​

{
  collection_id: string;  // Required: Collection identifier
}

Request Parameters​

collection_id (required)​

  • Type: string
  • Description: Identifier of the collection/group to fetch documents for
  • Example: "collection-123"

Success Response​

Status Code: 200

{
  statusCode: 200;
  data: [
    {
      document_id: string;           // Unique document identifier
      document_name: string;         // Document name
      document_description?: string;  // Document description
      document_type?: string;        // Document type (PDF, DOCX, TXT, IMG, OTHER)
      document_priority?: string;     // Document priority
      collection_id: string;          // Collection identifier
      document_file_path?: string;   // File path (if file-based)
      document_url?: string;          // Document URL (if URL-based)
      document_tags?: string[];       // Array of tags
      created_at: string;             // ISO timestamp
      updated_at: string;             // ISO timestamp
      collection_name?: string;       // Collection name
      avg_progress?: number;          // Average processing progress (0-100)
    },
    // ... more documents
  ];
  message: "OKAY";
}

Response Fields​

Each document in the array contains:

document_id​

  • Type: string
  • Description: Unique identifier for the document

document_name​

  • Type: string
  • Description: Name of the document

document_description​

  • Type: string (optional)
  • Description: Description of the document

document_type​

  • Type: string (optional)
  • Description: Type of document
  • Possible Values: "PDF", "DOCX", "TXT", "IMG", "OTHER"

collection_id​

  • Type: string
  • Description: Identifier of the collection/group this document belongs to

avg_progress​

  • Type: number (optional)
  • Description: Average processing progress across all pages (0-100)
  • Example: 85 (85% complete)

Error Responses​

Missing Required Fields (435)​

{
  statusCode: 435;
  data: {
  }
  message: "Collection ID is required";
}

Unauthorized (403)​

{
  statusCode: 403;
  data: {
  }
  message: "UNAUTHORIZED";
}

Causes:

  • Missing or invalid Authorization header
  • Expired or invalid access token

Server Fault (500)​

{
  statusCode: 500;
  data: {
  }
  message: "Failed to fetch documents";
}

Example Requests​

Example 1: Get Documents for Collection​

This example shows retrieving all documents for a specific collection:

# Step 1: Generate access token
curl -X POST https://api.example.com/generate-client-auth-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "fingerprint": "device-fingerprint-123",
    "user": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "group_name": "my-domain"
    }
  }'

# Response:
# {
#   "statusCode": 200,
#   "data": {
#     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
#   },
#   "message": "OKAY"
# }

# Step 2: Get documents using the access token
curl -X POST https://api.example.com/get-documents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "collection_id": "collection-123"
  }'

Response:

{
  "statusCode": 200,
  "data": [
    {
      "document_id": "doc-abc-123",
      "document_name": "Document 1",
      "document_description": "First document",
      "document_type": "PDF",
      "collection_id": "collection-123",
      "document_file_path": "documents/doc1.pdf",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "collection_name": "My Collection",
      "avg_progress": 100
    },
    {
      "document_id": "doc-def-456",
      "document_name": "Document 2",
      "document_description": "Second document",
      "document_type": "DOCX",
      "collection_id": "collection-123",
      "document_file_path": "documents/doc2.docx",
      "created_at": "2024-01-14T09:20:00Z",
      "updated_at": "2024-01-14T09:20:00Z",
      "collection_name": "My Collection",
      "avg_progress": 75
    }
  ],
  "message": "OKAY"
}

Behavior Notes​

Collection Filtering​

  • Only documents for the specified collection_id are returned
  • collection_id is required and must be provided
  • Empty arrays are returned if no documents exist in the collection

Processing Progress​

  • The avg_progress field indicates the average processing progress across all document pages
  • Progress ranges from 0 to 100
  • Documents that haven't been processed yet may not have a progress value

Response Ordering​

  • Documents are returned in an unspecified order
  • You may need to sort them client-side if a specific order is required

Empty Results​

  • If no documents exist in the collection, an empty array [] is returned
  • This is not an error condition