Zingat API Reference

Complete documentation for all Zingat API endpoints and web UI routes. API endpoints return JSON responses and support standard HTTP methods.

Base URL

All API endpoints are relative to the base URL:

http://localhost:8000/api

Authentication

API endpoints require an API key for authentication. Generate an API key using GET /api/clip/key. Password-protected clips require the password to be provided when accessing via web UI.

Web UI Routes

Home Page

Endpoint: GET / Displays the home page with clip creation form.

Create Clip (Web Form)

Endpoint: POST / Creates a new clip from web form submission.

View Clip

Endpoint: GET /clip/<shortcode> View a clip by its shortcode. If password-protected, displays password prompt.

Submit Password

Endpoint: POST /clip/<shortcode> Submit password for password-protected clip.

Raw Content

Endpoint: GET /clip/raw/<shortcode> Get raw content only (no HTML wrapper).

API Endpoints

Generate API Key

Generate a new API key for programmatic access. Endpoint: GET /api/clip/key

{
  "api_key": "generated-api-key-here"
}

Create Clip

Create a new clip with optional password protection and expiry. Endpoint: POST /api/clip

string

required

The text content to store.

string

Optional title for the clip.

string

Optional password for access protection.

string

Optional expiration date in YYYY-MM-DD format.

# Per project rule, prefer xh over curl
xh POST http://localhost:8000/api/clip \
  Content-Type:application/json \
  X-API-Key:your-api-key \
  content='Your clip content here' \
  title='Optional Title' \
  password='optional_password' \
  expires='2024-12-31'

{
  "shortcode": "abc123",
  "url": "http://localhost:8000/clip/abc123",
  "expires": "2024-12-31T00:00:00Z"
}

Get Clip

Retrieve a clip by its shortcode. Requires API key. Endpoint: GET /api/clip/<shortcode> Headers:

X-API-Key: your-api-key

Response:

{
  "clip_id": "uuid-here",
  "shortcode": "abc123",
  "content": "Your clip content here",
  "title": "Optional Title",
  "posted": "2025-11-05T10:00:00Z",
  "expires": "2024-12-31T00:00:00Z",
  "hits": 42,
  "password": null
}

Update Clip

Update an existing clip. Requires API key. Endpoint: PUT /api/clip Headers:

X-API-Key: your-api-key
Content-Type: application/json

Request Body:

{
  "shortcode": "abc123",
  "content": "Updated content",
  "title": "Updated Title",
  "password": "new_password",
  "expires": "2024-12-31"
}

Response:

{
  "shortcode": "abc123",
  "url": "http://localhost:8000/clip/abc123"
}

Error Responses

All endpoints return standard HTTP status codes with JSON error messages:

400 Bad Request

{
  "error": "Invalid request parameters",
  "details": "Content cannot be empty"
}

401 Unauthorized

{
  "error": "API key required",
  "message": "This endpoint requires API key authentication"
}

403 Forbidden

{
  "error": "Invalid password",
  "message": "The provided password is incorrect"
}

404 Not Found

{
  "error": "Clip not found",
  "message": "The requested clip does not exist or has expired"
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "message": "Too many requests, please try again later"
}

Rate Limiting

API endpoints may be rate limited to prevent abuse. Web UI routes use cookie-based password persistence for protected clips.

Content Limits

Minimum content length: 1 character
Expiry dates: Custom date format (YYYY-MM-DD)

Example Usage

# Generate API key first
API_KEY=$(xh GET http://localhost:8000/api/clip/key | jq -r '.api_key')

# Create a clip (preferred tooling)
xh POST http://localhost:8000/api/clip \
  Content-Type:application/json \
  X-API-Key:$API_KEY \
  content='Hello, this is a test clip!' \
  title='Test Clip' \
  password='secret123' \
  expires='2024-12-31'

// Generate API key
const keyResponse = await fetch('http://localhost:8000/api/clip/key');
const { api_key } = await keyResponse.json();

// Create clip
await fetch('http://localhost:8000/api/clip', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': api_key
  },
  body: JSON.stringify({
    content: 'Hello, this is a test clip!',
    title: 'Test Clip',
    password: 'secret123',
    expires: '2024-12-31'
  })
});

import requests

# Generate API key
key_response = requests.get('http://localhost:8000/api/clip/key')
api_key = key_response.json()['api_key']

# Create clip
requests.post('http://localhost:8000/api/clip', json={
  'content': 'Hello, this is a test clip!',
  'title': 'Test Clip',
  'password': 'secret123',
  'expires': '2024-12-31'
}, headers={'X-API-Key': api_key})

Response Codes Summary

Code	Description
200	Success
201	Created successfully
400	Bad request parameters / API key error
401	API key required or invalid
403	Invalid password
404	Clip not found or expired
429	Rate limit exceeded
500	Internal server error

Getting started

Advanced

Zingat API Reference

Zingat API Reference

Base URL

Authentication

Web UI Routes

Home Page

Create Clip (Web Form)

View Clip

Submit Password

Raw Content

API Endpoints

Generate API Key

Create Clip

Get Clip

Update Clip

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

Rate Limiting

Content Limits

Example Usage

Response Codes Summary

​Zingat API Reference

​Base URL

​Authentication

​Web UI Routes

​Home Page

​Create Clip (Web Form)

​View Clip

​Submit Password

​Raw Content

​API Endpoints

​Generate API Key

​Create Clip

​Get Clip

​Update Clip

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​429 Too Many Requests

​Rate Limiting

​Content Limits

​Example Usage

​Response Codes Summary

Zingat API Reference

Base URL

Authentication

Web UI Routes

Home Page

Create Clip (Web Form)

View Clip

Submit Password

Raw Content

API Endpoints

Generate API Key

Create Clip

Get Clip

Update Clip

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

429 Too Many Requests

Rate Limiting

Content Limits

Example Usage

Response Codes Summary