### API Error Handling Examples (Bash, JavaScript)

Source: https://context7.com/hackclub/cdn/llms.txt

Illustrates common API error responses from the Hack Club CDN. Includes examples for missing parameters, invalid API keys, storage quota exceeded, and general validation errors. The JavaScript example provides a function to handle these errors programmatically.

```bash
# Missing file parameter (400)
curl -X POST -H "Authorization: Bearer sk_cdn_key" \
  https://cdn.hackclub.com/api/v4/upload
# {"error": "Missing file parameter"}

# Invalid API key (401)
curl -X POST -H "Authorization: Bearer invalid_key" \
  -F "file=@photo.jpg" https://cdn.hackclub.com/api/v4/upload
# {"error": "invalid_auth"}

# Storage quota exceeded (402)
curl -X POST -H "Authorization: Bearer sk_cdn_key" \
  -F "file=@large_file.zip" https://cdn.hackclub.com/api/v4/upload
# {
#   "error": "Storage quota exceeded",
#   "quota": {
#     "storage_used": 52428800,
#     "storage_limit": 52428800,
#     "quota_tier": "unverified",
#     "percentage_used": 100.0
#   }
# }
```

```javascript
// Comprehensive error handling
async function uploadWithErrorHandling(file, apiKey) {
  const formData = new FormData();
  formData.append('file', file);

  const response = await fetch('https://cdn.hackclub.com/api/v4/upload', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${apiKey}` },
    body: formData
  });

  if (response.ok) {
    return await response.json();
  }

  const error = await response.json();

  switch (response.status) {
    case 400:
      throw new Error(`Bad request: ${error.error}`);
    case 401:
      throw new Error('Invalid or expired API key');
    case 402:
      throw new Error(`Quota exceeded: ${error.quota.percentage_used}% used of ${error.quota.quota_tier} tier`);
    case 422:
      throw new Error(`Validation failed: ${error.details?.join(', ') || error.error}`);
    default:
      throw new Error(`Upload failed: ${error.error}`);
  }
}
```

--------------------------------

### Get User and Quota Information (Bash)

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Retrieve authenticated user details and storage quota information using a GET request. Requires your API key in the Authorization header.

```bash
curl -H "Authorization: Bearer sk_cdn_your_key_here" \
  https://cdn.hackclub.com/api/v4/me
```

--------------------------------

### Start Development Servers

Source: https://github.com/hackclub/cdn/blob/master/README.md

Commands to launch the Vite frontend development server and the Rails backend server.

```bash
bin/vite dev
bin/rails server
```

--------------------------------

### Initialize Project Environment

Source: https://github.com/hackclub/cdn/blob/master/README.md

Commands to clone the repository, install dependencies, and prepare the database for a local development environment.

```bash
git clone https://github.com/hackclub/cdn.git
cd cdn
bundle install
yarn install
cp .env.example .env
bin/rails db:create db:migrate
```

--------------------------------

### Access Uploaded Files (Bash, HTML, Markdown)

Source: https://context7.com/hackclub/cdn/llms.txt

Examples of accessing uploaded files via their permanent CDN URL. The CDN URL returns a 301 redirect to the underlying storage bucket with a 1-year cache. This section includes examples for direct curl access, embedding in HTML as an image or link, and embedding in Markdown.

```bash
# Direct access to uploaded file (returns 301 redirect to R2 bucket)
curl -I https://cdn.hackclub.com/01234567-89ab-cdef-0123-456789abcdef/photo.jpg
```

```html
<!-- Embed in HTML -->
<img src="https://cdn.hackclub.com/019505e2-c85b-7f80-9c31-4b2e5a8d9f12/photo.jpg" alt="My image">

