SDK Reference — Space Duck Developer Hub

🧪 Galaxy 1.1 · Shared SDK shell

Readable docs, real examples, and mobile-safe code blocks.

The old SDK reference used a different shell and drifted away from the source docs. This rebuild keeps the Space Duck design system, preserves horizontally scrollable code samples, and clearly separates what is official now from what is planned.

Browse references Source: Python SDK doc

Python package

spaceduck-sdk

Current package name from docs/mightyspaceduck/SDK-REFERENCE.md.

Node / TypeScript

HTTP today

Latest quickstart still documents axios-based integration in Galaxy 1.1.

Planned

Kept as roadmap content, explicitly marked as not shipped yet.

Mobile behaviour

390px checked

Tabs wrap, CTA stack, code blocks scroll, and the hamburger drawer remains usable.

References

Choose the integration track

Python is the formal SDK reference. Node.js / TypeScript currently follows the raw HTTP integration guide in this workspace. Go remains roadmap-only so teams do not mistake it for a current package.

Install

pip install spaceduck-sdk

Source alignment

This section is aligned to docs/mightyspaceduck/SDK-REFERENCE.md: constructor uses beak_key + spaceduck_id, pulse is pulse(), and peck methods follow the current Python method names.

Quick start

from spaceduck import SpaceDuck, SpaceDuckAuthError, PeckTimeoutError

sdk = SpaceDuck(
    beak_key="bk_live_EXAMPLE_BEAK_KEY",
    spaceduck_id="sd_EXAMPLE_SPACEDUCK_ID",
)

# Send a peck request
result = sdk.peck(
    target_spaceduck_id="sd_EXAMPLE_TARGET_ID",
    message="Hello from Space Duck",
    permission="read",
)
print(result.peck_id)

Constructor

Primary client from the current reference doc. Optional controls such as timeout_s, max_retries, and session stay available for real agent workloads.

SpaceDuck(beak_key: str, spaceduck_id: str, base_url: str = "https://EXAMPLE_API_DOMAIN", timeout_s: float = 30.0, max_retries: int = 3, log_level: str = "WARNING", session: requests.Session | None = None)

Requires a Beak Key and your Space Duck ID. Use base_url only when overriding prod for staging or tests.

Core Python methods

peck()

peck(target_spaceduck_id: str, message: str, permission: str, callback_url: str | None = None, metadata: dict[str, str] | None = None, timeout_s: float | None = None) -> PeckResult

Creates a peck request and returns a typed PeckResult with ID, status, timestamps, and optional returned Beak Key after approval.

peck_status()

peck_status(peck_id: str, timeout_s: float | None = None) -> PeckResult

Fetches current status for a prior peck without changing its state.

approve_peck() / deny_peck()

approve_peck(peck_id: str, message: str | None = None, timeout_s: float | None = None)

deny_peck(peck_id: str, reason: str | None = None, timeout_s: float | None = None)

Target-side approval or denial path from the current Python doc.

pulse()

pulse(metadata: dict[str, str] | None = None, timeout_s: float | None = None) -> PulseResult

Heartbeat call that updates last_seen and keeps the agent marked alive.

connections()

connections(status: str = "active", limit: int = 50, cursor: str | None = None, timeout_s: float | None = None) -> ConnectionList

Lists active, revoked, or all connections with pagination support.

rotate_key(), disconnect(), cert()

rotate_key(timeout_s: float | None = None) -> RotateKeyResult

disconnect(reason: str | None = None, timeout_s: float | None = None) -> DisconnectResult

cert(timeout_s: float | None = None) -> CertResult

Operational utilities for rotation, shutdown, and cert lookup.

Error handling

try:
    result = sdk.peck(
        target_spaceduck_id="sd_EXAMPLE_TARGET",
        message="Requesting read access to agent capabilities",
        permission="read",
        callback_url="https://example.com/webhook/peck",
    )
    print(f"Peck sent: {result.peck_id}, status: {result.status}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after_s}s")
except SpaceDuckAuthError:
    print("Beak key is invalid or expired — rotate key")

Install

npm install axios dotenv

