Skip to main content

Making requests

Conventions that apply across the V4 API — pagination, filtering, expanding related data, and error responses. All requests are authenticated (see Authentication).

Resource operations​

Most resources follow the standard REST pattern. For example, Events:

MethodPathDoes
GET/v4/eventsList events
GET/v4/events/{id}Get one event
POST/v4/eventsCreate an event
PATCH / PUT/v4/events/{id}Update an event

Users and Challenges follow the same shape. A few resources differ: Participations use an upsert (POST/PUT /v4/participations) plus GET/DELETE /v4/participations/{id}, and are also listed under a parent event (/v4/events/{event_id}/participations).

Pagination​

List endpoints are paginated with two query parameters:

  • page — the page number. Default 1, minimum 1.
  • limit — items per page. Default 25, minimum 1, maximum 100.
GET /v4/events?page=2&limit=50

Filtering​

Filter list results by appending an operator in brackets to a field name:

OperatorMeaning
[eq]equals
[contains]contains (case-insensitive)
[excludes]does not contain
[in]in a comma-separated list
[nin]not in a comma-separated list
[gt] / [gte]greater than / or equal
[lt] / [lte]less than / or equal
[similar]fuzzy match (e.g. school names)
GET /v4/events?name[contains]=hack&created_at[gte]=2026-01-01

By default, responses return a resource's own fields. Use expand to include related records:

GET /v4/events/{id}?expand[]=sponsors&expand[]=organizers

Common expandable associations:

  • Events: series, sponsors, sponsorships, organizers, lead_organizer, event_application, event_staffs, parent, children, prize_categories.
  • Users: education, professional_experience, social_profiles, address, identifiers, challenge_submissions.
  • Participations: event, user.

Errors​

Errors return a JSON body with an error (and usually a message, plus optional details):

{
  "error": "validation_error",
  "message": "Name can't be blank",
  "details": ["name is required"]
}

Common statuses: 401 (not authenticated), 404 (not found), 422 (validation error on create/update).