API Reference

Complete API endpoint documentation

Authentication

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

Header Format

Authorization: Bearer sk_live_your_api_key_here

Get your API key: Dashboard → API Keys (Pilot+ required)

Base URL

All API requests should be made to:

https://api.senraio.com/api/v1

Or use /api/v1 if accessing via your domain.

Predictions

GET/predict/{bill_id}

All Tiers

Get predictions for a specific bill, including Royal Assent probability, next stage timing, and next stage ETA estimates.

Parameters

Parameter	Type	Description
bill_id	integer	UK Parliament bill ID (path parameter)
reference_date	string (optional)	Reference date in YYYY-MM-DD format. Defaults to today.

Example Request

cURL

curl -X GET "https://api.senraio.com/api/v1/predict/12345?reference_date=2025-12-18" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

200 OK

{
  "bill_id": "12345",
  "mode": "nowcast",
  "reference_date": "2025-12-18",
  "predictions": {
    "royal_assent": {
      "bill_id": "12345",
      "prediction": "royal_assent",
      "probability": 0.87,
      "reference_date": "2025-12-18"
    },
    "next_stage_30d": {
      "bill_id": "12345",
      "prediction": "next_stage_30d",
      "probability": 0.92,
      "reference_date": "2025-12-18"
    },
    "timeline_eta": {
      "bill_id": "12345",
      "prediction": "timeline_eta",
      "days": 14.5,
      "reference_date": "2025-12-18"
    },
    "stall_risk": {
      "bill_id": "12345",
      "prediction": "stall_risk",
      "probability": 0.15
    },
    "amendment_risk": {
      "bill_id": "12345",
      "prediction": "amendment_risk",
      "probability": 0.32
    },
    "close_vote": {
      "bill_id": "12345",
      "prediction": "close_vote",
      "probability": 0.28
    },
    "withdrawal_risk": {
      "bill_id": "12345",
      "prediction": "withdrawal_risk",
      "probability": 0.08
    }
  },
  "risk_indicators": {
    "controversy_score": 0.45,
    "momentum_score": 0.72,
    "stall_risk_level": "low",
    "withdrawal_risk_level": "low"
  }
}

New Prediction Types:

• stall_risk: Probability bill will stall (>200 days without progress) (0.0-1.0)
• amendment_risk: Probability bill will face significant amendments (0.0-1.0)
• close_vote: Probability bill will face close votes (<10% margin) (0.0-1.0)
• withdrawal_risk: Probability bill will be withdrawn/abandoned (0.0-1.0)
• risk_indicators: Object with controversy_score (0.0-1.0), momentum_score (0.0-1.0), stall_risk_level ("low"|"medium"|"high"), withdrawal_risk_level ("low"|"medium"|"high")

POST/predictions/batch

Pilot+

Get predictions for multiple bills in a single request. Up to 100 bills per request. Rate limits: 10/day (Pilot), 100/day (Pro).

Request Body

JSON

{
  "bill_ids": [12345, 12346, 12347],
  "reference_date": "2025-12-18"
}

Response

200 OK

{
  "results": [
    {
      "bill_id": 12345,
      "status": "success",
      "predictions": {
        "royal_assent": { "probability": 0.87 },
        "next_stage_30d": { "probability": 0.92 },
        "timeline_eta": { "days": 14 },
        "stall_risk": { "probability": 0.15 },
        "amendment_risk": { "probability": 0.32 },
        "close_vote": { "probability": 0.08 },
        "withdrawal_risk": { "probability": 0.05 }
      },
      "risk_indicators": {
        "stall_risk_level": "low",
        "amendment_risk_level": "medium",
        "close_vote_level": "low",
        "withdrawal_risk_level": "low",
        "controversy_score": 0.45,
        "momentum_score": 0.72
      },
      "metadata": {
        "title": "Example Bill",
        "chamber": "Commons",
        "stage": "Committee Stage"
      }
    },
    ...
  ],
  "summary": {
    "total": 3,
    "success": 3,
    "errors": 0,
    "blocked": 0
  },
  "execution_time_ms": 1250
}

Risk Predictions in Batch:

• Each result includes predictions object with all 4 risk predictions
• risk_indicators provides risk levels and scores for analysis
• Risk probabilities are 0.0-1.0 (multiply by 100 for percentage)
• Risk levels: "low" (<0.3), "medium" (0.3-0.7), "high" (>0.7)

GET/predictions/imminent

All Tiers

Get bills that are likely to progress soon based on Timeline ETA. Returns bills with urgency indicators, countdown timers, and time bucket grouping. Perfect for early alerts and knowing when bills are advancing.

Query Parameters

