NZ Tech Events API

Programmatic access to New Zealand tech event listings.

Base URL

https://techevents.co.nz/api/v1/

You can also use /api/latest/ which always points to the current API version.

Authentication

Public endpoints (listing and viewing events) require no authentication. Creating, updating, and deleting events requires a bearer token.

Getting a Token

Approved organisers and admins can generate API tokens from the API Tokens page (requires sign-in).

Using a Token

Include the token in the Authorization header:

Authorization: Bearer techevents_your_token_here

Example (curl)

curl -H "Authorization: Bearer techevents_your_token" \
     https://techevents.co.nz/api/v1/events/mine

Endpoints

List Events

GET /api/v1/events — No auth required

Returns approved upcoming events by default.

Query Parameters

ParamTypeDescription
scopestringupcoming (default) or past
regionstringFilter by region (e.g., auckland, wellington, online)
citystringFilter by city name (requires region)
event_typestringFilter by type (e.g., meetup, conference)
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 25, max: 100)

Example Response

{
  "events": [
    {
      "id": 1,
      "title": "Ruby Meetup Auckland",
      "description": "Plain text description...",
      "description_markdown": "**Markdown** description...",
      "short_summary": "Brief summary",
      "start_date": "2026-04-15",
      "end_date": null,
      "start_time": "18:00",
      "end_time": "20:00",
      "cost": "Free",
      "event_type": "meetup",
      "registration_url": "https://...",
      "address": "123 Queen St",
      "locations": [
        { "region": "auckland", "city": "Auckland CBD" }
      ],
      "approved": true,
      "created_at": "2026-03-20T10:00:00Z",
      "updated_at": "2026-03-20T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 1,
    "total_count": 1,
    "per_page": 25
  }
}

Show Event

GET /api/v1/events/:id — No auth required

Returns a single approved event. Returns 404 if the event doesn't exist or isn't approved.


My Events

GET /api/v1/events/mine — Auth required

Returns all events owned by the token holder, including unapproved events. Supports page and per_page parameters.


Create Event

POST /api/v1/events — Auth required

Request Body

{
  "event": {
    "title": "My Event",
    "description_markdown": "Event description in **Markdown**",
    "short_summary": "Brief summary (optional)",
    "start_date": "2026-04-15",
    "end_date": "2026-04-16",
    "start_time": "09:00",
    "end_time": "17:00",
    "cost": "Free",
    "event_type": "meetup",
    "registration_url": "https://example.com",
    "address": "123 Queen Street",
    "source": "Events in Aotearoa",
    "source_url": "https://example.com/source",
    "locations": [
      { "region": "auckland", "city": "Auckland CBD" }
    ]
  }
}

Required Fields

FieldType
titlestring (max 200 chars)
description_markdownstring (Markdown or plain text)
start_datedate (YYYY-MM-DD)
event_typestring (see valid values below)
locationsarray (at least one with region)

Returns 201 Created with the event JSON on success, or 422 with validation errors.


Update Event

PATCH /api/v1/events/:id — Auth required

Update an event you own. All fields are optional (partial updates). If locations is provided, it replaces all existing locations.


Delete Event

DELETE /api/v1/events/:id — Auth required

Delete an event you own.

Valid Enum Values

Event Types

conference, meetup, workshop, hackathon, webinar, networking, other, talk, awards

Regions

northland, auckland, waikato, bay_of_plenty, gisborne, hawkes_bay, taranaki, manawatu_whanganui, wellington, tasman, nelson, marlborough, west_coast, canterbury, otago, southland, apac, online

Error Responses

All errors return JSON with consistent structure:

{ "error": "Not found", "status": 404 }

Validation errors include field-level detail:

{
  "errors": {
    "title": ["can't be blank"],
    "base": ["at least one location is required"]
  },
  "status": 422
}
CodeMeaning
200Success
201Created
401Missing or invalid token
403Not the event owner
404Not found
422Validation errors
429Rate limited

Rate Limiting

ScopeLimit
Read endpoints (index, show, mine)120 requests per minute
Write endpoints (create, update, delete)30 requests per minute

Exceeding the limit returns 429 Too Many Requests.

Machine-Readable Spec

A JSON spec is available at /api/v1/spec.json (also at /api/latest/spec.json).