API Reference

The UnifiedLayer REST API is OpenAI-compatible with a unifiedlayer extension for sources, credits, and analytics. You can use it from any server, script, or frontend — no SDK required.

Base URL

https://www.unifiedlayer.space

All endpoints are prefixed with /api/v1/. If you are self-hosting UnifiedLayer, replace the base URL with your own domain.

Authentication

Every API request requires authentication. UnifiedLayer supports two modes:

	App-Key Auth	Session Auth
Best for	Servers, scripts, backend APIs, curl	Browsers, mobile apps, client-side React
Headers required	`x-client-id` + `x-app-id` + `x-api-key`	`Authorization: Bearer <token>` + `x-app-id`
API key in browser?	Yes — do not use client-side	No — token is scoped and temporary
Per-user tracking	No	Yes — tied to a `userId`
Token expiry	Never	7 days
Revocable	Only by regenerating API key	Yes — `DELETE /api/v1/auth/session`

App-Key Auth headers

x-client-id:  <your Client ID>      — found on the Profile page
x-app-id:     <your App ID>         — found on the App detail page
x-api-key:    <your API Key>        — found on the App detail page

Session Auth headers

Authorization: Bearer ul_sess_<token>
x-app-id:      <your App ID>

Which one should I use?

Use App-Key Auth from servers and Route Handlers. Use Session Auth in the browser. See the Session endpoint docs for the full token creation flow.

Response Format

Every endpoint that generates an AI response returns an UnifiedLayerChatCompletion object. This is a strict superset of the OpenAI chat.completion format — existing OpenAI clients can parse it without modification.

json

{
  "id": "ul-cmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "meta-llama/llama-4-maverick-17b-128e-instruct",
  "thread_id": "thread_abc123",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I can help you with that.",
        "tool_calls": null
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 10,
    "total_tokens": 25
  },
  "unifiedlayer": {
    "sources": [
      {
        "filename": "support-docs.pdf",
        "text": "Our office hours are Monday to Friday, 9am–6pm EST.",
        "score": 0.92
      }
    ],
    "creditsLeft": 4.75,
    "creditsUsed": 0.0003,
    "analyticsId": "analytics_abc"
  }
}

Field reference

Field	Type	Description
`id`	string	Unique completion ID, prefixed `ul-cmpl-`.
`object`	string	Always `"chat.completion"`.
`created`	number	Unix timestamp of when the completion was generated.
`model`	string	The model that generated the response.
`thread_id`	string	The thread this message belongs to (thread-based endpoints only).
`choices[].message.role`	string	Always `"assistant"` for AI responses.
`choices[].message.content`	string \| null	The text response. `null` if the model only called tools.
`choices[].message.tool_calls`	array \| null	Tool calls requested by the model. `null` if none.
`choices[].finish_reason`	string	`"stop"` — natural end; `"tool_calls"` — model wants to call tools.
`usage.prompt_tokens`	number	Tokens consumed by the input (messages + context).
`usage.completion_tokens`	number	Tokens consumed by the model's output.
`usage.total_tokens`	number	Sum of prompt + completion tokens.
`unifiedlayer.sources`	array	Retrieved document chunks used for context (empty if no Knowledge Base is attached).
`unifiedlayer.sources[].filename`	string	Name of the source document.
`unifiedlayer.sources[].text`	string	The passage that was retrieved.
`unifiedlayer.sources[].score`	number	Cosine similarity score (0–1). Higher is more relevant.
`unifiedlayer.creditsLeft`	number	Your remaining credit balance after this request.
`unifiedlayer.creditsUsed`	number	Credits deducted for this specific request.
`unifiedlayer.analyticsId`	string	Analytics record ID for this call (visible in the dashboard).

Credits System

API calls that reach the LLM deduct credits from your Client balance based on token usage. Credits are deducted proportionally: a request that consumes more tokens costs more.

Every response includes unifiedlayer.creditsLeft and unifiedlayer.creditsUsed so you can monitor consumption in real time. When your balance reaches zero, all API calls return 402 Payment Required.

Top up your balance from the Billing section of the dashboard.

WARNING

If you are building for multiple end users, monitor creditsLeft to detect when your balance is low. Consider setting up an alert or auto-top-up to avoid service interruptions.

Endpoints Overview

Method	Path	Description
`POST`	`/api/v1/auth/session`	Create a per-user session token
`DELETE`	`/api/v1/auth/session`	Revoke a session token
`POST`	`/api/v1/chat/completions`	OpenAI-compatible stateless chat
`GET`	`/api/v1/threads`	List threads
`POST`	`/api/v1/threads`	Create a new thread
`GET`	`/api/v1/threads/:threadId`	Get a thread
`DELETE`	`/api/v1/threads/:threadId`	Delete a thread
`GET`	`/api/v1/threads/:threadId/messages`	List messages in a thread
`POST`	`/api/v1/threads/:threadId/advance`	Send a message and get AI response

Quick Start

App-Key Auth (server / curl)

bash

curl -X POST https://www.unifiedlayer.space/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-app-id: YOUR_APP_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "messages": [
      { "role": "user", "content": "What is your refund policy?" }
    ]
  }'

Session Auth (browser / SDK flow)

Step 1 — Create a session from your server:

bash

curl -X POST https://www.unifiedlayer.space/api/v1/auth/session \
  -H "Content-Type: application/json" \
  -H "x-client-id: YOUR_CLIENT_ID" \
  -H "x-app-id: YOUR_APP_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "userId": "user_12345" }'

Response:

json

{
  "sessionToken": "ul_sess_a3f8c2d1e4b7a9f0c3d2e1b4a7f0c3d2e1b4a7f0c3d2e1b4",
  "userId": "user_12345",
  "appId": "YOUR_APP_ID",
  "expiresAt": "2026-03-15T10:30:00.000Z"
}

Step 2 — Use the session token in the browser:

bash

curl -X POST https://www.unifiedlayer.space/api/v1/threads/thread_abc123/advance \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ul_sess_a3f8c2d1e4b7a9f0c3d2e1b4a7f0c3d2e1b4a7f0c3d2e1b4" \
  -H "x-app-id: YOUR_APP_ID" \
  -d '{ "message": { "role": "user", "content": "What is your refund policy?" } }'

Next Steps

Session Auth — Full session creation, usage, and revocation reference
Chat Completions — OpenAI-compatible stateless chat
Threads — Thread lifecycle and all thread endpoints
Error Reference — All error codes with example payloads and debugging tips

API Reference ​

Base URL ​

Authentication ​

App-Key Auth headers ​

Session Auth headers ​

Response Format ​

Field reference ​

Credits System ​

Endpoints Overview ​

Quick Start ​

App-Key Auth (server / curl) ​

Session Auth (browser / SDK flow) ​

Next Steps ​

API Reference

Base URL

Authentication

App-Key Auth headers

Session Auth headers

Response Format

Field reference

Credits System

Endpoints Overview

Quick Start

App-Key Auth (server / curl)

Session Auth (browser / SDK flow)

Next Steps