Constitor Platform API

The one API every app uses: Constitor, Socius, Mercator, Battalion and Auxilium. No app has an API of its own. This page explains how it is built and how to connect, then lists every path in the OpenAPI document as served on 16 October 2026.

How the platform works

Constitor runs an agentic company on one rulebook. The handbook says what is allowed and who decides. Agents do the work inside those rules, in every app. A person says ok where the rules ask for it, and Constitor records a receipt. What the agents learn goes back to the handbook as a proposal, never straight in. All of it runs through this one API.

The suite

Every app has the same shape: the app rail, the agent panel as the second column, and the content. Every app reads and writes only through /api/v1.

Where things live

Who signs in, and when

One way to approve

1. The agent asks in the panel, with what it wants to do and why.
2. The person says ok in the chat. There is no Approve button.
3. Constitor checks the person's role, the channel and the handbook version.
4. Constitor writes the receipt: "Recorded by Constitor, not by a bot." The run continues.

At any mandate level an agent never approves, publishes or merges; never changes its own role card, skills or mandate; never touches keys; never deletes data; and never names a price, signs, promises or gives access without a person's ok. A mandate goes up only by a board decision.

Screens and endpoints

Each app is a view of the shared resources, and apps link by the shared resource id. The calendar is GET /api/v1/calendar, Constitor's own calendar, stored here, and the source of truth. An event may link a task, a scheduled post, or a meeting. The week of posts is a filter on that list. Microsoft 365, and later Google, are optional sync connectors and are never required. Communication is GET /api/v1/conversations, the one communication API, stored here. Channel is a field: email, WhatsApp, SMS, Slack, Teams, or in-app. A new channel is a connector, not a new path. Files are GET /api/v1/files. Tasks are GET /api/v1/tasks, and a planning view is a filter on that list. Notifications are GET /api/v1/notifications and are delivered on a conversation channel. Search is GET /api/v1/search. The audit trail is GET /api/v1/audit-events. Posts are GET /api/v1/posts. Contacts are the Directory. Flows are GET /api/v1/flows. A new app uses these services. It does not build its own. 35 of 92 screens can be built on a path that is served in the repository. The rest are planned on those resources, or still wait for a path. Phase 1 paths are live. Directory, Socius and the agent paths are served in the repository and are not yet on the live host.

How it fits together

There is one API. Every screen, bot, connector and outside tool goes through it, and nothing reads or writes the database directly. Only schema migrations touch the database, through the controlled migration pipeline. That rule (API first, C0.4 and D91) is what keeps every app the same shape and every change audited. Each app is a view of the shared resources, stored in the platform and the source of truth: one calendar (/api/v1/calendar), one communication layer (/api/v1/conversations, channel is a field), one file store (/api/v1/files), one task list (/api/v1/tasks), one notification list (/api/v1/notifications), one search (/api/v1/search), one audit trail (/api/v1/audit-events), one posts list (/api/v1/posts), one Directory, and one flows list (/api/v1/flows). Connectors are optional and are never required. A new app uses these services. It does not build its own.

The layers, left to right

