Organization library — the placement map (owners and admins)

Returns every package the organization can see (org-owned + system), grouped by type, each carrying its placements: one entry per space the package is placed in and the caller reads, saying WHY it is there (via: home, shared, system) and whether that space runs it (state: active, inactive, none). Members, guests and delegated credentials cannot access this administrative endpoint. Ephemeral packages are excluded. The spaces list and the placements include only spaces the caller can enter, and each package type also requires that type's read permission in the space. Acting on the map is the same pair of doors as anywhere else: POST /api/spaces/{spaceId}/packages activates a package in a space — creating the offer that places it when the caller holds <type>:share in its home — and DELETE /api/spaces/{spaceId}/packages/{scope}/{name} deactivates it there.

GET/api/library

Authorization

better-auth.session_token<token>

Cookie session from Better Auth. Requires X-Org-Id header for org-scoped routes.

In: cookie

Header Parameters

X-Org-Id?string

Organization ID. Required for cookie auth. Not needed for API key auth (org resolved from key).

Formatuuid

curl -X GET "https://your-instance/api/library"

{
  "object": "library",
  "spaces": [
    {
      "id": "spc_3e6f8a1b-2c4d-4e70-8f92-a1b3c5d7e9f0",
      "name": "Default",
      "isDefault": true
    },
    {
      "id": "spc_7f0a2c4e-6b81-4d3f-9e57-c2a4b6d8e0f1",
      "name": "Staging",
      "isDefault": false
    }
  ],
  "packages": {
    "agent": [
      {
        "id": "pkg_inbox_triage",
        "type": "agent",
        "source": "local",
        "name": "Inbox Triage",
        "description": "Sorts incoming Gmail threads into priority buckets.",
        "home_space_id": "spc_3e6f8a1b-2c4d-4e70-8f92-a1b3c5d7e9f0",
        "home_writable": true,
        "home_deletable": true,
        "home_shareable": true,
        "published": true,
        "placements": [
          {
            "space_id": "spc_3e6f8a1b-2c4d-4e70-8f92-a1b3c5d7e9f0",
            "via": "home",
            "state": "active",
            "chat_enforced": false,
            "shared_by": null
          },
          {
            "space_id": "spc_7f0a2c4e-6b81-4d3f-9e57-c2a4b6d8e0f1",
            "via": "shared",
            "state": "none",
            "chat_enforced": false,
            "shared_by": {
              "user_id": "usr_1",
              "name": "Alex"
            }
          }
        ]
      }
    ],
    "skill": [],
    "mcp-server": [],
    "integration": [
      {
        "id": "pkg_gmail",
        "type": "integration",
        "source": "system",
        "name": "Gmail",
        "description": "Google Mail OAuth integration.",
        "home_space_id": null,
        "home_writable": false,
        "home_deletable": false,
        "home_shareable": false,
        "published": true,
        "placements": [
          {
            "space_id": "spc_3e6f8a1b-2c4d-4e70-8f92-a1b3c5d7e9f0",
            "via": "system",
            "state": "active",
            "chat_enforced": false,
            "shared_by": null
          },
          {
            "space_id": "spc_7f0a2c4e-6b81-4d3f-9e57-c2a4b6d8e0f1",
            "via": "system",
            "state": "inactive",
            "chat_enforced": false,
            "shared_by": null
          }
        ]
      }
    ]
  }
}

{
  "type": "https://docs.appstrate.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing session",
  "code": "unauthorized",
  "request_id": "req_abc123"
}

{
  "type": "https://docs.appstrate.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Insufficient permissions",
  "code": "forbidden",
  "request_id": "req_abc123"
}