API Reference - HashBin.org

Overview

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

Base URL

https://hashbin.org/api

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.

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": 1024,
  "cost_cents": 1,
  "expiration": "2027-01-24T00:00:00Z"
}

GET /api/content/:cid

Download content by hash

Parameters

Parameter	Type	Description
cid	string	REQUIRED 256t content hash

Response

Binary content with appropriate Content-Type header

GET /api/content/:cid/metadata

Get content metadata

Response

{
  "cid": "00000123...",
  "size": 1024,
  "uploaded": "2026-01-01T00:00:00Z",
  "expires": "2027-01-01T00:00:00Z",
  "status": "active"
}

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