Documentation

Your first request

Ask the workspace owner for a Chatsax API key. Set it in your application environment; use the dashboard to try requests without writing a client.

curl https://chatsax.com/v1/read \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "url": "https://example.com"
}'

JSON Reader output normally contains data.title, data.url, and data.content. Usage fields come from the provider; do not treat a missing value as zero.

Use your Chatsax key

Send Authorization: Bearer $CHATSAX_API_KEY. Chatsax keys are separate from Jina provider keys. The upstream key is injected by the gateway and is not delivered to the browser.

An administrator creates scoped keys in Key Manager. Save a new key when it is displayed; later listings show its prefix. Each key has its own request limits and owns the classifiers and batch jobs it creates.

curl https://chatsax.com/api/me \
  -H "Authorization: Bearer $CHATSAX_API_KEY"

Browser sessions keep the key in session storage. “Remember on this device” additionally persists it in local storage. Disconnecting removes the locally stored key. Avoid shared devices for administrator access.

API reference

https://chatsax.com · Provider schema reference

The research model catalog includes older downloadable weights. The machine API catalog lists callable models. Check /v1/models before choosing a model for production.

Reader and Search

Reader extracts a known URL. Search discovers URLs from a query and returns readable results. Keep navigation fragments in POST JSON, and choose JSON or streaming with the Accept header.

curl https://chatsax.com/v1/search \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "q": "agent retrieval architecture",
  "num": 3
}'

Viewport, supplied HTML/PDF, CSS selectors, browser settings, caching, and Markdown options are available in the playground. ReaderLM-v2 is a separate conversion mode with additional provider usage. Cookies and DNT require special care with any caches you add.

A single Reader request reads one resource. It is not a recursive website crawl. Use your own queue and URL policy when collecting a whole site.

Embeddings and reranking

Use retrieval.query for questions and retrieval.passage for indexed documents. Keep model, dimensions, and task settings consistent across an index. For multimodal inputs, choose an omni or supported visual model.

curl https://chatsax.com/v1/embeddings \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "model": "jina-embeddings-v5-text-nano",
  "task": "retrieval.passage",
  "dimensions": 256,
  "normalized": true,
  "input": [
    "Build useful tools for agents.",
    "为智能体提供可靠的检索接口。"
  ]
}'

curl https://chatsax.com/v1/rerank \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "model": "jina-reranker-v3.5",
  "query": "agent search infrastructure",
  "top_n": 2,
  "return_documents": true,
  "documents": [
    "A gateway for agent retrieval tools.",
    "A recipe for vegetable soup.",
    "API keys and search result ranking."
  ]
}'

Rerank results use original input indices and descending relevance scores. v3.5 supports max_doc_length up to 8192 tokens per document and optional document embeddings. Ranking scores are not calibrated probabilities.

Classify with your labels

curl https://chatsax.com/v1/classify \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "model": "jina-embeddings-v5-text-nano",
  "input": [
    "Please cancel my subscription."
  ],
  "labels": [
    "Billing",
    "Technical support",
    "Feedback"
  ]
}'

Zero-shot classification needs model, input, and meaningful labels. For few-shot classification, supply a classifier_id owned by the current key instead. Label limits and supported modalities depend on the model.

Count tokens and split text

curl https://chatsax.com/v1/segment \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "content": "Agent tools need clear interfaces.\n工具需要清晰的接口。",
  "tokenizer": "cl100k_base",
  "return_tokens": true,
  "return_chunks": true,
  "max_chunk_length": 1000
}'

head and tail are mutually exclusive token slices. max_chunk_length is a character-based chunk control; it is not the model context length. Token counts vary by tokenizer, particularly with CJK text and emoji.

Persistent jobs and trained classifiers

Create a batch with input_url pointing to a JSONL file, or inline JSONL objects in input. Current provider batch models are v5-text-small and v5-text-nano. Poll the returned job ID, then download output and errors separately.

curl https://chatsax.com/v1/batch/embeddings \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "model": "jina-embeddings-v5-text-nano",
  "input_url": "https://your-domain.example/embedding-input.jsonl",
  "task": "retrieval.passage"
}'

Replace the example URL with a file you control. Batch input objects follow the provider’s current JSONL format; its older input_file examples do not match the current schema. Never reuse another key’s job ID.

curl https://chatsax.com/v1/train \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "model": "jina-embeddings-v5-text-nano",
  "access": "private",
  "input": [
    {
      "text": "Reset my password",
      "label": "Account"
    },
    {
      "text": "My invoice is incorrect",
      "label": "Billing"
    }
  ]
}'

Chatsax defaults new classifiers to private. Store the returned classifier_id. Use POST /v1/train with that ID to update it, and DELETE /v1/classifiers/{id} to remove it. Requests from other keys cannot use resources created by this key.

Research with sources

curl https://chatsax.com/v1/deepsearch \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "model": "jina-deepsearch-v1",
  "messages": [
    {
      "role": "user",
      "content": "Explain current approaches to late interaction retrieval, with sources."
    }
  ],
  "stream": true,
  "reasoning_effort": "low"
}'

For HTTP clients, consume SSE incrementally and support cancellation. Render citations and provider usage separately from answer text. Budget and domain-filter options belong in the request body. Grounding is implemented through DeepSearch structured output, rather than the retired Grounding endpoint.

The chat route accepts jina-deepsearch-v1 for research and jina-vlm for visual chat. VLM is experimental; do not assume the same availability or behavior as DeepSearch.

Connect agents through MCP

Chatsax provides a remote MCP endpoint at /mcp. Use a client supporting HTTP MCP and custom Authorization headers. Available tools reflect the key scopes: read, search, embed, rerank, classify, segment, and deepsearch.

{
  "mcpServers": {
    "chatsax": {
      "url": "https://chatsax.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_CHATSAX_API_KEY"
      }
    }
  }
}

Use the client’s secret storage or environment-variable feature for the key. MCP research tool calls currently return a completed response, while the REST DeepSearch endpoint can stream. A long research call still needs a suitable client timeout.

curl https://chatsax.com/mcp \
  -H "Authorization: Bearer $CHATSAX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "my-agent",
      "version": "1.0.0"
    }
  }
}'

Limits, usage, and failures

The gateway returns an error object and request_id for its own errors. Provider errors may preserve the upstream response. Account-specific minute and daily limits are visible through /api/me; provider token limits also apply.

Usage records include route, model, status, latency, and available token counts. A request cancelled after work starts may still consume provider resources. Do not blindly retry training or batch creation without checking whether a resource was created.

Source transparency

Chatsax independently operates the gateway and application. Jina currently supplies the model and retrieval APIs. Third-party names identify the provider; they do not imply that Chatsax is an official Jina service.

Open-source application code and model weights have different licenses. Many recent Jina weights use CC-BY-NC-4.0, and v4 uses a Qwen research license. Check the official model card before commercial self-hosting.

A foundation you can extend

These are development directions, not features promised as already deployed. The stable boundary is the API contract; individual providers can change behind it.

Follow the Chatsax project