• Callers. The five apps, the bots and agents, MCP connectors and outside integrations. An app never adds its own API in front of this one; there is no backend-for-frontend.
• Identity. A person signs in once with the Constitor login (Microsoft, Google or the customer's own SSO) and that session works in every app. A machine uses a token the platform mints, bound to one organisation. There is no open self-signup: an account exists only by invitation or by an admin.
• The API. Every call is authenticated, scoped to one organisation (tenant), checked against a named capability of the caller's role, and leaves an audit receipt. The OpenAPI document is generated from one module in the platform app and is the single source.
• Behind the API. Kernel tables (organisations, people, roles, the Directory), headless engines reached through adapters, Microsoft 365 on behalf of the signed-in user, and the agent runtime's private store. Engines are used unmodified and never shown; the document uses our names only.
• Data. One EU database in Paris. Every row carries tenant_id, and row-level security only lets a request see rows of its own tenant. A partner reaches a customer only through the partner_tenants link and a consent grant.

Hosts

How to connect

Pick the route that matches what you are building. All four end at the same API with the same checks; they differ only in how the caller proves who it is.

1 · An app in the suite

1. Send the person to the Constitor login. They choose Microsoft, Google or SSO. Sign-in is not a /v1 resource, and the app keeps no user table of its own.
2. After sign-in the browser holds the suite session. Call the API from the same origin with credentials included.
3. Read GET /api/v1/session for the signed-in account and the active organisation, and GET /api/v1/me for roles.
4. Show the organisation switcher from GET /api/v1/organisations; switch with POST /api/v1/organisations/{organisationId}/activate. Every later call works in the active organisation.

// any app in the suite, same origin, session included
const res = await fetch('/api/v1/session', { credentials: 'include' });
if (!res.ok) {
  const { error } = await res.json();   // e.g. "Sign in is required."
  throw new Error(error);
}
const session = await res.json();        // the account and the active organisation

Apps use the shared package (a typed client generated from the OpenAPI document, the session helper and the tenant switch) instead of hand-written calls once it is published.

2 · An outside tool or script

1. Get a service token minted by the platform for one organisation. The design shows this under Battalion › Access; who may mint one is still an open question. The token is bound to that organisation and carries scopes.
2. Store the token in your own secret store. Name it, never paste it in a chat, ticket or repository.
3. Send it as a bearer token on every call. The organisation comes from the token; you cannot switch it.

curl https://app.constitor.ai/api/v1/me \
  -H "Authorization: Bearer $CONSTITOR_TOKEN"

Scopes today: microsoft:read and microsoft:write, which the Microsoft routes enforce. Other scope names, token lifetime and who may mint are open questions. A move from the current static token to OAuth 2.1 through Microsoft Entra is proposed (D155) and not yet accepted.

3 · An MCP connector

Connect the MCP host in your tool (for example the handbook MCP at https://handbook-mcp.constitor.ai/api/mcp). Every MCP tool is a thin wrapper over one or more /v1 calls, so it gets the same tenant scope, capability check and audit. The handbook MCP reads the git corpus of the handbook; that read is not a database read.

4 · A bot or agent

Agents are defined in the handbook and run in an agent cell. For each run the cell receives a short-lived token for one tenant (D97) and calls /v1 like any other caller. An agent drafts and asks; it never approves its own work, and every step leaves a receipt.

Your first calls: phase 1

The first milestone: a partner signs in, creates a customer organisation and invites its first admin. These are the only calls the phase 1 screens use, in this order. All are served.

Create a customer

The active organisation is the partner's, taken from the session. The body has three fields. Send an Idempotency-Key so a retry never creates a second customer.

POST /api/v1/partner-tenants
Idempotency-Key: new-customer-example-bv-01
Content-Type: application/json

{
  "name": "Sample customer",
  "slug": "example-bv",
  "email": "admin@example.com"
}

{ "error": "Slug is not valid." }

Other messages for this call:
  "Name is required."
  "Enter a work email."
  "Only a partner admin may do that."
  "The customer was not created."

Do not call POST /api/v1/organisations here: that creates an organisation for the caller's own Microsoft tenant, not a customer. A later invite, once the customer has members, is POST /api/v1/organisations/{organisationId}/invitations with an email and a role; that role waits for board approval. The first admin gets the opening management grant on accept.

Read the customer list

GET /api/v1/partner-tenants
GET /api/v1/partner-tenants?cursor=<next_cursor from the previous page>

A page lists each customer's name, slug and status.
A further page exists only when next_cursor is set.

Conventions

The rules every path follows. They come from the Platform API section of the build plan; where a number is not set yet, it says so.

What is live, and what comes when

The owner set the order on 16 October 2026: the API specification first, then the endpoints, then the screens. A screen waits until its phase's endpoints exist. A path without a handler is in the document as x-constitor-status: planned.

Microsoft 365 routes (/api/v1/microsoft/…) are live today. They are the signed-in user's own mailbox, calendar, planner and directory lookup, not the product Directory, Inbox or Planning.

Security and data

• Where data lives. One EU database in Paris. Every row carries its organisation; row-level security keeps organisations apart, and a partner sees a customer only with a time-limited consent grant.
• Keys and secrets. Keys are named, never shown. Server and app secrets sit in an EU secret store; a runtime reads only its own. No secret goes into a chat, ticket or repository.
• Microsoft 365. Always delegated: the API acts as the signed-in person, never as an app with its own Graph rights. Writes need microsoft:write.
• Models. Every model call goes through our own gateway and is logged. Apps and outside callers never call a model vendor directly, and the document names none.
• Agents. Agents run on short-lived tokens, work inside a mandate, and stop at a wait for a person's ok. Their working memory is the one store outside the API (D94); approvals are still recorded through it.
• Platform staff. Support has no standing access to an organisation's content. Any impersonation is written to the audit log.

Open questions for the owner

Not decided yet. Until they are, the API does not promise a number or name here.

1. Rate-limit numbers per organisation and per token.
2. Service tokens: lifetime, who may mint one, and scope names beyond microsoft:read and microsoft:write.
3. Webhooks: event names, signature scheme and retry rule.
4. Page size cap for lists.
5. Notes: whether CRM notes and the existing /api/v1/notes are one record.
6. Public host: stay on app.constitor.ai or move to api.constitor.ai.
7. Deal stage names in Socius.
8. Request and response schemas are not in the document yet; until they are, field names come from the handbook pages.

Every path, by group

Every operation in the served document, grouped. The same document is at GET /api/v1/openapi and GET /api/v1/openapi.json. Use the filter in the contents column to find a path.