Create Job

Submit a document for parsing.

POST /v1/jobs

Request Body

Parameter	Type	Required	Description
`source_type`	string	Yes	Document source type: `"url"` or `"file"`
`source_url`	string	Conditional	Required if `source_type` is `"url"`. URL of the document.
`file_name`	string	Conditional	Required if `source_type` is `"file"`. Name of the file including extension.
`data_id`	string	No	Your custom identifier for this document. Included in results for easy mapping. Max 128 chars, alphanumeric with `-`, `_`, `.` allowed.
`parsing_params`	object	No	Parsing configuration options.
`parsing_params.model`	string	No	Model to use: `"base"` (default) or `"advanced"`. Different credit costs apply.
`parsing_params.ocr_enabled`	boolean	No	Enable OCR for scanned documents or images. Default: `false`.
`llm_config`	object	No	v2 only (`POST /v2/jobs`). Bring-your-own-key (BYOK) OpenAI-compatible LLM credentials. Flat `{api_key, model, base_url}` applies to both channels; `models` picks per-channel model ids on the same endpoint; `text` / `vision` objects replace a channel entirely. When omitted, server defaults are used.
`llm_config.api_key`	string	Conditional	Required with `base_url` plus `model` and/or `models`. Provider API key.
`llm_config.model`	string	Conditional	Default model for both channels (overridden by `models.*`).
`llm_config.base_url`	string	Conditional	Required with `api_key` plus `model` and/or `models`. OpenAI-compatible base URL.
`llm_config.models`	object	No	Per-channel model ids sharing root `api_key` / `base_url`.
`llm_config.models.text`	string	No	Text / planning model id.
`llm_config.models.vision`	string	No	Vision / VLM model id.
`llm_config.text`	object	No	Text / planning LLM provider config (replaces root for text).
`llm_config.text.api_key`	string	Conditional	Required when `text` is present. Provider API key.
`llm_config.text.model`	string	Conditional	Required when `text` is present. Model identifier.
`llm_config.text.base_url`	string	Conditional	Required when `text` is present. OpenAI-compatible base URL.
`llm_config.vision`	object	No	Vision / VLM provider config (replaces root for vision).
`llm_config.vision.api_key`	string	Conditional	Required when `vision` is present. Provider API key.
`llm_config.vision.model`	string	Conditional	Required when `vision` is present. Model identifier.
`llm_config.vision.base_url`	string	Conditional	Required when `vision` is present. OpenAI-compatible base URL.

Response

For `source_type: "url"`

Status: 202 Accepted

The job is immediately queued for processing.

{
  "job_id": "job_abc123def456",
  "status": "pending",
  "source_type": "url",
  "data_id": "my_document_001",
  "created_at": "2025-01-15T10:30:00Z"
}

For `source_type: "file"`

Status: 200 OK

Returns an upload URL for the file.

{
  "job_id": "job_xyz789ghi012",
  "status": "waiting-file",
  "source_type": "file",
  "data_id": "my_document_002",
  "upload_url": "https://storage.knowhereto.ai/uploads/job_xyz789ghi012?X-Amz-...",
  "upload_headers": {
    "Content-Type": "application/pdf"
  },
  "created_at": "2025-01-15T10:30:00Z"
}

Examples

Parse Document from URL

cURL
Python
Node.js

curl -X POST https://api.knowhereto.ai/v1/jobs \
  -H "Authorization: Bearer $KNOWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "url",
    "source_url": "https://arxiv.org/pdf/1706.03762.pdf",
    "data_id": "attention_paper",
    "parsing_params": {
      "model": "base",
      "ocr_enabled": false
    }
  }'

import requests

response = requests.post(
    "https://api.knowhereto.ai/v1/jobs",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "source_type": "url",
        "source_url": "https://arxiv.org/pdf/1706.03762.pdf",
        "data_id": "attention_paper",
        "parsing_params": {
            "model": "base",
            "ocr_enabled": False
        }
    }
)

job = response.json()
print(f"Job ID: {job['job_id']}")
print(f"Status: {job['status']}")

const response = await fetch('https://api.knowhereto.ai/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_type: 'url',
    source_url: 'https://arxiv.org/pdf/1706.03762.pdf',
    data_id: 'attention_paper',
    parsing_params: {
      model: 'base',
      ocr_enabled: false
    }
  })
});

const job = await response.json();
console.log(`Job ID: ${job.job_id}`);
console.log(`Status: ${job.status}`);

Upload Local File

cURL
Python
Node.js

# Step 1: Create job
curl -X POST https://api.knowhereto.ai/v1/jobs \
  -H "Authorization: Bearer $KNOWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "file",
    "file_name": "quarterly_report.pdf",
    "data_id": "q3_2025_report"
  }'

# Response:
# {
#   "job_id": "job_xyz789",
#   "status": "waiting-file",
#   "upload_url": "https://storage.knowhereto.ai/...",
#   "upload_headers": {"Content-Type": "application/pdf"}
# }

