---
title: "Create or upsert a corpus entry"
method: POST
path: "/tenants/{slug}/corpus"
tags: ["corpus"]
---

# Create or upsert a corpus entry

`POST /tenants/{slug}/corpus`

## Request

- Base URL: `https://api.animam.ai`
- URL: `https://api.animam.ai/tenants/{slug}/corpus`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`
  - OAuth 2 (authorization code, authorization URL `https://api.animam.ai/oauth/authorize`, token URL `https://api.animam.ai/oauth/token`, scopes: `corpus:write`)

Creates a new entry. If `externalId` is provided, performs an idempotent upsert (designed for CMS sync flows like the WordPress plugin).

## Path parameters

- `slug` string, required: Tenant slug (URL-safe identifier).

## Request body

- CreateCorpusBody
  - `title` string, required
  - `content` string, required: Full body of the entry.
  - `summary` string: Short summary surfaced in prompt; full content fetched on-demand via EXPLORE_CORPUS.
  - `segmentSlug` string
  - `priority` integer
  - `isActive` boolean
  - `externalId` string: Idempotency key from caller (e.g. wp-post-42). Upserts on conflict.
  - `source` string
  - `sourceUrl` string, uri
  - `locale` string: 2-letter ISO language code of the entry (en, fr, es, …). Used to scope retrieval per visitor locale on multilingual sites.

## Response `200`

Existing entry updated (upsert path).

- object
  - `corpus` CorpusEntry, required
    - `id` string, uuid, required
    - `title` string, required
    - `content` string, required
    - `summary` string, nullable, required
    - `priority` integer, required
    - `isActive` boolean, required
    - `externalId` string, nullable, required
    - `source` string, nullable, required
    - `sourceUrl` string, nullable, required
    - `segment` object, nullable, required
      - `slug` string, required
      - `name` string, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `created` false, required

## Other responses

- `201`: Entry created.
- `400`: Validation error.
- `429`: Corpus limit reached for the current plan.

---

[API](https://skmtc.dev/animam/apis/animam-api.md) · [All operations](https://skmtc.dev/animam/apis/animam-api/llms.txt) · [OpenAPI document](https://skmtc.dev/animam/apis/animam-api/revisions/138c3cf374f1?raw)