canonical: https://jentic.com/apis/heyhack.com/heyhack

# Heyhack API

The Heyhack API offers a focused interface for hackathon and event management. Across three endpoints, organisers can list and create hackathons and register teams for an event. Authentication uses an API key passed in the Authorization header, generated from the Heyhack platform. The narrow surface makes the API a fit for organisers who need to programmatically expose hackathon listings on a community site or onboard teams from a custom signup form.

## For AI agents

List existing hackathons, create new ones, and register teams via API key authentication for the Heyhack hackathon-management platform.

## Scope

Does not handle judging, sponsor billing, or project submissions - use for listing hackathons and registering teams only.

## Capabilities

- List all hackathons currently visible to the authenticated organiser
- Create a new hackathon record on Heyhack with title, dates, and metadata
- Register a team for a hackathon by submitting team details to POST /teams
- Embed a live hackathon list on a community site by polling GET /hackathons
- Automate team intake from a Typeform or custom signup page into Heyhack

## Use cases

### Community Event Listing

Developer communities and university programs use GET /hackathons to power a 'live hackathons' page on their site, polled hourly to reflect new events without manual updates. The same call can drive a Slack or Discord bot that announces new hackathons as they're created in Heyhack.

Example prompt: Call GET /hackathons, filter for events with start_date in the next 30 days, and post the titles to a Slack channel.

### Programmatic Team Registration

Organisers bypass the standard signup form by sending team details directly to POST /teams from a custom landing page or partner platform. This lets organisers integrate hackathon registration into existing community signup flows while Heyhack still owns team data and event coordination.

Example prompt: Submit POST /teams with name 'Quantum Otters', members array, and hackathon_id 1234, then confirm the team appears in GET /hackathons output.

### Programmatic Hackathon Provisioning

Sponsors running multiple events provision hackathon records via POST /hackathons from an internal admin tool, attaching dates, sponsor logos, and prize details. This avoids manual setup in the Heyhack UI when launching dozens of regional or themed events at once.

Example prompt: Call POST /hackathons with title 'Climate Tech Sprint', start_date and end_date, and a sponsor list, then verify the new hackathon id is returned.

### AI Agent Event Coordination

Through Jentic, an AI assistant can answer 'what hackathons are running this month?' by calling GET /hackathons or register a team on a user's behalf. Jentic's vault holds the API key, so the agent never sees the credential while still completing multi-step coordination.

Example prompt: Search Jentic for 'list hackathons', execute GET /hackathons, and summarise the upcoming events in plain language.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/hackathons` | List all hackathons |
| POST | `/hackathons` | Create a new hackathon |
| POST | `/teams` | Register a team for a hackathon |

## Key resources

- **Hackathons** — List existing hackathons or create a new event
- **Teams** — Register a team for a hackathon

## Why Jentic

- **Setup:** Wiring the Heyhack API by hand means learning its API key auth passed in the Authorization header and writing your own retry logic around its hackathon and team endpoints. Through Jentic you install once, import the Heyhack API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Heyhack takes the hackathon and team details in the request body rather than a resource id in the path, so limit the agent to the operations it needs, such as listing hackathons. You choose the operations it may call, so creating a hackathon or registering a team is only included if you add it.
- **Credential handling:** Your Heyhack API key is stored once, encrypted, by your own Jentic One instance and injected as the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list hackathons' or 'register a team', and Jentic returns the matching Heyhack operation with its input schema so the agent calls the right endpoint without scanning the spec.

## Related APIs

- **Calendly API** — Calendly handles scheduling for participant interviews, mentor sessions, and judging slots around a hackathon
- **GitHub API** — GitHub manages the project repositories and code submissions teams produce during the hackathon
- **OpenAI API** — OpenAI provides language model inference for summarising hackathon submissions or matching teams with mentors

## FAQ

### What authentication does the Heyhack API use?

Heyhack uses an API key passed as a token in the Authorization header. Through Jentic, the key is stored encrypted in the vault and injected at execution time, so the agent never holds the raw value.

### Can I register a team for a hackathon with the Heyhack API?

Yes. POST /teams accepts the team name, members, and target hackathon_id. The same call can be wired to a custom signup form so registrations flow into Heyhack without using the default UI.

### How many endpoints does the Heyhack API expose?

The current spec covers three endpoints: GET /hackathons, POST /hackathons, and POST /teams. The surface is intentionally narrow and focused on listing events and onboarding teams.

### How do I list hackathons through Jentic?

Run pip install jentic, search for 'list hackathons', and execute against GET /hackathons. Jentic resolves the API key from the vault and returns the JSON response so the agent can filter or summarise the events.

### Does the Heyhack API support webhooks for new registrations?

Webhook delivery is not exposed in the current spec; new team registrations are observed by polling GET /hackathons or by relying on Heyhack's UI-side notifications. For real-time mirroring, schedule a periodic GET and diff the team list.

### Can I limit what my agent is allowed to do with the Heyhack API?

Yes. Because you run Jentic One yourself, you decide which Heyhack operations your agent may call, so you can allow read-only listing through GET /hackathons while leaving out POST /hackathons and POST /teams. Since Heyhack passes hackathon and team details in the request body rather than a resource id in the path, scoping happens at the operation level: creating a hackathon or registering a team is only reachable if you add it. Your API key is held by your own instance and injected at call time, so the agent acts only within the operations and credentials your rules permit.