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:
1. Category
What it isA 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
| Field | Type | Notes |
|---|---|---|
| category_id | UUID | Primary key |
| name | string | Unique within your organisation |
| description | string | Optional, up to 1 000 chars |
| created_at | time | ISO-8601 |
2. Topic
What it isA 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
| Field | Type | Notes |
|---|---|---|
| topic_id | UUID | Primary key |
| category_id | UUID | Parent category |
| name | string | Unique within its category |
| description | string | Optional |
| created_at | time |
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:
raw– plain text or markdown you POST directly.document– a file you upload (PDF, DOCX, etc.).web– (reserved) content pulled from a URL.
processing_status reaches completed it is searchable and can be cited in generated answers.
Key fields
| Field | Type/Example | Notes |
|---|---|---|
| id | UUID | Primary key |
| type | enum | raw, document, web |
| title | string | Human-readable title |
| summary | string | Optional abstract |
| version_num | int | Increments on each update |
| processing_status | enum | queued → processing → completed/failed |
| category_id | UUID | Optional for scoping |
| topic_id | UUID | Optional for finer scope |
| created_at | time |
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.
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.