API Reference¶

Complete reference for the Adaptensor REST API.

Base URL: https://api.adaptensor.com (or your self-hosted instance)

Authentication¶

All API requests require an API key passed in the Authorization header:

Authorization: Bearer your-api-key

Or use the Python SDK which handles this automatically:

from adaptensor import Adaptensor
client = Adaptensor(api_key="your-api-key")

Endpoints Overview¶

Endpoint	Method	Description
`/health`	GET	Check API health
`/info`	GET	Get API version and config
`/stats`	GET	Get usage statistics
`/documents/upload`	POST	Upload a document
`/documents`	GET	List all documents
`/documents/index`	POST	Build search index
`/query`	POST	Search documents
`/embed`	POST	Generate embedding
`/embed_and_quantize`	POST	Embed with AdaptHex

Health¶

Check if the API is operational.

Request¶

GET /health

Response¶

{
  "status": "healthy",
  "timestamp": "2025-11-30T12:00:00Z"
}

Python SDK¶

if client.health():
    print("API is healthy")

Info¶

Get API version and configuration.

Request¶

GET /info

Response¶

{
  "name": "Adaptensor API",
  "version": "3.0.0",
  "embedding_model": "all-MiniLM-L6-v2",
  "embedding_dimensions": 384,
  "hex_mode": "hex8",
  "chunk_size": 512,
  "chunk_overlap": 64
}

Stats¶

Get usage statistics for your account.

Request¶

GET /stats

Response¶

{
  "documents": 5,
  "chunks": 3508,
  "queries": 127,
  "storage_bytes": 1458432,
  "index_size": 3508
}

Python SDK¶

stats = client.stats()
print(f"Documents: {stats['documents']}")
print(f"Chunks: {stats['chunks']}")

Upload Document¶

Upload a document for processing.

Request¶

POST /documents/upload
Content-Type: multipart/form-data

file: <binary file data>

Supported Formats¶

PDF (.pdf)
Word (.docx)
Text (.txt)
HTML (.html)
Markdown (.md)
CSV (.csv)

Response¶

{
  "status": "success",
  "doc_id": "eb920b0ec1dd",
  "filename": "contract.pdf",
  "size_bytes": 2150432,
  "text_length": 45230,
  "message": "Document uploaded and parsed. Call /documents/index to build search index."
}

Python SDK¶

doc = client.documents.upload("contract.pdf")
print(f"Uploaded: {doc.doc_id}")

cURL¶

curl -X POST "https://api.adaptensor.com/documents/upload" \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@contract.pdf"

List Documents¶

List all uploaded documents.

Request¶

GET /documents

Response¶

{
  "documents": [
    {
      "doc_id": "eb920b0ec1dd",
      "filename": "contract.pdf",
      "size_bytes": 2150432,
      "text_length": 45230,
      "status": "indexed"
    },
    {
      "doc_id": "a1b2c3d4e5f6",
      "filename": "report.docx",
      "size_bytes": 1024000,
      "text_length": 28500,
      "status": "indexed"
    }
  ],
  "count": 2
}

Python SDK¶

for doc in client.documents.list():
    print(f"{doc.filename}: {doc.size_bytes:,} bytes")

Build Index¶

Parse, chunk, embed, and index all uploaded documents.

Request¶

POST /documents/index
Content-Type: application/json

{
  "doc_ids": ["eb920b0ec1dd"]  // Optional: specific docs only
}

Response¶

{
  "status": "success",
  "documents_processed": 2,
  "total_chunks": 3508,
  "index_size": 3508,
  "elapsed_seconds": 285.4,
  "message": "Indexed 3508 chunks. Ready to search!"
}

Python SDK¶

result = client.documents.index()
print(f"Indexed {result.total_chunks} chunks in {result.elapsed_seconds:.1f}s")

cURL¶

curl -X POST "https://api.adaptensor.com/documents/index" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{}'

Search¶

Search documents with semantic query.

Request¶

POST /query
Content-Type: application/json

{
  "query": "termination clause",
  "top_k": 5
}

Parameters¶

Parameter	Type	Required	Default	Description
`query`	string	Yes	-	Natural language search query
`top_k`	integer	No	5	Number of results to return

Response¶

{
  "query": "termination clause",
  "count": 5,
  "elapsed_ms": 136.4,
  "results": [
    {
      "chunk_id": "eb920b0ec1dd_chunk_42",
      "text": "Either party may terminate this agreement with 30 days written notice...",
      "score": 0.8234,
      "metadata": {
        "doc_id": "eb920b0ec1dd",
        "filename": "contract.pdf",
        "chunk_index": 42
      }
    },
    {
      "chunk_id": "eb920b0ec1dd_chunk_43",
      "text": "Upon termination, all confidential information must be returned...",
      "score": 0.7891,
      "metadata": {
        "doc_id": "eb920b0ec1dd",
        "filename": "contract.pdf",
        "chunk_index": 43
      }
    }
  ]
}

Python SDK¶

results = client.query("termination clause", top_k=5)

for chunk in results:
    print(f"[{chunk.score:.2f}] {chunk.text[:100]}...")

cURL¶

curl -X POST "https://api.adaptensor.com/query" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "termination clause", "top_k": 5}'

Embed¶

Generate embedding for text.

Request¶

POST /embed
Content-Type: application/json

{
  "text": "machine learning algorithms"
}

Response¶

{
  "embedding": [0.0234, -0.1456, 0.0891, ...],
  "dimensions": 384
}

Python SDK¶

result = client.embed("machine learning", quantize=False)
print(f"Vector: {result.embedding[:5]}...")

Embed and Quantize¶

Generate embedding with AdaptHex compression.

Request¶

POST /embed_and_quantize
Content-Type: application/json

{
  "text": "machine learning algorithms",
  "mode": "hex8"
}

Parameters¶

Parameter	Type	Required	Default	Description
`text`	string	Yes	-	Text to embed
`mode`	string	No	"hex8"	Compression mode: "hex8" (4x), "hex4" (8x), "binary" (32x)

Response¶

{
  "embedding": [0.0234, -0.1456, 0.0891, ...],
  "hex_embedding": "80827E7C74807C7F82807B7F7F7C747F75847F858276807B867A88...",
  "dimensions": 384,
  "mode": "hex8",
  "compression_ratio": 4
}

Python SDK¶

result = client.embed("machine learning", quantize=True, mode="hex8")
print(f"Hex: {result.hex_embedding[:50]}...")

Error Responses¶

All errors follow this format:

{
  "error": "Error message description"
}

HTTP Status Codes¶

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
404	Not Found - Resource doesn't exist
408	Timeout - Request took too long
500	Server Error - Internal error

Common Errors¶

No documents indexed:

{"error": "No documents indexed. Call /documents/index first."}

Invalid file type:

{"error": "Unsupported file type. Supported: pdf, docx, txt, html, md, csv"}

File too large:

{"error": "File exceeds maximum size of 50MB"}

Rate Limits¶

Tier	Requests/min	Requests/day
Starter	60	5,000
Professional	300	50,000
Enterprise	Custom	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1701345600

SDKs¶

Official SDKs handle authentication, retries, and response parsing:

Python: pip install adaptensor (docs)
JavaScript: Coming soon
Go: Coming soon

Need Help?¶

Email: hello@adaptensor.com
GitHub: github.com/adaptensor