Reference

What you can license

137 components across three funnels, and 53 endpoints. Every table on this page is generated from the same registry the engine authorises against, so a documented tier cannot drift from an enforced one.

All 53 endpoints answer today

A route declared before its handler exists answers 501 and says so, rather than 404 — there are none of those right now.

Three funnels, derived rather than chosen

What a component costs to buy is decided by whether using it involves personal data, and how. Not by its price and not by its tier — a tier says how dangerous a capability is to hand over, which is a different question from what paperwork it needs.

Card, no conversation 47 components

No personal data in, none out. Sellable to a stranger with a card, instantly.

Card and a click-through agreement 53 components

Personal data goes in and nothing about a person is read from or written to the ledger. A data-processing agreement is needed and a capsule is not, because there is no stored model to project: you already have the words and are asking us about them. One thing is kept: a stateless turn your canon could not answer leaves the question on your coverage list, with nobody attached, for 90 days unless you change it — then the words are deleted and only the count stays.

Contract, and the person's own authorisation 37 components

Reads or writes a person's model. Needs a capsule, and a capsule needs that person to authorise it. Not self-serve at any price, which is the argument of the architecture rather than a policy somebody set.

Endpoints

Each names the component it authorises against. That is not documentation of the implementation — it is the implementation: the middleware reads the component off the route rather than from anything a handler passed, so a handler cannot check the wrong one.

adaptations

GET /v1/adaptationsPublished adaptations of approved canon, for a channel to show.marketing.adaptations.read
Examples

curl

curl -X GET https://api.boethios.ai/v1/adaptations \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/adaptations", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/adaptations",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())

canon

POST /v1/canon/searchFused retrieval over your corpus, with provenance.retrieval.search
Examples

curl

curl -X POST https://api.boethios.ai/v1/canon/search \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"annual leave entitlement","limit":5}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/canon/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "query": "annual leave entitlement",
    "limit": 5
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/canon/search",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "query": "annual leave entitlement",
        "limit": 5,
    },
)
print(response.status_code, response.json())
POST /v1/canon/sourcesAdd a source to your corpus.knowledge.claims.propose
Examples

curl

curl -X POST https://api.boethios.ai/v1/canon/sources \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Staff handbook 2026","publisher":"Your organisation","authorityTier":"institutional","reviewBy":"2027-10-01"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/canon/sources", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Staff handbook 2026",
    "publisher": "Your organisation",
    "authorityTier": "institutional",
    "reviewBy": "2027-10-01"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/canon/sources",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "title": "Staff handbook 2026",
        "publisher": "Your organisation",
        "authorityTier": "institutional",
        "reviewBy": "2027-10-01",
    },
)
print(response.status_code, response.json())
POST /v1/canon/claimsPropose a claim for approval. Pending claims never reach an answer.knowledge.claims.propose
Examples

curl

curl -X POST https://api.boethios.ai/v1/canon/claims \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"<source id from POST /v1/canon/sources>","text":"Full-time staff receive 28 days of paid annual leave, including bank holidays.","authorityDomain":["employment"],"authorityTier":"institutional","reviewBy":"2027-10-01","moduleTags":["work"]}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/canon/claims", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "source": "<source id from POST /v1/canon/sources>",
    "text": "Full-time staff receive 28 days of paid annual leave, including bank holidays.",
    "authorityDomain": [
      "employment"
    ],
    "authorityTier": "institutional",
    "reviewBy": "2027-10-01",
    "moduleTags": [
      "work"
    ]
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/canon/claims",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "source": "<source id from POST /v1/canon/sources>",
        "text": "Full-time staff receive 28 days of paid annual leave, including bank holidays.",
        "authorityDomain": [
            "employment",
        ],
        "authorityTier": "institutional",
        "reviewBy": "2027-10-01",
        "moduleTags": [
            "work",
        ],
    },
)
print(response.status_code, response.json())
GET /v1/canon/claims/:idOne claim, with its authority and review date.knowledge.claims.read
Examples

curl

curl -X GET https://api.boethios.ai/v1/canon/claims/<id> \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/canon/claims/<id>", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/canon/claims/<id>",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/canon/documentsUpload a PDF, scan or text file. Stored now, read by a worker.knowledge.uploads
Examples

curl

