HTTP API — Multi-LLM, RAG & Batch

A single, OpenAI-compatible REST surface to build LinkWorld into your own software: multi-provider inference, managed retrieval (RAG), and batch processing — EU-sovereign by default, and metered per one of your own end-customers so you can bill them cleanly.

Base URL: https://api.linkworld.ai

Why it exists

You already have a product with your own customers. This API lets you:

Not pick one model vendor. Route by intent (eu-sovereign / frontier / cheapest) or an explicit provider/model — one key, one API, with failover.
Not manage RAG. Push documents (text or PDF); we chunk, embed and store the vectors — retrieval is one call.
Bill per your customer. Every call is tagged to one of your tenants; usage rolls up per tenant so you can attribute and resell.
Stay EU-sovereign. The default inference and all embeddings run under EU jurisdiction; US frontier models are an explicit, per-call opt-in.

It’s a drop-in for an existing OpenAI/OpenAI-compatible client — point your base_url at https://api.linkworld.ai/v1 and set your key.

Authentication

Two headers on every request:

Authorization: Bearer rk_live_…      # your organization key
X-LW-Tenant: <your-customer-id>      # which of YOUR customers this call is for

X-LW-Tenant is a free-form id you choose (e.g. cust_8f2a). Tenants are created implicitly on first use — you don’t pre-register them. Usage accumulates per tenant automatically. Optionally register one up front to attach a name (see Tenants & usage).

Model tiers & policy

Pick intent, not a vendor — we resolve the concrete provider and can swap backends without you re-integrating.

`tier`	Routes to	Jurisdiction
`eu-sovereign` (default)	EU-hosted open model → EU providers, with fallback	EU
`frontier`	Newest frontier models (opt-in)	US
`cheapest`	Lowest-cost available	EU

Model policy — enforced, not trusted. Set contains_pii: true on a request and a non-EU model is rejected (403). Personal data can never reach a US model, technically guaranteed:

{ "tier": "frontier", "contains_pii": true, "messages": [ … ] }
// → 403 policy_violation: PII may only use an EU-sovereign model

You may also send an explicit provider (anthropic · openai · mistral · ollama · ovh) or just a model — a plain OpenAI-style {"model":"…"} is routed by name (e.g. a Qwen… model → EU, gpt… → OpenAI, claude… → Anthropic).

Chat completions

POST /v1/chat/completions — OpenAI-compatible request and response.

curl https://api.linkworld.ai/v1/chat/completions \
  -H "Authorization: Bearer rk_live_…" \
  -H "X-LW-Tenant: cust_8f2a" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": "eu-sovereign",
    "messages": [{"role": "user", "content": "Summarise this in one sentence: …"}]
  }'

{
  "id": "chatcmpl-…",
  "object": "chat.completion",
  "model": "mistral-medium-latest",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "…"},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 29, "completion_tokens": 36, "total_tokens": 65, "cost_usd": 0.00008},
  "provider": "mistral",
  "tenant": "cust_8f2a"
}

provider, tenant and usage.cost_usd are LinkWorld extensions — standard OpenAI clients ignore unknown fields. Swap "tier": "eu-sovereign" for "tier": "frontier" (or a specific model) with no other change.

Embeddings

POST /v1/embeddings — OpenAI-compatible. EU-only embedder (Mistral, or a self-hosted model) → inherently safe for personal data.

curl https://api.linkworld.ai/v1/embeddings \
  -H "Authorization: Bearer rk_live_…" \
  -H "X-LW-Tenant: cust_8f2a" \
  -H "Content-Type: application/json" \
  -d '{"input": ["first text", "second text"]}'

{
  "object": "list",
  "data": [{"object": "embedding", "index": 0, "embedding": [ … 1024 floats … ]}],
  "model": "mistral:mistral-embed",
  "usage": {"prompt_tokens": 13, "total_tokens": 13}
}

input accepts a string or an array of strings. Vectors are 1024-dimensional and unit-normalized.

Managed RAG

Stop managing embeddings and a vector database. Push documents into a collection per tenant; we chunk, embed (EU) and store the vectors. Query is one call (hybrid vector + full-text retrieval).

Create a collection (idempotent):

curl https://api.linkworld.ai/v1/rag/handbook \
  -H "Authorization: Bearer rk_live_…" -H "X-LW-Tenant: cust_8f2a" -X POST

Add a text document:

curl https://api.linkworld.ai/v1/rag/handbook/documents \
  -H "Authorization: Bearer rk_live_…" -H "X-LW-Tenant: cust_8f2a" \
  -H "Content-Type: application/json" \
  -d '{"title": "Onboarding", "text": "…full document text…"}'

Upload a file (PDF or text):

curl https://api.linkworld.ai/v1/rag/handbook/files \
  -H "Authorization: Bearer rk_live_…" -H "X-LW-Tenant: cust_8f2a" \
  -F "[email protected];type=application/pdf" -F "title=Handbook"
# → { "document_id": "…", "chunks": 14, "chars": 20431, "status": "indexed" }

Query:

curl https://api.linkworld.ai/v1/rag/handbook/query \
  -H "Authorization: Bearer rk_live_…" -H "X-LW-Tenant: cust_8f2a" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I reset a password?", "top_k": 4}'
# → { "matches": [{ "text": "…", "title": "…", "score": 0.83, "document_id": "…" }] }

GET /v1/rag/{collection}/documents lists documents. Collections are isolated per tenant — one tenant never sees another’s data.

Batch

Non-urgent work at roughly half price. Submit a set of completions; each is processed and metered at the batch rate. Poll by id for results.

curl https://api.linkworld.ai/v1/batches \
  -H "Authorization: Bearer rk_live_…" -H "X-LW-Tenant: cust_8f2a" \
  -H "Content-Type: application/json" \
  -d '{"requests": [
    {"custom_id": "a", "tier": "eu-sovereign", "messages": [{"role":"user","content":"…"}]},
    {"custom_id": "b", "tier": "eu-sovereign", "messages": [{"role":"user","content":"…"}]}
  ]}'
# → 202 { "id": "batch_…", "status": "completed", "results": [ … ] }

curl https://api.linkworld.ai/v1/batches/batch_… \
  -H "Authorization: Bearer rk_live_…"   # poll

Each item honours the same tier / provider / contains_pii options as chat completions, and errors are isolated per item.

Tenants & usage

Register a tenant (optional — otherwise created on first call):

curl https://api.linkworld.ai/v1/tenants \
  -H "Authorization: Bearer rk_live_…" -H "Content-Type: application/json" \
  -d '{"id": "cust_8f2a", "name": "Acme GmbH", "external_id": "CRM-42"}'

Usage — one tenant, or the org-wide rollup you bill on:

curl "https://api.linkworld.ai/v1/usage?tenant=cust_8f2a" -H "Authorization: Bearer rk_live_…"
curl  https://api.linkworld.ai/v1/usage              -H "Authorization: Bearer rk_live_…"
# → { "totals": {"tenants": 12, "calls": 3401, "cost_usd": 4.72}, "per_tenant": [ … ] }

Sovereignty & data handling

Default path is EU end-to-end. Inference under eu-sovereign and all embeddings run under EU jurisdiction. US frontier models are only reached when you explicitly set tier: "frontier" (or a US model), and never for requests flagged contains_pii.
Which backend runs a request is an implementation detail we can move (managed EU providers today, extendable to fully self-hosted EU compute). Concrete subprocessors are disclosed in the DPA.
You stay the contract with your customers; we meter per your tenant so you attribute and resell.