Use the API

The DataMind Platform API lets your own applications call the pay-as-you-go models in the OpenAI request format, so existing OpenAI code and SDKs work with a new base URL and header. Kartlos Premium and Kartlos Standard are not available through the API; they work only inside DataMind OS.

Before you start

You need the company API key. An Administrator creates it in Finish company setup and manages it in Settings. The examples below read it from the DATAMIND_API_KEY environment variable.

Setting	Value
Base URL	`https://platform.datamind.ai/llm`
Authentication	`x-api-key: <api_key>` header. An `Authorization: Bearer` header alone is not accepted.
Request body	JSON, with `Content-Type: application/json`

Step 1: Choose a model

List the models your key can use:

bash

curl https://platform.datamind.ai/llm/models \
  -H "x-api-key: $DATAMIND_API_KEY"

Pick an entry whose billing is payg and use its id as model in the next step. Each entry also tells you what the model can do and costs:

Field	What it tells you
`price_per_1m_input`, `price_per_1m_output`, `price_per_1m_cached`	Your price in USD per 1M tokens.
`context_length`, `max_output_tokens`	The context window (input and answer together) and the longest answer, in tokens.
`supports_tools`, `supports_structured_output`, `supports_thinking`	Function calling, JSON-schema output and reasoning.
`reasoning`	For a thinking model: whether thinking is `mandatory` and its `supported_efforts`.

The Models page shows the same list.

Step 2: Send a chat request

Send model and messages, as in the OpenAI Chat Completions API:

bash

curl https://platform.datamind.ai/llm/chat/completions \
  -H "x-api-key: $DATAMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model_id>",
    "messages": [
      { "role": "system", "content": "You answer in one short paragraph." },
      { "role": "user", "content": "What is a data lakehouse?" }
    ],
    "user": "customer-4821"
  }'

The answer is in choices[0].message.content, and usage holds the token counts. What each request costs you is on the Usage page. user is optional: send your end user's identifier there, and the Usage page lets you filter requests by it in the External ID column.

Use an OpenAI SDK

Instead of curl, you can use an OpenAI SDK. OpenAI SDKs send their key as Authorization: Bearer, so pass the DataMind key in the x-api-key header as well:

python

import os
from openai import OpenAI

api_key = os.environ["DATAMIND_API_KEY"]
client = OpenAI(
    base_url="https://platform.datamind.ai/llm",
    api_key=api_key,
    default_headers={"x-api-key": api_key},
)

completion = client.chat.completions.create(
    model="<model_id>",
    messages=[{"role": "user", "content": "Summarise the benefits of dbt in two lines."}],
)
print(completion.choices[0].message.content)

javascript

import OpenAI from "openai";

const apiKey = process.env.DATAMIND_API_KEY;
const client = new OpenAI({
  baseURL: "https://platform.datamind.ai/llm",
  apiKey,
  defaultHeaders: { "x-api-key": apiKey },
});

const completion = await client.chat.completions.create({
  model: "<model_id>",
  messages: [{ role: "user", content: "Name three uses of embeddings." }],
});
console.log(completion.choices[0].message.content);

Tune a request

Stream the answer

Add "stream": true (stream=True in the SDK). The answer arrives as server-sent events, each carrying an OpenAI-style chunk with the text in choices[0].delta.content; the last chunk carries usage. If the stream breaks after it starts, the last event is event: error with the code stream_interrupted: send the request again. Closing the connection stops the request; you pay for the tokens generated before it stopped. No stream_options is needed: usage is always included.

Control thinking

For a model with supports_thinking, send a reasoning object:

"reasoning": { "effort": "high" } sets the effort. Use a value from the model's supported_efforts.
"reasoning": { "enabled": false } turns thinking off, when the model's thinking is not mandatory.

In the Python SDK, pass reasoning and provider through extra_body={...}. In the JavaScript SDK, add them to the request object.

Choose the provider order

Send "provider": { "sort": "price" } to override the company's Provider sort for one request. The values are throughput, latency, price and balanced.

Embeddings and web tools

Embeddings

Send model and input, a string or an array of strings. The embedding model is qwen/qwen3-embedding-8b, and the response follows the OpenAI embeddings shape. It does not appear in GET /llm/models.

bash

curl https://platform.datamind.ai/llm/embeddings \
  -H "x-api-key: $DATAMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3-embedding-8b",
    "input": ["Quarterly revenue by region", "Monthly active customers"]
  }'

Web search and web read

GET /llm/web/search searches the web for q. POST /llm/web/read returns the content of the page at url. Each returns the result as JSON. Each successful call uses Premium tokens; the Web Search and Web Read tiles on Pricing show how many.

bash

curl -G https://platform.datamind.ai/llm/web/search \
  -H "x-api-key: $DATAMIND_API_KEY" \
  --data-urlencode "q=Georgia GDP growth 2026"

curl https://platform.datamind.ai/llm/web/read \
  -H "x-api-key: $DATAMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/report" }'

Handle errors

Most errors use the OpenAI shape {"error": {"message": "...", "type": "...", "code": "..."}}. Act on code. Errors from the model provider pass through unchanged, and their code is the HTTP status number.

Status	`code`	Meaning	What to do
400	`invalid_request`	The body is not valid JSON, misses a required field or has an invalid value, names a model that is not available, or asks for a thinking effort the model does not support.	Fix the request. Take model IDs and efforts from `GET /llm/models`.
400	`content_filter`	Your company blocks personal data, and the request contained some.	Remove the personal data and send again.
401	`invalid_api_key`	The `x-api-key` header is missing, or the key was rotated or revoked.	Send the current key. An Administrator manages it in Settings.
402	`budget_exceeded`	Extra spend reached the monthly spend cap.	An Administrator raises the cap in Settings, or wait for the next billing window.
402	`no_active_subscription`	The company has no active plan.	An Administrator selects a plan on Pricing.
413	`PAYLOAD_TOO_LARGE`	The request body is too large.	Send fewer or smaller images or files, or shorten the conversation.
429	`rate_limit_exceeded`	More requests this minute than your company's limit.	Wait for the time in the `retry-after` header, then retry.
429	`concurrency_limit_exceeded`	Too many requests running at once.	Retry when a running request finishes.
500	`internal_error`	An unexpected error on the DataMind side.	Retry. If it repeats, contact DataMind support.
502	`upstream_unavailable`	The model provider could not be reached.	Retry, or choose another model.
503	`service_unavailable`	A required service is briefly unavailable.	Retry shortly.
504	`upstream_timeout`	The model provider did not answer in time.	Retry, or shorten the request.

Tip

Retry 429, 500, 502, 503 and 504 with a short back-off. A 402 is a billing state: retrying does not help until the plan or the spend cap changes.

Questions, answered

Can I call Kartlos Premium or Kartlos Standard through the API?

No. GET /llm/models lists them with billing subscription, but a request to them is refused. Use any model whose billing is payg.

Why does my OpenAI SDK get 401 invalid_api_key?

The SDK sends the key only as Authorization: Bearer. Add the x-api-key header, as in Use an OpenAI SDK.

Where do I see what my API calls cost?

The Usage page lists every chat request with its tokens and cost. The Dashboard shows the totals, including the Premium tokens your web searches and web reads used.