curl -X POST https://api.boethios.ai/v1/canon/documents \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -F "title=Staff handbook 2026" \
  -F "publisher=Your organisation" \
  -F "authorityTier=institutional" \
  -F "moduleTags=work" \
  -F "authorityDomain=employment" \
  -F "reviewBy=2027-10-01" \
  -F "file=@handbook.pdf"

TypeScript

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("title", "Staff handbook 2026");
form.append("publisher", "Your organisation");
form.append("authorityTier", "institutional");
form.append("moduleTags", "work");
form.append("authorityDomain", "employment");
form.append("reviewBy", "2027-10-01");
form.append("file", new Blob([await readFile("handbook.pdf")]), "handbook.pdf");

const response = await fetch("https://api.boethios.ai/v1/canon/documents", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
  body: form,
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/canon/documents",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    data={
        "title": "Staff handbook 2026",
        "publisher": "Your organisation",
        "authorityTier": "institutional",
        "moduleTags": "work",
        "authorityDomain": "employment",
        "reviewBy": "2027-10-01",
    },
    files={"file": open("handbook.pdf", "rb")},
)
print(response.status_code, response.json())
GET /v1/canon/documentsYour uploads, and how many are waiting or failed.knowledge.uploads
Examples

curl

curl -X GET https://api.boethios.ai/v1/canon/documents \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/canon/documents", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/canon/documents",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
GET /v1/canon/documents/:idOne upload: its state, and the reason if it failed.knowledge.uploads
Examples

curl

curl -X GET https://api.boethios.ai/v1/canon/documents/<id> \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/canon/documents/<id>", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/canon/documents/<id>",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
DELETE /v1/canon/documents/:idDelete the file. The claims it produced remain.knowledge.uploads
Examples

curl

curl -X DELETE https://api.boethios.ai/v1/canon/documents/<id> \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/canon/documents/<id>", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.delete(
    "https://api.boethios.ai/v1/canon/documents/<id>",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
GET /v1/canon/reviewWhat in your corpus is going stale.knowledge.claims.read
Examples

curl

curl -X GET https://api.boethios.ai/v1/canon/review \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/canon/review", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/canon/review",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())

capsules

POST /v1/capsulesRequest a capsule. The person authorises it, not you.licensing.requestthe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/capsules \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"your-user-123","purpose":"tailoring onboarding steps to what they told us they want","attributes":["goal.care_work"],"scope":"module:work","days":30}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/capsules", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ref": "your-user-123",
    "purpose": "tailoring onboarding steps to what they told us they want",
    "attributes": [
      "goal.care_work"
    ],
    "scope": "module:work",
    "days": 30
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/capsules",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "ref": "your-user-123",
        "purpose": "tailoring onboarding steps to what they told us they want",
        "attributes": [
            "goal.care_work",
        ],
        "scope": "module:work",
        "days": 30,
    },
)
print(response.status_code, response.json())
GET /v1/capsulesThe capsules you hold, and where each one stands.licensing.usethe person
Examples

curl

curl -X GET https://api.boethios.ai/v1/capsules \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/capsules", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/capsules",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
GET /v1/capsules/:idOne capsule: requested, link opened, answered, reads, revoked.licensing.usethe person
Examples

curl

curl -X GET https://api.boethios.ai/v1/capsules/<id> \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/capsules/<id>", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/capsules/<id>",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
DELETE /v1/capsules/:idRevoke one you hold.licensing.usethe person
Examples

curl

curl -X DELETE https://api.boethios.ai/v1/capsules/<id> \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/capsules/<id>", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.delete(
    "https://api.boethios.ai/v1/capsules/<id>",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/capsules/:id/linkA fresh consent link for a capsule nobody has answered yet.licensing.requestthe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/capsules/<id>/link \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url":"https://your-app.example/welcome"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/capsules/<id>/link", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "return_url": "https://your-app.example/welcome"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/capsules/<id>/link",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "return_url": "https://your-app.example/welcome",
    },
)
print(response.status_code, response.json())

catalogue

GET /v1/catalogueWhat you may call, at what tier, and what each refuses.licensing.registry
Examples

curl

curl -X GET https://api.boethios.ai/v1/catalogue \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/catalogue", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/catalogue",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())

character

GET /v1/characterThe persona as declared, with its registers and commitments.persona.read
Examples

