API Reference

ClawDNA Cloud API — the hosted sync hub. Base URL: https://hub.clawdna.io/v1

Rate Limits

Bundles

Push Bundle

Upload a .dna identity bundle to the hub.

Request

Content type: multipart/form-data

Response 201

{
  "bundle_id": "a1b2c3d4-...",
  "stored_at": "2026-03-15T14:22:00Z",
  "url": "https://r2.clawdna.io/bundles/...",
  "webhook_notifications_sent": 3
}

Get Latest Bundle

Retrieve the latest manifest and a signed download URL.

Response 200

{
  "manifest": { /* BundleManifest */ },
  "download_url": "https://r2.clawdna.io/..."
}

Response 404

{ "error": "no_bundles_found" }

List Bundles

List bundles for an agent with pagination.

Response 200

{
  "bundles": [ /* BundleManifest[] */ ],
  "total": 42,
  "has_more": true
}

Download Bundle

Redirects to a signed R2 download URL (1 hour expiry).

Response 302

Redirect to signed R2 URL.

Environments

List Environments

List all registered environments for an agent.

Response 200

{
  "envs": [
    {
      "env_id": "pedro-main",
      "role": "primary",
      "last_seen": "2026-03-15T14:22:00Z",
      "tags": ["production"]
    }
  ]
}

Register Environment

Register a new environment for sync.

Request

{
  "agent_id": "my-bot",
  "env_id": "vps-bot-1",
  "role": "replica",
  "tags": ["staging"],
  "webhook_url": "https://..."
}

Update Environment

Update environment metadata, role, or webhook URL.

Fleet

Fleet Push

Push a bundle to multiple environments simultaneously. Returns an async job.

Request

{
  "agent_id": "my-bot",
  "bundle_id": "a1b2c3d4-...",
  "env_ids": ["vps-1", "vps-2"],
  "filter_tags": ["production"]
}

Response 202

{
  "job_id": "job-xyz",
  "status_url": "/v1/fleet/jobs/job-xyz"
}

Memory

Distill Memory

Use an LLM to extract core facts from raw session memory. Requires Pro tier or above.

Request

{
  "agent_id": "my-bot",
  "raw_memory": "/* MEMORY.md content */",
  "context": "ClawBot — friendly sales assistant"
}

Response 200

{
  "distilled": "/* Structured facts in MEMORY.md format */",
  "extracted_count": 12,
  "tokens_used": 1847
}

Webhooks

Register Webhook

Register an environment webhook to receive push notifications.

Request

{
  "agent_id": "my-bot",
  "env_id": "vps-bot-1",
  "url": "https://my-server.com/webhook",
  "secret": "my-webhook-secret",
  "events": ["push", "fleet.push"]
}

Webhook Payload

Sent to registered URLs when push events occur.

// Header: X-ClawDNA-Signature: hmac-sha256=<sig>
{
  "event": "push",
  "agent_id": "my-bot",
  "bundle_id": "a1b2c3d4-...",
  "pushed_by_env_id": "pedro-main",
  "pushed_at": "2026-03-15T14:22:00Z",
  "download_url": "https://r2.clawdna.io/...",
  "changed_files": ["SOUL.md", "MEMORY.md"]
}

Signatures use HMAC-SHA256 with the webhook secret and are verified using timing-safe comparison to prevent replay attacks.

Billing

Get Subscription

Returns the current subscription tier, usage, and limits.

Get Usage

Returns current billing period usage: pushes, pulls, distillation tokens, storage.

Create Checkout Session

Creates a Stripe checkout session for upgrading or changing tier.

Request

{
  "tier": "pro",
  "return_url": "https://clawco.io/billing"
}