Imprints and Pools API

An imprint is a named bundle of library items (skills, memories, rules, tasks, prompts, preferences and artifacts) that an agent can learn at once. Build one, add your items to it, then install it on any agent: the agent reads the imprint's items beside its own. Items in an imprint stay where they are in the library and stay yours; an agent reads them, never rewrites them.

An imprint is one kind of pool: a named collection a library item belongs to through its linkedIds. The other kinds are custom (your own collections), org-global (the one pool every agent in the organization reads) and agent (an agent's own pool, whose id is the agent's id). The imprint routes work on imprints only; the pool routes work on any pool you can see.

All endpoints require authentication via the X-API-Key header and the scope shown.

---

Pool Object

{
  "_id": "AWLHeNshCSkBprupP",
  "name": "Folder Basics",
  "description": "How projects are organized into folders.",
  "scope": "imprint",
  "ownerId": "usr_abc",
  "organizationId": "org_xyz",
  "isPublic": false,
  "sharedWith": [],
  "createdAt": "2026-10-11T08:00:00.000Z",
  "updatedAt": "2026-10-11T08:00:00.000Z",
  "counts": { "total": 2, "prompts": 1, "skills": 1 }
}

Field	Type	Description
_id	string	The pool's id: the value an item's linkedIds holds
name	string	Its name
description	string	What an agent learns from it
scope	string	imprint, custom, org-global or agent
ownerId	string	Who created it
organizationId	string | null	The organization it belongs to
isPublic, sharedWith	boolean, string[]	Who else may see it
counts	object	How many items of each type it holds (memory, rules, skills, prompts, tasks, artifacts, preferences) and their total

---

Imprints

GET /api/v1/library/imprints

The imprints you can see, each a pool with its counts.

Scope: memory:read

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Results per page (default 50, at most 200)
cursor	string	No	meta.nextCursor of the previous page; omit for the first page

Response 200 OK: a page of pools, meta.nextCursor set while more remain.

---

POST /api/v1/library/imprints

Create an empty imprint. Add items to it, then install it on agents.

Scope: memory:write

Request Body

Field	Type	Required	Description
name	string	Yes	Its name, e.g. "Helicopter Piloting"
description	string	No	What an agent learns from it

Response 201 Created: the new imprint, a pool with scope imprint.

---

GET /api/v1/library/imprints/:id

An imprint with what it holds.

Scope: memory:read

Parameter	Type	Required	Description
id	string	Yes	Imprint id

Response 200 OK: the pool with contents, its items by type, each { _id, label } (a skill's or prompt's name, a memory's content, a rule's or task's description, an artifact's title, a preference's key):

{
  "data": {
    "_id": "AWLHeNshCSkBprupP",
    "name": "Folder Basics",
    "scope": "imprint",
    "counts": { "total": 1, "prompts": 1 },
    "contents": { "prompts": [{ "_id": "xxmuLJR46aHYeXRhP", "label": "qa-folder-question" }] }
  },
  "meta": { "requestId": "req_abc123" }
}

---

DELETE /api/v1/library/imprints/:id

Delete an imprint. Its items stay in the library and lose the grouping, and agents that had it installed stop reading it.

Scope: memory:write

Parameter	Type	Required	Description
id	string	Yes	Imprint id

Response 204 No Content

---

POST /api/v1/library/imprints/:id/items

Add a library item you can change to an imprint. Its other memberships are kept; adding an item already in the imprint changes nothing.

Scope: memory:write

Parameter	Type	Required	Description
id	string	Yes	Imprint id

Request Body

Field	Type	Required	Description
resourceType	string	Yes	memory, rules, skills, prompts, tasks, artifacts or preferences
resourceId	string	Yes	The item's id

Response 201 Created: the item as the imprint's contents list it, { resourceType, _id, label }.

---

DELETE /api/v1/library/imprints/:imprintId/items/:resourceType/:resourceId

Take an item out of an imprint. The item stays in the library.

Scope: memory:write

Parameter	Type	Required	Description
imprintId	string	Yes	Imprint id
resourceType	string	Yes	The item's type, as when it was added
resourceId	string	Yes	The item's id

Response 204 No Content

---

Installing on agents

An installed imprint is one of the agent's shared pools: the agent reads its items at its next start. Restart a running agent to apply an install or an uninstall.

POST /api/v1/agents/:id/imprints

Install an imprint on an agent you can change. You must be able to see the imprint.

Scope: agents:write

Parameter	Type	Required	Description
id	string	Yes	Agent id

Request Body

Field	Type	Required	Description
imprintId	string	Yes	Imprint id

Response 201 Created: the installed imprint, a pool.

---

DELETE /api/v1/agents/:agentId/imprints/:id

Uninstall an imprint from an agent.

Scope: agents:write

Parameter	Type	Required	Description
agentId	string	Yes	Agent id
id	string	Yes	Imprint id

Response 204 No Content

---

Pools

GET /api/v1/library/pools

The pools you can see. Asking for scope=org-global creates your organization's org-global pool the first time.

Scope: memory:read

Query Parameters

Parameter	Type	Required	Description
scope	string	No	Only pools of this scope: custom, imprint, org-global or agent
counts	boolean	No	true adds each pool's counts
limit	integer	No	Results per page (default 50, at most 200)
cursor	string	No	meta.nextCursor of the previous page

Response 200 OK: a page of pools.

---

POST /api/v1/library/pools

Create a pool. Put its _id in an item's linkedIds to add the item to it.

Scope: memory:write

Request Body

Field	Type	Required	Description
name	string	Yes	Its name
description	string	No	What it holds
scope	string	No	custom (default) or imprint

Response 201 Created: the new pool.

---

GET /api/v1/library/pools/:id

A pool with its counts.

Scope: memory:read

Parameter	Type	Required	Description
id	string	Yes	Pool id

Response 200 OK: the pool.

---

PATCH /api/v1/library/pools/:id

Rename a pool or change its description.

Scope: memory:write

Parameter	Type	Required	Description
id	string	Yes	Pool id

Request Body

Field	Type	Required	Description
name	string	No	New name
description	string	No	New description

Response 200 OK: the updated pool.

---

DELETE /api/v1/library/pools/:id

Delete a pool. Its items stay in the library and lose the grouping; agents that read it stop reading it. An org-global or agent pool cannot be deleted (403).

Scope: memory:write

Parameter	Type	Required	Description
id	string	Yes	Pool id

Response 204 No Content

---

Sharing

An imprint is a pool, so the two share one set of permissions: owner, members (role editor can use and change it, user can only use it) and visibility (public: every user can find and use it; in a multi-tenant deployment, every user of its organization). Changing them stays with its owner and editors. The same routes are served under /library/pools/:id/permissions.

Method	Path	Does	Scope
GET	/api/v1/library/imprints/:id/permissions	Owner, members (userId, role) and visibility	memory:read
POST	/api/v1/library/imprints/:id/permissions/members	Share with a user: { "userId", "role": "editor" | "user" }	memory:write
DELETE	/api/v1/library/imprints/:imprintId/permissions/members/:userId	Stop sharing with a user	memory:write
PATCH	/api/v1/library/imprints/:id/permissions	{ "visibility": "public" | "private" }	memory:write

Each, except a member's removal (204), answers the permissions as they are now: { "resourceId", "owner", "members", "visibility" }.