Custom data - Lua CLI

Custom data is the agent’s own storage: named collections of JSON entries, each optionally indexed for semantic search by a searchText. These routes are the REST twin of the Data runtime object and address the same collections your tools read. Verified against lua-cli 3.33.0.

Base URL and authentication

Reads need knowledge:read and writes knowledge:write on the agent; the host, the bearer header, and the error envelope are on the REST API overview. Collections are not partitioned by environment.

The entry

string

Entry id, a UUID.

object

The JSON you stored.

string

The text embedded for semantic search, when set.

number

Unix time in milliseconds.

number

Unix time in milliseconds.

Collection and entry ids are path segments: a collection named search cannot be read by id because .../<collection>/search is the search route.

Endpoints

GET /developer/agents/:agentId/custom-data

Lists the agent’s collections with counts and timestamps.

string

required

The agent.

Response 200 with { "data": [...], "count" }.

array

One item per collection: name, entryCount, lastUpdatedAt, firstCreatedAt (Unix milliseconds), and indexes on collections that declared one.

Show indexes

string[]

The indexed data paths, one or two.

string

pending, building, ready, failed, or rejected.

string

Why the index is failed or rejected.

number

Unix milliseconds of the last declaration and the last filtered read that used it.

number

Number of collections.

Equivalent: Data.collections().

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data', {
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>' },
});
const collections: { data: Array<{ name: string; entryCount: number }>; count: number } = await response.json();
for (const collection of collections.data) console.log(collection.name, collection.entryCount);

curl "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>"

POST /developer/agents/:agentId/custom-data/:collection

Creates an entry and, when searchText is given, embeds it for semantic search.

string

required

The agent.

string

required

Collection name; created on first write.

any

required

The value to store: an object, array, string, number, or boolean. null and an empty string are refused.

string

Text to embed. Include every term you expect a search to match. A string only; the options object the SDK’s Data.create() types is not accepted here and answers 400 with searchText must be a string.

Response 201 with the entry. Errors

Status	Code or message	Meaning	Fix
`400`	`data should not be empty`	`data` is missing, `null`, or `""`	Send a value
`400`	`searchText must be a string`	`searchText` is not a string	Send a string, or omit it

Equivalent: Data.create('movies', data, 'Inception Nolan sci-fi').

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies', {
  method: 'POST',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: { title: 'Inception', year: 2010 }, searchText: 'Inception Nolan sci-fi heist dreams' }),
});
const entry: { id: string; data: { title: string; year: number }; createdAt: number } = await response.json();
console.log(entry.id);

curl -X POST "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "title": "Inception", "year": 2010 }, "searchText": "Inception Nolan sci-fi heist dreams" }'

GET /developer/agents/:agentId/custom-data/:collection

Returns the entries that match a filter, one page at a time.

string

required

The agent.

string

required

The collection.

string

A JSON Lua Query over data: dot notation for nested fields, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, and $and or $or at the root. Omit it for every entry.

integer

default:"1"

Page number from 1.

integer

default:"10"

From 1 to 100; larger values are clamped.

Response 200 with

{ "data": [...entries], "pagination": { currentPage, totalPages, totalCount, limit, hasNextPage, hasPrevPage, nextPage, prevPage } }

. Errors

Status	Code or message	Meaning	Fix
`400`	A filter validation message	`filter` is not valid JSON or uses an operator outside the grammar	Fix the filter
`400`	`Pagination offset may not exceed 100000`	`(page - 1) × limit` is over 100,000	Narrow the filter

Equivalent: Data.get('movies', { year: { $gte: 2010 } }, 1, 20).

const params = new URLSearchParams({ filter: JSON.stringify({ year: { $gte: 2010 } }), page: '1', limit: '20' });
const response = await fetch(`https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies?${params}`, {
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>' },
});
const page: { data: Array<{ id: string; data: Record<string, unknown> }>; pagination: { totalCount: number } } =
  await response.json();
console.log(page.pagination.totalCount);

curl -G "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  --data-urlencode 'filter={"year":{"$gte":2010}}' \
  --data-urlencode 'page=1' --data-urlencode 'limit=20'

GET /developer/agents/:agentId/custom-data/:collection/search

Returns the entries whose searchText is semantically closest to a query.

string

required

The agent.

string

required

The collection.

string

required

Natural-language query.

integer

default:"5"

From 1 to 20; larger values are clamped to 20.