curl

curl -X GET https://api.boethios.ai/v1/character \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/character", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/character",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/character/validateRun the scenario suite against a candidate persona.persona.consistency
Examples

curl

curl -X POST https://api.boethios.ai/v1/character/validate \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/character/validate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/character/validate",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={},
)
print(response.status_code, response.json())

events

GET /v1/eventsYour events, oldest first after a cursor. The feed behind your webhooks.events.feed
Examples

curl

curl -X GET https://api.boethios.ai/v1/events \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/events", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/events",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())

live

POST /v1/live/sessionOpen a voice call with a person: a room, and a token for their browser to join it.live.capsulethe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/live/session \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"your-user-123","register":"default"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/live/session", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ref": "your-user-123",
    "register": "default"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/live/session",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "ref": "your-user-123",
        "register": "default",
    },
)
print(response.status_code, response.json())

notices

GET /v1/noticesCorrection notices owed to you: something you read about a person has changed.state.notices.integrator
Examples

curl

curl -X GET https://api.boethios.ai/v1/notices \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/notices", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/notices",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/notices/:id/ackSay you have been told. Marks the notice delivered.state.notices.integrator
Examples

curl

curl -X POST https://api.boethios.ai/v1/notices/<id>/ack \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/notices/<id>/ack", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/notices/<id>/ack",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())

outcomes

GET /v1/outcomes/measuresThe measures you may record against: the catalogue and your own.outcomes.outcomes
Examples

curl

curl -X GET https://api.boethios.ai/v1/outcomes/measures \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/outcomes/measures", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/outcomes/measures",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/outcomes/measuresDeclare a measure for your own people, before any reading exists.outcomes.outcomes
Examples

curl

curl -X POST https://api.boethios.ai/v1/outcomes/measures \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"work.settled","scope":"module:work","question":"How settled do you feel about work this week, from 0 to 10?","unit":"points","direction":"higher_is_better","sources":["self_reported"]}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/outcomes/measures", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "key": "work.settled",
    "scope": "module:work",
    "question": "How settled do you feel about work this week, from 0 to 10?",
    "unit": "points",
    "direction": "higher_is_better",
    "sources": [
      "self_reported"
    ]
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/outcomes/measures",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "key": "work.settled",
        "scope": "module:work",
        "question": "How settled do you feel about work this week, from 0 to 10?",
        "unit": "points",
        "direction": "higher_is_better",
        "sources": [
            "self_reported",
        ],
    },
)
print(response.status_code, response.json())
POST /v1/outcomesRecord a reading against a declared measure.outcomes.outcomesthe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/outcomes \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"your-user-123","measure":"ucla3","value":5,"source":"self_reported"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/outcomes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ref": "your-user-123",
    "measure": "ucla3",
    "value": 5,
    "source": "self_reported"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/outcomes",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "ref": "your-user-123",
        "measure": "ucla3",
        "value": 5,
        "source": "self_reported",
    },
)
print(response.status_code, response.json())
GET /v1/outcomes/cohort/:measureCohort report for your population, or a refusal below the floor.outcomes.outcomesthe person
Examples

curl

curl -X GET https://api.boethios.ai/v1/outcomes/cohort/ucla3 \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/outcomes/cohort/ucla3", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/outcomes/cohort/ucla3",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
GET /v1/outcomes/experimentsYour experiments, with each arm's size above the cohort floor.outcomes.experimentsthe person
Examples

curl

curl -X GET https://api.boethios.ai/v1/outcomes/experiments \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/outcomes/experiments", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/outcomes/experiments",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/outcomes/experimentsStart an experiment on your own people for one module.outcomes.experiments
Examples

curl

curl -X POST https://api.boethios.ai/v1/outcomes/experiments \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"work.state_q4","scope":"module:work","question":"Do work answers help more when they draw on what the person told us?"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/outcomes/experiments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "key": "work.state_q4",
    "scope": "module:work",
    "question": "Do work answers help more when they draw on what the person told us?"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/outcomes/experiments",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "key": "work.state_q4",
        "scope": "module:work",
        "question": "Do work answers help more when they draw on what the person told us?",
    },
)
print(response.status_code, response.json())
POST /v1/outcomes/experiments/:key/endStop drawing arms. Arms already drawn, and readings in them, stay.outcomes.experiments
Examples

