Logo
Search
Docs

Create library

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

Create a library

Authentication

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

Authorization: Bearer <YOUR_API_KEY>

Request body

name string Required

Library name.

Validation: required|string|max:255
Stored in knowledge_bases.name
description string Optional Nullable
Validation: nullable|string|max:5000
Stored in knowledge_bases.description
audience string Optional Nullable

Super admins only — chooses builder (feeds the AI-chat/build flows) vs assistant (feeds voice assistants). Ignored for everyone else, who always get assistant. Defaults to assistant when omitted.

Validation: nullable|string|in:builder,assistant
Stored in knowledge_bases.audience

Errors

StatusMeaningBody
422 Caller (non–super-admin) already owns a library {"message":"You already have a library. Add documents to it instead of creating another."}
422 No reseller could be resolved for the new library (super admin only) {"message":"reseller_id required"}
422 Validation failed {"message":"…","errors":{"field":["…"]}}
403 Policy denied — outside your organization, or you cannot write to this resource {"message":"This action is unauthorized."}
401 Missing or invalid bearer token
403 Feature knowledge_docs not enabled for the account

Notes

  • End users are limited to one owned library — see Overview's "One owned library per user".
  • workspace_id is set to the caller's active content workspace for non–super-admins, and is always null for a super admin's library.
  • A super admin's new library has no owner_user_id (it is an org-level library, not a personal one) unless reseller_id is supplied to target a specific organization; without it, the request fails with the reseller_id required error above because a super admin account carries no reseller_id of its own.
curl --request POST \
  --url https://app.sulus.ai/api/v1/kb/knowledge-bases \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Product FAQs",
  "description": "Customer-facing answers for the support line."
}'
import requests

url = "https://app.sulus.ai/api/v1/kb/knowledge-bases"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}
payload = {
  "name": "Product FAQs",
  "description": "Customer-facing answers for the support line."
}

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

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

func main() {
	url := "https://app.sulus.ai/api/v1/kb/knowledge-bases"
	payload := strings.NewReader(`{
  "name": "Product FAQs",
  "description": "Customer-facing answers for the support line."
}`)
	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	req.Header.Add("Content-Type", "application/json")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
Response 201 
{
    "data": {
        "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "reseller_id": "f1e2d3c4-b5a6-4978-8901-234567890abc",
        "workspace_id": "9a8b7c6d-5e4f-4a3b-9c8d-7e6f5a4b3c2d",
        "owner_user_id": 42,
        "created_by": 42,
        "name": "Product FAQs",
        "description": "Customer-facing answers for the support line.",
        "audience": "assistant",
        "created_at": "2026-07-30T14:22:03.000000Z",
        "updated_at": "2026-07-30T14:22:03.000000Z"
    }
}