API Documentation

Build permanent citation infrastructure with the cit.is preservation API.

Base URL

All API endpoints are relative to your server's base URL: - Production: https://cit.is - With prefix: https://cit.is/{prefix} (where prefix is your configured URL prefix)

Authentication

Some endpoints require API key authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

Core Endpoints

Permanent Preservation

POST /_add

Create a permanent archive and citation for any URL. **Request Body:** 
{
  "url": "https://example.com",
  "shortcode": "custom-code",  // optional
  "text_fragment": "specific text to highlight"  // optional
}
**Response:** 
{
  "url": "https://cit.is/abc123",
  "shortcode": "abc123", 
  "archive_url": "https://example.com",
  "message": "Archive created."
}
**Example:** 
curl -X POST "https://cit.is/_add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "text_fragment": "important text"
  }'

Citation Access

GET /{shortcode}

View archived content with preservation overlay. **Parameters:** - `shortcode`: The shortcode identifier for the archived content **Response:** HTML page with archive overlay and citation metadata **Example:** 
curl "https://cit.is/abc123"

GET /{shortcode}.pdf

Download PDF artifact of archived content (when available). **Parameters:** - `shortcode`: The shortcode identifier **Response:** PDF file download **Example:** 
curl "https://cit.is/abc123.pdf" -o archive.pdf

Preservation Analytics

GET /_analytics/{shortcode}

Get detailed preservation and access analytics. Requires authentication. **Parameters:** - `shortcode`: The shortcode identifier **Response:** 
{
  "shortcode": "abc123",
  "url": "https://example.com",
  "created_at": "2023-06-01T12:00:00Z",
  "total_visits": 42,
  "visits": [
    {
      "visited_at": "2023-06-01T12:30:00Z",
      "country": "US"
    }
  ],
  "creator_key": "api_key_123",
  "text_fragment": "highlighted text"
}
**Example:** 
curl "https://cit.is/_analytics/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /_public_analytics/{shortcode}

Get public preservation metrics (no authentication required). **Parameters:** - `shortcode`: The shortcode identifier **Response:** Same format as `/_analytics/{shortcode}` but accessible without authentication.

Citation Management

GET /_shortcodes

List your preserved citations based on access level. **Query Parameters:** - `limit`: Maximum number of results (default: 100) - `offset`: Offset for pagination (default: 0) **Response:** 
{
  "shortcodes": [
    {
      "shortcode": "abc123",
      "url": "https://example.com",
      "created_at": "2023-06-01T12:00:00Z",
      "total_visits": 42,
      "creator_key": "api_key_123",
      "text_fragment": "highlighted text"
    }
  ],
  "total_count": 150,
  "access_level": "creator"
}
**Example:** 
curl "https://cit.is/_shortcodes?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT /_update/{shortcode}

Update an existing citation. Requires master key or creator key. **Parameters:** - `shortcode`: The shortcode to update **Request Body:** 
{
  "shortcode": "new-shortcode",  // optional
  "url": "https://new-url.com",  // optional  
  "text_fragment": "new highlight",  // optional
  "created_at": "2023-06-01T12:00:00Z"  // optional, master only
}
**Response:** 
{
  "message": "Citation updated successfully",
  "shortcode": "new-shortcode",
  "updated_fields": ["url", "text_fragment"]
}

Access Management

POST /_api/keys

Create a new API key for citation management. Requires master key. **Request Body:** 
{
  "account": "[email protected]",
  "description": "Academic research integration",
  "max_uses_total": 1000,  // optional
  "max_uses_per_day": 100  // optional
}
**Response:** 
{
  "api_key": "generated_key_here",
  "account": "[email protected]",
  "description": "Academic research integration",
  "max_uses_total": 1000,
  "max_uses_per_day": 100,
  "is_active": true
}

PUT /_api/keys/{api_key}

Update an existing API key. Requires master key. **Parameters:** - `api_key`: The API key to update **Request Body:** 
{
  "max_uses_total": 2000,  // optional
  "max_uses_per_day": 200,  // optional
  "is_active": false  // optional
}
**Response:** 
{
  "message": "API key updated successfully"
}

System Information

GET /_health

Health check endpoint. **Response:** 
{
  "status": "healthy"
}

GET /_info

Get service information. **Response:** 
{
  "service": "cit.is Citation Preservation Service",
  "archive_mode": "singlefile",
  "prefix": "archive"
}

GET /_cache/stats

Get preservation cache statistics. **Response:** 
{
  "api_cache": {
    "entries": 50,
    "max_entries": 1000
  },
  "file_cache": {
    "entries": 10,
    "max_entries": 100
  },
  "visits": {
    "total_visits": 1234,
    "unique_shortcodes": 56
  }
}

DELETE /_cache/clear

Clear all preservation caches. Requires master key. **Response:** 
{
  "message": "All caches cleared"
}

DELETE /_cache/pages

Clear page cache. Requires master key. **Response:** 
{
  "message": "Page cache cleared"
}

Error Responses

All endpoints may return these error responses:

  • 400 Bad Request: Invalid request format or parameters
  • 401 Unauthorized: Missing or invalid API key
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource already exists (e.g., shortcode collision)
  • 500 Internal Server Error: Server error

Error Format: 

{
  "detail": "Error message describing what went wrong"
}

Rate Limiting

API keys can have usage limits: - Total Usage Limit: Maximum number of requests across the key's lifetime - Daily Usage Limit: Maximum number of requests per day

When limits are exceeded, you'll receive a 401 Unauthorized response.

Integration Examples

Academic Research Workflow

# 1. Create API key for research project (requires master key)
curl -X POST "https://cit.is/_api/keys" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer MASTER_KEY" \
  -d '{
    "account": "[email protected]",
    "description": "Climate change research project",
    "max_uses_per_day": 100
  }'

# 2. Preserve a source with highlighted text
curl -X POST "https://cit.is/_add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer RESEARCHER_API_KEY" \
  -d '{
    "url": "https://nature.com/articles/climate-study-2023",
    "text_fragment": "global temperature increased by 1.2°C"
  }'

# 3. Access the permanent citation
curl "https://cit.is/abc123"

# 4. Get preservation analytics
curl "https://cit.is/_analytics/abc123" \
  -H "Authorization: Bearer RESEARCHER_API_KEY"

Journalism Integration

# Preserve source material for article
curl -X POST "https://cit.is/_add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer JOURNALIST_API_KEY" \
  -d '{
    "url": "https://government.gov/official-statement",
    "shortcode": "gov-statement-2023"
  }'

# Download PDF artifact for records
curl "https://cit.is/gov-statement-2023.pdf" -o official-statement.pdf

Open Source Foundation

cit.is is built on the deepcite open-source preservation engine, licensed under AGPLv3. The code is available for inspection, contribution, and independent deployment.

For questions or support, please refer to the project repository or create an issue on our open-source forge.