curl

curl -X POST https://api.boethios.ai/v1/outcomes/experiments/<key>/end \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/outcomes/experiments/<key>/end", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/outcomes/experiments/<key>/end",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())

pathways

POST /v1/pathways/stepsCount a pathway step for the code somebody arrived through. Never who.marketing.pathways
Examples

curl

curl -X POST https://api.boethios.ai/v1/pathways/steps \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entry":"<code from a campaign entry point>","step":"asked_to_continue"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/pathways/steps", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "entry": "<code from a campaign entry point>",
    "step": "asked_to_continue"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/pathways/steps",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "entry": "<code from a campaign entry point>",
        "step": "asked_to_continue",
    },
)
print(response.status_code, response.json())

people

POST /v1/peopleOnboard one of your users as a subject you own.subject.subjectsthe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/people \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"your-user-123","ageBand":"age_25_39"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/people", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ref": "your-user-123",
    "ageBand": "age_25_39"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/people",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "ref": "your-user-123",
        "ageBand": "age_25_39",
    },
)
print(response.status_code, response.json())
GET /v1/people/:refRead through a capsule. The only person read there is.licensing.usethe person
Examples

curl

curl -X GET https://api.boethios.ai/v1/people/your-user-123 \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/people/your-user-123", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/people/your-user-123",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
GET /v1/people/:ref/pendingWhat has been inferred about them and not confirmed.state.confirm.readthe person
Examples

curl

curl -X GET https://api.boethios.ai/v1/people/your-user-123/pending \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/people/your-user-123/pending", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/people/your-user-123/pending",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/people/:ref/recordsBring across what your own system held about them before. Inferences arrive unconfirmed.subject.subjectsthe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/people/your-user-123/records \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"yourapp.user_notes","records":[{"id":"note-1","at":"2026-09-01T10:00:00Z","kind":"inference","scope":"module:work","attribute":"pref.step_by_step","class":"PREFERENCE","value":"prefers things one step at a time"}]}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/people/your-user-123/records", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "source": "yourapp.user_notes",
    "records": [
      {
        "id": "note-1",
        "at": "2026-09-01T10:00:00Z",
        "kind": "inference",
        "scope": "module:work",
        "attribute": "pref.step_by_step",
        "class": "PREFERENCE",
        "value": "prefers things one step at a time"
      }
    ]
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/people/your-user-123/records",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "source": "yourapp.user_notes",
        "records": [
            {
                "id": "note-1",
                "at": "2026-09-01T10:00:00Z",
                "kind": "inference",
                "scope": "module:work",
                "attribute": "pref.step_by_step",
                "class": "PREFERENCE",
                "value": "prefers things one step at a time",
            },
        ],
    },
)
print(response.status_code, response.json())

persona

GET /v1/personaYour published persona, and every version of it.persona.author
Examples

curl

curl -X GET https://api.boethios.ai/v1/persona \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/persona", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/persona",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/personaPublish a persona. Runs the consistency probes and refuses a failure.persona.author
Examples

curl

curl -X POST https://api.boethios.ai/v1/persona \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"persona":"You are Ada, an onboarding guide for new staff…","sourceRef":"persona-v3","name":"Ada"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/persona", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "persona": "You are Ada, an onboarding guide for new staff…",
    "sourceRef": "persona-v3",
    "name": "Ada"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/persona",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "persona": "You are Ada, an onboarding guide for new staff…",
        "sourceRef": "persona-v3",
        "name": "Ada",
    },
)
print(response.status_code, response.json())
POST /v1/persona/checkThe same probes, no row written.persona.author
Examples

curl

curl -X POST https://api.boethios.ai/v1/persona/check \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"persona":"You are Ada, an onboarding guide for new staff…"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/persona/check", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "persona": "You are Ada, an onboarding guide for new staff…"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/persona/check",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "persona": "You are Ada, an onboarding guide for new staff…",
    },
)
print(response.status_code, response.json())
DELETE /v1/personaWithdraw it, with a reason. Your users hear the declared character again.persona.author
Examples

curl

curl -X DELETE https://api.boethios.ai/v1/persona \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"replaced by a new version"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/persona", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "reason": "replaced by a new version"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.delete(
    "https://api.boethios.ai/v1/persona",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "reason": "replaced by a new version",
    },
)
print(response.status_code, response.json())

