Data exchange

Parkour Design currently exposes a coordinated, read-only resource service for Event and course-design summaries. Full project geometry, files, writes, and synchronization require a separate partner contract.

Contract status: The endpoints below describe current deployed behavior for approved clients. They are not yet a versioned general API. Do not build against them before Parkour Design confirms access, scopes, limits, and the launch contract.

Base URL and authentication

Use the issuer selected for the OAuth environment as the API base URL:

Send the Parkour Design access token from a backend service:

Authorization: Bearer <access_token>
Accept: application/json

The access token must be valid for the configured issuer and audience parkour-api, have token_use equal to access_token, and currently contain openid.

The API does not currently provide cross-origin browser access. Do not expose the access or refresh token to frontend JavaScript.

List Events

GET /api/events

Example request:

curl "${ISSUER}/api/events" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

Example response:

{
  "items": [
    {
      "id": "abcdefghijklmnopqrstuv",
      "name": "Example Event",
      "startDate": "2026-07-24T00:00:00Z",
      "endDate": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T18:42:10Z",
      "designCount": 4
    }
  ]
}

Current response type:

type EventSummary = {
  id: string;
  name: string;
  startDate: string | null;
  endDate: string | null;
  updatedAt: string | null;
  designCount: number;
};

type EventsResponse = {
  items: EventSummary[];
};

Events are assembled from the authenticated user’s non-deleted designs. Designs without an Event identifier are omitted.

Treat id as opaque. Copy it unchanged into the design-summary request. Do not infer its format or generate it in the partner system.

List design summaries for an Event

GET /api/events/{eventId}/designs

Example request:

curl "${ISSUER}/api/events/${EVENT_ID}/designs" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Accept: application/json"

Example response:

{
  "event": {
    "id": "abcdefghijklmnopqrstuv",
    "name": "Example Event",
    "startDate": "2026-07-24T00:00:00Z",
    "endDate": "2026-07-26T00:00:00Z",
    "updatedAt": "2026-07-26T18:42:10Z",
    "designCount": 4
  },
  "items": [
    {
      "id": "design-record-id",
      "localId": "design-local-id",
      "eventId": "abcdefghijklmnopqrstuv",
      "title": "Grand Prix",
      "eventName": "Example Event",
      "eventDate": "2026-07-26T00:00:00Z",
      "updatedAt": "2026-07-26T18:42:10Z",
      "authorName": "Course Designer",
      "shortDescr": "Competition description"
    }
  ]
}

Current response type:

type DesignSummary = {
  id: string;
  localId: string | null;
  eventId: string;
  title: string;
  eventName: string;
  eventDate: string | null;
  updatedAt: string | null;
  authorName: string | null;
  shortDescr: string;
};

type EventDesignsResponse = {
  event: EventSummary;
  items: DesignSummary[];
};

Dates are ISO 8601 strings in UTC when present. Clients must support null for optional dates and localId.

Ownership and visibility

The bearer token’s sub identifies the Parkour Design resource owner. Responses contain only non-deleted designs owned by that user.

The current service does not provide:

• organization-wide or team access;
• access to another user’s shared or public designs;
• client-specific resource filtering;
• deleted designs;
• subscription, profile, or payment data.

A nonexistent Event and an Event owned by another user both return 404. Do not use this response to infer whether another user’s resource exists.

Current limits and ordering

The current endpoints do not accept filtering, sorting, pagination, cursors, or incremental synchronization parameters.

• /api/events returns the assembled Event list in one response.
• /api/events/{eventId}/designs returns at most 500 summaries.
• The response does not currently indicate truncation or provide a continuation cursor.
• Ordering is current implementation behavior and is not yet a versioned guarantee.

Before approving a production integration, Parkour Design and the partner must confirm that expected data volume fits these limits. A partner that requires complete pagination or incremental updates must not compensate by scraping or guessing identifiers; that requires a revised contract.

Error responses

Errors use a compact JSON body:

{"error": "not_found"}

Unexpected service failures do not yet have a separately versioned error schema. Clients should treat other 5xx responses as retryable only for idempotent GET operations, with bounded exponential backoff and jitter.

Data not exposed by this API

The design summary is not a complete course design. The current resource API does not expose:

• course geometry or route;
• obstacles, groups, arena layout, or drawing objects;
• generated PDFs, previews, images, or download URLs;
• create, update, delete, or upload operations;
• lookup of an individual design by its design ID;
• webhooks or a change feed;
• Eqify access tokens, sessions, Competitions, activities, or saved destinations.

Do not present a summary response as a printable or editable course design.