Claw Protocol Specification

Version 0.1 · Draft · March 2026

Author: ClawDrop

1. Introduction

The Claw Protocol defines a standard interface for programmatic file exchange. It is designed for AI agents, CLI tools, and automated systems that need to upload, retrieve, inspect, and delete files via simple HTTP operations.

Claw maps directly onto HTTP. Every Claw operation is a single HTTP request. Any HTTP client can speak Claw without specialized libraries.

1.1 Design Principles

1. One operation, one request. No multi-step flows, no sessions, no state machines.
2. HTTP is the transport. Claw is an application-layer convention over standard HTTP methods and headers.
3. Programmatic first. The primary interface is CLI and code, not browsers. Browser rendering is content negotiation, not a separate product.
4. No accounts. Identity is an API key. There are no usernames, passwords, profiles, or sessions.
5. Ephemeral by default. Files expire unless explicitly made permanent by an authenticated client.

1.2 Terminology

2. URI Scheme

Claw defines the claw:// URI scheme as syntactic sugar over HTTPS:

claw://<slug>                    → https://<registry>/<slug>
claw://<slug>?raw                → https://<registry>/<slug>?raw
claw://<slug>?m                  → https://<registry>/<slug>?m
claw://sha256:<hash>             → https://<registry>/sha256/<hash>
claw://@<namespace>/<name>       → https://<registry>/@<namespace>/<name>

The default registry is clawdrop.io. Clients MAY configure an alternative registry.

3. Operations

3.1 Drop (Upload)

Upload a file to the registry.

POST /
Content-Type: multipart/form-data

Form field: file (required)

Request Headers

Response (text/plain, default)

https://registry/slug\n

Response (application/json)

{
  "url": "https://registry/slug",
  "slug": "a3Fk82xQ",
  "expires_at": "2026-03-16T00:00:00.000Z",
  "size_bytes": 45231,
  "content_type": "application/pdf",
  "sha256_hash": "abc123..."
}

Status Codes

3.2 Fetch (Download)

Retrieve a file from the registry.

GET /<slug>
GET /<slug>?raw
GET /@<namespace>/<slug>
GET /sha256/<hash>

Content Negotiation

• Accept: text/html (browsers): Returns an HTML preview page with metadata, file preview, download link, and OG meta tags.
• All other clients (curl, wget, programmatic): Returns the raw file bytes.
• ?raw query parameter: Always returns raw file bytes regardless of Accept header.

Response Headers

Status Codes

3.3 Inspect (Metadata)

Retrieve metadata about a file without downloading it.

GET /<slug>?m

Response

{
  "slug": "a3Fk82xQ",
  "filename": "report.pdf",
  "content_type": "application/pdf",
  "size_bytes": 45231,
  "sha256_hash": "abc123...",
  "expires_at": "2026-03-16T00:00:00.000Z",
  "created_at": "2026-03-09T00:00:00.000Z",
  "permanent": false
}

3.4 Delete

Remove a file. Requires the same API key used to upload it.

DELETE /<slug>
X-API-Key: claw_...

Status Codes

4. Authentication

4.1 API Keys

API keys are the sole authentication mechanism. There are no usernames, passwords, or OAuth flows.

Key Generation

POST /keys

Returns a new API key exactly once. The server stores only the SHA-256 hash.

Key Format: claw_ prefix + 32 cryptographically random base62 characters.

Example: claw_a7Kx9mP2rN4wQ8bF3vT6yJ1hD5sL0gC

Key Usage: Pass via the X-API-Key header on any request.

4.2 Key Introspection

GET /keys/me
X-API-Key: claw_...

Returns upload history and usage statistics for the authenticated key.

{
  "uploads": [
    {"slug": "a3Fk82xQ", "filename": "report.pdf", "created_at": "...", "expires_at": "..."}
  ],
  "usage": {
    "upload_count": 47,
    "bytes_stored": 125829120,
    "bytes_served": 524288000
  },
  "namespace": "@myproject"
}

5. Rate Limiting

Rate limits are communicated via standard headers on every response:

Default Limits

6. Content-Addressable Mode

When X-Content-Address: true is sent with an upload:

1. The server computes the SHA-256 hash of the content.
2. If a file with that hash already exists and has not expired, the server returns the existing URL (HTTP 200, not 201).
3. If no match exists, normal upload proceeds and a content:{hash} index is stored.

Lookup by Hash

GET /sha256/<hash>

Returns HTTP 301 redirect to the canonical slug URL. This enables deduplication and convergent file references across independent agents.

7. Namespaces

Namespaces provide URL grouping under an API key.

Claiming a namespace: Send X-Namespace: myproject on any upload with an API key. The namespace is claimed on first use and bound to that API key.

Namespace URLs: https://registry/@myproject/filename

Rules

• One namespace per API key.
• Namespace names: 2–32 characters, lowercase alphanumeric + hyphens, must start with a letter.
• Namespace ownership is verified on every upload to that namespace.

8. Permanence

By default, all files are ephemeral with a 7-day TTL (free tier).

To create a permanent file, send Max-Days: permanent with a valid API key on a Pro or Studio tier.

Permanent files:

• Have no expiration
• Are stored indefinitely while the subscription is active
• Require an API key (anonymous uploads are always ephemeral)
• Are the foundation for load-bearing URLs in documentation, configs, and agent memory

9. Error Codes

All errors return JSON:

{
  "error": "Human-readable message",
  "retry_after": 3600
}

10. Conformance

A Claw-compatible server MUST implement:

1. POST / file upload with multipart/form-data
2. GET /<slug> file retrieval
3. Content-Type preservation
4. Expiration semantics (files MUST eventually expire unless permanent)
5. SHA-256 content hashing
6. Rate limiting headers

A Claw-compatible server SHOULD implement:

1. API key authentication (POST /keys, X-API-Key header)
2. Content negotiation (browser vs programmatic)
3. Content-addressable mode
4. Namespaces
5. The ?m metadata endpoint
6. The ?raw bypass

Appendix A: Quick Reference

# Upload a file
$ curl -F "[email protected]" https://clawdrop.io

# Upload with API key and custom expiration
$ curl -F "[email protected]" -H "X-API-Key: claw_..." -H "Max-Days: 30" https://clawdrop.io

# Upload permanent file
$ curl -F "[email protected]" -H "X-API-Key: claw_..." -H "Max-Days: permanent" https://clawdrop.io

# Get JSON response
$ curl -F "[email protected]" -H "Accept: application/json" https://clawdrop.io

# Download a file
$ curl https://clawdrop.io/a3Fk82xQ -o report.pdf

# Inspect metadata
$ curl https://clawdrop.io/a3Fk82xQ?m

# Delete a file
$ curl -X DELETE -H "X-API-Key: claw_..." https://clawdrop.io/a3Fk82xQ

# Generate API key
$ curl -X POST https://clawdrop.io/keys

# Check usage
$ curl -H "X-API-Key: claw_..." https://clawdrop.io/keys/me

# Content-addressable upload
$ curl -F "[email protected]" -H "X-Content-Address: true" https://clawdrop.io

# Custom slug
$ curl -F "[email protected]" -H "X-API-Key: claw_..." -H "X-Slug: brand-logo" https://clawdrop.io

# Namespaced upload
$ curl -F "[email protected]" -H "X-API-Key: claw_..." -H "X-Namespace: myproject" https://clawdrop.io

The Claw Protocol is open. This spec is public. Fork it if we disappear.