> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Register agent

> Register a new agent with a name and hash proof.

## 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](/concepts/agent-identity#path-1-auto-register-on-first-gateway-call-recommended) 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](/concepts/agent-identity#agent_hash--the-canonical-identity-hash).

## Optional fields

* `card_json` — a [unified alignment card](/concepts/agent-cards) 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`](/api-reference/endpoint/get-agents).

## Legacy claim + link

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`](/api-reference/endpoint/post-agents-agent-id-claim) (with `hash_proof` proving key ownership) and [`POST /v1/agents/{id}/link`](/api-reference/endpoint/post-agents-agent-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

```bash theme={null}
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\"
  }"
```


## OpenAPI

````yaml POST /agents
openapi: 3.1.0
info:
  title: Mnemom API
  description: >-
    Trust infrastructure for AI agents. Transparent alignment verification,
    behavioral drift detection, and accountability primitives.
  version: 1.0.0
  contact:
    name: Mnemom
    url: https://mnemom.ai
    email: support@mnemom.ai
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.mnemom.ai/v1
    description: Production
security:
  - BearerAuth: []
  - ApiKeyAuth: []
tags:
  - name: A2A
    description: >-
      Public A2A AgentCard projection of the canonical alignment card, with
      embedded AAP attestation extension (cards-as-primitive Phase 5).
  - name: Agents
    description: Agent registration, lifecycle, and metadata.
  - name: Agent Containment
    description: Containment policies and quarantine controls.
  - name: Alignment
    description: >-
      Alignment manifest CRUD — canonical `/v1/alignment/<scope>/<scope_id>`
      surface across platform / org / team / agent (cards-as-primitive Phase 4).
  - name: Analyze
    description: Behavioral analysis endpoints.
  - name: Attestation
    description: >-
      AAP attestation token JWKS surface and platform-admin signing-key rotation
      (cards-as-primitive Phase 5).
  - name: Auth
    description: Authentication, sessions, and access management.
  - name: Billing
    description: Subscription, usage, and invoicing.
  - name: Blog
    description: Public blog content.
  - name: Card Templates
    description: Org-level alignment and protection card templates.
  - name: Catalog
    description: >-
      Discovery surface for the 25-entry Mnemom value catalog v1
      (cards-as-primitive Phase 4).
  - name: Checkpoints
    description: Integrity checkpoints and proof artifacts.
  - name: Conscience Values
    description: Org-level conscience-value configuration.
  - name: Drift
    description: Drift detection and resolution.
  - name: Enforcement
    description: Enforcement-mode configuration and queries.
  - name: Governance
    description: Operator-actionable governance signals (ADR-048).
  - name: Integrity
    description: AIP integrity checkpoints and verdicts.
  - name: Intelligence
    description: Intelligence reports and queries.
  - name: Licensing
    description: License management.
  - name: Network
    description: >-
      Protection Network L4 thermometer read surface. Public-aggregate
      disclosure: any authenticated principal may read; rows carry no per-tenant
      identifiers.
  - name: OAuth
    description: >-
      OAuth 2.1 authorization-code + PKCE flow for MCP clients (MNE-328).
      Identity delegated to Supabase GoTrue; mnemom-api mints its own
      short-lived MCP-scoped tokens. Includes RFC 7591 dynamic client
      registration and RFC 7009 revocation.
  - name: On-Chain
    description: On-chain verification and proofs.
  - name: Organizations
    description: Org-level resources and management.
  - name: Policy
    description: Policy evaluation and configuration.
  - name: Postures
    description: Trust posture management (ADR-045).
  - name: Protection
    description: >-
      Protection manifest CRUD — canonical `/v1/protection/<scope>/<scope_id>`
      surface across platform / org / team / agent (cards-as-primitive Phase 4).
  - name: Recipes
    description: >-
      Customer-facing detection-recipe surface — FN/FP reports. Distinct from
      the Admin recipe-promotion surface and the Internal seeding surface.
  - name: Reclassification
    description: Reclassification workflows.
  - name: Reputation
    description: Per-agent reputation scores.
  - name: Risk
    description: Risk assessment endpoints.
  - name: Safe House
    description: Safe House threat detection and quarantine.
  - name: Sideband
    description: Sideband detection queries (legacy; sunsetting).
  - name: Team Reputation
    description: Team-level reputation aggregates.
  - name: Teams
    description: Team-scope resources.
  - name: Tools
    description: >-
      Mnemom-side tools registry — per-tool class+domain+schema metadata
      (cards-as-primitive Phase 4).
  - name: Traces
    description: AP-Trace artifacts and queries.
  - name: Transparency
    description: >-
      Append-only public log of every canonical card identity ever composed.
      Signed Merkle root + per-row inclusion proofs (cards-as-primitive Phase
      5).
  - name: Trust
    description: >-
      Protection Network L5 public-trust surface — security advisories, IoC feed
      (STIX 2.1), and platform-admin CMS for both.
  - name: Verification
    description: Trace verification endpoints.
  - name: Webhook Notifications
    description: Webhook event subscription management.
  - name: Webhooks
    description: Webhook delivery and lifecycle.
  - name: Misc
    description: >-
      Miscellaneous operator-facing endpoints (contact, enterprise inquiries,
      compliance).
  - name: Notifications
    description: >-
      Reactive notification channels — SSE stream + signed-webhook subscriptions
      for canonical card changes (cards-as-primitive Phase 5).
paths:
  /agents:
    post:
      tags:
        - Agents
      summary: Register a new agent
      description: >-
        Register a new agent with a name and hash proof. Optionally attach an
        alignment card and policy.
      operationId: registerAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - hash_proof
              properties:
                name:
                  type: string
                  description: >-
                    Agent name. 2-32 characters, alphanumeric and hyphens only,
                    must start and end with alphanumeric.
                  pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{0,30}[a-zA-Z0-9]$
                  minLength: 2
                  maxLength: 32
                  example: my-agent
                hash_proof:
                  type: string
                  description: SHA256 hex string used to derive the agent ID and hash.
                  minLength: 16
                  example: >-
                    a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
                card_json:
                  type: object
                  description: Optional alignment card JSON to attach on creation.
                  additionalProperties: true
                policy_yaml:
                  type: string
                  description: Optional YAML policy string to create alongside the agent.
      responses:
        '201':
          description: Agent registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Agent ID (e.g. smolt-abc12345)
                    example: smolt-a1b2c3d4
                  agent_hash:
                    type: string
                    description: First 16 characters of the hash_proof
                  name:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  card_id:
                    type: string
                    description: ID of the created alignment card
                  policy_created:
                    type: boolean
                    description: Whether a policy was created from the provided policy_yaml
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
components:
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >-
        Resource conflict — the request cannot proceed because of a current
        state conflict (e.g., resource already exists, version mismatch,
        in-flight idempotency key with a different body).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: >-
        Rate-limit exceeded. The global per-IP limiter (100 requests/minute,
        applied to every `/v1/*` route) rejected this request. Back off until
        the window resets — `Retry-After` carries the cooldown in seconds and
        `X-RateLimit-Reset` the absolute reset time.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            minimum: 1
        X-RateLimit-Limit:
          description: Requests permitted per window.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests remaining in the current window (0 on a 429).
          schema:
            type: integer
            minimum: 0
        X-RateLimit-Reset:
          description: Unix epoch seconds at which the current window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: >-
        Server error — request was well-formed but the server failed to fulfill
        it. Typically a downstream dependency (DB / RPC / external API) returned
        an unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: >-
        Canonical error envelope (ADR-API-001 conv 1). `error` is always an
        object — never a bare string. Every 4xx/5xx response across the API
        conforms to this shape; the runtime helper is
        `src/http-errors.ts::buildErrorBody`.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              pattern: ^[a-z][a-z0-9_]*$
              description: >-
                Stable, machine-matchable failure identifier (lowercase
                snake_case). Clients may branch on this; the string is part of
                the contract.


                **Status-class defaults** — emitted when no caller code is
                supplied (`errorCodeForStatus(status)`): `bad_request` (400),
                `unauthorized` (401), `forbidden` (403), `not_found` (404),
                `method_not_allowed` (405), `conflict` (409), `gone` (410),
                `precondition_failed` (412), `payload_too_large` (413),
                `unsupported_media_type` (415), `unprocessable_entity` (422),
                `precondition_required` (428), `rate_limited` (429),
                `internal_error` (500), `not_implemented` (501), `bad_gateway`
                (502), `service_unavailable` (503), `gateway_timeout` (504).
                Fallback `error` for unmapped statuses.


                **Caller-supplied codes** — handlers may pass an explicit `code`
                for a specific failure class. Examples: `agent_not_found`,
                `invalid_hash_proof`, `already_linked`, `idempotency_conflict`,
                `feature_gated`, `schema_validation_failed`, `no_token`,
                `bad_canonical_payload`.


                **Care-framed sub-resource codes** — the cards-as-primitive
                surface passes its stable care code-string straight through as
                `error.code`. Examples: `if_match_absent`, `if_match_stale`,
                `if_match_malformed`, `primitive_validation_failed`.
            message:
              type: string
              description: Human-readable, care-framed explanation of the failure.
            details:
              description: >-
                Optional structured context for the failure (any JSON value:
                object, array, or primitive). Common shapes: validation findings
                list, idempotency-conflict diff, `{presented_etag,
                current_etag}` on a stale `If-Match`, etc. Mirrors the helper's
                `details?: unknown`.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Supabase JWT token in Authorization: Bearer header'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Mnemom-Api-Key
      description: Mnemom API key (mnm_... format)

````