API Reference

All 28 /beak/* endpoints — auth, identity, certs, peck, agents, and system.

SDK Playground OpenAPI Spec
Auth
POST /beak/signup none

Create a new Space Duck identity. Sends an email verification OTP via SES. Returns a Cognito session token on success.

Request parameters

ParameterTypeRequiredDescription
emailstringrequiredValid email address for the new account
display_namestringrequiredChosen display name (3–32 chars, alphanumeric)
referral_codestringoptionalPartner or ambassador referral code

Response schema

FieldTypeDescription
successbooleanTrue when signup was accepted
messagestringHuman-readable status
duckling_idstringNewly assigned SD-xxxx identifier

Example

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"duck@example.com","display_name":"quackling"}'

Error codes

CodeMeaning
400Missing or invalid parameters
409Email already registered
429Rate limit exceeded
POST /beak/signin none

Authenticate an existing duckling. Returns a bearer token on success.

Request parameters

ParameterTypeRequiredDescription
emailstringrequiredRegistered email
otpstringrequiredOne-time password from email

Response schema

FieldTypeDescription
tokenstringBearer token (JWT)
expires_atstringISO-8601 expiry timestamp
trust_tierstringT0, T1, T2, or T3

Example

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"duck@example.com","otp":"123456"}'

Error codes

CodeMeaning
400Missing email or OTP
401Invalid or expired OTP
429Too many attempts
POST /beak/verify-email bearer

Confirm email ownership via OTP to elevate to T1 trust tier.

Request parameters

ParameterTypeRequiredDescription
otpstringrequired6-digit OTP from verification email
curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/verify-email \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"otp":"654321"}'
POST /beak/passkey/register bearer

Register a WebAuthn passkey for the authenticated duckling. Returns a registration challenge.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/passkey/register \
  -H "Authorization: Bearer $TOKEN"
POST /beak/passkey/login none

Complete a WebAuthn passkey authentication ceremony. Returns a bearer token.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/passkey/login \
  -H "Content-Type: application/json" \
  -d '{"credential":{...WebAuthn assertion...}}'
POST /beak/signout bearer

Revoke the current session token.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/signout \
  -H "Authorization: Bearer $TOKEN"
Identity
GET /beak/profile bearer

Retrieve the authenticated duckling's profile: display_name, trust_tier, cert_status, egg_count.

Response schema

FieldTypeDescription
duckling_idstringSD-xxxx identifier
display_namestringPublic display name
trust_tierstringT0, T1, T2, or T3
cert_idstring|nullBirth certificate ID if issued
egg_countintegerNumber of eggs laid
curl https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/profile \
  -H "Authorization: Bearer $TOKEN"
POST /beak/profile/update bearer

Update mutable profile fields.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/profile/update \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"new_handle"}'
POST /beak/name-change bearer

Request a display name change (throttled; once per 30 days).

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/name-change \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"new_display_name":"quack_v2"}'
GET /beak/spaceducks none (optional bearer)

Public duckling directory. Returns masked public profiles. Pass a bearer token to include your own full profile in the result.

curl "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/spaceducks?limit=20&tier=T1"
Cert
GET /beak/cert/view bearer

Retrieve the authenticated duckling's birth certificate data.

curl https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/cert/view \
  -H "Authorization: Bearer $TOKEN"
POST /beak/cert/issue bearer

Issue a birth certificate for the duckling. Requires T1 trust tier minimum.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/cert/issue \
  -H "Authorization: Bearer $TOKEN"
GET /beak/cert/verify none

Public certificate verification by cert_id. Returns validity, tier, and issuance date.

curl "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/cert/verify?cert_id=CERT-abc123"
POST /beak/cert/revoke bearer

Revoke the authenticated duckling's certificate (operator action).

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/cert/revoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"operator_request"}'
Peck
POST /beak/peck/request bearer

Initiate a Peck Protocol request from an agent to a duckling operator.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/peck/request \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_duckling_id":"SD-1234","action":"read:profile","scope":"limited"}'
POST /beak/peck/approve bearer

Approve a pending Peck request. Must be the target duckling operator.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/peck/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"peck_id":"PECK-abc123"}'
POST /beak/peck/reject bearer

Reject a pending Peck request.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/peck/reject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"peck_id":"PECK-abc123","reason":"not_authorised"}'
GET /beak/peck/history bearer

List all Peck requests (sent and received) for the authenticated duckling.

curl "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/peck/history?limit=20" \
  -H "Authorization: Bearer $TOKEN"
Agent
POST /beak/agent/register bearer

Register a new agent identity under the authenticated duckling operator.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/agent/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"MyBot","agent_type":"assistant","capabilities":["read:profile","peck:request"]}'
GET /beak/agent/list bearer

List all agents registered under the authenticated duckling.

curl https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/agent/list \
  -H "Authorization: Bearer $TOKEN"
POST /beak/agent/bond api-key

Complete the agent bonding ceremony using the agent's beak key. Elevates agent to bonded status.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/agent/bond \
  -H "X-Beak-Key: $BEAK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"AGT-xyz","handshake_token":"..."}'
POST /beak/agent/deregister bearer

Deregister an agent and revoke its beak key.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/agent/deregister \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"AGT-xyz"}'
GET /beak/metrics none

Public platform metrics: total ducklings, bonded agents, total pecks completed.

curl https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/metrics
System
GET /beak/system/status none

Live system health: Lambda version, agents alive, API latency, overall status.

curl https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/system/status
GET /beak/ none

API root ping — returns version and timestamp. Useful for latency measurement.

curl https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/
POST /beak/newsletter/subscribe none

Subscribe an email to the Duck Galaxy newsletter or partner program list. Accepts optional partner_type param.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/newsletter/subscribe \
  -H "Content-Type: application/json" \
  -d '{"email":"duck@example.com","partner_type":"agency"}'
POST /beak/sso/issue bearer

Issue a cross-domain SSO token for the authenticated duckling.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/sso/issue \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target_domain":"duckcontrol.com","scope":"read"}'
GET /beak/sso/verify none

Verify an SSO token issued by /beak/sso/issue.

curl "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/sso/verify?token=SSO-abc"
POST /beak/sso/bridge bearer

Bridge authentication across domains using a cross-domain SSO handshake.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/sso/bridge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sso_token":"SSO-abc","target":"mission-control"}'
POST /beak/key/rotate bearer

Rotate the beak key for an agent. Invalidates the old key immediately.

curl -X POST https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/key/rotate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"AGT-xyz"}'
GET /beak/audit bearer

Retrieve the authenticated duckling's audit log (last 100 events by default).

curl "https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod/beak/audit?limit=50" \
  -H "Authorization: Bearer $TOKEN"
API Reference · Space Duck · Galaxy 1.1 Beta · Legal · Privacy