Core Concepts

Every request uses the base URL https://apiv2.senso.ai/api/v1 and your key in an X-API-Key header. API Keys shows how to get one.

What your organization can use depends on its Senso products. Gaps need Senso's Fetch product. An industry's results, prompts, and everything under "How Senso writes for you" and "Generated content" need Senso's GEO product (Generative Engine Optimization). Without the product, a request answers 403.

Most work costs credits: processing a document, a search, an evaluation, a generated page, and each scheduled run of your prompts. An organization out of credits gets 402.

At a glance

Your organization

GET /org/me returns your organization: its name, websites, industry, the AI models it tracks under models, the countries it asks from under locations, and whether scheduled runs and generation are on.

API Reference: Organization

The knowledge base

Everything is a node

The knowledge base is a tree. Every item in it is a node, and every node is one of two types:

Root                                folder
├── Policies                        folder
│   ├── Refund policy               content  (raw text)
│   └── shipping-policy.pdf         content  (file)
└── shared-context                  folder
    └── Existing-customer pricing   content  (raw text)

A content node's content.type says what kind of document it is:

{
  "kb_node_id": "6d982360-...",
  "parent_id": "73b78a4e-...",
  "content_id": "fba6665f-...",
  "type": "content",
  "name": "Refund policy",
  "content": {
    "id": "fba6665f-...",
    "type": "raw",
    "content_type": "text/markdown",
    "title": "Refund policy",
    "summary": "How long customers have to ask for a refund.",
    "version_num": 1,
    "processing_status": "complete"
  },
  "tags": [{ "name": "refund-policy" }],
  "effective_role": "admin"
}

Two IDs for every document

Adding documents

There are three ways in:

• Text. Send text or markdown with POST /org/kb/raw, into a folder you choose or Root. Markdown files go in this way too.
• Files. Describe up to 10 files with POST /org/kb/upload, each up to 100 MB. Senso returns an upload URL for each, and you upload the file there within the hour. The URL carries its own authorization, so the upload takes no API key.
• Your website. Website import brings in your home page and up to 19 more pages as raw documents, in a folder named Website, and drafts a brand kit if you have none. Start it from the Senso app or with senso website-import start in the Senso CLI.

Processing

Senso processes every document you add before search can use it. Nothing is searchable until processing_status is complete. Read it from the node with GET /org/kb/nodes/{id}:

Reading, editing and organizing

• Read. A text document's text is at GET /org/kb/nodes/{id}/content. An uploaded file has no text there; GET /org/kb/nodes/{id}/download-url gives a link to download it.
• Browse. Start at GET /org/kb/root and list each folder's children, or find nodes by name anywhere with GET /org/kb/find. Lists return 50 nodes at most; page through longer ones with limit and offset.
• Edit. Every edit saves a new version, and Senso processes it again. Search answers from the new version once it is complete. A file is replaced by uploading the new one in its place.
• Earlier versions. Read any of them with ?version= on /content.
• Rename and move. Renaming a document changes its title too.
• Delete. Deleting a folder deletes everything in it. A document that is still processing answers 409; try again when it is complete.

API Reference: Knowledge Base

Search

Search answers a question from your knowledge base and returns the passages behind the answer, with the document each came from. Five endpoints take the same request and differ in what they return:

Search only returns documents the caller can see. A key restricted to some folders searches only those.

API Reference: Search

Gaps

When /org/search, /org/search/full or /org/search/stream finds nothing, Senso records the question as a gap: something your knowledge base cannot answer yet. Context and content searches do not record gaps.

• The first time a question finds nothing from the API, its gap is weak, and left out of the default list. Asked again, by anyone, it becomes open.
• A later search that answers the question resolves its gap.
• Senso also records claims an evaluation found unsupported by your documents, or contradicted by them.

Keep test and monitoring searches out of your gaps with the header X-Senso-Signals: off. The search still runs and still costs credits; it just never records a gap.

API Reference: Gaps

Industries, AI models and prompts

These are how Senso sees what AI models say about your market.

Industries

An industry is a market Senso tracks, such as accounting and tax software, or AI agent platforms in Canada. Each industry has up to 1,000 industry prompts: questions people ask AI models about that market. Senso asks the AI models those questions on a schedule and records every answer: which brands it names, and which websites it cites.

