Library
GET /api/orgs/{org_id}/library
Section titled “GET /api/orgs/{org_id}/library”List Library
Browse or search the organization’s files and artifacts.
Without q this is a plain newest-first listing: exact total,
real SQL paging to any depth.
With q it is a hybrid search — trigram matching on names and
artifact content, unioned with cosine similarity over embeddings, fused and
ranked. Note that total then means the number of ranked candidates this
endpoint will return, not the number of rows in the org that match; it is
bounded by the per-channel candidate caps, and it moves as the query is
typed. Clients should not render it as a corpus count.
Rows created before the embedding sweep’s epoch have no vector, so they are reachable by name but not semantically. Semantic matching is document-level: the sweep embeds a bounded head of each document, so a term deep inside a large PDF may not match.
type narrows to one backing table on its own: a MIME family excludes
artifacts and an artifact type excludes uploads, because a facet chip means
“only these”, not “these plus everything else”. Pass kind to be explicit.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| agent_id | query | string (uuid) | no | |
| chat_id | query | string (uuid) | no | |
| kind | query | "file" | "artifact" | no | Restrict to uploads or agent artifacts |
| limit | query | integer | no | Max rows to return (1-100). Omit to return every row. |
| offset | query | integer | no | Rows to skip — pass the previous response’s next_offset. |
| org_id | path | string (uuid) | yes | |
| q | query | string | no | Hybrid search query |
| type | query | string | no | Facet token: a MIME family (image/document/spreadsheet/presentation/text/data/archive/other) or an artifact type (text/code/markdown/json/file). |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Successful Response | Page_LibraryItem_ |
| 422 | Validation Error | HTTPValidationError |