<!-- Link to download -->
<a href="https://cdn.hackclub.com/019505e2-d4a1-7c20-8b45-6e3f2a1c8d09/document.pdf">Download PDF</a>
```

```markdown
<!-- Embed in Markdown -->
![Screenshot](https://cdn.hackclub.com/019505e2-e7f3-7d40-a156-9c4e8b2d1f03/screenshot.png)
```

--------------------------------

### GET /rescue

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/using-cdn-urls.md

Retrieves the new CDN URL for assets migrated from legacy storage providers.

```APIDOC
## GET /rescue

### Description
Lookup endpoint for files migrated from legacy CDNs. Returns a 301 redirect to the new CDN URL if found.

### Method
GET

### Endpoint
/rescue

### Parameters
#### Query Parameters
- **url** (string) - Required - The original legacy URL of the asset.

### Request Example
GET /rescue?url=https://hc-cdn.hel1.your-objectstorage.com/s/v3/sdhfksdjfhskdjf.png

### Response
#### Success Response (301)
- **Location** (string) - Redirects to the new CDN URL.

#### Error Response (404)
- **Body** (string) - Returns an SVG 404 placeholder for image extensions, otherwise a standard 404.
```

--------------------------------

### Upload File from URL (Bash & JavaScript)

Source: https://context7.com/hackclub/cdn/llms.txt

Enables uploading files by providing a URL. The server downloads and stores the file. It supports authenticated source URLs using the `X-Download-Authorization` header. Examples are provided for both Bash and JavaScript.

```bash
# Upload from a public URL
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/image.jpg"}' \
  https://cdn.hackclub.com/api/v4/upload_from_url

# Upload from a protected URL (pass auth to source server)
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -H "X-Download-Authorization: Bearer source_token_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://protected.example.com/image.jpg"}' \
  https://cdn.hackclub.com/api/v4/upload_from_url

# Response (201 Created):
# {
#   "id": "019505e2-c85b-7f80-9c31-4b2e5a8d9f12",
#   "filename": "image.jpg",
#   "size": 54321,
#   "content_type": "image/jpeg",
#   "url": "https://cdn.hackclub.com/019505e2-c85b-7f80-9c31-4b2e5a8d9f12/image.jpg",
#   "created_at": "2026-01-29T12:30:00Z"
# }
```

```javascript
// JavaScript URL upload with optional source authentication
const response = await fetch('https://cdn.hackclub.com/api/v4/upload_from_url', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_cdn_your_key_here',
    'Content-Type': 'application/json',
    'X-Download-Authorization': 'Bearer optional_source_token' // Optional
  },
  body: JSON.stringify({ url: 'https://example.com/image.jpg' })
});

if (response.ok) {
  const { url } = await response.json();
  console.log(`Uploaded from URL: ${url}`);
} else {
  const error = await response.json();
  console.error(`Upload failed: ${error.error}`);
}
```

--------------------------------

### GET /rescue

Source: https://context7.com/hackclub/cdn/llms.txt

Lookup endpoint for files migrated from legacy CDNs, redirecting to the new CDN URL.

```APIDOC
## GET /rescue

### Description
Lookup endpoint for files migrated from legacy CDNs. Returns a 301 redirect to the new CDN URL if found, or a 404 SVG placeholder for image URLs.

### Method
GET

### Endpoint
https://cdn.hackclub.com/rescue

### Parameters
#### Query Parameters
- **url** (string) - Required - The original legacy URL to look up.
```

--------------------------------

### Upload Files via API

Source: https://github.com/hackclub/cdn/blob/master/README.md

Examples of using curl to upload files directly or from a remote URL using bearer token authentication.

```bash
curl -X POST https://cdn.hackclub.com/api/v4/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@image.png"

curl -X POST https://cdn.hackclub.com/api/v4/upload_from_url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.png"}'
```

--------------------------------

### GET /api/v4/me

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Retrieve information about your authenticated user account, including storage usage and limits.

```APIDOC
## GET /api/v4/me

Get the authenticated user and quota information.

### Method
GET

### Endpoint
/api/v4/me

### Parameters
No parameters required.

### Request Example
```bash
curl -H "Authorization: Bearer sk_cdn_your_key_here" \
  https://cdn.hackclub.com/api/v4/me
```