number

default:"0.6"

Minimum similarity from 0 to 1; results under it are dropped.

Response 200 with { "data": [...entries with score], "count" }; each entry carries a score from 0 to 1. This is a flat list, not the paginated envelope the filter route returns. Errors

Status	Code or message	Meaning	Fix
`400`	A validation message	`searchText` is missing	Send a query

Equivalent: Data.search('movies', 'mind-bending thriller', 5, 0.7).

const params = new URLSearchParams({ searchText: 'mind-bending thriller', limit: '5', scoreThreshold: '0.7' });
const response = await fetch(`https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies/search?${params}`, {
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>' },
});
const results: { data: Array<{ id: string; score: number; data: Record<string, unknown> }>; count: number } =
  await response.json();
for (const hit of results.data) console.log(hit.score.toFixed(2), hit.data['title']);

curl -G "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies/search" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  --data-urlencode 'searchText=mind-bending thriller' --data-urlencode 'limit=5' --data-urlencode 'scoreThreshold=0.7'

GET /developer/agents/:agentId/custom-data/:collection/:entryId

Returns one entry. Errors

Status	Code or message	Meaning	Fix
`404`	`Custom data entry not found`	No such entry in this collection for this agent	Check the ids

Equivalent: Data.getEntry('movies', '<entryId>').

PUT /developer/agents/:agentId/custom-data/:collection/:entryId

Merges new fields into an entry and optionally re-embeds it.

object

required

Fields to merge into the stored data.

string

New text to embed.

Response 200 with { "status": "success", "message": "Custom data entry updated" }. Errors

Status	Code or message	Meaning	Fix
`400`	`data should not be empty`	`data` is missing or empty	Send the fields to merge
`404`	`Custom data entry not found`	No such entry	Check the ids

Equivalent: Data.update('movies', '<entryId>', { rating: 9 }, 'Inception Nolan sci-fi').

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies/<<ENTRY_ID>>', {
  method: 'PUT',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ data: { rating: 9 } }),
});
const result: { status: string; message: string } = await response.json();
console.log(result.status);

curl -X PUT "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies/<<ENTRY_ID>>" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "rating": 9 } }'

PATCH /developer/agents/:agentId/custom-data/:collection/:entryId

Sets and unsets top-level fields of data atomically, and sets or clears the embedding.

object

Top-level fields to write.

string[]

Top-level fields to remove.

string or null

A string re-embeds the entry; null clears both the text and its vector; omit it to leave the embedding alone.

Response 200 with { "status": "success", "message" }; 404 Custom data entry not found when the entry does not exist.

DELETE /developer/agents/:agentId/custom-data/:collection/:entryId

Deletes one entry. Response 200 with { "status": "success", "message": "Custom data entry deleted" }; 404 Custom data entry not found when the entry does not exist. Equivalent: Data.delete('movies', '<entryId>').

const response = await fetch('https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies/<<ENTRY_ID>>', {
  method: 'DELETE',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>' },
});
const result: { status: string } = await response.json();
console.log(result.status);

curl -X DELETE "https://api.heylua.ai/developer/agents/<<YOUR_AGENT_ID>>/custom-data/movies/<<ENTRY_ID>>" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>"

​Base URL and authentication

​The entry

​Endpoints

​GET /developer/agents/:agentId/custom-data

​POST /developer/agents/:agentId/custom-data/:collection

​GET /developer/agents/:agentId/custom-data/:collection

​GET /developer/agents/:agentId/custom-data/:collection/search

​GET /developer/agents/:agentId/custom-data/:collection/:entryId

​PUT /developer/agents/:agentId/custom-data/:collection/:entryId

​PATCH /developer/agents/:agentId/custom-data/:collection/:entryId

​DELETE /developer/agents/:agentId/custom-data/:collection/:entryId

​See also

Base URL and authentication

The entry

Endpoints

GET /developer/agents/:agentId/custom-data

POST /developer/agents/:agentId/custom-data/:collection

GET /developer/agents/:agentId/custom-data/:collection

GET /developer/agents/:agentId/custom-data/:collection/search

GET /developer/agents/:agentId/custom-data/:collection/:entryId

PUT /developer/agents/:agentId/custom-data/:collection/:entryId

PATCH /developer/agents/:agentId/custom-data/:collection/:entryId

DELETE /developer/agents/:agentId/custom-data/:collection/:entryId

See also