API Overview

The Knowhere API provides a simple interface for document parsing. All endpoints follow RESTful conventions and use JSON for request and response bodies.

Base URL

https://api.knowhereto.ai

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Endpoints

Method	Endpoint	Description
POST	/v1/jobs	Create a new parsing job
GET	/v1/jobs/{job_id}	Get job status and results

Request Format

• Content-Type: application/json
• Character Encoding: UTF-8

curl -X POST https://api.knowhereto.ai/v1/jobs \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_type": "url", "source_url": "https://example.com/doc.pdf"}'

Response Format

All responses follow a consistent structure.

Success Response

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

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "source_url is required when source_type is 'url'",
    "request_id": "req_xyz789"
  }
}

HTTP Status Codes

Status	Meaning
200 OK	Request succeeded
202 Accepted	Job created (for URL source)
400 Bad Request	Invalid request parameters
401 Unauthorized	Invalid or missing API key
403 Forbidden	Insufficient permissions
404 Not Found	Resource not found
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error
503 Service Unavailable	Service temporarily unavailable

Rate Limiting

API requests are rate-limited per API key:

• Default limit: 60 requests per minute (RPM)

Rate limit information is included in response headers:

RateLimit-Limit: 60
RateLimit-Remaining: 58
RateLimit-Reset: 1672531200

When rate limited, you'll receive a 429 response:

{
  "success": false,
  "error": {
    "code": "RESOURCE_EXHAUSTED",
    "message": "Rate limit exceeded. Please retry after 15 seconds.",
    "request_id": "req_abc123",
    "details": {
      "retry_after": 15
    }
  }
}

Request IDs

Every response includes a request_id for debugging and support:

{
  "error": {
    "code": "...",
    "message": "...",
    "request_id": "req_abc123def456"
  }
}

Include this ID when contacting support.

Pagination

Currently, the API does not support listing jobs. Each job must be queried individually using its job_id.

Versioning

The API uses URL path versioning:

https://api.knowhereto.ai/v1/jobs
                          ^^
                          version

When we release breaking changes, we'll increment the version number. The current version (v1) will remain available and supported.

Next Steps

• Create Job - Submit documents for parsing
• Get Job - Check status and retrieve results