API and SDK basics

Use the Klu API to run deployed Actions, manage Context libraries, record feedback, and inspect sessions. The public REST API is served from https://api.klu.ai/v1.

Prerequisites

Before you make a request:

  1. Create a Klu workspace.
  2. Open Settings → Developers, then select New API Key.
  3. Create an Action or Context library for the resource you want to use.

An API key belongs to one workspace. Requests can access only resources available to that workspace. The API also requires the user associated with the key to be verified and the workspace to have an active subscription.

Authenticate a request

Send your API key as a Bearer token in the Authorization header. JSON requests also need Content-Type: application/json.

List Actions

curl 'https://api.klu.ai/v1/actions?limit=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'

A successful response is paginated:

Response

{
  "data": [],
  "total_count": 0,
  "has_next_page": false
}

Missing, invalid, inactive, or out-of-workspace credentials cause the request to fail. Keep API keys on your server and out of browser bundles, logs, and source control.

Install an SDK

The checked-in SDK package names are klu for Python and @kluai/core for TypeScript.

python -m pip install klu

Create a client with the same workspace API key:

import os

from klu import Klu

klu = Klu(os.environ["KLU_API_KEY"])

The current REST contract is authoritative for endpoint paths and request fields. In particular, current Action execution uses POST /v1/actions/{guidOrSlug}/prompt. If an installed SDK version sends Action prompts to the legacy collection endpoint, use the REST examples in Klu Actions or update the SDK before shipping.

Core identifiers

Klu resources use GUIDs. Save the GUID returned when you create a resource or copy it from the corresponding page in the app.

  • An Action GUID or slug identifies the Action to execute.
  • A data GUID identifies one stored generation and is used for feedback.
  • A Context GUID identifies a document library.
  • A document GUID identifies a document inside one Context.
  • A session GUID identifies conversation history for one Action.

Do not substitute a display name where an endpoint requires a GUID.

Request and response conventions

The API uses snake_case for most response fields, including data_guid, feedback_url, total_count, and has_next_page. A few request fields are camel case because that is the current schema, including extUserId, async_mode, modelOptions, and Context creation fields such as responseLength and splitterConfig.

List endpoints generally accept skip and limit. The response tells you whether another page exists:

{
  "data": [],
  "total_count": 125,
  "has_next_page": true
}

Validation errors include malformed GUIDs, known fields with the wrong type, and unsupported metadata-filter values. A request can also fail when the target resource does not exist, is deleted, or belongs to another workspace.

Actions and deployments

An Action combines a prompt, model, model configuration, optional Context libraries, and optional tools. Run it by GUID or slug. You can select a deployed environment with environment or a numeric version with version.

The execution endpoint accepts synchronous, streaming, and asynchronous modes. Each mode has a different response shape. See Klu Actions before choosing one.

Context and metadata

A Context library stores documents for retrieval. Attach a Context to an Action, then pass metadata when running that Action to restrict retrieval. Context search uses the field name metadata_filter; the two endpoint schemas are intentionally different.

Metadata filter keys must be 1–64 characters and contain only letters, numbers, _, ., or -. Values can be strings, numbers, booleans, or non-empty arrays of those scalar types, with at most 100 values per array.

Sessions

A session belongs to an Action. Create the session first, then pass its GUID as session on later Action requests. Klu includes the saved session history when it formats subsequent prompts.

Use extUserId to associate a session or generation with an identifier from your application. Treat it as an opaque reference; avoid placing secrets in it.

Direct Action API and gateway integration

The Action API and the Klu gateway are separate integrations:

  • POST /v1/actions/{guidOrSlug}/prompt formats and executes a managed Action through the Klu API.
  • POST /v1/actions/{guid}/gateway_payload prepares an OpenAI-compatible payload and provider headers for server-side forwarding.
  • A separately deployed Klu gateway proxies OpenAI-compatible requests and logs them to Klu when you send the Klu headers.

Use the direct Action API unless you specifically need an OpenAI-compatible proxy. See Integrate an OpenAI client with the Klu gateway for the gateway flow.

Run an Action