presence

GET /v1/presence/visemesThe fifteen speech visemes a rig must expose, and the ARPAbet they map from.embodiment.visemes
Examples

curl

curl -X GET https://api.boethios.ai/v1/presence/visemes \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/presence/visemes", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/presence/visemes",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/presence/rigCheck a .glb against the fifteen, and against your last export.embodiment.rig
Examples

curl

curl -X POST https://api.boethios.ai/v1/presence/rig \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -F "file=@character.glb"

TypeScript

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("character.glb")]), "character.glb");

const response = await fetch("https://api.boethios.ai/v1/presence/rig", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
  body: form,
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/presence/rig",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    data={},
    files={"file": open("character.glb", "rb")},
)
print(response.status_code, response.json())
GET /v1/presence/rigYour validation history. Two exports are what catch a lost target.embodiment.rig
Examples

curl

curl -X GET https://api.boethios.ai/v1/presence/rig \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/presence/rig", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/presence/rig",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
GET /v1/presence/rig/:idOne validation: the manifest we kept, and the report you were shown.embodiment.rig
Examples

curl

curl -X GET https://api.boethios.ai/v1/presence/rig/<id> \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/presence/rig/<id>", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/presence/rig/<id>",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
POST /v1/presence/timelinePhoneme spans to viseme cues and expression tracks, for a caller who aligns their own audio.embodiment.visemes
Examples

curl

curl -X POST https://api.boethios.ai/v1/presence/timeline \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Take your time.","audio":"https://your-cdn.example/speech.wav","phonemes":[{"phoneme":"T","start":0,"end":0.08},{"phoneme":"EY1","start":0.08,"end":0.22},{"phoneme":"K","start":0.22,"end":0.3},{"phoneme":"Y","start":0.3,"end":0.36},{"phoneme":"AO1","start":0.36,"end":0.52},{"phoneme":"R","start":0.52,"end":0.6},{"phoneme":"T","start":0.6,"end":0.68},{"phoneme":"AY1","start":0.68,"end":0.98},{"phoneme":"M","start":0.98,"end":1.12}],"durationSeconds":1.4,"register":"default"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/presence/timeline", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "text": "Take your time.",
    "audio": "https://your-cdn.example/speech.wav",
    "phonemes": [
      {
        "phoneme": "T",
        "start": 0,
        "end": 0.08
      },
      {
        "phoneme": "EY1",
        "start": 0.08,
        "end": 0.22
      },
      {
        "phoneme": "K",
        "start": 0.22,
        "end": 0.3
      },
      {
        "phoneme": "Y",
        "start": 0.3,
        "end": 0.36
      },
      {
        "phoneme": "AO1",
        "start": 0.36,
        "end": 0.52
      },
      {
        "phoneme": "R",
        "start": 0.52,
        "end": 0.6
      },
      {
        "phoneme": "T",
        "start": 0.6,
        "end": 0.68
      },
      {
        "phoneme": "AY1",
        "start": 0.68,
        "end": 0.98
      },
      {
        "phoneme": "M",
        "start": 0.98,
        "end": 1.12
      }
    ],
    "durationSeconds": 1.4,
    "register": "default"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/presence/timeline",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "text": "Take your time.",
        "audio": "https://your-cdn.example/speech.wav",
        "phonemes": [
            {
                "phoneme": "T",
                "start": 0,
                "end": 0.08,
            },
            {
                "phoneme": "EY1",
                "start": 0.08,
                "end": 0.22,
            },
            {
                "phoneme": "K",
                "start": 0.22,
                "end": 0.3,
            },
            {
                "phoneme": "Y",
                "start": 0.3,
                "end": 0.36,
            },
            {
                "phoneme": "AO1",
                "start": 0.36,
                "end": 0.52,
            },
            {
                "phoneme": "R",
                "start": 0.52,
                "end": 0.6,
            },
            {
                "phoneme": "T",
                "start": 0.6,
                "end": 0.68,
            },
            {
                "phoneme": "AY1",
                "start": 0.68,
                "end": 0.98,
            },
            {
                "phoneme": "M",
                "start": 0.98,
                "end": 1.12,
            },
        ],
        "durationSeconds": 1.4,
        "register": "default",
    },
)
print(response.status_code, response.json())

