Corpus - Animam Documentation

Endpoints to manage the chatbot’s corpus (knowledge base).

GET /tenants//corpus

List all corpus entries. Required scope: corpus:read

Request

curl https://api.animam.ai/tenants/my-company/corpus \
  -H "Authorization: Bearer ak_your_token"

Query Parameters

Param	Type	Description
`page`	number	Page (default: 1)
`limit`	number	Entries per page (default: 50, max: 100)
`segmentSlug`	string	Filter by segment slug

Response

{
  "corpus": [
    {
      "id": "3f8a1c2e-9d4b-4e6a-8f21-7c0d5b9e1a34",
      "title": "Return Policy",
      "content": "You have 30 days to return...",
      "summary": null,
      "priority": 5,
      "isActive": true,
      "externalId": null,
      "source": null,
      "sourceUrl": null,
      "segment": { "slug": "checkout", "name": "Checkout" },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 42,
    "totalPages": 1
  }
}

GET /tenants//corpus/

Retrieve a specific entry. Required scope: corpus:read

curl https://api.animam.ai/tenants/my-company/corpus/corp_abc123 \
  -H "Authorization: Bearer ak_your_token"

POST /tenants//corpus

Create a new entry. Required scope: corpus:write

Request

curl -X POST https://api.animam.ai/tenants/my-company/corpus \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Business hours",
    "content": "We are open Monday to Friday, 9am to 6pm. Saturday 10am to 4pm.",
    "segmentSlug": "contact",
    "priority": 5
  }'

Body

Field	Type	Required	Description
`title`	string	Yes	Entry title (max 255 chars)
`content`	string	Yes	Content (markdown) — the full version
`summary`	string	No	Short version the agent reads in every conversation (max 500 chars). See below.
`segmentSlug`	string	No	Associated segment slug
`priority`	number	No	Priority 0-100 (default: 0)
`externalId`	string	No	Idempotency key from the caller (e.g. `wp-post-42`) — upserts on conflict

`summary` vs `content` — a two-tier knowledge base

An entry has two levels, and choosing between them is the single decision that determines whether a large knowledge base works at all. Without a summary, the whole content goes into the system prompt of every conversation. That is fine for a handful of short entries. With a summary, only the summary is in the prompt; the content stays out and the agent fetches it on demand through its explore_corpus tool (injected automatically as soon as one entry has a summary). This is what lets fifty entries coexist: prompt sections are capped, and past the cap later entries are simply never loaded — silently. A summary must carry the substance in compressed form, not describe the entry. The test: if the agent only had the summary, would its answer be right — merely less detailed? If the answer is “it would know nothing”, the summary is wrong.

The field is named summary, which sounds like catalogue metadata. It is not: it is the text the model reads. "Covers our pricing and refund rules" leaves the agent unable to answer anything. "Refunds within 14 days, no questions asked; shipping is not refunded" lets it answer, and tells it there is more worth fetching.

Response

{
  "corpus": {
    "id": "9c8d7e6f-5a4b-4c3d-2e1f-0a9b8c7d6e5f",
    "title": "Business hours",
    "content": "We are open...",
    "summary": null,
    "priority": 5,
    "isActive": true,
    "externalId": null,
    "source": null,
    "sourceUrl": null,
    "segment": { "slug": "contact", "name": "Contact" },
    "createdAt": "2024-01-25T10:30:00Z",
    "updatedAt": "2024-01-25T10:30:00Z"
  }
}

PATCH /tenants//corpus/

Modify an existing entry. Required scope: corpus:write

curl -X PATCH https://api.animam.ai/tenants/my-company/corpus/corp_abc123 \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated content",
    "priority": 8
  }'

DELETE /tenants//corpus/

Delete an entry. Required scope: corpus:write

curl -X DELETE https://api.animam.ai/tenants/my-company/corpus/corp_abc123 \
  -H "Authorization: Bearer ak_your_token"

Response

{
  "deleted": true,
  "id": "corp_abc123"
}

POST /tenants//corpus/bulk

Batch upsert corpus entries, keyed by externalId (idempotent — re-sending the same externalId updates the existing entry instead of creating a duplicate). Used for the WordPress initial sync. Required scope: corpus:write

curl -X POST https://api.animam.ai/tenants/my-company/corpus/bulk \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "externalId": "wp-post-1", "title": "Hours", "content": "Open 9am-6pm", "segmentSlug": "contact", "priority": 5 },
      { "externalId": "wp-post-2", "title": "Price", "content": "$49/month", "segmentSlug": "pricing", "priority": 10 }
    ]
  }'

Body

Field	Type	Required	Description
`items`	array	Yes	Up to 50 entries per call

Each item accepts externalId (required), title (required), content (required), summary, sourceUrl, source, segmentSlug, priority, isActive.

Response

{
  "created": 1,
  "updated": 1,
  "skipped": 0,
  "total": 2,
  "limitRemaining": 18,
  "results": [
    { "externalId": "wp-post-1", "status": "created" },
    { "externalId": "wp-post-2", "status": "updated" }
  ]
}

New entries beyond the tenant’s corpus limit come back with status: "skipped" and a reason.

​GET /tenants//corpus

​Request

​Query Parameters

​Response

​GET /tenants//corpus/

​POST /tenants//corpus

​Request

​Body

​summary vs content — a two-tier knowledge base

​Response

​PATCH /tenants//corpus/

​DELETE /tenants//corpus/

​Response

​POST /tenants//corpus/bulk

​Body

​Response

GET /tenants//corpus

Request

Query Parameters

Response

GET /tenants//corpus/

POST /tenants//corpus

Request

Body

`summary` vs `content` — a two-tier knowledge base

Response

PATCH /tenants//corpus/

DELETE /tenants//corpus/

Response

POST /tenants//corpus/bulk

Body

Response