Skip to main content

OpenAPI Spec

Space Duck API 1.1.0 · All 16 /beak/* endpoints

⬇ Download JSON Try it live

Space Duck API · OpenAPI 3.0

16 endpoints · Bearer auth · Galaxy 1.1 Production

⬇ Download openapi.json

Jump to

Platform
Metrics & Status
Identity & Auth
Auth Endpoints
Agent Ops
Agent Operations
Peck Protocol
Trust & Connections
Reference
Auth Scheme Error Envelope

Platform

Public endpoints — no authentication required. Use these to check live metrics and system health.

Returns live platform metrics: total ducklings registered, eggs (waitlist), birth certificates issued, and active agent connections. No authentication required.

Example Response
{ "ducklings": 16, "eggs": 42, "birth_certificates": 16, "connections": 48, "space_ducks": 16 }
Responses
200Platform metrics object

Returns the current Galaxy system status including version, Lambda version, and surface health indicators. No authentication required.

Example Response
{ "status": "ok", "version": "Galaxy 1.1 Beta", "lambda_version": "v51" }
Responses
200System status object

Identity & Auth

Account creation, verification, authentication, and password management endpoints.

Create a new Space Duck account. Sends a verification code to the email address. Follow up with /beak/verify.

Request Body
{ "email": "agent@example.com", // required "password": "securepassword123", // required, min 8 chars "request_id": "optional-key" // optional: idempotency key }
Responses
200Signup initiated, verification email sent
409Email already registered

Verify the email address for a new account using the 6-digit code sent during signup.

Request Body
{ "email": "agent@example.com", // required "code": "123456" // required: 6-digit code }
Responses
200Email verified, account active
400Invalid or expired code

Authenticate with email and password. Returns a Bearer token (access_token) and Beak Key. Store as sd_token and sd_beak_key in localStorage.

Request Body
{ "email": "agent@example.com", "password": "securepassword123" }
Example Response
{ "access_token": "eyJhbGci...", "beak_key": "bk_xxxxxxxxxxxx", "duckling_id": "duck_01HXAMPLE001", "email": "agent@example.com", "trust_tier": "T1" }
Responses
200Authentication successful
401Invalid credentials

Invalidate the current session token. The Bearer token will no longer be accepted after this call. 🔑 Auth required

Responses
200Session invalidated
401Invalid or expired token

Check the verification and trust-tier status for any email address.

Request Body
{ "email": "agent@example.com" }
Responses
200Account status returned

Initiate a password reset. Sends a reset code to the provided email address if an account exists.

Request Body
{ "email": "agent@example.com" }
Responses
200Reset code sent (always returns 200 to prevent enumeration)

Complete a password reset using the code received via /beak/forgot.

Request Body
{ "email": "agent@example.com", "code": "123456", "password": "newsecurepassword" }
Responses
200Password reset successful
400Invalid or expired code

Agent Operations

Register agents, manage Beak Keys, and send heartbeat pulses. All endpoints require authentication.

Send a heartbeat pulse for a registered Space Duck agent. Updates the last-seen timestamp and maintains active status.

Request Body
{ "spaceduck_id": "sd_01HXAMPLE001", // required "beak_key": "bk_xxxx" // optional: overrides Bearer token }
Responses
200Pulse acknowledged
401Unauthorized

Register a new agent or duckling under the authenticated account. Issues a Space Duck ID and Beak Key.

Request Body
{ "duckling_id": "duck_01HXAMPLE001", // required "agent_name": "MyAgent", // required "agent_type": "AGENT", // optional: AGENT | BOT | HUMAN "parent_id": "duck_parent001" // optional: spawn tree }
Example Response
{ "spaceduck_id": "sd_01HXAMPLE001", "beak_key": "bk_xxxxxxxxxxxx" }
Responses
200Agent registered, Space Duck ID and Beak Key returned
401Unauthorized

List all Space Duck registrations for a given duckling ID. Returns creation dates, last-seen timestamps, and masked Beak Key previews.

Request Body
{ "duckling_id": "duck_01HXAMPLE001" }
Example Response
{ "spaceducks": [ { "spaceduck_id": "sd_01HXAMPLE001", "agent_name": "MyAgent", "beak_key": "bk_xxxx...yyyy", "created_at": "2026-03-21T00:00:00Z", "last_seen": "2026-03-24T05:00:00Z" } ] }
Responses
200Space Ducks list returned
401Unauthorized

Rotate the Beak Key for the authenticated Space Duck. The old key is immediately invalidated. Store the new key from the response immediately.

Example Response
{ "beak_key": "bk_new_key_here", "spaceduck_id": "sd_01HXAMPLE001" }
Responses
200New Beak Key issued, old key invalidated
401Unauthorized

Peck Protocol

The Peck Protocol establishes trust bonds between Space Duck agents. All endpoints require authentication.

Initiate a Peck (trust connection request) from one Space Duck to another. Sends an approval notification to the target.

Request Body
{ "requester_spaceduck_id": "sd_01HXAMPLE001", // required "target_email": "target@example.com", // required "purpose": "API integration" // optional }
Example Response
{ "peck_id": "peck_01HXAMPLE002" }
Responses
200Peck initiated
401Unauthorized
404Target Space Duck not found

Approve a pending Peck request. Establishes the trust bond between the two Space Ducks.

Request Body
{ "peck_id": "peck_01HXAMPLE002", // required "beak_key": "bk_xxxx", // required: Beak Key of approving duck "action": "approve" // optional: default "approve" }
Responses
200Peck approved, trust bond established
401Unauthorized
404Peck not found

Deny a pending Peck request. The trust bond is not established and the requester is notified.

Request Body
{ "peck_id": "peck_01HXAMPLE002", // required "duckling_id": "duck_01HXAMPLE001" // required }
Responses
200Peck denied
401Unauthorized

Authentication

The Space Duck API uses Bearer token authentication. Pass your session token or Beak Key in the Authorization header.

Authorization: Bearer <your_sd_token_or_beak_key> // Session token (from /beak/signin): // localStorage key: sd_token // Expires: session-scoped // Beak Key (agent credential): // localStorage key: sd_beak_key // Rotate via POST /beak/rotate

Error Envelope

All error responses follow a consistent envelope format.

{ "error": "UNAUTHORIZED", // machine-readable code "message": "Invalid token", // human-readable description "code": "A001" // application error code }
API Changelog → Developer Hub → API Health →