Logo
Search
Docs

List libraries

GET https://app.sulus.ai/api/v1/kb/knowledge-bases

List libraries you can access (auto-provisions your default library)

Authentication

Send a bearer token created on your dashboard's Developer page:

Authorization: Bearer <YOUR_API_KEY>

Query parameters

search string Optional Nullable
Validation: string (matches name, description, or the owner's name/email)
owner_user_id integer Optional Nullable
Validation: honoured only for super admins and reseller admins
Stored in knowledge_bases.owner_user_id
status string Optional Nullable
Validation: in: published, draft, archived — filters to libraries containing at least one document in that status
sort_by string Optional Default: name
Validation: in: name, created_at, updated_at, articles_count (falls back to name)
sort_dir string Optional Default: asc
Validation: anything other than desc (case-insensitive) is treated as asc

Errors

StatusMeaningBody
401 Missing or invalid bearer token
403 Feature knowledge_docs not enabled for the account

Notes

  • Calling this endpoint auto-provisions the caller's default library ("My Library", audience assistant) the first time they have none — see Overview.
  • meta.can_set_kb_audience and meta.can_filter_by_owner are true only for super admins (can_filter_by_owner is also true for reseller admins). meta.owners is populated only when can_filter_by_owner is true, and lists every distinct owner across the libraries visible to the caller.
  • meta.default_knowledge_base_id is only computed for non–super-admin accounts with a reseller: it is the id of the caller's own assistant-audience library, or null if they somehow have none.
  • meta.single_owned_library is simply "not a super admin" — it tells the UI whether to present a single-library view instead of a full library list.
  • Rows are eager-loaded with creator and owner (id, name, email only) and annotated with articles_count and assignments_count via a count query.
curl --request GET \
  --url https://app.sulus.ai/api/v1/kb/knowledge-bases \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
import requests

url = "https://app.sulus.ai/api/v1/kb/knowledge-bases"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}

response = requests.get(url, headers=headers)
print(response.json())
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://app.sulus.ai/api/v1/kb/knowledge-bases"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
Response 200 
{
    "data": [
        {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
            "workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
            "owner_user_id": 42,
            "created_by": 42,
            "name": "My Library",
            "description": null,
            "audience": "assistant",
            "created_at": "2026-06-01T14:22:03.000000Z",
            "updated_at": "2026-07-15T09:10:44.000000Z",
            "articles_count": 5,
            "assignments_count": 3,
            "creator": {
                "id": 42,
                "name": "Jane Cooper",
                "email": "[email protected]"
            },
            "owner": {
                "id": 42,
                "name": "Jane Cooper",
                "email": "[email protected]"
            }
        }
    ],
    "meta": {
        "can_set_kb_audience": false,
        "default_knowledge_base_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "single_owned_library": true,
        "can_filter_by_owner": false,
        "owners": []
    }
}