sessions

POST /v1/sessionsOpen a conversation with a person, so turns carry context.reason.loopthe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/sessions \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"your-user-123"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ref": "your-user-123"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/sessions",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "ref": "your-user-123",
    },
)
print(response.status_code, response.json())
POST /v1/sessions/:id/endEnd a conversation. Its working note goes unless the person kept it.reason.loopthe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/sessions/<id>/end \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"your-user-123"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/sessions/<id>/end", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ref": "your-user-123"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/sessions/<id>/end",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "ref": "your-user-123",
    },
)
print(response.status_code, response.json())

story

GET /v1/story/worksYour published narrative works: series, investigations, quests, curricula.story.works.read
Examples

curl

curl -X GET https://api.boethios.ai/v1/story/works \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/story/works", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/story/works",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())
GET /v1/story/works/:idOne work's structure, as somebody at a given reveal stage may be shown it.story.works.read
Examples

curl

curl -X GET https://api.boethios.ai/v1/story/works/<id> \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/story/works/<id>", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/story/works/<id>",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())

turn

POST /v1/turnThe twelve layers, with the person's context. Needs a capsule.reason.loopthe person
Examples

curl

curl -X POST https://api.boethios.ai/v1/turn \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ref":"your-user-123","text":"I want to move into care work. Where do I start?","register":"default"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/turn", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ref": "your-user-123",
    "text": "I want to move into care work. Where do I start?",
    "register": "default"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/turn",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "ref": "your-user-123",
        "text": "I want to move into care work. Where do I start?",
        "register": "default",
    },
)
print(response.status_code, response.json())
POST /v1/turn/statelessThe twelve layers, grounded in canon only. Reads no ledger.reason.canon
Examples

curl

curl -X POST https://api.boethios.ai/v1/turn/stateless \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"What does the handbook say about annual leave?","module":"work"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/turn/stateless", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "text": "What does the handbook say about annual leave?",
    "module": "work"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/turn/stateless",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "text": "What does the handbook say about annual leave?",
        "module": "work",
    },
)
print(response.status_code, response.json())

usage

GET /v1/usageCalls and distinct people per day. What a dispute is settled with.licensing.use
Examples

curl

curl -X GET https://api.boethios.ai/v1/usage \
  -H "Authorization: Bearer $BOETHIOS_KEY"

TypeScript

const response = await fetch("https://api.boethios.ai/v1/usage", {
  method: "GET",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.get(
    "https://api.boethios.ai/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
)
print(response.status_code, response.json())

voice

POST /v1/voice/speakSynthesis. Text in, audio out, in the register you name.voice.voice
Examples

curl

curl -X POST https://api.boethios.ai/v1/voice/speak \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Take your time.","register":"default"}'

TypeScript

import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.boethios.ai/v1/voice/speak", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "text": "Take your time.",
    "register": "default"
  }),
});
await writeFile("speech.wav", Buffer.from(await response.arrayBuffer()));

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/voice/speak",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "text": "Take your time.",
        "register": "default",
    },
)
open("speech.wav", "wb").write(response.content)
POST /v1/voice/speak/alignedSynthesis with ARPAbet phoneme spans, which is what drives a face.voice.aligned
Examples

curl

curl -X POST https://api.boethios.ai/v1/voice/speak/aligned \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Take your time.","register":"default","language":"en"}'

TypeScript

const response = await fetch("https://api.boethios.ai/v1/voice/speak/aligned", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BOETHIOS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "text": "Take your time.",
    "register": "default",
    "language": "en"
  }),
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/voice/speak/aligned",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    json={
        "text": "Take your time.",
        "register": "default",
        "language": "en",
    },
)
print(response.status_code, response.json())
POST /v1/voice/hearTranscription, with its disclosure.voice.hearing
Examples

curl

curl -X POST https://api.boethios.ai/v1/voice/hear \
  -H "Authorization: Bearer $BOETHIOS_KEY" \
  -F "file=@utterance.webm"

TypeScript

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("utterance.webm")]), "utterance.webm");