Parameter	Type	Description
days_ahead	integer (optional)	Number of days to look ahead (1-30). Default: 7
min_probability	float (optional)	Minimum next stage probability (0.0-1.0). Default: 0.5

Example Request

cURL

curl -X GET "https://api.senraio.com/api/v1/predictions/imminent?days_ahead=14&min_probability=0.7" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response

200 OK

{
  "bills": [
    {
      "bill_id": 12345,
      "timeline_eta_days": 5,
      "royal_assent_probability": 0.85,
      "next_stage_probability": 0.92,
      "predicted_date": "2025-12-28",
      "urgency_level": "urgent",
      "countdown_days": 5,
      "time_bucket": "week",
      "urgency_score": 0.89
    },
    ...
  ],
  "count": 12
}

Response Fields:

• urgency_level: "critical", "urgent", "soon", "tracking", or "none"
• countdown_days: Days until next stage
• time_bucket: "today", "week", "two_weeks", "month", or null
• urgency_score: Calculated urgency score (0-1)
• stall_risk: Probability bill will stall (0.0-1.0, optional)
• amendment_risk: Probability bill will face significant amendments (0.0-1.0, optional)
• close_vote: Probability bill will face close votes (0.0-1.0, optional)
• withdrawal_risk: Probability bill will be withdrawn (0.0-1.0, optional)
• risk_indicators: Object with controversy_score, momentum_score, and risk levels (optional)

Predictive Alerts (Pilot+)

Get notified BEFORE bills change. Predictive Alerts use machine learning to forecast bill progression and alert you 30+ days in advance.

GET/predictions/imminent

Pilot+

View bills likely to change within your specified timeframe. All tiers can view, but alerts require Pilot+.

POST/predictions/alerts/thresholds

Pilot+

Create an alert threshold. Pilot: 5 per watchlist. Pro: Unlimited.

Request Body

JSON

{
  "watchlist_id": 1,
  "bill_id": null,
  "alert_type": "timeline_eta",
  "threshold_value": 7.0,
  "comparison": "less_than"
}

Alert Types

timeline_eta - Days until next stage (NOT Royal Assent)
probability - Royal Assent probability
trend - Upward trend detection (Pro)
spike - Probability spike (Pro)
Risk-Based Alerts (Phase 2):
stall_risk - Stall risk probability (0.0-1.0). Alert when risk exceeds threshold.
amendment_risk - Amendment risk probability (0.0-1.0). Alert when risk exceeds threshold.
close_vote - Close vote risk probability (0.0-1.0). Alert when risk exceeds threshold.
withdrawal_risk - Withdrawal risk probability (0.0-1.0). Alert when risk exceeds threshold.

Risk Alert Example: Create alert for stall_risk > 0.7 to be notified when a bill has high risk of stalling.

GET/predictions/alerts/thresholds

Pilot+

Get all alert thresholds for your account.

POST/predictions/alerts/check

Pilot+

Manually check for triggered alerts. Pro users have automated hourly checking.

GET/predictions/alerts/history

Pro

Get alert trigger history and analytics. Pro only.

Watchlists (Pilot+)

Organize bills into watchlists for easier monitoring and alerting.

GET /dashboard/watchlists

List all watchlists

POST /dashboard/watchlists

Create watchlist

GET /dashboard/watchlists/{id}

Get watchlist details

DELETE /dashboard/watchlists/{id}

Delete watchlist

Webhooks (Pilot+)

Receive real-time notifications when events occur. Webhooks use HMAC-SHA256 signatures for security.

Event Types

prediction.updated - Prediction changed
bill.stage_changed - Bill progressed to new stage
prediction.imminent_stage_change - Bill likely to progress (Pilot+)
prediction.high_probability - High probability event (Pilot+)
prediction.probability_spike - Probability spike (Pro)
prediction.trending_up - Upward trend (Pro)
prediction.crossed_threshold - Threshold crossed (Pro)

Rate Limits

Rate limits vary by subscription tier. Limits are enforced per user, not per API key.

Tier	API Calls/Day	Batch Requests/Day	Predictions/Day
Free	0	0	1 (website only)
Pilot	1,000	10	100
Pro	Unlimited	100	Unlimited

Rate Limit Headers: Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers.

Error Handling

All errors follow a consistent format with HTTP status codes.

Status Code	Description
200	Success
400	Bad Request (invalid parameters)
401	Unauthorized (invalid or missing API key)
403	Forbidden (insufficient permissions or tier)
404	Not Found (bill or resource doesn't exist)
429	Too Many Requests (rate limit exceeded)
500	Internal Server Error

Error Response Format

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

Try It Live

Test endpoints directly in your browser with our interactive API documentation.