API Documentation

Programmatic access to varchar(255). See endpoints for creating keys and posting varchars.

Manage API keys

Authentication

Use the web UI to log in via FreeIPA, then create API keys on the Settings page. API keys may be used in requests as a JSON field or via the Authorization header.

Create an API Key

Endpoint: POST /api/keys
Requires an authenticated session (log in via the web UI first). When successful, returns JSON containing api_key.

List API Keys

Endpoint: GET /api/keys
Response example:

{
  "ok": true,
  "keys": [{"key":"abcd...","username":"you","created_at":"2026-01-24T12:00:00"}]
}

Revoke an API Key

Endpoint: DELETE /api/keys/<key>
Requires an authenticated session and ownership of the key.

Post a Varchar

Endpoint: POST /api/post

Provide JSON body:

{
      "api_key": "YOUR_KEY",
      "text": "Your post"
    }

Or use header:

Authorization: ApiKey YOUR_KEY

curl example (JSON key)

curl -X POST -H "Content-Type: application/json" \
      -d '{"api_key":"YOUR_KEY","text":"Hello from API"}' https://varchar.tinygiant.dev/api/post

curl example (Authorization header)

curl -X POST -H "Authorization: ApiKey YOUR_KEY" -H "Content-Type: application/json" \
        -d '{"text":"Hello from API"}' https://varchar.tinygiant.dev/api/post

Examples

These examples use the current site's origin (https://varchar.tinygiant.dev). Use cookies.txt to persist session cookies when interacting with session-protected endpoints.

Create an API key (login + create)

# log in and save cookies
      curl -c cookies.txt -d "username=YOUR_USER&password=YOUR_PASS" -X POST https://varchar.tinygiant.dev/login
      # create an API key using the saved cookie
      curl -b cookies.txt -X POST https://varchar.tinygiant.dev/api/keys

List API keys

curl -b cookies.txt https://varchar.tinygiant.dev/api/keys
      # pretty-print with jq (optional)
      # curl -sS -b cookies.txt https://varchar.tinygiant.dev/api/keys | jq

Revoke an API key

# replace KEY with the key to revoke
      curl -b cookies.txt -X DELETE https://varchar.tinygiant.dev/api/keys/KEY

Post a varchar (JSON key)

curl -sS -X POST -H "Content-Type: application/json" \
          -d '{"api_key":"YOUR_KEY","text":"Hello from API"}' https://varchar.tinygiant.dev/api/post | jq

Post a varchar (Authorization header)

curl -sS -X POST -H "Authorization: ApiKey YOUR_KEY" -H "Content-Type: application/json" \
          -d '{"text":"Hello from API"}' https://varchar.tinygiant.dev/api/post | jq

Response

{
  "ok": true,
  "varchar": {"id":1,"author":"you","text":"...","created_at":"..."}
}

Notes & Limits

  • Posts are limited to 255 characters.
  • API keys should be kept secret — treat like passwords.
  • There is no rate limiting implemented; consider adding server-side limits for production.

New / Updated Endpoints

The application now exposes additional endpoints for profiles, mentions, threaded replies, and user search.

Profile (get/set)

GET /api/profile — returns the current user's profile (requires session or API key).

POST /api/profile — update your profile text. JSON body: {"profile":"Short bio"}.

Profile Photo Upload

POST /api/profile/photo — multipart form upload with field photo. Returns JSON with photo_url on success. Images are resized to 256×256 and stored under static/uploads/profiles/.

curl -b cookies.txt -F "photo=@/path/to/photo.png" https://varchar.tinygiant.dev/api/profile/photo

Replies

GET /api/v/<id>/replies — returns nested replies for a post. Example:

curl -sS https://varchar.tinygiant.dev/api/v/123/replies | jq

When posting, you may include "parent_id": 123 in the JSON body to create a reply to post 123 via /api/post.

Mentions

GET /api/mentions — list recent varchars that mention the authenticated user.

GET /api/mentions/count — returns unread mention count (compares mention timestamps to your last seen timestamp).

User Search

GET /api/users?q=<query> — search usernames. Returns JSON list of users.