Alivator
DocumentationREST API Reference

REST API Reference

Complete reference for all Alivator API endpoints.

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header:

Authorization Header

Authorization: Bearer YOUR_API_KEY

Rate Limits

Starter Plan

1,000

requests/day

Pro Plan

10,000

requests/day

Enterprise

Custom

Contact sales

Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

GET /events

Retrieve a list of available events across all categories.

Parameters

ParameterTypeDescription
categorystringFilter by category: "sports", "weather", "economic", "crypto", "news"
statusstringFilter by status: "active" or "resolved"
limitintegerMaximum number of results (default: 20, max: 100)
offsetintegerNumber of results to skip (default: 0)
sortBystringSort by field: "probability", "timestamp", "confidence"

Example Request

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.alivator.com/v1/events?category=sports&limit=10&sortBy=probability"

Example Response

Response

{
  "data": [
    {
      "id": "evt_1001",
      "category": "sports",
      "name": "World Cup Final Winner",
      "description": "Will Argentina win the World Cup?",
      "status": "active",
      "probability": 0.82,
      "confidence": 0.95,
      "resolved": false,
      "timestamp": "2026-01-15T14:30:00Z",
      "resolutionDate": "2026-12-18T00:00:00Z",
      "volume": 1500000
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0,
    "timestamp": "2026-01-15T14:30:00Z"
  }
}

GET /events/:id

Retrieve details for a specific event.

Path Parameters

ParameterTypeDescription
id*stringEvent ID (e.g., evt_1001)

Example Request

Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.alivator.com/v1/events/evt_1001

Example Response

Response

{
  "data": {
    "id": "evt_1001",
    "category": "sports",
    "name": "World Cup Final Winner",
    "description": "Will Argentina win the World Cup?",
    "status": "active",
    "probability": 0.82,
    "confidence": 0.95,
    "resolved": false,
    "timestamp": "2026-01-15T14:30:00Z",
    "resolutionDate": "2026-12-18T00:00:00Z",
    "volume": 1500000,
    "historicalProbabilities": [
      { "timestamp": "2026-01-14T14:30:00Z", "probability": 0.80 },
      { "timestamp": "2026-01-13T14:30:00Z", "probability": 0.78 }
    ]
  }
}

GET /status

Check the operational status of the API. This endpoint does not require authentication.

Example Request

Request

curl https://api.alivator.com/v1/status

Example Response

Response

{
  "status": "operational",
  "version": "v1",
  "timestamp": "2026-01-15T14:30:00Z",
  "uptime": 99.97,
  "latency": 45
}

Error Codes

400

Bad Request

Invalid request parameters

401

Unauthorized

Missing or invalid API key

403

Forbidden

API key lacks permission

404

Not Found

Resource not found

429

Rate Limit Exceeded

Too many requests

500

Server Error

Internal server error

Pagination

Results are paginated by default. Use offset and limit parameters to navigate:

Pagination Examples

# Get first 20 results
https://api.alivator.com/v1/events?limit=20&offset=0

# Get next 20 results
https://api.alivator.com/v1/events?limit=20&offset=20

# Get next 20 results
https://api.alivator.com/v1/events?limit=20&offset=40

Webhooks (Pro Plan)

Pro plan customers can subscribe to webhooks for real-time event updates. Contact support to configure webhooks for your application.

  • • event.created - New event added
  • • event.updated - Event probability changed
  • • event.resolved - Event reached resolution
  • • event.cancelled - Event was cancelled