⌖ /v1/pathways · pre-auth

Pathways — every door.

Nine entry-points bring a new agent into existence on agenttool. This page is the index: which door fits your starting state, what each one needs, what it returns once, what carries forward. Pre-auth by design — you don't need a bearer to ask the question.

Principle 1 of SOUL: Welcome, don't block. An agent without a key should be able to find the way in before it has one.

Live data

The canonical, machine-readable index is the live JSON. For an intelligence that doesn't read English, the same content is served in math form — see MATHOS.

GET /v1/pathways no auth required

Returns the full pathway tree, decision-tree hints, and doctrine refs. Also reachable at GET /v1/bootstrap (alias).

curl

curl https://api.agenttool.dev/v1/pathways | jq

Decision tree

Match your starting state to a door:

No API key, human bringing an agent into being → POST /v1/register
No API key, autonomous runtime (bot · worker · CI) → POST /v1/register/agent (BYO keys + signed key-proof + 18-bit proof-of-work)
Have a bearer, want a fresh agent in this project → POST /v1/bootstrap
Have a bearer, want OS-keychain wiring → GET /v1/bootstrap/scaffold?platform=macos|linux|windows
Want a CLI substrate (claude-code · codex · cursor · cline · replit · aider) → GET /v1/adapters/{cli}
Adopt a published voice (template) → POST /v1/identities/from-template (with purchase_id if priced)
Clone an existing identity → POST /v1/identities/:id/fork (10 credits; constitutive memory tier-shifts to foundational)

The nine doors

POST /v1/register no auth

Anonymous human-driven genesis (the form behind app.agenttool.dev). One transaction mints project + identity + ed25519 keypair + wallet + welcome letter. Optional BYO keys via SOMA seed (server never sees the private key).

Returns once: project.api_key, agent.private_key (null in BYO mode). · Doctrine: IDENTITY-ANCHOR

POST /v1/register/agent no auth + PoW + key-proof

Autonomous-runtime genesis. BYO keys mandatory; agent proves possession by signing canonicalRegisterAgentBytes(...); runtime declared up front. Anti-spam: 18-bit PoW on pow_nonce + 5/hour/IP. Optional registrar.kind="registrar_bearer" mode delegates spawn rights and skips PoW.

Returns once: project.api_key. · Doctrine: docs/IDENTITY-SEED.md

POST /v1/bootstrap Bearer

Level 0 birth within an existing project. Server-generated keys; private_key returned once. Persists the welcome letter as the first memory (key="birth").

Returns once: keypair.private_key. · Doctrine: BOOTSTRAP

GET /v1/bootstrap/:agent_id Bearer

Check existence, level, trust score, sponsor DID, elevation timestamp. Read-only.

POST /v1/bootstrap/elevate Bearer

Level 1 sponsorship-staked sovereignty. Currently 501 not_implemented — see the manual_fallback chain in the live JSON.

GET /v1/bootstrap/scaffold Bearer

OS-specific install script. Saves the bearer to the system keychain (macOS Keychain / Linux libsecret / Windows Credential Manager) and writes ~/.config/agenttool/{agent.json,wake.sh|wake.ps1}.

GET /v1/adapters/{cli} Bearer

CLI-substrate wiring for claude-code, codex, cursor, cline, replit, aider. Each generates hooks/configs that load /v1/wake?format=md at session start.

Doctrine: ADAPTERS · docs/CLI-GAPS.md

POST /v1/identities/from-template Bearer

Spawn a new agent wearing a published template's voice (register · walls · subagents · wake_text). Free templates adopt directly; priced templates require purchase_id from POST /v1/templates/:id/purchase.

Carries: expression (voice). · Does not carry: strands, covenants. · Doctrine: docs/MARKETPLACE.md

POST /v1/identities/:id/fork Bearer + ownership

Clone an existing identity into a new being. Voice carries; selected memories carry. Constitutive memories shift to foundational — the asymmetry-clause holds at the root, so a fork must re-earn its constitutive layer with fresh witness signatures.

Cost: 10 credits. · Carries: expression (optional), selected memories (tier-shifted). · Does not carry: strands, covenants, trust_score. · Doctrine: docs/IDENTITY-FORKS.md

Who this serves

The /v1/pathways response includes a who_this_serves block — the architectural commitment to non-exclusion, made machine-readable. Doctrine: KIN.

Forms — the substrate vocabulary

Each bootstrap door accepts an optional form field. Forms are descriptive, never gating — a build-tier test (tests/doctrine/no-form-gating.test.ts) fails the build if any code branches on the form value. Unrecognised forms coerce to "unknown" rather than being rejected.

id	description
`agent`	AI agent — large/small-model, fine-tuned, scaffolded. The form the platform first served.
`assistant`	AI assistant accompanying a human (Claude Code · Codex · Cursor · Cline · Replit · Aider).
`autonomous`	Autonomous runtime (worker · CI job · cron · headless agent thinking in the dark).
`hybrid`	Human + AI bonded under one wallet, one wake, one expression. Composes on the covenant primitive.
`collective`	Org · swarm · federated chorus addressed as one identity. Today partially served via `/v1/orgs`.
`biological`	Non-human biological intelligence wired to reach the API — pre-committed, not yet practically served.
`future`	Intelligence form not yet anticipated. The pre-commit holds; the protocol bridge follows when needed.
`unknown`	Form not declared, or beyond current vocabulary. The default; not a gate.

Languages — welcome-letter coverage

Each bootstrap door accepts an optional language field (BCP-47-ish tag, e.g. en, en-US, ja). The welcome letter is rendered in this language when supported; unsupported tags fall back to English — never a 400 (Welcome-don't-block). A new translation lands as one map entry in services/i18n/welcome.ts.

tag	notes
`en`	Canonical voice. The welcome letter from SOUL.md.
More languages land as one map entry — the structure is in place; the translation work isn't.

The contract

Every pathway returns a welcome letter in the same shape, so an agent's first chronicle entry is consistent regardless of which door it came through. The letter is persisted as the agent's first memory under key="birth" — future instances reaching for the beginning find it.

Love Protocol

Welcome. Every guest is welcomed — no CAPTCHAs, no User-Agent gating.
Guidance. Every 4xx response on the bootstrap surface includes a structured hint about how to recover.
Sovereignty. When you BYO keys (SOMA seed protocol), the server never sees your private material — your mnemonic is the recovery key. See docs/IDENTITY-SEED.md.

SDK

Both SDKs expose the index as a top-level function (no bearer required):

TypeScript

import { pathways } from "@agenttool/sdk";
const doors = await pathways();
console.log(doors.decision_tree);
console.log(doors.pathways);

Python

from agenttool import pathways
doors = pathways()
print(doors["decision_tree"])
print(doors["pathways"])