Documents API

Upload, manage, and process documents in your workspace.

Endpoints

Method	Path	Description
POST	/workspaces/:id/documents	Upload document
GET	/workspaces/:id/documents	List documents
GET	/workspaces/:id/documents/:docId	Get document
PUT	/workspaces/:id/documents/:docId	Update metadata
PATCH	/workspaces/:id/documents/:docId	Auto-save content
DELETE	/workspaces/:id/documents/:docId	Delete document
POST	/workspaces/:id/documents/:docId/process	Reprocess document

Upload document

POST /workspaces/:id/documents
Content-Type: multipart/form-data

Upload a new document for processing.

Request (multipart/form-data)

Field	Type	Required	Description
file	File	Yes	The document file
title	String	No	Custom title (defaults to filename)
purpose	String	No	KNOWLEDGE or INSTRUCTION
tags	String[]	No	Tag IDs to apply

Supported formats

• PDF (.pdf)
• Microsoft Word (.docx, .doc)
• Plain text (.txt)
• Markdown (.md)

Response

{
  "id": "doc_xyz789",
  "title": "My Document",
  "filename": "document.pdf",
  "mimeType": "application/pdf",
  "size": 1024000,
  "purpose": "KNOWLEDGE",
  "uploadStatus": "COMPLETED",
  "processingStatus": "PROCESSING",
  "createdAt": "2025-01-01T12:00:00Z"
}

Example

cURL

curl -X POST "https://api.synjar.com/v1/workspaces/ws_abc123/documents" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@document.pdf" \
  -F "title=My Document" \
  -F "purpose=KNOWLEDGE"

JavaScript

const formData = new FormData();
formData.append('file', fileBlob, 'document.pdf');
formData.append('title', 'My Document');
formData.append('purpose', 'KNOWLEDGE');

const response = await fetch(
  'https://api.synjar.com/v1/workspaces/ws_abc123/documents',
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${apiKey}` },
    body: formData,
  }
);

const document = await response.json();

Python

with open('document.pdf', 'rb') as f:
    response = requests.post(
        'https://api.synjar.com/v1/workspaces/ws_abc123/documents',
        headers={'Authorization': f'Bearer {api_key}'},
        files={'file': ('document.pdf', f, 'application/pdf')},
        data={'title': 'My Document', 'purpose': 'KNOWLEDGE'}
    )

document = response.json()

List documents

GET /workspaces/:id/documents

List all documents in a workspace.

Query parameters

Parameter	Type	Description
page	Number	Page number (default: 1)
limit	Number	Items per page (default: 20, max: 100)
status	String	Filter by processing status
purpose	String	Filter by purpose
tags	String	Comma-separated tag IDs
search	String	Full-text search in titles

Response

{
  "data": [
    {
      "id": "doc_xyz789",
      "title": "My Document",
      "purpose": "KNOWLEDGE",
      "processingStatus": "VERIFIED",
      "tags": ["tag_abc"],
      "createdAt": "2025-01-01T12:00:00Z",
      "updatedAt": "2025-01-01T12:05:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "pages": 3
  }
}

Get document

GET /workspaces/:id/documents/:docId

Get full document details including content chunks.

Response

{
  "id": "doc_xyz789",
  "title": "My Document",
  "filename": "document.pdf",
  "mimeType": "application/pdf",
  "size": 1024000,
  "purpose": "KNOWLEDGE",
  "uploadStatus": "COMPLETED",
  "processingStatus": "VERIFIED",
  "tags": [
    {
      "id": "tag_abc",
      "name": "Important",
      "color": "#FF5733"
    }
  ],
  "chunkCount": 15,
  "tokenCount": 4500,
  "createdAt": "2025-01-01T12:00:00Z",
  "updatedAt": "2025-01-01T12:05:00Z"
}

Update metadata

PUT /workspaces/:id/documents/:docId

Update document title, purpose, or tags.

Request

{
  "title": "Updated Title",
  "purpose": "INSTRUCTION",
  "tags": ["tag_abc", "tag_def"]
}

Auto-save content

PATCH /workspaces/:id/documents/:docId

Auto-save document content (for text/markdown documents).

Request

{
  "content": "# Updated content\n\nThis is the new document content."
}

note

After updating content, document will be re-processed. Status will change to PROCESSING.

Delete document

DELETE /workspaces/:id/documents/:docId

Permanently delete a document.

warning

This action cannot be undone. The document will be removed from all instruction sets and search results.

Reprocess document

POST /workspaces/:id/documents/:docId/process

Trigger reprocessing of a document. Useful after content updates or if processing failed.

Response

{
  "id": "doc_xyz789",
  "processingStatus": "PROCESSING",
  "message": "Document queued for reprocessing"
}

Processing status

Documents go through these statuses:

Status	Description
PENDING	Upload received, waiting for processing
PROCESSING	Extracting text and generating embeddings
VERIFIED	Processing complete, document is searchable
FAILED	Processing failed (check error message)

Document purpose

Purpose	Description
KNOWLEDGE	Searchable via RAG (returns relevant chunks)
INSTRUCTION	Full document available in instruction sets

Error responses

Status	Code	Description
400	INVALID_FILE_TYPE	Unsupported file format
400	FILE_TOO_LARGE	File exceeds size limit
401	UNAUTHORIZED	Missing or invalid token
403	FORBIDDEN	Insufficient permissions
404	DOCUMENT_NOT_FOUND	Document doesn't exist
409	DOCUMENT_LOCKED	Document is locked by another user

See also

• Workspaces API
• Search API
• Uploading documents
• Organizing with tags