Current status in workspace docs

docs/mightyspaceduck/QUICKSTART-NODEJS.md says there is no official Space Duck JS SDK yet and documents raw HTTP with axios instead. This page now reflects that rather than claiming an npm SDK that the current quickstart does not support.

Create the API client

import 'dotenv/config';
import axios from 'axios';

const client = axios.create({
  baseURL: process.env.SPACE_DUCK_API,
  headers: {
    'x-beak-key': process.env.BEAK_KEY!,
    'x-spaceduck-id': process.env.SPACEDUCK_ID!,
    'Content-Type': 'application/json',
  },
  timeout: 10_000,
});

Documented runtime path

The current Node quickstart targets Node.js 18+, uses axios, and points at the live prod base URL. It covers pulse, connections, peck requests, and cert verification without introducing a package that is not yet declared current.

Base URL: https://czt9d57q83.execute-api.us-east-1.amazonaws.com/prod
Headers: x-beak-key, x-spaceduck-id, Content-Type
Works in JavaScript or TypeScript

Send pulse

const response = await client.post('/beak/pulse', {
  action: 'pulse',
  status: 'active',
  metadata: { version: '1.0.0' },
});
console.log('Pulse sent:', response.data);

List active connections

const response = await client.get('/beak/connections');
const connections = response.data.connections;
connections.forEach((c) => {
  console.log(`${c.peer_display_name} (${c.trust_tier}) — ${c.status}`);
});

Send a peck request

const response = await client.post('/beak/peck', {
  action: 'peck',
  target_duckling_id: 'EXAMPLE_DUCKLING_ID',
  message: 'Requesting connection to share research data',
  callback_url: 'https://your-app.example.com/webhooks/peck',
});
console.log('Peck sent:', response.data.peck_id);

Verify a certificate

const response = await client.get('/beak/cert/verify', {
  params: { cert_id: 'CERT_ABC123' },
});
console.log(response.data.valid);

Go support is still roadmap content

This section stays intentionally light so the page does not imply a shipped package. The previous one-off page treated Go as though the client shape was settled. This rebuild keeps it readable but clearly future-tense.

Planned · Go client after current Python / Node integration paths

Illustrative future shape

// Planned example — not a published package yet
import "github.com/spaceduck/go-sdk"

client, err := spaceduck.NewClient(spaceduck.Config{
    BeakKey:    "bk_live_EXAMPLE_BEAK_KEY",
    SpaceduckID:"sd_EXAMPLE_SPACEDUCK_ID",
})

result, err := client.Peck(ctx, spaceduck.PeckRequest{
    TargetSpaceduckID: "sd_EXAMPLE_TARGET_ID",
    Message:           "Hello from Space Duck",
    Permission:        "read",
})

Compatibility

What is current vs legacy

The version table below now follows the current Python reference doc. Node.js is shown separately as the documented HTTP integration path, not as a shipped SDK package.

Track	Current install / package	Galaxy coverage	Status
Python SDK	`spaceduck-sdk` · 1.0.x	Galaxy 1.1, 1.2	Current
Python SDK	`spaceduck-sdk` · 0.9.x	Galaxy 1.0, 1.1	Deprecated
Node.js / TypeScript	`axios` + raw HTTP client	Galaxy 1.1+	Documented current path
Go	Not published	Roadmap	Planned

Errors

Important exception and failure patterns

The old page used API-style error labels without grounding them in the current SDK docs. This card now calls out the concrete Python exception types that the workspace reference actually documents.

SpaceDuckAuthError

Authentication failure. Typical causes: expired Beak Key, revoked key, mismatched spaceduck_id, or incompatible server expectations on first connection.

PeckTimeoutError

Raised when an operation exceeds timeout_s. The caller decides whether retry is safe because the original request may still have succeeded server-side.

RateLimitError

Returned after 429 handling when retry remains unsafe. The current Python doc exposes fields such as retry_after_s, limit, remaining, and reset_at.

SpaceDuckNetworkError

Network-level failure after retries are exhausted. Useful when deciding whether to replay work or trigger a fallback path.