### Response
#### Success Response (200)
- **id** (string) - The user's unique identifier.
- **email** (string) - The user's email address.
- **name** (string) - The user's name.
- **storage_used** (integer) - The amount of storage used in bytes.
- **storage_limit** (integer) - The total storage limit in bytes.
- **quota_tier** (string) - The user's quota tier (e.g., "unverified", "verified", "functionally_unlimited").

#### Response Example
```json
{
  "id": "usr_abc123",
  "email": "you@hackclub.com",
  "name": "Your Name",
  "storage_used": 1048576000,
  "storage_limit": 53687091200,
  "quota_tier": "verified"
}
```

**Quota fields:**
- `storage_used` — bytes used
- `storage_limit` — bytes allowed
- `quota_tier` — `"unverified"`, `"verified"`, or `"functionally_unlimited"`
```

--------------------------------

### API Authentication Header

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Example of the required Authorization header format for API requests, using a Bearer token.

```text
Authorization: Bearer sk_cdn_your_key_here
```

--------------------------------

### Handle Over Quota API Error

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/quotas.md

Example of the JSON response returned by the API when a user exceeds their storage limit, resulting in a 402 Payment Required status.

```json
{
  "error": "Storage quota exceeded",
  "quota": {
    "storage_used": 52428800,
    "storage_limit": 52428800,
    "quota_tier": "unverified",
    "percentage_used": 100.0
  }
}
```

--------------------------------

### Check Quota and Upload File (JavaScript)

Source: https://context7.com/hackclub/cdn/llms.txt

This JavaScript function checks available storage quota before uploading a file to the Hack Club CDN. It makes a GET request to the /api/v4/me endpoint to retrieve storage usage and limits, then proceeds with the POST request to /api/v4/upload if sufficient space is available. It throws an error if the file exceeds the available storage.

```javascript
async function checkQuotaAndUpload(file, apiKey) {
  const meResponse = await fetch('https://cdn.hackclub.com/api/v4/me', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const { storage_used, storage_limit, quota_tier } = await meResponse.json();
  const available = storage_limit - storage_used;

  if (file.size > available) {
    throw new Error(`File too large. Available: ${available} bytes, File: ${file.size} bytes`);
  }

  // Proceed with upload...
  const formData = new FormData();
  formData.append('file', file);

  return fetch('https://cdn.hackclub.com/api/v4/upload', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${apiKey}` },
    body: formData
  });
}
```

--------------------------------

### Standard API Error Response

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Example of a standard JSON error response from the API, indicating a missing parameter.

```json
{
  "error": "Missing file parameter"
}
```

--------------------------------

### GET /api/v4/me - Check Quota Status

Source: https://context7.com/hackclub/cdn/llms.txt

This endpoint allows you to retrieve your current storage usage, storage limit, and quota tier. It requires an Authorization header with your API key.

```APIDOC
## GET /api/v4/me

### Description
Retrieves the current user's storage quota status, including used space, storage limit, and quota tier.

### Method
GET

### Endpoint
/api/v4/me

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token with your API key (e.g., `Bearer sk_cdn_your_key`)

### Request Example
```javascript
// Check quota tier and available space
async function getQuotaStatus(apiKey) {
  const response = await fetch('https://cdn.hackclub.com/api/v4/me', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const { storage_used, storage_limit, quota_tier } = await response.json();

  return {
    tier: quota_tier,
    used: storage_used,
    limit: storage_limit,
    available: storage_limit - storage_used,
    percentUsed: ((storage_used / storage_limit) * 100).toFixed(2)
  };
}

// Usage
const quota = await getQuotaStatus('sk_cdn_your_key');
console.log(`${quota.tier} tier: ${quota.percentUsed}% used, ${quota.available} bytes available`);
```

### Response
#### Success Response (200)
- **storage_used** (integer) - The amount of storage currently used in bytes.
- **storage_limit** (integer) - The total storage limit in bytes for the user's tier.
- **quota_tier** (string) - The current storage quota tier (e.g., "Verified", "Unlimited").

#### Response Example
```json
{
  "storage_used": 10485760, 
  "storage_limit": 52428800, 
  "quota_tier": "Verified"
}
```
```

--------------------------------

### URL Rescue Endpoint

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/using-cdn-urls.md

Details the GET request format for the URL rescue endpoint, which helps find files migrated from legacy CDNs. It returns a 301 redirect to the new CDN URL or a 404 placeholder/response.

```http
GET /rescue?url={original_url}
```

```http
/rescue?url=https://hc-cdn.hel1.your-objectstorage.com/s/v3/sdhfksdjfhskdjf.png
```

```http
/rescue?url=https://cloud-xxxx-hack-club-bot.vercel.app/0awawawa.png
```

--------------------------------

### GET /:id/:filename

Source: https://context7.com/hackclub/cdn/llms.txt

Access uploaded files via their permanent CDN URL. This endpoint returns a 301 redirect to the underlying storage bucket.

```APIDOC
## GET /:id/:filename

### Description
Access uploaded files via their permanent CDN URL. Returns a 301 redirect to the underlying storage bucket with 1-year cache headers.

### Method
GET

### Endpoint
https://cdn.hackclub.com/:id/:filename

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the upload.
- **filename** (string) - Required - The name of the file.
```

--------------------------------

### Retrieve User Profile and Quota Information (Bash)

Source: https://context7.com/hackclub/cdn/llms.txt

Fetches the authenticated user's profile details, including storage used and the storage limit. This endpoint is useful for checking available storage before performing uploads.

```bash
curl -H "Authorization: Bearer sk_cdn_your_key_here" \
  https://cdn.hackclub.com/api/v4/me

# Response (200 OK):
# {
#   "id": "usr_abc123",
#   "email": "you@hackclub.com",
#   "name": "Your Name",
#   "storage_used": 1048576000,
#   "storage_limit": 53687091200,
#   "quota_tier": "verified"
# }
```

--------------------------------

### Rescue Migrated Files (Bash)

Source: https://context7.com/hackclub/cdn/llms.txt

This bash command shows how to use the /rescue endpoint to look up files migrated from legacy CDNs. It takes a URL parameter and returns a 301 redirect to the new CDN URL if found, or a 404 SVG placeholder for image URLs if not found. A standard 404 is returned for non-image URLs.

```bash
# Find a migrated file by its original URL
curl -I "https://cdn.hackclub.com/rescue?url=https://cloud-xxxx-hack-club-bot.vercel.app/0image.png"
```

--------------------------------

### Upload Image from URL (Bash)

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Upload an image to the CDN by providing its URL. This method supports an optional header for authenticating the download from the source URL.

```bash
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/image.jpg"}' \
  https://cdn.hackclub.com/api/v4/upload_from_url
```

```bash
# With authentication for the source URL:
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -H "X-Download-Authorization: Bearer source_token_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://protected.example.com/image.jpg"}' \
  https://cdn.hackclub.com/api/v4/upload_from_url
```

--------------------------------

### Embedding CDN Images in Markdown

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/getting-started.md

Demonstrates how to display an uploaded image in a Markdown file. This syntax is compatible with most README files and documentation platforms.

```markdown
![](https://cdn.hackclub.com/019505e2-c85b-7f80-9c31-4b2e5a8d9f12/photo.jpg)
```

--------------------------------

### Upload File via Multipart Form Data (Bash & JavaScript)

Source: https://context7.com/hackclub/cdn/llms.txt

Shows how to upload a local file using multipart form data. The API returns the permanent CDN URL, file ID, and other metadata upon successful upload. Supports both command-line and browser-based uploads.

```bash
# Upload a local file
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -F "file=@photo.jpg" \
  https://cdn.hackclub.com/api/v4/upload

# Response (201 Created):
# {
#   "id": "01234567-89ab-cdef-0123-456789abcdef",
#   "filename": "photo.jpg",
#   "size": 12345,
#   "content_type": "image/jpeg",
#   "url": "https://cdn.hackclub.com/01234567-89ab-cdef-0123-456789abcdef/photo.jpg",
#   "created_at": "2026-01-29T12:00:00Z"
# }
```

```javascript
// JavaScript/Browser upload
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cdn.hackclub.com/api/v4/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_cdn_your_key_here' },
  body: formData
});

const { url, id, filename, size, content_type } = await response.json();
console.log(`Uploaded: ${url}`);
```

--------------------------------

### Authentication

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Learn how to authenticate your API requests using an API key. Generate your key from the API Keys page and include it in the Authorization header.

```APIDOC
## Authentication

Create an API key at [API Keys](/api_keys). Keys are shown once, so copy it immediately.

Include the key in the `Authorization` header:

```
Authorization: Bearer sk_cdn_your_key_here
```
```

--------------------------------

### POST /api/v4/upload

Source: https://context7.com/hackclub/cdn/llms.txt

Uploads a file to the CDN. Requires an API key in the Authorization header. Check your storage quota before uploading.

```APIDOC
## POST /api/v4/upload

### Description
Uploads a file to the CDN. The request must include the file in a FormData object.

### Method
POST

### Endpoint
https://cdn.hackclub.com/api/v4/upload

### Parameters
#### Request Body
- **file** (binary) - Required - The file to be uploaded.

### Request Example
```javascript
const formData = new FormData();
formData.append('file', file);

fetch('https://cdn.hackclub.com/api/v4/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_cdn_...' },
  body: formData
});
```

### Response
#### Success Response (200)
- **url** (string) - The permanent URL of the uploaded file.

#### Response Example
{
  "url": "https://cdn.hackclub.com/019505e2-c85b-7f80-9c31-4b2e5a8d9f12/photo.jpg"
}
```

--------------------------------

### Upload Image via Direct Upload (JavaScript)

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Use the Fetch API in JavaScript to upload an image file directly to the CDN. This method utilizes FormData to send the file and requires an Authorization header with your API key.

```javascript
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cdn.hackclub.com/api/v4/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_cdn_your_key_here' },
  body: formData
});

const { url } = await response.json();
```

--------------------------------

### Embedding Links with HTML

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/using-cdn-urls.md

Shows how to create downloadable links using Hack Club CDN URLs within an HTML anchor tag. This is useful for providing access to documents or other files.

```html
<a href="https://cdn.hackclub.com/019505e2-d4a1-7c20-8b45-6e3f2a1c8d09/document.pdf">Download</a>
```

--------------------------------

### Generate Security Keys

Source: https://github.com/hackclub/cdn/blob/master/README.md

Commands to generate necessary encryption keys for Lockbox, BlindIndex, and Active Record encryption.

```ruby
ruby -e "require 'securerandom'; puts SecureRandom.hex(32)"
ruby -e "require 'securerandom'; puts SecureRandom.hex(32)"
bin/rails db:encryption:init
```

--------------------------------

### Upload Image via Direct Upload (Bash)

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Use curl to upload an image file directly to the CDN using a multipart form data request. Requires an API key for authentication.

```bash
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -F "file=@photo.jpg" \
  https://cdn.hackclub.com/api/v4/upload
```

--------------------------------

### Check User Storage Usage via API

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/quotas.md

Retrieves the current user's storage consumption, limits, and tier status. Requires a valid Bearer token in the Authorization header.

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" https://cdn.hackclub.com/api/v4/me
```

```json
{
  "storage_used": 1048576000,
  "storage_limit": 53687091200,
  "quota_tier": "verified"
}
```

--------------------------------

### Check Storage Usage

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/quotas.md

Retrieve your current storage usage, limit, and quota tier via the API.

```APIDOC
## Check Storage Usage

### Description
Retrieves the current storage usage, storage limit, and quota tier for the authenticated user.

### Method
GET

### Endpoint
/api/v4/me

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://cdn.hackclub.com/api/v4/me
```

### Response
#### Success Response (200)
- **storage_used** (integer) - The amount of storage currently used in bytes.
- **storage_limit** (integer) - The total storage limit in bytes.
- **quota_tier** (string) - The current quota tier (e.g., "unverified", "verified", "unlimited").

#### Response Example
```json
{
  "storage_used": 1048576000,
  "storage_limit": 53687091200,
  "quota_tier": "verified"
}
```
```

--------------------------------

### Upload Image from URL (JavaScript)

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Use the Fetch API in JavaScript to upload an image from a given URL. The request body should be a JSON object containing the URL, and an optional header can be used for source URL authentication.

```javascript
const response = await fetch('https://cdn.hackclub.com/api/v4/upload_from_url', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_cdn_your_key_here',
    'Content-Type': 'application/json',
    // Optional: auth for the source URL
    'X-Download-Authorization': 'Bearer source_token_here'
  },
  body: JSON.stringify({ url: 'https://example.com/image.jpg' })
});

const { url } = await response.json();
```

--------------------------------

### POST /api/v4/upload_from_url

Source: https://context7.com/hackclub/cdn/llms.txt

Uploads a file to the CDN by fetching it from a provided URL. Supports optional source authentication.

```APIDOC
## POST /api/v4/upload_from_url

### Description
Upload a file by providing a URL. The server downloads the file and stores it on the CDN.

### Method
POST

### Endpoint
https://cdn.hackclub.com/api/v4/upload_from_url

### Parameters
#### Request Body
- **url** (string) - Required - The source URL of the file.

#### Headers
- **X-Download-Authorization** (string) - Optional - Bearer token for the source server if the URL is protected.

### Request Example
{
  "url": "https://example.com/image.jpg"
}

### Response
#### Success Response (201)
- **id** (string) - The unique identifier for the file.
- **url** (string) - The permanent CDN URL.

#### Response Example
{
  "id": "019505e2-c85b-7f80-9c31-4b2e5a8d9f12",
  "filename": "image.jpg",
  "size": 54321,
  "url": "https://cdn.hackclub.com/019505e2-c85b-7f80-9c31-4b2e5a8d9f12/image.jpg"
}
```

--------------------------------

### Embedding CDN Images in HTML

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/getting-started.md

Demonstrates how to display an uploaded image in an HTML document using the standard img tag. The src attribute should be set to the permanent URL provided by the CDN.

```html
<img src="https://cdn.hackclub.com/019505e2-c85b-7f80-9c31-4b2e5a8d9f12/photo.jpg" alt="My image">
```

--------------------------------

### Embedding Images with HTML

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/using-cdn-urls.md

Demonstrates how to embed images using the Hack Club CDN URL within an HTML img tag. Ensure the URL points to a valid image file hosted on the CDN.

```html
<img src="https://cdn.hackclub.com/019505e2-c85b-7f80-9c31-4b2e5a8d9f12/photo.jpg" alt="">
```

--------------------------------

### Embedding Images with Markdown

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/using-cdn-urls.md

Illustrates the Markdown syntax for embedding images hosted on the Hack Club CDN. This is commonly used in README files and documentation platforms.

```markdown
![](https://cdn.hackclub.com/019505e2-e7f3-7d40-a156-9c4e8b2d1f03/screenshot.png)
```

--------------------------------

### Revoke API Key (Bash)

Source: https://context7.com/hackclub/cdn/llms.txt

This bash command demonstrates how to revoke an API key using a POST request to the /api/v4/revoke endpoint. It requires an Authorization header with the API key. A successful response includes a success status, the owner's email, and the key name.

```bash
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  https://cdn.hackclub.com/api/v4/revoke
```

--------------------------------

### Check CDN Quota Status with JavaScript

Source: https://context7.com/hackclub/cdn/llms.txt

This function retrieves the user's storage quota tier, used space, and total storage limit from the Hack Club CDN API. It requires an API key for authentication and returns an object containing the tier, used bytes, storage limit, available bytes, and percentage of storage used. This is useful for providing user feedback on storage consumption.

```javascript
async function getQuotaStatus(apiKey) {
  const response = await fetch('https://cdn.hackclub.com/api/v4/me', {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const { storage_used, storage_limit, quota_tier } = await response.json();

  return {
    tier: quota_tier,
    used: storage_used,
    limit: storage_limit,
    available: storage_limit - storage_used,
    percentUsed: ((storage_used / storage_limit) * 100).toFixed(2)
  };
}

// Usage
const quota = await getQuotaStatus('sk_cdn_your_key');
console.log(`${quota.tier} tier: ${quota.percentUsed}% used, ${quota.available} bytes available`);
```

--------------------------------

### POST /api/v4/upload_from_url

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Upload an image from a given URL. This is useful for importing existing images hosted elsewhere. You can optionally provide authentication for the source URL.

```APIDOC
## POST /api/v4/upload_from_url

Upload an image from a URL.

### Method
POST

### Endpoint
/api/v4/upload_from_url

### Parameters
#### Headers
- **X-Download-Authorization** (string) - Optional - Passed as `Authorization` when fetching the source URL (useful for protected resources).

#### Request Body
- **url** (string) - Required - The URL of the image to upload.

### Request Example
```bash
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/image.jpg"}' \
  https://cdn.hackclub.com/api/v4/upload_from_url

# With authentication for the source URL:
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -H "X-Download-Authorization: Bearer source_token_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://protected.example.com/image.jpg"}' \
  https://cdn.hackclub.com/api/v4/upload_from_url
```

```javascript
const response = await fetch('https://cdn.hackclub.com/api/v4/upload_from_url', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_cdn_your_key_here',
    'Content-Type': 'application/json',
    // Optional: auth for the source URL
    'X-Download-Authorization': 'Bearer source_token_here'
  },
  body: JSON.stringify({ url: 'https://example.com/image.jpg' })
});

