API Reference

Authentication

All requests require a valid API key passed as a Bearer token in the Authorization header.

curl https://www.paranormalobserver.com/v1/reports \
  -H "Authorization: Bearer po_live_your_api_key_here"

Base URL

https://www.paranormalobserver.com/v1

Endpoints

GET /v1/reports

Returns a paginated list of published sighting reports, newest first.

Query Parameters

Example

curl "https://www.paranormalobserver.com/v1/reports?category=UFO&limit=5" \
  -H "Authorization: Bearer po_live_..."

Response

{
  "data": [
    {
      "id": "uuid",
      "title": "Triangular craft over Route 9",
      "categories": ["UFO"],
      "hynek_class": "NL",
      "sighting_date": "2024-08-14",
      "sighting_time": "22:30:00",
      "narrative": "...",
      "quality_score": 72,
      "witness_count": 2,
      "created_at": "2024-08-15T10:00:00Z",
      "url": "https://www.paranormalobserver.com/report/uuid"
    }
  ],
  "meta": {
    "total": 342,
    "limit": 5,
    "offset": 0,
    "has_more": true
  },
  "rate_limit": {
    "limit": 100,
    "remaining": 94,
    "reset_at": "2024-08-16T00:00:00Z"
  }
}

GET /v1/reports/:id

Returns a single report with full location, witness, and evidence detail.

curl "https://www.paranormalobserver.com/v1/reports/uuid-here" \
  -H "Authorization: Bearer po_live_..."

Response

{
  "data": {
    "id": "uuid",
    "title": "...",
    "categories": ["Ghost"],
    "hynek_class": null,
    "sighting_date": "2024-06-01",
    "sighting_time": "02:15:00",
    "duration": "10 minutes",
    "narrative": "...",
    "quality_score": 61,
    "witness_count": 1,
    "location": {
      "display": "Rural Vermont",
      "setting": "rural",
      "coordinates": { "lat": 44.26, "lng": -72.57 }
    },
    "witness": {
      "group_size": 1,
      "age_range": "30-39",
      "prior_belief": "skeptic"
    },
    "evidence": [
      {
        "id": "uuid",
        "type": "image/jpeg",
        "description": "Photo taken at scene",
        "url": "https://..."
      }
    ],
    "created_at": "...",
    "url": "https://www.paranormalobserver.com/report/uuid"
  },
  "rate_limit": { ... }
}

GET /v1/stats

Returns aggregate statistics for the entire archive.

curl "https://www.paranormalobserver.com/v1/stats" \
  -H "Authorization: Bearer po_live_..."

Response

{
  "data": {
    "total_reports": 1247,
    "reports_last_30_days": 38,
    "categories": [
      { "name": "UFO", "count": 521 },
      { "name": "Ghost", "count": 312 }
    ],
    "hynek_classes": [
      { "name": "NL", "count": 287 },
      { "name": "CE1", "count": 156 }
    ],
    "generated_at": "2024-08-15T12:00:00Z"
  },
  "rate_limit": { ... }
}

Rate Limiting

Rate limits are per API key, per 24-hour rolling window. Response headers show current usage.

When exceeded, the API returns HTTP 429. Upgrade to Observer+ for 1,000 requests/day and up to 5 keys.

Error Codes

{
  "error": "Rate limit exceeded. Resets at Thu, 15 Aug 2024 00:00:00 GMT."
}