Skip to main content
Sections are named tree nodes that group chunks within a document version. They reflect the logical structure of a document — chapters, headings, topics — and can be nested. Each section has a parent (DOCUMENT_VERSION or another SECTION) and is ordered within its siblings via a linked-list structure (prev_sibling_path_id, next_sibling_path_id).

​
Create section


POST https://api-staging.knowledgestack.ai/v1/sections Create a new section as a child of a document version or an existing section.

​
Request body

​
name
string
required
Section name. 1–255 characters. Can contain any characters.
​
parent_path_id
string (uuid)
required
path_part_id of the parent. Must be a DOCUMENT_VERSION or SECTION type path part.
​
page_number
integer
The page in the source document where this section begins. Must be > 0.
​
prev_sibling_path_id
string (uuid)
Insert this section after the specified sibling path_part_id. If null or omitted, the section is appended to the end of the sibling list.

​
Response 200

Returns a SectionResponse.
​
id
string (uuid)
Section ID.
​
path_part_id
string (uuid)
Underlying path part ID.
​
name
string
Section name.
​
page_number
integer | null
Source document page number.
​
parent_path_id
string (uuid)
Parent path part ID.
​
prev_sibling_path_id
string (uuid) | null
Previous sibling path part ID in the ordered list.
​
next_sibling_path_id
string (uuid) | null
Next sibling path part ID in the ordered list.
​
materialized_path
string
Full path from root.
​
system_managed
boolean
Whether this section is system-managed.
​
system_metadata
SectionSystemMetadata
System-managed metadata, including aggregate statistics (information_statistics).
​
tenant_id
string (uuid)
Owning tenant.
​
created_at
string (datetime)
Creation timestamp (ISO 8601).
​
updated_at
string (datetime)
Last update timestamp (ISO 8601).

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/sections \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Introduction",
    "parent_path_id": "<document-version-path-part-id>",
    "page_number": 1
  }'

​
Get sections (bulk)


GET https://api-staging.knowledgestack.ai/v1/sections/bulk Fetch multiple sections by ID in a single request.
Non-existent IDs are silently skipped. The maximum number of IDs per request is 200.

​
Query parameters

​
section_ids
string[]
required
Comma-separated list of section IDs to retrieve.

​
Response 200

Returns an array of SectionResponse objects. See Create section for field descriptions.

​
Example

curl "https://api-staging.knowledgestack.ai/v1/sections/bulk?section_ids=<id-1>,<id-2>,<id-3>" \
  -H "Authorization: Bearer <your-api-key>"

​
Get section


GET https://api-staging.knowledgestack.ai/v1/sections/{section_id} Get a single section by its ID.

​
Path parameters

​
section_id
string (uuid)
required
The section ID.

​
Response 200

Returns a SectionResponse. See Create section for field descriptions.

​
Example

curl "https://api-staging.knowledgestack.ai/v1/sections/<section-id>" \
  -H "Authorization: Bearer <your-api-key>"

​
Update section


PATCH https://api-staging.knowledgestack.ai/v1/sections/{section_id} Update a section’s name, page number, or position within its siblings. All fields are optional. To reorder: provide prev_sibling_path_id to insert after a specific sibling, or set move_to_head: true to move to the front of the sibling list. Do not provide both.

​
Path parameters

​
section_id
string (uuid)
required
The section ID to update.

​
Request body

​
name
string
New section name. 1–255 characters.
​
page_number
integer
Updated page number. Must be > 0.
​
prev_sibling_path_id
string (uuid)
Move after this sibling path part ID.
​
move_to_head
boolean
Set to true to move this section to the beginning of the sibling list. Defaults to false.
​
parent_path_part_id
string (uuid)
Reparent to a new parent path part. Must be a DOCUMENT_VERSION or SECTION within the same document version.

​
Response 200

Returns the updated SectionResponse.

​
Example

# Rename
curl -X PATCH https://api-staging.knowledgestack.ai/v1/sections/<section-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Overview"}'

# Move to head of sibling list
curl -X PATCH https://api-staging.knowledgestack.ai/v1/sections/<section-id> \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"move_to_head": true}'

​
Delete section


DELETE https://api-staging.knowledgestack.ai/v1/sections/{section_id} Delete a section and all of its child sections and chunks.
This is a cascading delete. All nested sections and their chunks are permanently removed.

​
Path parameters

​
section_id
string (uuid)
required
The section ID to delete.

​
Response 200

Returns an empty {} on success.

​
Example

curl -X DELETE https://api-staging.knowledgestack.ai/v1/sections/<section-id> \
  -H "Authorization: Bearer <your-api-key>"

​
Dissolve section


POST https://api-staging.knowledgestack.ai/v1/sections/{section_id}/dissolve Dissolve a section by converting it to a TEXT chunk and reparenting its children. Specifically:
  1. The section’s name becomes the content of a new TEXT chunk at the section’s position.
  2. All children of the section are reparented to the section’s parent.
  3. The section itself is deleted.
This is useful when you want to flatten a section into its parent without losing the heading text or the child content.

​
Path parameters

​
section_id
string (uuid)
required
The section to dissolve.

​
Response 200

Returns a DissolveSectionResponse.
​
text_chunk_id
string (uuid)
ID of the newly created TEXT chunk containing the section’s name.
​
reparented_children
integer
Number of children that were reparented to the section’s former parent.

​
Example

curl -X POST https://api-staging.knowledgestack.ai/v1/sections/<section-id>/dissolve \
  -H "Authorization: Bearer <your-api-key>"

{
  "text_chunk_id": "c3d4e5f6-0000-0000-0000-000000000003",
  "reparented_children": 5
}