Querying events

Use POST /api/events/query when you need to find multiple events. The request body controls the authorization scope, filters, sort order, and page size.

This guide queries one project with an API key. The same operation can also use a bearer token as described in the authentication guide.

Before you begin

You need:

• the HIO API base URL;
• an API key assigned to the project; and
• the project’s GUID.

HIO_API_URL="https://api.example.com"
HIO_API_KEY="your-issued-api-key"
HIO_PROJECT_ID="00000000-0000-0000-0000-000000000000"

Make a basic query

The projects array limits the query to projects the credential is authorized to access. Page numbers start at 1 in this example.

curl --request POST \
  --url "$HIO_API_URL/api/events/query" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "x-api-key: $HIO_API_KEY" \
  --data "{
    \"page\": 1,
    \"itemsPerPage\": 25,
    \"sort\": \"start\",
    \"sortDir\": \"Asc\",
    \"projects\": [\"$HIO_PROJECT_ID\"]
  }"

For an external integration, the request must include at least one authorized scope: organizations, projects, eventIds, topLevelIds, or parentIds. The request is rejected if the credential cannot access every identifier in the selected scope.

Understand the response

A successful response is a paged query result:

{
  "page": 1,
  "itemsPerPage": 25,
  "count": 57,
  "numberOfPages": 3,
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Opening session",
      "start": "2026-09-15T13:00:00Z"
    }
  ]
}

The event objects can contain more fields than this shortened example. Use the generated operation reference as the source of truth for the current request and response schemas.

Filter by text and time

Add terms, startUtc, and endUtc to find matching events in a UTC time window:

{
  "page": 1,
  "itemsPerPage": 25,
  "sort": "start",
  "sortDir": "Asc",
  "projects": ["00000000-0000-0000-0000-000000000000"],
  "terms": "workshop",
  "startUtc": "2026-09-15T00:00:00Z",
  "endUtc": "2026-09-16T00:00:00Z"
}

Common filters include:

Field	Purpose
terms	Search text associated with an event.
eventTypes	Include events with selected event-type GUIDs.
categories	Include events associated with selected category GUIDs.
parentIds	Find child events for selected parent-event GUIDs.
topLevelOnly	Limit results to top-level events.
publish	Filter by published state.
timePeriodFilter	Use All, Upcoming, or Past.

Omit unused optional filters instead of sending empty values. This makes the request easier to read and avoids unintentionally changing the query.

Query from JavaScript

The example below keeps credentials on a trusted server and checks the response before reading the result.

const response = await fetch(`${process.env.HIO_API_URL}/api/events/query`, {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'x-api-key': process.env.HIO_API_KEY,
  },
  body: JSON.stringify({
    page: 1,
    itemsPerPage: 25,
    sort: 'start',
    sortDir: 'Asc',
    projects: [projectId],
    timePeriodFilter: 'Upcoming',
  }),
});

if (!response.ok) {
  const details = await response.text();
  throw new Error(`HIO event query failed (${response.status}): ${details}`);
}

const contentType = response.headers.get('content-type') ?? '';
if (!contentType.includes('application/json')) {
  const details = await response.text();
  throw new Error(`HIO returned an unexpected response: ${details}`);
}

const result = await response.json();

for (const event of result.data ?? []) {
  console.log(event.name);
}

Do not broaden the query accidentally

Only send identifiers the integration is meant to access. A valid credential does not grant access to every project or event in HIO.

Adapt this guide

When writing another guide, copy this file and replace:

1. the frontmatter title and description;
2. the goal and prerequisites;
3. the smallest working request;
4. the response explanation and common variations; and
5. the link to the corresponding generated operation reference.

Keep detailed field definitions in the generated reference. A guide should focus on the workflow, decisions, and examples a developer needs to succeed.