API Reference
Base URL: https://dothack.ainative.studio
Interactive docs: Swagger UI | OpenAPI spec
All endpoints require authentication unless noted otherwise. Include Authorization: Bearer <token> or X-API-Key: <key> in your request headers.
Hackathons
Create hackathon
POST /api/v1/hackathons
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Hackathon name |
| description | string | No | Detailed description |
| start_date | datetime | Yes | Start date (ISO 8601) |
| end_date | datetime | Yes | End date (ISO 8601) |
| status | string | No | DRAFT, LIVE, COMPLETED (default: DRAFT) |
| location | string | No | Physical or virtual location |
| is_online | boolean | No | Whether it's online (default: false) |
| max_participants | integer | No | Participant cap |
Get hackathon
GET /api/v1/hackathons/{hackathon_id}
List hackathons
GET /api/v1/hackathons
Query parameters: status, limit, offset
Tracks
Create track
POST /api/v1/hackathons/{hackathon_id}/tracks
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Track name (e.g., "AI/ML") |
| description | string | No | Track description |
| color | string | No | Display color (hex) |
List tracks
GET /api/v1/hackathons/{hackathon_id}/tracks
Get / Update / Delete track
GET /api/v1/hackathons/{hackathon_id}/tracks/{track_id}
PATCH /api/v1/hackathons/{hackathon_id}/tracks/{track_id}
DELETE /api/v1/hackathons/{hackathon_id}/tracks/{track_id}
Prizes
Create prize
POST /api/v1/hackathons/{hackathon_id}/prizes
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Prize name |
| description | string | No | Prize details |
| amount | number | No | Monetary value |
| currency | string | No | Currency code (USD, EUR) |
| track_id | string | No | Restrict to specific track |
List / Get / Update / Delete prizes
GET /api/v1/hackathons/{hackathon_id}/prizes
GET /api/v1/hackathons/{hackathon_id}/prizes/{prize_id}
PATCH /api/v1/hackathons/{hackathon_id}/prizes/{prize_id}
DELETE /api/v1/hackathons/{hackathon_id}/prizes/{prize_id}
Participants
Join hackathon
POST /api/v1/hackathons/{hackathon_id}/join
| Field | Type | Required | Description |
|---|---|---|---|
| role | string | Yes | builder, judge, mentor |
List participants
GET /api/v1/hackathons/{hackathon_id}/participants
Query parameters: role, limit, offset
Invite judges
POST /api/v1/hackathons/{hackathon_id}/invite-judges
Teams
Create team
POST /api/v1/hackathons/{hackathon_id}/teams
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Team name |
| description | string | No | Team description |
List / Get / Update / Delete teams
GET /api/v1/hackathons/{hackathon_id}/teams
GET /api/v1/hackathons/{hackathon_id}/teams/{team_id}
PATCH /api/v1/hackathons/{hackathon_id}/teams/{team_id}
DELETE /api/v1/hackathons/{hackathon_id}/teams/{team_id}
Manage members
POST /api/v1/hackathons/{hackathon_id}/teams/{team_id}/members
DELETE /api/v1/hackathons/{hackathon_id}/teams/{team_id}/members/{user_id}
Submissions
Create submission
POST /api/v1/hackathons/{hackathon_id}/submissions
| Field | Type | Required | Description |
|---|---|---|---|
| team_id | string | Yes | Team UUID |
| project_name | string | Yes | Project title |
| description | string | No | Project description |
| track_id | string | No | Track to submit under |
Upload file to submission
POST /api/v1/hackathons/{hackathon_id}/submissions/{submission_id}/files
Content-Type: multipart/form-data
List / Get / Update / Delete submissions
GET /api/v1/hackathons/{hackathon_id}/submissions
GET /api/v1/hackathons/{hackathon_id}/submissions/{submission_id}
PATCH /api/v1/hackathons/{hackathon_id}/submissions/{submission_id}
DELETE /api/v1/hackathons/{hackathon_id}/submissions/{submission_id}
Judging
Submit score
POST /api/v1/hackathons/{hackathon_id}/judging/scores
| Field | Type | Required | Description |
|---|---|---|---|
| submission_id | string | Yes | Submission to score |
| judge_id | string | Yes | Judge's user ID |
| scores | object | Yes | Criteria scores |
| total_score | number | Yes | Overall score |
| feedback | string | No | Written feedback |
Get leaderboard
GET /api/v1/hackathons/{hackathon_id}/judging/leaderboard
Get judge assignments
GET /api/v1/hackathons/{hackathon_id}/judging/assignments
Rubrics
Create rubric
POST /api/v1/hackathons/{hackathon_id}/rubrics
List / Get / Update / Delete rubrics
GET /api/v1/hackathons/{hackathon_id}/rubrics
GET /api/v1/hackathons/{hackathon_id}/rubrics/{rubric_id}
PATCH /api/v1/hackathons/{hackathon_id}/rubrics/{rubric_id}
DELETE /api/v1/hackathons/{hackathon_id}/rubrics/{rubric_id}
Get active rubric
GET /api/v1/hackathons/{hackathon_id}/rubrics/active
Search
Universal search
GET /api/v1/search?query=AI+chatbot&limit=10
Semantic search across all hackathons, submissions, and projects.
Hackathon-scoped search
GET /api/v1/search/{hackathon_id}?query=machine+learning&track_id=ai-ml
Dashboard
Role-based analytics dashboards:
GET /api/v1/dashboard/organizer # Organizer stats
GET /api/v1/dashboard/builder # Builder activity
GET /api/v1/dashboard/judge # Judge assignments
GET /api/v1/dashboard/{hackathon_id}/overview # Hackathon overview
Analytics & Export
Get hackathon statistics
GET /api/v1/hackathons/{hackathon_id}/analytics/stats
Export hackathon data
GET /api/v1/hackathons/{hackathon_id}/analytics/export?format=json
GET /api/v1/hackathons/{hackathon_id}/analytics/export?format=csv
Error Format
All errors follow a consistent format:
{
"error": {
"status_code": 404,
"message": "Hackathon not found",
"path": "/api/v1/hackathons/invalid-id"
}
}
| Status | Meaning |
|---|---|
| 400 | Bad request / validation error |
| 401 | Authentication required |
| 403 | Forbidden (insufficient role) |
| 404 | Resource not found |
| 422 | Validation error (see details) |
| 429 | Rate limited |
| 500 | Internal server error |
| 503 | Upstream service unavailable |
| 504 | Upstream service timeout |