# Step 2: Upload file
curl -X PUT "https://storage.knowhereto.ai/..." \
  -H "Content-Type: application/pdf" \
  --data-binary @quarterly_report.pdf

import requests

# Step 1: Create job and get upload URL
response = requests.post(
    "https://api.knowhereto.ai/v1/jobs",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "source_type": "file",
        "file_name": "quarterly_report.pdf",
        "data_id": "q3_2025_report"
    }
)

job = response.json()
print(f"Job ID: {job['job_id']}")

# Step 2: Upload file to presigned URL
with open("quarterly_report.pdf", "rb") as f:
    upload_response = requests.put(
        job["upload_url"],
        headers=job.get("upload_headers", {}),
        data=f.read()
    )

if upload_response.status_code in [200, 204]:
    print("Upload successful!")
else:
    print(f"Upload failed: {upload_response.status_code}")

import fs from 'fs';

// Step 1: Create job and get upload URL
const response = await fetch('https://api.knowhereto.ai/v1/jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_type: 'file',
    file_name: 'quarterly_report.pdf',
    data_id: 'q3_2025_report'
  })
});

const job = await response.json();
console.log(`Job ID: ${job.job_id}`);

// Step 2: Upload file to presigned URL
const fileBuffer = fs.readFileSync('quarterly_report.pdf');
const uploadResponse = await fetch(job.upload_url, {
  method: 'PUT',
  headers: job.upload_headers || {},
  body: fileBuffer
});

if (uploadResponse.ok) {
  console.log('Upload successful!');
} else {
  console.log(`Upload failed: ${uploadResponse.status}`);
}

With Advanced Options

curl -X POST https://api.knowhereto.ai/v1/jobs \
  -H "Authorization: Bearer $KNOWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "url",
    "source_url": "https://example.com/scanned_document.pdf",
    "data_id": "scanned_001",
    "parsing_params": {
      "model": "advanced",
      "ocr_enabled": true
    }
  }'

With Custom LLM (BYOK)

llm_config is available on POST /v2/jobs only. OpenAI-compatible providers only.

Flat {api_key, model, base_url} → both text and vision (multimodal shorthand)
{api_key, base_url, models: {text, vision}} → same endpoint, different model ids
text / vision objects → fully replace that channel (set both for different endpoints)
a channel with no resolved model keeps the server default

cURL
Python
Node.js

curl -X POST https://api.knowhereto.ai/v2/jobs \
  -H "Authorization: Bearer $KNOWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_type": "url",
    "source_url": "https://example.com/scanned_document.pdf",
    "data_id": "scanned_001",
    "parsing_params": {
      "model": "advanced",
      "ocr_enabled": true
    },
    "llm_config": {
      "api_key": "sk-...",
      "model": "gpt-4.1",
      "base_url": "https://api.openai.com/v1"
    }
  }'

import requests

response = requests.post(
    "https://api.knowhereto.ai/v2/jobs",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "source_type": "url",
        "source_url": "https://example.com/scanned_document.pdf",
        "data_id": "scanned_001",
        "parsing_params": {
            "model": "advanced",
            "ocr_enabled": True
        },
        "llm_config": {
            "api_key": "sk-...",
            "model": "gpt-4.1",
            "base_url": "https://api.openai.com/v1"
        }
    }
)

job = response.json()
print(f"Job ID: {job['job_id']}")

const response = await fetch('https://api.knowhereto.ai/v2/jobs', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    source_type: 'url',
    source_url: 'https://example.com/scanned_document.pdf',
    data_id: 'scanned_001',
    parsing_params: {
      model: 'advanced',
      ocr_enabled: true
    },
    llm_config: {
      api_key: 'sk-...',
      model: 'gpt-4.1',
      base_url: 'https://api.openai.com/v1'
    }
  })
});

const job = await response.json();
console.log(`Job ID: ${job.job_id}`);

Errors

Code	HTTP Status	Description
`INVALID_ARGUMENT`	400	Missing or invalid parameters
`UNAUTHENTICATED`	401	Invalid API key
`RESOURCE_EXHAUSTED`	429	Rate limit exceeded

Example Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "source_url must be a valid HTTP or HTTPS URL",
    "request_id": "req_abc123",
    "details": {
      "field": "source_url",
      "reason": "INVALID_URL_FORMAT"
    }
  }
}

Supported File Formats

Format	Extension	Max Size
PDF	`.pdf`	100 MB
Word	`.docx`	50 MB
Excel	`.xlsx`	50 MB
PowerPoint	`.pptx`	100 MB

Next Steps

Get Job - Check job status and retrieve results
File Upload Guide - Detailed upload instructions

Request Body​

Response​

For source_type: "url"​

For source_type: "file"​

Examples​

Parse Document from URL​

Upload Local File​

With Advanced Options​

With Custom LLM (BYOK)​

Errors​

Example Error Response​

Supported File Formats​

Next Steps​