Apps and Data API

Apps organize Actions, Workflows, Data, and fine-tunes. Data records capture an Action input, output, model details, token counts, latency, metadata, and optional session or run relationships.

Prerequisites and authentication

Send every request to https://api.klu.ai/v1 with a workspace API key. The key selects the workspace used by list and create operations.

curl 'https://api.klu.ai/v1/apps?skip=0&limit=20' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json'

App endpoints

Create an App with a required name and a nullable description.

curl --request POST 'https://api.klu.ai/v1/apps' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Support assistant","description":"Customer support Actions"}'

{
  "guid": "11111111-1111-4111-8111-111111111111",
  "name": "Support assistant",
  "description": "Customer support Actions",
  "slug": "support-assistant",
  "created_at": "2026-08-18T08:00:00.000Z",
  "updated_at": "2026-08-18T08:00:00.000Z",
  "created_by_id": "USER_ID",
  "last_updated_by_id": null
}

For an update, send either or both mutable fields. The URL supplies guid.

curl --request PUT 'https://api.klu.ai/v1/apps/11111111-1111-4111-8111-111111111111' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"description":"Production customer support Actions"}'

Deleting an App marks it deleted and returns the App representation. App creation can fail with 429 Too Many Requests when the workspace's App allowance is exhausted. Missing Apps return 404 for detail, update, delete, and relationship routes.

App relationship responses

The Actions route returns an array with guid, name, action_type, model, and audit timestamps/IDs. See Actions API for Action execution contracts. The Workflows and fine-tunes routes return arrays and accept skip and limit, but do not include a pagination envelope. The App Data route uses the standard pagination envelope described below.

Data endpoints

Create Data when you need to log a generation performed outside Klu. action, input, and output are required. input can be a string, array, or object.

curl --request POST 'https://api.klu.ai/v1/data' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "action":"22222222-2222-4222-8222-222222222222",
    "input":"Summarize the latest support ticket",
    "output":"The customer needs help resetting MFA.",
    "model":"gpt-4.1-mini",
    "model_provider":"openai",
    "num_input_tokens":8,
    "num_output_tokens":9,
    "latency":0.84,
    "metadata":{"source":"support-queue"}
  }'

The response is the stored record. A representative response is:

{
  "guid": "33333333-3333-4333-8333-333333333333",
  "full_prompt_sent": "",
  "num_input_tokens": 8,
  "num_output_tokens": 9,
  "metadata": { "source": "support-queue" },
  "latency": 0.84,
  "model_provider": "openai",
  "model": "gpt-4.1-mini",
  "created_at": "2026-08-18T08:05:00.000Z",
  "updated_at": "2026-08-18T08:05:00.000Z",
  "input": "Summarize the latest support ticket",
  "output": "The customer needs help resetting MFA."
}

Optional create fields are version, app, session, runId, guid, full_prompt_sent, system_message, prompt_template, raw request/response fields, token and cost fields, latency, and metadata. The referenced Action must exist. If supplied, relationship GUIDs must resolve to valid records.

Updates can change App, Action, version, Session, prompt fields, input/output, raw fields, model/provider, metadata, token counts, and latency. The update contract accepts version_id for the version relationship. Data detail and list responses expose the normalized public fields shown above; not every accepted cost or relationship field is returned.

Pagination

GET /apps, GET /data, and GET /apps/{guid}/data accept numeric skip and limit query parameters. Both default to skip=0&limit=100 and return:

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

Advance by adding the previous limit to skip while has_next_page is true. App Workflows and fine-tunes also default to 100 but return a bare array.

SDK examples

from klu import Klu

klu = Klu("YOUR_API_KEY")
app = await klu.apps.create("Support assistant", "Customer support Actions")
saved = await klu.apps.get(app.guid)

The SDK App Data helpers expect a bare array, while the current REST App Data route returns a pagination envelope. Use REST for App Data pagination. See SDK exports for the complete client surfaces and unsupported operations.