Sign in

v2

latestOpenAPI 3.1.02026-08-0382170235.8 KB
pots

Create a POT

Create a new Knowledge Pot (POT) with a Constitution — 3–10 foundational axioms that define what's true in the POT's domain. Returns the POT with assigned UUID and the Constitution materialised as facts at POT Score 1.0.

The workspace this POT belongs to is taken from the X-Workspace-ID header.

Renamed from POST /pots/from-json (deprecated, removed). Legacy callers should update to this route.

post/pots

Request body

namestring required

POT display name

slugstring required

URL-friendly identifier

descriptionstring

POT description

domainstring

Knowledge domain

Example request

{
  "constitution": [
    {
      "content": "Acme Corp was founded in 2020",
      "keywords": [
        "founding",
        "history"
      ],
      "rationale": "Founding date is foundational"
    },
    {
      "content": "Acme Corp's mission is to build great products",
      "rationale": "Mission statement"
    },
    {
      "content": "Acme Corp headquarters are in San Francisco",
      "rationale": "Location is foundational"
    }
  ],
  "description": "Internal knowledge for Acme Corp",
  "domain": "business",
  "name": "Company Knowledge Base",
  "slug": "company-kb"
}

Response

POT created successfully

idstring uuid required
slugstring required
workspace_idstring uuid required
namestring required
descriptionstring required
domainstring

Knowledge domain of the POT (from config.pot.domain). Exposed so clients — e.g. scipot pot export — can round-trip it; the coverage-gap routing key derives from it.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "constitution": {
    "approved_by": "system",
    "fact_count": 3,
    "facts": [
      {
        "content": "SciPot builds memory infrastructure for AI agents",
        "id": "const_001",
        "level": "CONSTITUTION",
        "pot_score": 1
      }
    ],
    "last_updated": "2026-01-06T10:30:45Z",
    "version": "1.0"
  },
  "created_at": "2026-01-06T10:30:45.123456Z",
  "description": "A POT about SciPot itself",
  "id": "018d1e8c-7b29-7a3e-8c1d-5e9a1c2d3e4f",
  "name": "SciPot Meta-POT",
  "slug": "scipot-pot",
  "updated_at": "2026-01-06T10:30:45.123456Z",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000"
}