List an agent knowledge library

GET

https://api.v2.rasen.ai/v1/agents/:agent_id/knowledge/sources

GET

/v1/agents/:agent_id/knowledge/sources

curl https://api.v2.rasen.ai/v1/agents/agent_id/knowledge/sources \
     -H "Authorization: Bearer <api_key>"

{
  "items": [
    {
      "source": {
        "id": "kb_01j00000000000000000000000",
        "name": "example",
        "kind": "url",
        "state": "pending",
        "revision": "example",
        "created_at": "2026-09-25T10:00:00Z",
        "failure": null,
        "content_sha256": "example",
        "content_bytes": 0,
        "media_type": "example",
        "ingested_at": "2026-09-25T10:02:00Z",
        "updated_at": "2026-09-25T10:06:00Z",
        "owner": {
          "type": "workspace"
        },
        "resource_key": "3f8e5a0c-9d1b-4c7e-a2f4-6b0d9e1c7a55",
        "poll_after_seconds": 1
      },
      "relation": "owned"
    }
  ],
  "next_cursor": "eyJwYWdlIjoyfQ"
}

Returns agent-owned sources and linked workspace sources. Ownership and attachment are distinct. Reads do not ingest. Archived sources excluded unless state=archived is requested. ID-list filters use repeated query names. Raw supplied ID count across fields is at most 100. Cursor binds normalized filters; filtered lists are not exact batch retrieval.

Authentication

AuthorizationBearer

Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

Path parameters

agent_idstringRequired1-128 characters

Resource identity within the authenticated workspace.

Query parameters

limitintegerOptional1-200Defaults to 50

Page size; 50 by default, at most 200.

cursorstringOptional

Opaque cursor bound to the workspace, every filter, grouping and limit. Send them unchanged with it. Expires after 24 hours.

source_idlist of stringsOptional

Repeat the query name for multiple IDs. OR within this field; AND across fields. Maximum 100 raw ID entries total across all ID filters. Blank values are invalid. Unknown/inaccessible IDs produce no rows, not an existence disclosure. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.

statelist of enumsOptional

Omitted excludes archived sources. Repeat for OR within this field; AND with other fields. These are not ID entries; at most 16 values per field, the same bound as the POST form. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.

resource_keylist of stringsOptional

Exact resource-key lookup inside this agent library. It ignores the archive scoping of this list but returns only sources owned by this agent or linked shared sources; a key that belongs to another agent source returns no row. For cross-owner reconciliation use GET /knowledge/sources?resource_key=. Repeat the name for several keys (OR). Counts toward the 100 raw filter values. An empty array is invalid and refused: SDKs refuse it before sending, and the server refuses an empty or blank value. Omission means no filter.

Response headers

X-Request-IdstringOptional

Safe server request correlation ID.

RateLimit-LimitintegerOptional

Requests allowed in the current window for the tightest applicable limit.

RateLimit-RemainingintegerOptional

Requests left in the current window.

RateLimit-ResetintegerOptional

Seconds until the current window resets.

Response

List an agent knowledge library.

itemslist of objects

next_cursorstring or null

Opaque continuation cursor. Null means the last page.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error