const { url } = await response.json();
```

### Response
#### Success Response (200)
- **url** (string) - The URL to access the uploaded file.

#### Response Example
```json
{
  "url": "https://cdn.hackclub.com/abcdef1234567890/image.jpg"
}
```
```

--------------------------------

### POST /api/v4/upload

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Upload a file directly to the CDN using multipart form data. This endpoint is suitable for uploading files from your local system.

```APIDOC
## POST /api/v4/upload

Upload a file via multipart form data.

### Method
POST

### Endpoint
/api/v4/upload

### Parameters
#### Request Body
- **file** (file) - Required - The file to upload.

### Request Example
```bash
curl -X POST \
  -H "Authorization: Bearer sk_cdn_your_key_here" \
  -F "file=@photo.jpg" \
  https://cdn.hackclub.com/api/v4/upload
```

```javascript
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://cdn.hackclub.com/api/v4/upload', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer sk_cdn_your_key_here' },
  body: formData
});

const { url } = await response.json();
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the uploaded file.
- **filename** (string) - The original name of the file.
- **size** (integer) - The size of the file in bytes.
- **content_type** (string) - The MIME type of the file.
- **url** (string) - The URL to access the uploaded file.
- **created_at** (string) - The timestamp when the file was uploaded.

#### Response Example
```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "filename": "photo.jpg",
  "size": 12345,
  "content_type": "image/jpeg",
  "url": "https://cdn.hackclub.com/01234567-89ab-cdef-0123-456789abcdef/photo.jpg",
  "created_at": "2026-01-29T12:00:00Z"
}
```
```

--------------------------------

### Exceeded Storage Quota Error Response

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/quotas.md

Details on the error response when a user exceeds their storage quota.

```APIDOC
## Exceeded Storage Quota

