Skip to content

Document API

Manage documents in knowledge repositories programmatically. Upload, update, query, and delete documents for RAG-powered AI agents.

List Documents

Retrieve all documents in a repository with pagination.

Endpoint: GET /repositories/{repositoryId}/documents

Parameters

Parameter Type Location Required Description
repositoryId string (UUID) path Yes Repository identifier
start number query No Page start value (default: 0)
limit number query No Documents per page (default: 50)

Example

curl "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/{repoId}/documents?start=0&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "documents": [
      {
        "id": "doc_123",
        "title": "Product Guide",
        "content": "Document content...",
        "metadata": {},
        "createdAt": "2025-01-01T00:00:00Z",
        "updatedAt": "2025-01-15T00:00:00Z"
      }
    ],
    "pagination": {
      "total": 150,
      "start": 0,
      "limit": 50
    }
  },
  "error": null
}

Create Document

Upload a new document to a repository.

Endpoint: POST /repositories/{repositoryId}/documents

Parameters

Parameter Type Location Required Description
repositoryId string (UUID) path Yes Repository identifier

Request Body

{
  "title": "Document Title",
  "content": "Full document content",
  "metadata": {
    "source": "API",
    "category": "Product Docs",
    "tags": ["guide", "tutorial"]
  }
}

Example

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/{repoId}/documents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting Started Guide",
    "content": "This is a comprehensive guide...",
    "metadata": {
      "author": "API User",
      "version": "1.0"
    }
  }'

Response

{
  "data": {
    "id": "doc_abc123",
    "title": "Getting Started Guide",
    "content": "This is a comprehensive guide...",
    "metadata": {
      "author": "API User",
      "version": "1.0"
    },
    "createdAt": "2025-01-20T12:00:00Z",
    "updatedAt": "2025-01-20T12:00:00Z"
  },
  "error": null
}

Get Document

Retrieve a specific document by ID.

Endpoint: GET /repositories/{repositoryId}/documents/{id}

Parameters

Parameter Type Location Required Description
repositoryId string (UUID) path Yes Repository identifier
id string (UUID) path Yes Document identifier

Example

curl "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/{repoId}/documents/{docId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Document

Update an existing document's content or metadata.

Endpoint: PUT /repositories/{repositoryId}/documents/{id}

Parameters

Parameter Type Location Required Description
repositoryId string (UUID) path Yes Repository identifier
id string (UUID) path Yes Document identifier

Request Body

{
  "title": "Updated Title",
  "content": "Updated content",
  "metadata": {
    "version": "2.0",
    "lastEditor": "API"
  }
}

Example

curl -X PUT "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/{repoId}/documents/{docId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Getting Started Guide",
    "content": "This is the updated version...",
    "metadata": {
      "version": "2.0"
    }
  }'

Delete Document

Remove a document from a repository.

Endpoint: DELETE /repositories/{repositoryId}/documents/{id}

Parameters

Parameter Type Location Required Description
repositoryId string (UUID) path Yes Repository identifier
id string (UUID) path Yes Document identifier

Example

curl -X DELETE "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/{repoId}/documents/{docId}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "deleted": true,
    "id": "doc_abc123"
  },
  "error": null
}

Query Documents

Search and retrieve documents using vector similarity search.

Endpoint: POST /repositories/{repositoryId}/documents/query

Parameters

Parameter Type Location Required Description
repositoryId string (UUID) path Yes Repository identifier

Request Body

{
  "query": "How to set up authentication?",
  "limit": 10,
  "filters": {
    "category": "Security",
    "tags": ["authentication"]
  }
}
Field Type Required Description
query string Yes Search query text
limit number No Max results to return (default: 10)
filters object No Metadata filters for narrowing results

Example

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/repositories/{repoId}/documents/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication best practices",
    "limit": 5
  }'

Response

{
  "data": {
    "results": [
      {
        "id": "doc_123",
        "title": "Authentication Guide",
        "content": "Excerpt from document...",
        "score": 0.95,
        "metadata": {
          "category": "Security"
        }
      }
    ],
    "query": "authentication best practices",
    "totalResults": 5
  },
  "error": null
}

Finding Repository ID

To find your repository ID:

  1. Navigate to Knowledge in the platform
  2. Select your repository
  3. The repository ID is shown in the URL or settings

Alternatively, use the Repository API to list all repositories.

Best Practices

Document Structure

{
  "title": "Clear, Descriptive Title",
  "content": "Well-formatted markdown or plain text",
  "metadata": {
    "source": "api|manual|crawled",
    "category": "category-name",
    "tags": ["tag1", "tag2"],
    "author": "author-name",
    "version": "1.0",
    "language": "en",
    "custom_field": "custom value"
  }
}

Tips

  1. Use Metadata: Add relevant metadata for better filtering and organization
  2. Keep Documents Focused: One topic per document for better retrieval
  3. Update Regularly: Keep documents current with PUT requests
  4. Batch Operations: Use pagination when listing large document sets
  5. Test Queries: Verify vector search results match expectations

Common Use Cases

Bulk Document Upload

import requests

API_KEY = "your_api_key"
REPO_ID = "your_repo_id"
BASE_URL = "https://PLATFORM-URL-PLACEHOLDER/v1/api"

documents = [
    {"title": "Doc 1", "content": "Content 1"},
    {"title": "Doc 2", "content": "Content 2"},
]

for doc in documents:
    response = requests.post(
        f"{BASE_URL}/repositories/{REPO_ID}/documents",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=doc
    )
    print(f"Created: {response.json()['data']['id']}")

Search and Update

# Search for outdated docs
response = requests.post(
    f"{BASE_URL}/repositories/{REPO_ID}/documents/query",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"query": "version 1.0", "filters": {"version": "1.0"}}
)

# Update found documents
for doc in response.json()['data']['results']:
    requests.put(
        f"{BASE_URL}/repositories/{REPO_ID}/documents/{doc['id']}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={"metadata": {"version": "2.0"}}
    )