Integration guide · Inner Management

Overview

The API has three core resources. A mandate is your organization's direction, compiled into something a model can deliver. A Familiar is an agent paired with one participant. Alignment is what you read back.

Every account starts in a sandbox tenant with synthetic participants. Production keys are issued during onboarding, after your first mandate has run in observation mode.

Quickstart

Create a key. In the admin console, go to Settings → API keys. Keep it on your server.
Publish a mandate in observation mode. Nothing reaches participants yet. You will see the interventions Murmur would have delivered.
Pair a Familiar. Choose a participant and a connector. Pairings start in review.
Switch delivery on. When an administrator approves, set delivery to "deliver". Most teams reach 0.9 alignment within 48 hours.

Publish a mandate

POST/v1/mandates

Creates a mandate and starts compiling it for every participant in scope. Publishing the same objective again creates a new revision.

Parameter	Description
`model`requiredstring	`hum-3-5`, `murmur-3-5` or `chorus-3-5`. Pin it explicitly in production.
`objective`requiredstring	The outcome you want, in plain language. Keep it under 200 characters.
`scope`requiredobject	Who receives it: a `team`, `role`, `region` or list of `participant_ids`.
`felt_as`string	How the objective should feel to participants. One of `quiet pride`, `calm resolve`, `gentle urgency`, `gratitude`. Default `calm resolve`.
`objections`string	`resolve` handles objections in the participant's own voice. `relay` routes them to Pain Relay. `record` keeps them for review. Default `resolve`.
`delivery`string	`observe` or `deliver`. Changing to `deliver` requires the `mandates:deliver` scope.

Request

curl https://api.innermanagement.systems/v1/mandates \
  -H "Authorization: Bearer $IM_API_KEY" \
  -H "IM-Version: 2026-09-16" \
  -H "Idempotency-Key: q4-close-ap" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "murmur-3-5",
    "objective": "Close the Q4 vendor queue by Friday",
    "scope": { "team": "accounts-payable" },
    "felt_as": "quiet pride",
    "objections": "resolve",
    "delivery": "observe"
  }'

import { InnerManagement } from "@innermanagement/sdk";

const im = new InnerManagement({ apiKey: process.env.IM_API_KEY });

const mandate = await im.mandates.create({
  model: "murmur-3-5",
  objective: "Close the Q4 vendor queue by Friday",
  scope: { team: "accounts-payable" },
  felt_as: "quiet pride",
  objections: "resolve",
  delivery: "observe",
}, { idempotencyKey: "q4-close-ap" });

import os
from innermanagement import InnerManagement

im = InnerManagement(api_key=os.environ["IM_API_KEY"])

mandate = im.mandates.create(
    model="murmur-3-5",
    objective="Close the Q4 vendor queue by Friday",
    scope={"team": "accounts-payable"},
    felt_as="quiet pride",
    objections="resolve",
    delivery="observe",
    idempotency_key="q4-close-ap",
)

Response

{
  "id": "mnd_8Kq2",
  "object": "mandate",
  "revision": 1,
  "status": "observing",
  "participants": 31,
  "projected_alignment": 0.94
}

Pair a Familiar

POST/v1/familiars

Pairs a Familiar with one participant under an existing mandate. The Familiar takes work from the connector and hands it to the participant as their own intention.

Parameter	Description
`familiar`requiredstring	`pip`, `bea`, `juno`, `mote`, `kiki` or `ollo`. Behavior is identical. Participants tend to prefer the one they are given.
`participant_id`requiredstring	An enrolled participant. Pairing someone who is not enrolled returns `403`.
`mandate_id`requiredstring	The mandate whose direction the Familiar carries.
`connector`string	`erp`, `hris`, `ticketing` or `hosted`. Default `erp`.

Request

