Sync Document API

The sync-document endpoint allows you to create, update, or delete documents within a collection. This endpoint automatically handles document creation, updates, and deletion based on the provided parameters. Documents can be uploaded as files (base64 encoded) or referenced via URL.

Endpoint

POST /sync-document

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

Header	Required	Description
Authorization	Yes	Bearer access_token from generate-client-auth-token
Content-Type	Yes	Must be application/json

Request Body

{
  document_id?: string;           // Optional: Document identifier (required for updates/deletes)
  document_name?: string;         // Required for create: Name of the document
  document_description?: string;   // Optional: Description of the document
  document_type?: string;         // Optional: Type of document (PDF, DOCX, TXT, IMG, OTHER)
  document_priority?: string;      // Optional: Priority level
  collection_id?: string;         // Required for create: Collection/group identifier
  document_tags?: string[];       // Optional: Array of tags
  document_file_path?: string;    // Optional: File path (for file uploads)
  fileBase64?: string;            // Optional: Base64 encoded file content
  fileType?: string;              // Optional: File MIME type
  document_url?: string;          // Optional: URL to the document (for URL-based documents)
  is_delete?: boolean;           // Optional: Set to true to delete the document
  // ... other optional fields
}

Request Parameters

document_id (optional)

• Type: string
• Description: Unique identifier for the document. Required when updating or deleting a document
• Example: "doc-123" or "550e8400-e29b-41d4-a716-446655440000"

document_name (required for create)

• Type: string
• Description: Name of the document
• Example: "My Document"

document_description (optional)

• Type: string
• Description: Description of the document
• Example: "This is a document description"

document_type (optional)

• Type: string
• Description: Type of document
• Allowed Values: "PDF", "DOCX", "TXT", "IMG", "OTHER"
• Example: "PDF"

collection_id (required for create)

• Type: string
• Description: Identifier of the collection/group this document belongs to
• Example: "collection-123"

fileBase64 (optional, for file uploads)

• Type: string
• Description: Base64 encoded file content. Required for file uploads along with document_file_path
• Example: "JVBERi0xLjQKJeLjz9MKMy..."

document_file_path (optional, for file uploads)

• Type: string
• Description: File path where the file should be stored. Required for file uploads along with fileBase64
• Example: "documents/my-document.pdf"

fileType (optional, for file uploads)

• Type: string
• Description: MIME type of the file
• Example: "application/pdf"

document_url (optional, for URL-based documents)

• Type: string
• Description: URL to the document. Used for documents that are hosted externally
• Example: "https://example.com/document.pdf"

is_delete (optional)

• Type: boolean
• Description: Set to true to delete the document. When deleting, document_id must be provided
• Default: false

Success Response

Creating a Document

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
    collection_id: string;          // Collection identifier
    document_file_path?: string;   // File path (if file-based)
    document_url?: string;         // Document URL (if URL-based)
    created_at: string;            // ISO timestamp
    updated_at: string;            // ISO timestamp
    // ... other document fields
  };
  message: "OKAY";
}

Updating a Document

Status Code: 200

{
  statusCode: 200;
  data: {
    document_id: string;           // Unique document identifier
    document_name: string;         // Updated document name
    document_description?: string;  // Updated document description
    collection_id: string;          // Collection identifier
    created_at: string;             // ISO timestamp
    updated_at: string;             // ISO timestamp
    // ... other document fields
  };
  message: "OKAY";
}

Deleting a Document

Status Code: 200

{
  statusCode: 200;
  data: {
  }
  message: "OKAY";
}

Error Responses

Missing Required Fields (435)

{
  statusCode: 435;
  data: {
  }
  message: "Missing required fields: document_name, collection_id";
}

Unauthorized (403)

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

Causes:

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

Not Found (437)

{
  statusCode: 437;
  data: {
  }
  message: "Document not found";
}

Causes:

• Attempting to update or delete a document that doesn't exist
• Invalid document_id provided

Server Fault (500)

{
  statusCode: 500;
  data: {
  }
  message: "Failed to upload document file";
}

Example Requests

Example 1: Create a Document with File Upload

This example shows creating a document with a file upload:

# 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: Create document with file upload
curl -X POST https://api.example.com/sync-document \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{
    "document_name": "My Document",
    "document_description": "This is my document",
    "document_type": "PDF",
    "collection_id": "collection-123",
    "fileBase64": "JVBERi0xLjQKJeLjz9MKMy...",
    "document_file_path": "documents/my-document.pdf",
    "fileType": "application/pdf"
  }'

Response:

{
  "statusCode": 200,
  "data": {
    "document_id": "doc-abc-123-def-456",
    "document_name": "My Document",
    "document_description": "This is my document",
    "document_type": "PDF",
    "collection_id": "collection-123",
    "document_file_path": "documents/my-document.pdf",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  },
  "message": "OKAY"
}

Example 2: Create a Document with URL

curl -X POST https://api.example.com/sync-document \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "document_name": "External Document",
    "document_description": "Document from external URL",
    "collection_id": "collection-123",
    "document_url": "https://example.com/document.pdf"
  }'

Example 3: Update a Document

curl -X POST https://api.example.com/sync-document \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "document_id": "doc-abc-123-def-456",
    "document_name": "Updated Document Name",
    "document_description": "Updated description"
  }'

Example 4: Delete a Document

curl -X POST https://api.example.com/sync-document \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {access_token}" \
  -d '{
    "is_delete": true,
    "document_id": "doc-abc-123-def-456"
  }'

Behavior Notes

Document Creation

• If document_id is not provided, a new document is created
• document_name and collection_id are required for document creation
• For file uploads, both fileBase64 and document_file_path must be provided
• For URL-based documents, document_url can be provided instead
• File-based documents are automatically processed and split into pages

Document Updates

• When document_id is provided and is_delete is false or not set, the document is updated
• Only provided fields are updated; omitted fields remain unchanged
• File uploads are not supported for updates (only metadata can be updated)

Document Deletion

• When is_delete is true, document_id must be provided
• Deletion is permanent and cannot be undone
• All associated plan associations and document pages are automatically removed
• Vector embeddings are also deleted

File Processing

• File-based documents are automatically queued for processing
• Documents are split into pages for indexing
• Processing happens asynchronously in the background

Related Documentation

• Documents Overview - Learn about documents concepts
• Get Document Details API - Retrieve document by ID
• Get Documents API - Retrieve list of documents
• Download Document API - Download document files
• Client Credentials API - Authentication endpoint
• API Guidelines - General API response formats and error codes