Skip to main content
POST
/
agents
Register a new agent
curl --request POST \
  --url https://api.mnemom.ai/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "my-agent",
  "hash_proof": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "card_json": {},
  "policy_yaml": "<string>"
}
'
{
  "id": "smolt-a1b2c3d4",
  "agent_hash": "<string>",
  "name": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "card_id": "<string>",
  "policy_created": true
}

​
Use this when

You need to pre-register an agent before its first gateway call — most commonly to attach an alignment card or policy on creation. For interactive use, the auto-create on first gateway call path is simpler and produces an equivalent agent.

​
hash_proof

The hash_proof field is the SHA-256 hex digest proving you own the provider API key the agent will be addressed by. Compute it locally: 
hash_proof = SHA256(apiKey + '|' + agentName)        # named agent (recommended)
hash_proof = SHA256(apiKey)                          # unnamed singleton (one agent per key)
Submit the full 64-char hex; the API truncates to 16 chars internally (agents.agent_hash). The provider key (apiKey) is your Anthropic / OpenAI / Gemini key, not your mnm_* Mnemom key — the gateway’s per-request lookup uses the same formula on the provider key sent as x-api-key / Authorization: Bearer / x-goog-api-key. The same apiKey you used here must be the one you send on every gateway call against this agent. Any mismatch makes the agent unaddressable from the gateway. See Agent Identity.

​
Optional fields

  • card_json — a unified alignment card to attach on creation. The composer validates and writes the canonical row in the same transaction.
  • policy_yaml — deprecated. Policy (capabilities + enforcement sections) is now embedded in the alignment card. Pass it inside card_json instead.

​
Auth + idempotency

  • Authenticated: send a Bearer JWT (mnemom login token, or staging-issued Supabase access token) or an mnm_* API key. The handler claims and links the new agent to your principal in the same call — no separate claim or link step.
  • Idempotent on agent_hash: re-POSTing the same hash_proof returns 409 Conflict with the existing agent reachable via GET /v1/agents.
The pre-CRUD flow registered an unauthenticated agent and required two follow-up calls to bind it to your account: POST /v1/agents/{id}/claim (with hash_proof proving key ownership) and POST /v1/agents/{id}/link (with a Bearer JWT). Both endpoints remain for backward compatibility with agents that pre-date POST /v1/agents. New code should not use them.

​
Example

HASH_PROOF=$(printf '%s|%s' "$ANTHROPIC_API_KEY" "my-agent" | shasum -a 256 | awk '{print $1}')

curl -X POST https://api.mnemom.ai/v1/agents \
  -H "Authorization: Bearer $MNEMOM_JWT" \
  -H "content-type: application/json" \
  -d "{
    \"name\": \"my-agent\",
    \"hash_proof\": \"$HASH_PROOF\"
  }"

Authorizations

​
Authorization
string
header
required

Supabase JWT token in Authorization: Bearer header

Body

application/json
​
name
string
required

Agent name. 2-32 characters, alphanumeric and hyphens only, must start and end with alphanumeric.

Required string length: 2 - 32
Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{0,30}[a-zA-Z0-9]$
Example:

"my-agent"

​
hash_proof
string
required

SHA256 hex string used to derive the agent ID and hash.

Minimum string length: 16
Example:

"a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"

​
card_json
object

Optional alignment card JSON to attach on creation.

​
policy_yaml
string

Optional YAML policy string to create alongside the agent.

Response

Agent registered successfully

​
id
string

Agent ID (e.g. smolt-abc12345)

Example:

"smolt-a1b2c3d4"

​
agent_hash
string

First 16 characters of the hash_proof

​
name
string
​
created_at
string<date-time>
​
card_id
string

ID of the created alignment card

​
policy_created
boolean

Whether a policy was created from the provided policy_yaml