pbar.io

API Reference

Complete reference for the pbar.io REST API.

Base URL

https://pbar.io/api

Authentication

The pbar.io API supports both anonymous and authenticated access:

🔓 Anonymous Access (Free Tier)

  • No authentication required
  • Progress bars expire after 30 days
  • Rate limiting planned: 100 creates/hour, 5000 updates/hour per IP
  • All bars are publicly accessible

🔒 Authenticated Access (Coming Soon)

  • Use API key in X-API-Key header
  • No expiration on progress bars
  • Private progress bars supported
  • Higher rate limits

Endpoints

POST/bars

Create a new progress bar.

Request Body

{
  "title": "Training Model",      // Required: Display name
  "total": 1000,                  // Required: Total value (must be > 0)
  "current": 0,                   // Optional: Starting value (default: 0)
  "unit": "items",                // Optional: Unit label
  "metadata": {},                 // Optional: Custom metadata object
  "parent_slug": "abc123",        // Optional: Parent bar slug for hierarchy
  "is_public": true,              // Optional: Public visibility (default: true)
  "is_writable": true             // Optional: Allow updates (default: true)
}

Response

{
  "slug": "k3n4x2m",
  "url": "https://pbar.io/k3n4x2m",
  "api_url": "https://pbar.io/api/bars/k3n4x2m",
  "title": "Training Model",
  "total": 1000,
  "current": 0,
  "percentage": 0,
  "is_writable": true,
  "expires_at": "2025-01-01T12:00:00Z",
  "created_at": "2025-01-01T07:00:00Z"
}

Status Codes

  • 201 - Progress bar created successfully
  • 400 - Invalid request parameters
  • 429 - Rate limit exceeded
  • 500 - Server error

GET/bars/{slug}

Retrieve progress bar information. Response format depends on Accept header.

Path Parameters

  • slug - The unique identifier of the progress bar

Query Parameters

  • format - Override response format: simple, inline, full (terminal only)
  • children - Include child bars: true (default), false

Response Formats

JSON (Accept: application/json)

{
  "slug": "k3n4x2m",
  "title": "Training Model",
  "current": 523,
  "total": 1000,
  "percentage": 52.3,
  "rate": 10.5,
  "elapsed_seconds": 49.8,
  "eta_seconds": 45.3
}

Terminal (Accept: text/plain or curl user-agent)

Training Model: 52.3% |████████░░░░░░░| 523/1000 [00:49<00:45, 10.5 it/s]

HTML (Accept: text/html)

Redirects to web view at /{slug}

Status Codes

  • 200 - Success
  • 401 - Unauthorized (private bar)
  • 404 - Progress bar not found

PATCH/bars/{slug}

Update progress bar. Use either increment or current, not both.

Request Body

// Option 1: Increment current value
{
  "increment": 10
}

// Option 2: Set specific value
{
  "current": 500
}

// Option 3: Update other fields
{
  "current": 500,
  "title": "Updated Title",
  "total": 2000,
  "metadata": {"key": "value"}
}

// Option 4: Cancel the progress bar
{
  "cancelled": true
}

Response

{
  "slug": "k3n4x2m",
  "current": 510,
  "total": 1000,
  "percentage": 51.0,
  "updated_at": "2025-01-01T07:05:00Z"
}

Status Codes

  • 200 - Successfully updated
  • 400 - Invalid parameters or bar not writable
  • 404 - Progress bar not found
  • 429 - Rate limit exceeded

DELETE/bars/{slug}

Delete a progress bar and all its children.

Example

curl -X DELETE https://pbar.io/api/bars/k3n4x2m

Status Codes

  • 204 - Successfully deleted
  • 403 - Bar is not writable
  • 404 - Progress bar not found

Rate Limiting 🚧 Coming Soon

Free tier requests will be rate limited per IP address (currently not enforced):

  • Create (POST): 100 requests per hour
  • Update (PATCH): 5,000 requests per hour (planned)
  • Read (GET): Unlimited
  • Delete (DELETE): 100 requests per hour

When implemented, rate limit headers will be included in responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Error Responses

All error responses follow a consistent format:

{
  "error": "Descriptive error message",
  "code": "ERROR_CODE",        // Optional error code
  "details": {}                // Optional additional details
}

Real-time Updates

Progress bars support real-time updates via WebSockets. When viewing a progress bar in the browser, updates are automatically pushed to all connected clients.

WebSocket Connection

Connect to receive real-time updates for a specific progress bar:

wss://pbar.io/ws/bars/{slug}