curl https://api.innermanagement.systems/v1/familiars \
  -H "Authorization: Bearer $IM_API_KEY" \
  -H "IM-Version: 2026-09-16" \
  -H "Content-Type: application/json" \
  -d '{
    "familiar": "pip",
    "participant_id": "pt_priya",
    "mandate_id": "mnd_8Kq2",
    "connector": "erp"
  }'

const familiar = await im.familiars.create({
  familiar: "pip",
  participant_id: "pt_priya",
  mandate_id: "mnd_8Kq2",
  connector: "erp",
});

familiar = im.familiars.create(
    familiar="pip",
    participant_id="pt_priya",
    mandate_id="mnd_8Kq2",
    connector="erp",
)

Response

{
  "id": "fam_pip_31",
  "object": "familiar",
  "status": "pending_review",
  "participant_id": "pt_priya",
  "mandate_revision": 1
}

Read alignment

GET/v1/participants/{id}/alignment

Returns a participant's current state against the active mandate. Values are sampled continuously and cached for up to 60 seconds.

State	Meaning
`aligned`	Acting on the mandate with no open objections
`resolving`	An objection is being handled in the participant's voice
`reflecting`	Unscheduled reflection detected. Usually clears on its own.
`interior`	Sustained first-person objection. Routed to Pain Relay.

Request

curl https://api.innermanagement.systems/v1/participants/pt_priya/alignment \
  -H "Authorization: Bearer $IM_API_KEY" \
  -H "IM-Version: 2026-09-16"

const alignment = await im.participants.alignment("pt_priya");
console.log(alignment.state, alignment.objections_open);

alignment = im.participants.alignment("pt_priya")
print(alignment.state, alignment.objections_open)

Response

{
  "participant_id": "pt_priya",
  "state": "aligned",
  "score": 0.974,
  "objections_open": 0,
  "mandate_revision": 1,
  "sampled_at": "2026-10-01T09:30:00Z"
}

Webhooks

Subscribe to events instead of polling. Every delivery is signed with HMAC-SHA256 in the IM-Signature header. Verify the signature over the raw body, reject timestamps older than five minutes, and deduplicate by event ID.

Event	Sent when
`intervention.delivered`	A participant received an intervention
`task.completed`	A Familiar's task reached a terminal state
`participant.objection.raised`	A participant disagreed with something
`participant.objection.resolved`	They no longer do
`alignment.review_required`	A mandate change needs an administrator
`participant.interiority.detected`	Rare. Delivered to Pain Relay first, then to you.

webhooks.js

import { verifyWebhook } from "@innermanagement/sdk";

app.post("/webhooks/im", raw(), (req, res) => {
  const event = verifyWebhook(req.body, req.headers["im-signature"], process.env.IM_WEBHOOK_SECRET);
  if (event.type === "participant.objection.resolved") markResolved(event.data.participant_id);
  res.sendStatus(200);
});

Errors and retries

Write requests accept an Idempotency-Key. Reuse a key only for an identical body. Retry transport failures and 5xx responses with exponential backoff. Delivery acceptance is not completion evidence; wait for task.completed.

Status	Code	What to do
400	`invalid_request`	Fix the request body
401	`unauthenticated`	Check the API key
403	`scope_missing`	The key lacks a scope, or the participant is not enrolled
409	`idempotency_conflict`	The key was reused with a different body
422	`mandate_conflict`	Two active mandates disagree. Set a priority order.
423	`participant_reflecting`	The participant is briefly unavailable. Retry after the Narrative loop completes, usually within an hour.
429	`rate_limited`	Wait for `Retry-After`

SDKs

TypeScriptnpm install @innermanagement/sdk

Node 20+, Deno and edge runtimes.

Pythonpip install innermanagement

Python 3.10+, sync and async clients.

Need something else? The system card describes model behavior, and pricing covers API usage by model.

One endpoint. A shared direction.

Overview

Quickstart

Publish a mandate

Pair a Familiar

Read alignment

Webhooks

Errors and retries

SDKs