const response = await fetch("https://api.boethios.ai/v1/voice/hear", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BOETHIOS_KEY}` },
  body: form,
});
console.log(response.status, await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.boethios.ai/v1/voice/hear",
    headers={"Authorization": f"Bearer {os.environ['BOETHIOS_KEY']}"},
    data={},
    files={"file": open("utterance.webm", "rb")},
)
print(response.status_code, response.json())

Every component

137 of 159. The other 22 are never exposed — not expensive, not available — and are absent from this page rather than listed with “contact us” beside them. The policy kernel, the raw connection, the migration runner and the training-snapshot export are among them. A reference page that advertised those would be inviting a conversation we will refuse.

ComponentWhat it isTierHow you buy itEndpoints
audit.auditAudit trailT3contract
consent.consent.readConsent — readT1contract
consent.consent.writeConsent — writeT3contract
console.membersConsole membershipT3agreement
context.assembleContext assemblyT2contract
context.tokensToken budgetT1agreement
crisis.authoringCrisis taxonomy authoringT3agreement
crisis.draft-taxonomyDraft crisis taxonomyT1card
crisis.escalationEscalationsT3contract
crisis.gateundeclinableCrisis gateT1agreement
crisis.readinessRelease readinessT3agreement
crisis.rotaEscalation rotaT3agreement
domain.errorsVocabulary and errorsT1card
domain.lifecycleThe state lifecycle, describedT1card
domain.typesVocabulary and decay constantsT1card
embodiment.characterRenderer command vocabularyT1card
embodiment.expressionNonverbal expression tracksT1card
embodiment.rigRig validationT2agreement3
embodiment.visemesPhoneme to viseme, and the timelineT1card2
erasure.rightsRights and erasureT3contract
eval.account-evalAccount eval casesT1card
eval.admissionundeclinableQueue admissionT1card
eval.characterCharacter evals and the regression gateT1card
eval.latencyLatency measurementT2agreement
eval.module-evalModule evaluationT1card
eval.work-casesWork eval casesT1card
events.eventsThe event logT3contract
events.feedEvent feed and webhook signaturesT1card1
identity.devicesIdentity keys, attestation and migrationT3contract
identity.enneagramDeclared Enneagram type and its register hintsT3contract
knowledge.claims.proposeClaims — proposeT2agreement2
knowledge.claims.readClaims — readT1card2
knowledge.claims.writeClaims — writeT3agreement
knowledge.coverageCoverage of the corpusT3contract
knowledge.discoveryDiscovery plannerT3agreement
knowledge.documentsDocument and image readingT2agreement
knowledge.ingestClaim ingestT2agreement
knowledge.positionsScholars' positions and disputesT3agreement
knowledge.previewRetrieval previewT2agreement
knowledge.reviewReviewer queueT3agreement
knowledge.storyworldStoryworld stagingT3agreement
knowledge.structureStory structure over claimsT3agreement
knowledge.uploadsDocument upload and ingestT2agreement4
knowledge.work-corpusWork source manifestT1card
licensing.registryComponent registry, readT1card1
licensing.releasesRelease manifests and diffsT1card
licensing.requestCapsule requestsT2contract2
licensing.useCapsule read and introspectionT1contract5
live.audioVoice activity from PCM framesT1agreement
live.capsuleLive call through a capsuleT2contract1
live.clockLive call clockT1card
live.faceEstimated visemes for a live sentenceT1card
live.hearing-streamStreaming transcription for a live callT2agreement
live.loadFirst-audio load harnessT2agreement
live.pipelineStreaming model to voice to faceT2agreement
live.prosodyProsody, held for one turnT2agreement
live.transportLive call data channelT1agreement
live.turn-takingEnd of turn and barge-inT1agreement
live.voiceSentence voice for a live callT2agreement
live.workerLive session workerT2agreement
marketing.adaptationsAdaptations of approved canonT3agreement
marketing.adaptations.readAdaptations, read and checkedT1card1
marketing.entry-pointsCampaign entry pointsT1card
marketing.pathwaysAudience pathwaysT1card1
marketing.performancePathway performance and segmentsT1card
memory.briefProfile briefT2contract
memory.episodeEpisodic memoryT2contract
modules.elderElder moduleT1card
modules.lanesAnswerable-lane gatesT1card
modules.modulePurpose module declarationT1card
modules.registryModule registryT1card
modules.workWork moduleT1card
observability.telemetryTelemetryT1card
outcomes.experimentsOutcome experimentsT3contract3
outcomes.outcomesOutcome recordingT3contract4
outcomes.ucla3Loneliness instrumentT1card
persona.authorPersona authoringT3agreement4
persona.consistencyPersona consistency harnessT1card1
persona.readPersona — readT1card1
persona.scenario-setScenario setsT1card
persona.scenariosPersona scenariosT1card
policy.catalogueQuestion catalogue (seed)T1card
policy.dependencyAnti-dependency prohibitions, and what keeps eachT1card
policy.restraintRestraint ladderT1card
policy.routingWho answers — Boethios, the person, or a humanT2agreement
presence.accessCommunication needs — the director's third refusalT1contract
presence.directorThe presence directorT1card
presence.revealReveal state — the shared ladderT1card
realtime.livekitRealtime transportT2agreement
reason.aws-credentialsAWS credential chainT2agreement
reason.bedrockBedrock clientT2agreement
reason.buildBuilding a provider from a configurationT2agreement
reason.canonReasoning loop, canon onlyT2agreement1
reason.citationsCitation resolutionT1card
reason.configProvider configurationT2agreement
reason.declinesDecline vocabularyT1card
reason.fakeScripted provider, for testsT2agreement
reason.guardsundeclinableInput and output guardsT1agreement
reason.loopReasoning loop, with the personT2contract3
reason.openai-compatibleOpenAI-compatible clientT2agreement
reason.providerModel provider contractT2agreement
reason.routingPer-role provider routingT2agreement
reason.sigv4AWS request signingT2agreement
reason.styleRegister style passT2agreement
retrieval.embed-claimsClaim embeddingT1card
retrieval.fuseRank fusionT1card
retrieval.searchGrounded retrievalT1agreement1
slow.after-turnThe after-turn clockT2contract
slow.extractExtraction, the slow pathT2contract
slow.extraction-qualityExtraction quality measureT1card
slow.reflectReflection without a modelT2contract
state.ask.proposeConfirm-and-correct loop — proposeT2contract
state.ask.writeConfirm-and-correct loop — writeT3contract
state.confirm.proposeConfirmation gate — proposeT2contract
state.confirm.readConfirmation gate — readT1contract1
state.confirm.writeConfirmation gate — writeT3contract
state.factors.proposeFactor chains — effects drawn from factorsT2contract
state.notices.deliverCorrection notices — deliverT3contract
state.notices.integratorCorrection notices — your ownT1contract2
state.notices.oweCorrection notices — oweT2contract
state.notices.readCorrection notices — the person's own viewT1contract
state.repair.readDownstream repair — readT1contract
state.repair.runDownstream repair — re-deriveT2contract
state.state.readPerson ledger — readT1contract
state.state.writePerson ledger — writeT3contract
store.objectsObject storageT2agreement
story.works.authorNarrative layer structure, authoredT3agreement
story.works.readNarrative layer structure, readT1card2
subject.subjectsSubjects and releasesT3contract2
training.layersTrainable layersT3agreement
training.metricsAgreement metricsT1card
voice.alignedAligned voiceT1agreement1
voice.hearingTranscriptionT1agreement1
voice.reference-qualityReference recording checksT1card
voice.rightsCustom voice rights and referencesT3agreement
voice.trainingCustom voice training and checkpointsT3agreement
voice.voiceSpeech synthesisT1agreement1

What the tiers mean

T1 65 components

Read own-subject, or no personal data at all. Reading a person's own model on their behalf, and everything that touches no person: the retrieval stack, the module declarations, the persona scenarios, the pure measures.

T2 41 components

Propose only. Can produce candidates and cannot make them authoritative. Extraction and reflection both live here, and the confirmation gate is why that is safe: what they write is an interpretation, and an interpretation is not readable until the person confirms it.

T3 31 components

Governed write. Writes that need a verified role behind them: declarations on somebody's behalf, consent, erasure, the event log, console membership, the trainable layers.

Three that cannot be switched off

crisis.gate, eval.admission, reason.guards. They are T1, which is the point: they cost nothing and they are not optional. A tier is about how dangerous a capability is to hand over — these are dangerous to take away.

Create an account to switch any of the card-and-agreement components on, or sign in.