Developer Portal

Integrate with easy-host using the REST API. Upload, manage, and serve HTML content programmatically.

Authentication

All API endpoints require HTTP Basic Authentication. Include your credentials in every request.

curl -u username:password https://content.oglimmer.com/api/content

Quick Start

# 1. Upload a single HTML file
curl -u admin:changeme \
  -F "slug=hello" \
  -F "file=@index.html" \
  https://content.oglimmer.com/api/content

# 2. Upload a ZIP archive with multiple files
curl -u admin:changeme \
  -F "slug=my-site" \
  -F "file=@site.zip" \
  -F "title=My Website" \
  https://content.oglimmer.com/api/content

# 3. View your content
open https://content.oglimmer.com/s/hello

Base URL

All API endpoints are relative to:

https://content.oglimmer.com/api/content

Endpoints

List All Content

GET /api/content

Returns all content items owned by the authenticated user.

Example request:

curl -u admin:changeme https://content.oglimmer.com/api/content

Response: 200 OK

[
  {
    "id": 1,
    "slug": "hello",
    "title": "My Page",
    "sourceUrl": "https://example.com",
    "owner": "admin",
    "creator": "John Doe",
    "allowExternalResources": false,
    "createdAt": "2026-04-09T10:00:00Z",
    "updatedAt": "2026-04-09T10:30:00Z",
    "files": ["index.html", "style.css"]
  }
]

Create Content

POST /api/content

Upload a new content item. Accepts multipart/form-data.

Example request:

curl -u admin:changeme \
  -F "slug=my-page" \
  -F "file=@index.html" \
  -F "title=My Page" \
  -F "creator=John Doe" \
  -F "allowExternalResources=false" \
  https://content.oglimmer.com/api/content

Response: 201 Created

{
  "id": 2,
  "slug": "my-page",
  "title": "My Page",
  "owner": "admin",
  "creator": "John Doe",
  "allowExternalResources": false,
  "createdAt": "2026-04-09T11:00:00Z",
  "updatedAt": "2026-04-09T11:00:00Z",
  "files": ["index.html"]
}

Error responses:

• 400 Bad Request — Missing file or invalid slug format
• 409 Conflict — Slug already exists
• 413 Request Entity Too Large — File exceeds 10 MB limit

Get Content

GET /api/content/{slug}

Retrieve details for a specific content item.

Example request:

curl -u admin:changeme https://content.oglimmer.com/api/content/my-page

Response: 200 OK — Returns a content object (same structure as above).

Error responses:

• 404 Not Found — No content with that slug

Update Content

PUT /api/content/{slug}

Update an existing content item. All fields are optional — only provided fields are updated. Accepts multipart/form-data.

Example request:

curl -X PUT -u admin:changeme \
  -F "file=@updated.html" \
  -F "title=Updated Page" \
  https://content.oglimmer.com/api/content/my-page

Response: 200 OK — Returns the updated content object.

Error responses:

• 400 Bad Request — Invalid slug format, or a passphrase is required but missing
• 403 Forbidden — Wrong passphrase
• 404 Not Found — No content with that slug

Delete Content

DELETE /api/content/{slug}

Permanently delete a content item and all its files.

Example request:

curl -X DELETE -u admin:changeme \
  https://content.oglimmer.com/api/content/my-page

Response: 204 No Content — Empty response body on success.

Error responses:

• 404 Not Found — No content with that slug

Response Object

All endpoints that return content use this structure:

Public Serving

Uploaded content is publicly accessible at:

https://content.oglimmer.com/s/{slug}
https://content.oglimmer.com/s/{slug}/{path}

• The base URL (/s/{slug}) serves index.html
• Sub-paths resolve to files within the uploaded content
• Responses include appropriate Content-Type headers and 1-hour cache headers
• No authentication required — unless the content is encrypted (see below)

Encryption

Pass a passphrase when creating content to encrypt its files at rest. Visitors then have to enter that passphrase before anything is served.

# Upload an encrypted page
curl -u admin:changeme \
  -F "slug=private-page" \
  -F "file=@index.html" \
  -F "passphrase=correct horse battery staple" \
  https://content.oglimmer.com/api/content

How it is protected

• The passphrase derives a key with Argon2id (RFC 9106: 64 MiB, t=3, p=4, random per-content salt)
• That key wraps a random per-content data key, which seals every file with XChaCha20-Poly1305
• Only the wrapped key is stored. The passphrase is never persisted and cannot be recovered — lose it and the content is gone
• Metadata (slug, title, creator, file names) is not encrypted — only the file contents

Serving encrypted content

• GET /s/{slug} answers 401 Unauthorized with a passphrase form until the content is unlocked
• POST /unlock/{slug} with a passphrase form field (and optional next path) sets an HttpOnly cookie scoped to /s/{slug}, then redirects
• The cookie carries the decryption key for 12 hours by default, so sub-resources load without asking again
• Encrypted responses are sent Cache-Control: private, no-store and X-Robots-Tag: noindex
• Missing paths under locked content also answer 401, so the file layout stays private

Changing protection

# Encrypt content that is already public
curl -X PUT -u admin:changeme \
  -F "passphrase=new secret" \
  https://content.oglimmer.com/api/content/my-page

# Replace the files of encrypted content
curl -X PUT -u admin:changeme \
  -F "file=@updated.html" \
  -F "passphrase=new secret" \
  https://content.oglimmer.com/api/content/my-page

# Rotate the passphrase (revokes visitors who already unlocked it)
curl -X PUT -u admin:changeme \
  -F "passphrase=new secret" \
  -F "newPassphrase=even better secret" \
  https://content.oglimmer.com/api/content/my-page

# Remove encryption
curl -X PUT -u admin:changeme \
  -F "passphrase=even better secret" \
  -F "removeEncryption=true" \
  https://content.oglimmer.com/api/content/my-page

Slug Rules

• Lowercase letters, numbers, and hyphens only
• Must start and end with a letter or number
• Pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$

Limits

• Max upload size: 10 MB
• Rate limit: 10 requests/second per IP (returns 429 Too Many Requests when exceeded)
• ZIP uploads: __MACOSX and hidden files are automatically filtered
• Unlock attempts are rate limited like any other /s/ or /unlock/ request, and each attempt costs a deliberate 64 MiB Argon2id derivation