--- title: "API Reference" description: "Complete API reference for all DotHack endpoints" canonical: "https://docs.ainative.studio/docs/dothack/api-reference" last-updated: "2026-11-02T18:12:43.468Z" --- # API Reference Source: https://docs.ainative.studio/docs/dothack/api-reference > Complete API reference for all DotHack endpoints # API Reference **Base URL:** `https://dothack.ainative.studio` **Interactive docs:** [Swagger UI](https://dothack.ainative.studio/v1/docs) | [OpenAPI spec](https://dothack.ainative.studio/openapi.json) All endpoints require authentication unless noted otherwise. Include `Authorization: Bearer ` or `X-API-Key: ` in your request headers. --- ## Hackathons ### Create hackathon ```http 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 ```http GET /api/v1/hackathons/{hackathon_id} ``` ### List hackathons ```http GET /api/v1/hackathons ``` Query parameters: `status`, `limit`, `offset` --- ## Tracks ### Create track ```http 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 ```http GET /api/v1/hackathons/{hackathon_id}/tracks ``` ### Get / Update / Delete track ```http 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 ```http 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 ```http 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 ```http POST /api/v1/hackathons/{hackathon_id}/join ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | role | string | Yes | builder, judge, mentor | ### List participants ```http GET /api/v1/hackathons/{hackathon_id}/participants ``` Query parameters: `role`, `limit`, `offset` ### Invite judges ```http POST /api/v1/hackathons/{hackathon_id}/invite-judges ``` --- ## Teams ### Create team ```http 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 ```http 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 ```http 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 ```http 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 ```http POST /api/v1/hackathons/{hackathon_id}/submissions/{submission_id}/files Content-Type: multipart/form-data ``` ### List / Get / Update / Delete submissions ```http 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 ```http 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 ```http GET /api/v1/hackathons/{hackathon_id}/judging/leaderboard ``` ### Get judge assignments ```http GET /api/v1/hackathons/{hackathon_id}/judging/assignments ``` --- ## Rubrics ### Create rubric ```http POST /api/v1/hackathons/{hackathon_id}/rubrics ``` ### List / Get / Update / Delete rubrics ```http 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 ```http GET /api/v1/hackathons/{hackathon_id}/rubrics/active ``` --- ## Search ### Universal search ```http GET /api/v1/search?query=AI+chatbot&limit=10 ``` Semantic search across all hackathons, submissions, and projects. ### Hackathon-scoped search ```http GET /api/v1/search/{hackathon_id}?query=machine+learning&track_id=ai-ml ``` --- ## Dashboard Role-based analytics dashboards: ```http 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 ```http GET /api/v1/hackathons/{hackathon_id}/analytics/stats ``` ### Export hackathon data ```http 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: ```json { "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 |