Your organization belongs to one industry, chosen from Senso's catalog. Setting it changes which industry's results you read; it creates no prompts and starts no runs. From your industry you can see:

• how often each brand is named across the industry, over the last 30 days;
• each industry prompt, with how often each AI model named you, and its three most-named brands;
• which of the industry's prompts your organization does not track yet.

AI models

An AI model is an AI assistant Senso asks questions, such as chatgpt, google_ai_overviews or perplexity. GET /org/me lists the ones your organization tracks under models, and the countries it asks from under locations.

Prompts

A prompt is a question your organization tracks: Senso asks it on your organization's schedule, and it is what generated content answers. Import one from your industry's prompts, and Senso copies over its recent answers, or write your own with POST /org/prompts.

Importing turns on your organization's scheduled runs if they are not on yet: Senso sets up the AI models, countries and schedule it asks on, and each run costs credits. You can only import from your own industry, and a question you already track is skipped, not added twice.

type is where the question sits in a customer's journey: awareness, consideration, evaluation or decision. An industry prompt's funnel_stage becomes its type when you import it.

One thing, two names. The API also calls a prompt a GEO question. A geo_question_id is a prompt's prompt_id.

API Reference: Prompts

How Senso writes for you

Three settings shape what Senso writes: the brand kit (how you sound), content types (the shape of a page) and product lines (what you sell).

Brand kit

One per organization, used for everything Senso writes. Its guidelines take these six keys, and any other key is a 400:

API Reference: Brand Kit

Content types

A content type is a template for one kind of page, such as an FAQ article or a comparison page. Create as many as you need.

API Reference: Content Types

Product lines

A product line is one thing you sell: a name, and details in any shape you like, such as price, URL and who it is for.

The Builder in the Senso app uses product lines: you pick the ones a page is about. Generating a page for a prompt (/org/content-generation/sample, and scheduled generation) does not read them, so put facts those pages need in your knowledge base too.

API Reference: Product Lines

CTAs

A CTA (call to action) is a card on your published pages, such as "Book a demo": a title, a button label and the URL it goes to. One can be the organization default, which every page shows unless a page picks another or none.

A CTA is not the content type's cta_text. That is a link inside the page's text; a CTA is a card the published page shows beside it.

API Reference: CTA Templates

Generated content

Senso writes a page that answers one of your prompts, from your knowledge base, shaped by a content type and your brand kit. You can generate a page on request, or have Senso generate for your prompts on a schedule, set in your organization's generation settings. enable_content_generation and content_auto_publish in GET /org/me show whether scheduled generation, and publishing without review, are on.

Generated content is not in your knowledge base. It has its own content ID and its own endpoints under /org/content, and nothing Senso writes is searchable unless you add it to your knowledge base yourself. Knowledge base documents are read through /org/kb/nodes, never /org/content.

Generating a page

POST /org/content-generation/sample takes a prompt and a content type, and starts a job. Check the job with GET /org/content-generation/sample-jobs/{sample_job_id}: its status moves from queued to running, then ends completed, failed or expired. A completed job carries the page: its markdown, title, URL slug, and its content and version IDs.

Each prompt has one piece of generated content. Generating again for the same prompt, or saving your own draft for it with POST /org/content-engine/draft, adds a version rather than a second page.

API Reference: Content Generation

Review

A version is in one of three states:

API Reference: Content

Publishing

A destination is where a page goes live. Senso runs several domains that AI models read, such as citeables.com, and GET /org/destinations lists them with each one's publisher_id.

POST /org/content-engine/publish publishes a page to the destinations you name. Two things to know:

• Publishing sends the page text itself. Senso saves the raw_markdown you send as a new version and publishes that, so send the version you reviewed.
• Leave out publisher_ids and the page goes to every destination your organization has set up.

API Reference: Content Engine, Destinations

Errors

Every status the API returns, and what to do about it, is on Errors. Two to know first: 402 means your organization is out of credits or over its spending limit, and a 404 on a node you know exists means you cannot see it. See Permissions.

Next steps

• API Reference — every endpoint, request and response
• Permissions — who can see and change each folder and document
• Verification Loop — generate, check and publish a page
• CLI Reference — every command your agent can run