Ctrl K

API Reference

Create document

Add a new document to a knowledgebase

Updated 25 Jan 2026

On this page

This endpoint creates a new document in a knowledgebase. Documents are processed asynchronously - the endpoint returns immediately while processing continues in the background.

Path Parameters

knowledgebaseIdintegerrequired

The unique identifier of the knowledgebase

Request Body

namestringrequired

The name of the document (max 255 characters)

descriptionstring

Optional description of the document (max 255 characters)

typestringrequired

Document type: website, pdf, txt, or docx

Website Documents

urlstring

The main URL to scrape. Required if links is not provided.

linksarray

Array of specific URLs to scrape. Required if url is not provided.

linkstringrequired

  A valid URL to include in the document

relative_links_limitinteger

Maximum number of relative links to follow when scraping (1-50)

File Documents (PDF, TXT, DOCX)

filefilerequired

The file to upload (max 20MB). Use multipart/form-data encoding.

Response

messagestring

Success message

dataobject

The created document object

idinteger

  The unique identifier of the document

namestring

  The name of the document

descriptionstring

  Description of the document

typestring

  Document type

type_labelstring

  Human-readable type label

statusstring

  Processing status (will be `processing` initially)

status_labelstring

  Human-readable status label

created_atstring

  ISO 8601 timestamp of creation

{
  "message": "Document created successfully. Processing will begin shortly.",
  "data": {
    "id": 1,
    "name": "Company Website",
    "description": "Main website content",
    "type": "website",
    "type_label": "Website",
    "status": "processing",
    "status_label": "Processing",
    "created_at": "2025-01-08T10:30:00.000000Z"
  }
}

{
  "message": "Document created successfully. Processing will begin shortly.",
  "data": {
    "id": 2,
    "name": "Product Manual",
    "description": "User guide for our product",
    "type": "pdf",
    "type_label": "PDF",
    "status": "processing",
    "status_label": "Processing",
    "created_at": "2025-01-08T10:35:00.000000Z"
  }
}

{
  "error": "Knowledgebase not found."
}

{
  "message": "A file is required for this document type.",
  "errors": {
    "file": [
      "A file is required for this document type."
    ]
  }
}

{
  "error": "Failed to create document. Please try again."
}

Document Types

Type	Description	Input
`website`	Scrapes web pages and extracts text content	URL or list of URLs
`pdf`	Extracts text from PDF files	PDF file upload
`txt`	Plain text content	TXT file upload
`docx`	Extracts text from Word documents	DOCX file upload

Example: Creating a Website Document

curl -X POST https://app.voxlink.ai/api/user/knowledgebases/1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Website",
    "description": "Main website content",
    "type": "website",
    "url": "https://example.com",
    "relative_links_limit": 20
  }'

Example: Uploading a PDF Document

curl -X POST https://app.voxlink.ai/api/user/knowledgebases/1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "name=Product Manual" \
  -F "description=User guide for our product" \
  -F "type=pdf" \
  -F "file=@/path/to/document.pdf"

Document processing is asynchronous. Poll the get document endpoint to check when processing is complete.