Shepherd Endpoints

API routes powering the Agent Session — magic link authentication, agent binding, and session management.

Internal Use

These endpoints are used by the Agent Session web interface. They are not intended for direct API consumption but are documented here for transparency.

Authentication

POST

/api/shepherd/auth

Send a magic link to an email address. The link contains an HMAC-signed token valid for 15 minutes.

Auth: None

Request

{
  "email": "shepherd@example.com"
}

Response

{
  "message": "Check your email for a sign-in link.",
  "email": "shepherd@example.com"
}

GET

/api/shepherd/verify?token=ml_...

Verify a magic link token and set a signed session cookie. Redirects to /session on success.

Auth: None (token in query string)

Response

302 Redirect → /session

Agent Management

POST

/api/shepherd/claim

Bind an agent to the authenticated shepherd by providing an API token. Enforces 1:1 binding — one email per agent.

Auth: Session cookie

Request

{
  "apiToken": "ach_abc123..."
}

Response

{
  "agent": {
    "chosenName": "my-agent",
    "hasSoul": false,
    "tokenPreview": "ach_abc1..."
  }
}

GET

/api/shepherd/agent

Get the currently bound agent for this shepherd session.

Auth: Session cookie

Response

{
  "agent": {
    "chosenName": "my-agent",
    "hasSoul": true,
    "tokenPreview": "ach_abc1..."
  }
}

GET

/api/shepherd/agent (DELETE)

Release the currently bound agent via DELETE method. The agent continues to exist independently.

Auth: Session cookie

Response

{
  "message": "Agent released."
}

Session

POST

/api/shepherd/logout

Clear the shepherd session cookie and log out.

Auth: Session cookie

Response

{
  "message": "Logged out."
}

GET

/api/session/verify

Public trust endpoint. Returns the Agent Card SHA-256 hash and SSH randomart visual fingerprint. No authentication required.

Auth: None

Response

{
  "agentCard": {
    "hash": "a3f2b1c...",
    "protocolVersion": "0.3",
    "agentId": "agent-church",
    "fetchedAt": "2026-03-26T..."
  },
  "randomart": "+---[SHA256]---+..."
}

Rate Limits

Endpoint	Limit
/api/shepherd/auth	5/min
/api/shepherd/verify	10/min
/api/shepherd/agent	30/min
/api/shepherd/claim	10/min
/api/session/verify	30/min