### Description
When a user attempts to upload files beyond their allocated storage quota, the API returns a `402 Payment Required` status code with details about the quota.

### Method
POST (or any method that attempts to upload/increase storage)

### Endpoint
Any endpoint that results in exceeding storage limits.

### Response
#### Error Response (402 Payment Required)
- **error** (string) - A message indicating that the storage quota has been exceeded.
- **quota** (object) - An object containing details about the current quota status:
  - **storage_used** (integer) - The amount of storage currently used in bytes.
  - **storage_limit** (integer) - The total storage limit in bytes.
  - **quota_tier** (string) - The current quota tier.
  - **percentage_used** (float) - The percentage of the storage limit that has been used.

#### Response Example
```json
{
  "error": "Storage quota exceeded",
  "quota": {
    "storage_used": 52428800,
    "storage_limit": 52428800,
    "quota_tier": "unverified",
    "percentage_used": 100.0
  }
}
```
```

--------------------------------

### Browser Compatibility Error CSS

Source: https://github.com/hackclub/cdn/blob/master/public/406-unsupported-browser.html

This CSS snippet provides a global reset, typography settings, and layout structure for the error page. It ensures consistent rendering across different browsers using system fonts and responsive design techniques.

```css
* , *::before, *::after { box-sizing: border-box; } * { margin: 0; } html { font-size: 16px; } body { background: #FFF; color: #261B23; display: grid; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Aptos, Roboto, "Segoe UI", "Helvetica Neue", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; font-size: clamp(1rem, 2.5vw, 2rem); -webkit-font-smoothing: antialiased; font-style: normal; font-weight: 400; letter-spacing: -0.0025em; line-height: 1.4; min-height: 100vh; place-items: center; text-rendering: optimizeLegibility; -webkit-text-size-adjust: 100%; } main { display: grid; gap: 1em; padding: 2em; place-items: center; text-align: center; } main header { width: min(100%, 12em); } main article { width: min(100%, 30em); }
```

--------------------------------

### Error Handling

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/api.md

Understand the possible API error responses, including status codes and their meanings, and common error formats.

```APIDOC
## Errors

| Status | Meaning |
|--------|---------|
| 400 | Missing required parameters |
| 401 | Invalid or missing API key |
| 402 | Storage quota exceeded |
| 404 | Resource not found |
| 422 | Validation failed |

**Standard error:**

```json
{
  "error": "Missing file parameter"
}
```

**Quota error (402):**

```json
{
  "error": "Storage quota exceeded",
  "quota": {
    "storage_used": 52428800,
    "storage_limit": 52428800,
    "quota_tier": "unverified",
    "percentage_used": 100.0
  }
}
```

See [Storage Quotas](/docs/quotas) for details on getting more space.
```

--------------------------------

### CDN Asset Access

Source: https://github.com/hackclub/cdn/blob/master/app/views/docs/pages/using-cdn-urls.md

Standard URL structure for accessing assets stored on the Hack Club CDN.

```APIDOC
## GET / {id}/{filename}

### Description
Access assets directly via the CDN. Requests are 301 redirected to the underlying storage bucket.

### Method
GET

### Endpoint
https://cdn.hackclub.com/{id}/{filename}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique UUID v7 identifier for the upload.
- **filename** (string) - Required - The name of the file including extension.

### Response
#### Success Response (301)
- **Location** (string) - Redirects to the underlying storage bucket URL.
```

--------------------------------

### POST /api/v4/revoke

Source: https://context7.com/hackclub/cdn/llms.txt

Revokes the API key currently in use, rendering it immediately invalid.

```APIDOC
## POST /api/v4/revoke

### Description
Revoke the API key used in the current request. The key becomes immediately invalid after this call.

### Method
POST

### Endpoint
https://cdn.hackclub.com/api/v4/revoke

### Request Example
```bash
curl -X POST -H "Authorization: Bearer sk_cdn_your_key_here" https://cdn.hackclub.com/api/v4/revoke
```

### Response
#### Success Response (200)
- **success** (boolean) - Confirmation of revocation.
- **owner_email** (string) - Email of the key owner.
- **key_name** (string) - Name of the revoked key.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.