​
Core objects

Understanding the few fundamental objects used by the Senso API will make the individual endpoints far easier to reason about.
Think of the model as three layers: 
Category  →  Topic  →  Content
                       ↑
                       └── (optional) Generated or Search Results
Below is a plain-English description of each object, when you would create it, and how it relates to the others.

​
1. Category

What it is
A high-level “bucket” that groups together broad areas of knowledge (e.g. “Mortgages”, “Compliance”, “Product Support”). Why it exists
• Keeps very large knowledge bases navigable.
• Lets you scope searches or analytics to a business domain. Key fields
FieldTypeNotes
category_idUUIDPrimary key
namestringUnique within your organisation
descriptionstringOptional, up to 1 000 chars
created_attimeISO-8601

​
2. Topic

What it is
A finer-grained subdivision that lives inside a category. Examples inside “Mortgages” might be “First-time buyers”, “Refinancing”, “Rates & fees”. Why it exists
• Gives you more precise control when uploading or querying content.
• Lets UIs present hierarchies like Mortgages → Refinancing. Relationship
Topic has a many-to-one relationship with Category (a topic belongs to exactly one category). Key fields
FieldTypeNotes
topic_idUUIDPrimary key
category_idUUIDParent category
namestringUnique within its category
descriptionstringOptional
created_attime

​
3. Content

A single piece of knowledge you want the system to understand and search.
There are three native flavours, identified by the type field:
  1. raw – plain text or markdown you POST directly.
  2. document – a file you upload (PDF, DOCX, etc.).
  3. web – (reserved) content pulled from a URL.
All content, regardless of type, goes through the same pipeline: ingestion → chunking → vectorisation. Once processing_status reaches completed it is searchable and can be cited in generated answers. Key fields
FieldType/ExampleNotes
idUUIDPrimary key
typeenumraw, document, web
titlestringHuman-readable title
summarystringOptional abstract
version_numintIncrements on each update
processing_statusenumqueued → processing → completed/failed
category_idUUIDOptional for scoping
topic_idUUIDOptional for finer scope
created_attime
For document content you’ll also see file_url, file_name, mime_type once processing is complete.
For raw content you can fetch the full text.

​
4. SearchResult (implicit)

When you call /search, the API returns:
  • the original query
  • an AI-generated answer
  • an array of results – each is a snippet (“chunk”) of content that backed the answer.
Fields inside each result let you trace back to the original content_id, version_id, and even chunk_index for audit or debugging.

​
5. GenerateJob / Generated Content

The /generate endpoint returns freshly composed text (generated_text) along with the same style of sources array used in search results.
If you set "save": true in the request, the generated text is stored as a new content item and the response will include its content_id.

​
How it all fits together

  • Create Categories first, then Topics inside them.
  • Upload Content (raw or files) and tag it with the relevant category/topic IDs—this is optional but highly recommended for precise search.
  • Use /search to ask questions or /generate to have the model write something new, both of which cite underlying content chunks for transparency.
That’s the entire mental model: three persisted objects (Category, Topic, Content) plus two dynamic response types (SearchResult, Generated text). Everything else in the API is simply CRUD or query operations on these objects.