API Reference

Overview

The HashBin.org API provides programmatic access to content upload, metadata, and account management. All API requests must be made over HTTPS.

Base URL

API: https://hashbin.org/api Content: https://256t.us/{cid}

Authentication

Programs authenticate with an API key, sent in either header:

Authorization: ApiKey hbk_... X-API-Key: hbk_...

Each key holds only the scopes you give it (for example content:write to publish, balance:read to read the balance) and can carry limits: a monthly spending limit, largest upload, longest retention, allowed content types, or specific CIDs. Anything else answers 403. Keys, apps, settings and deposits always need your own sign-in. Create and narrow keys from your dashboard; the full scope list is in docs/API.md.

For third-party browser integrations, use the hosted SDK at https://hashbin.org/sdk/hashbin.js and follow the SDK Guide. Raw files are served from 256t.us; see content security.

Authentication

GET /api/auth/session

Get current user session information (signed-in session only)

Response

{ "authenticated": true, "user": { "id": "user_abc123", "email": "user@example.com", "name": "John Doe" } }
GET /api/auth/apikeys

List all API keys for authenticated user

Response

[ { "key_id": "6f1c...", "name": "Publisher", "scopes": ["content:write"], "caveats": { "monthly_spend_limit_cents": 200 }, "created_at": "2026-10-27T00:00:00Z", "expires_at": "2027-01-25T00:00:00Z", "last_used_at": "2026-10-27T12:00:00Z", "revoked": false } ]
POST /api/auth/apikeys

Create a new API key

Request Body

{ "name": "Publisher", "scopes": ["content:write"], "caveats": { "max_upload_bytes": 1048576, "monthly_spend_limit_cents": 200 }, "expires_at": "2027-01-25T00:00:00Z" }

Response

{ "key_id": "6f1c...", "api_key": "hbk_...", "name": "Publisher", "scopes": ["content:write"], "caveats": { "max_upload_bytes": 1048576, "monthly_spend_limit_cents": 200 }, "created_at": "2026-10-27T00:00:00Z", "expires_at": "2027-01-25T00:00:00Z" }

Important: The key value is only shown once. Store it securely.

Balance

GET /api/balance

Get current wallet balance

Response

{ "balance_cents": 1250, "balance_formatted": "$12.50" }

Content

POST /api/content

Upload new content (requires authentication). The cost is deducted from your balance. Maximum upload size is 90 MB; larger requests get 413 Payload Too Large.

Send the raw bytes as the request body, or a multipart/form-data body with a content file field (and an optional retention_months field). The server computes the 256t hash.

Request

Name Where Description
Content-Type header MIME type stored with the content (for raw bodies), or multipart/form-data
retention_months query or form field Whole months of retention, minimum 1 (default 1). OAuth clients always use the user's default retention.

Response

{ "cid": "00000123...", "size_bytes": 1024, "cost_cents": 1, "expires_at": "2027-01-24T00:00:00Z", "new_balance_cents": 999, "url": "https://256t.us/00000123..." }
GET /api/content/:cid

Get content metadata, including the dedicated content URL

Parameters

Parameter Type Description
cid string REQUIRED 256t content hash

Response

{ "hash_256t": "00000123...", "size_bytes": 1024, "expires_at": "2027-01-01T00:00:00Z", "url": "https://256t.us/00000123...", "download_domain": "256t.us" }
GET https://256t.us/:cid

Download raw content from the isolated content domain

Response

Binary content with the original content type and restrictive headers such as Content-Security-Policy: default-src 'none'; sandbox.

GET /api/content/:cid/exists

Check if content exists

Response

{ "exists": true, "cid": "00000123..." }

Error Responses

All errors follow a consistent format:

{ "error": "Error message", "details": { "field": "Additional context" } }

HTTP Status Codes

Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Missing or invalid authentication
402 Payment Required - Insufficient balance
404 Not Found - Resource does not exist
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error