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

Most endpoints require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys can be created and managed from your dashboard.

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

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

{ "keys": [ { "id": "key_abc123", "name": "Production API Key", "created": "2026-01-01T00:00:00Z", "expires": "2027-01-01T00:00:00Z", "lastUsed": "2026-01-24T12:00:00Z" } ] }
POST /api/auth/apikeys

Create a new API key

Request Body

{ "name": "My API Key", "expiresInDays": 365 }

Response

{ "id": "key_abc123", "key": "hb_live_...", "name": "My API Key", "created": "2026-01-24T00:00:00Z", "expires": "2027-01-24T00: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

Request Headers

Header Type Description
Content-Type string Must be application/octet-stream
X-Content-Hash string REQUIRED 256t hash of content
X-Retention-Days number REQUIRED Retention duration (multiple of 30)

Response

{ "cid": "00000123...", "size_bytes": 1024, "cost_cents": 1, "expires_at": "2027-01-24T00:00:00Z", "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