External API (v1)
Integrate FAIR voting into your hackathon or external systems. Authenticate with an API key, call the same voting and results endpoints, and stay within rate limits.
Overview
The External API is for hackathon organizers and external systems that need to:
- List and inspect hackathons and polls they own
- Fetch poll results (when allowed by poll settings)
- Validate voter tokens and submit votes programmatically
Base URL:
https://your-domain.com/api/external/v1All responses are JSON. Use HTTPS in production. Authentication is required on every request via an API key.
Authentication
Send your API key on every request using one of these methods:
- Header:
X-API-Key: <your_api_key> - Bearer token:
Authorization: Bearer <your_api_key>
API keys are created in the admin dashboard under Integrations. Each key is tied to your admin account; you can create multiple keys (e.g. one per integration) and revoke them at any time. The raw key is shown only once when you create it—store it securely.
Manage API keysEndpoints
| Method | Path | Description |
|---|---|---|
| GET | /hackathons | List hackathons for your organization |
| GET | /hackathons/:id | Get one hackathon by ID |
| GET | /hackathons/:id/polls | List polls for a hackathon |
| GET | /polls/:id | Get poll details |
| GET | /polls/:id/results | Get poll results (if public or you own the poll) |
| POST | /vote/validate | Validate a voter token; body: { "token": "..." } |
| POST | /vote/submit | Submit a vote (voter or judge); same body as the public vote API |
All paths are relative to the base URL above. Request and response shapes match the internal voting API where applicable.
Rate limits
Each API key has a requests-per-minute limit (default 60). When you exceed it, the API returns 429 Too Many Requests with a Retry-After header and a JSON body including retryAfter (seconds) and optional usage info.
You can set a higher limit per key when creating it in Integrations (e.g. for high-volume integrations). Paid plans may offer higher default limits.
How you're charged
Usage is tracked per API key for billing. Each request is recorded (endpoint and timestamp); no personally identifiable information is stored.
- Free tier: Limited requests per month; suitable for small hackathons and testing.
- Paid tiers: Higher rate limits and monthly request quotas; contact us for pricing and SLA.
Rate limits are enforced in real time. If you need a custom plan or higher limits, get in touch via the contact details on the main docs or the FAIR website.
Errors
Typical HTTP status codes and response bodies:
- 400 Bad Request — Invalid body or validation failed (e.g. missing token, invalid team ID). Response includes
errorand optionallydetails. - 401 Unauthorized — Missing or invalid/revoked API key. Provide
X-API-KeyorAuthorization: Bearer <key>. - 403 Forbidden — Valid key but no access to the resource (e.g. results not public, or you don’t own the hackathon/poll).
- 404 Not Found — Hackathon or poll ID not found.
- 429 Too Many Requests — Rate limit exceeded. Response includes
retryAfterandusage; use theRetry-Afterheader to back off. - 500 Internal Server Error — Server error; retry with backoff.