Collections
GET/POST /v1/collections, GET/PATCH/DELETE /v1/collections/{id} — organize documents, scope retrieval, attach to domains.
Tenant-wide knowledge collections via API key. This is the same resource as the dashboard's Knowledge Collections tab and the same underlying service — creating a collection here shows up in the dashboard immediately, and vice versa.
List collections
GET https://api.liyaengine.ai/v1/collections
Authorization: Bearer liya_xxxxxxxxxxxx{
"success": true,
"data": {
"collections": [
{
"id": "col_abc123",
"slug": "contracts",
"label": "Contracts",
"color": "#6366f1",
"created_at": "2026-01-01T00:00:00.000Z",
"domain_keys": ["legal-ops"],
"tags": [],
"visibility": "workspace",
"last_synced_at": null,
"retrieval_config": null,
"default_embedding_model": null,
"default_chunking_strategy": null,
"default_chunk_size": null,
"default_chunk_overlap": null
}
]
}
}Create a collection
POST https://api.liyaengine.ai/v1/collections
Authorization: Bearer liya_xxxxxxxxxxxx
Content-Type: application/json
{
"slug": "contracts",
"label": "Contracts",
"domain_keys": ["legal-ops"],
"default_embedding_model": "text-embedding-3-large",
"default_chunking_strategy": "semantic"
}slug must be lowercase letters, numbers, hyphens, and underscores. domain_keys is required — a collection must be attached to at least one currently-active domain. Returns 201 with { "data": { "collection": {...} } }, or 409 SLUG_CONFLICT if the slug is already taken in this tenant.
Get a collection
GET https://api.liyaengine.ai/v1/collections/{id}
Authorization: Bearer liya_xxxxxxxxxxxx404 if the collection doesn't exist or belongs to another tenant.
Update a collection
PATCH https://api.liyaengine.ai/v1/collections/{id}
Authorization: Bearer liya_xxxxxxxxxxxx
Content-Type: application/json
{
"label": "Master Services Agreements",
"tags": ["legal", "high-priority"],
"visibility": "restricted"
}All fields optional — only what you pass gets changed. visibility: "restricted" gates further mutation of the collection to admin/owner dashboard roles; API-key callers aren't role-scoped, so this gate doesn't apply to them.
Delete a collection
DELETE https://api.liyaengine.ai/v1/collections/{id}
Authorization: Bearer liya_xxxxxxxxxxxxReturns { "success": true }. This deletes the collection itself, not just its attachment to a domain — see Knowledge Collections for the domain-attach/detach endpoints, which are dashboard-only for now.
Using an SDK
import { LiyaEngine } from '@liyaengine/sdk';
const client = new LiyaEngine({ apiKey: process.env.LIYA_API_KEY! });
const collection = await client.collections.create({
slug: 'contracts',
label: 'Contracts',
domain_keys: ['legal-ops'],
});