Skip to content

Events

Get events list metadata

HEAD /api/events.json

Markdown · Authoritative OpenAPI

Request policy

Operation
headEvents
Access
anonymous
Automatic retries
None
Redirects
Returned to the caller without following
Request body limit
No request body
Pagination
No collection iterator

Parameters

limit number

Requested page size (default 50). Numeric values are floored and clamped to 1–100.

cursor string

Opaque cursor copied from a returned pagination link. Arbitrary strings are rejected with 400; windowed feed cursors must retain their original filters.

sort string

Sort field and direction (e.g., "year:desc", "addedAt:asc")

facets string

Include facet metadata in response meta (set to 1)

type string

Filter by concert or sports event

Allowed: "concert" | "sports"

city string

Filter by city

year number

Filter by event year

q string

Search title, venue, participants, league, and location

Request headers

  • API-Version (optional) — Header-based API version selection. Omit it, send an empty value, or send 1.0.0; surrounding whitespace is ignored.
  • Idempotency-Key (optional) — Accepted for clients that attach a key uniformly. GET, HEAD, and OPTIONS are already safe and intrinsically idempotent, so read responses are not stored in an idempotency replay cache.

Responses

200

Headers only

Response headers
{
  "Content-Usage": {
    "description": "IETF AIPREF usage preferences for this public content",
    "schema": {
      "type": "string",
      "examples": [
        "train-ai=y, search=y"
      ]
    }
  },
  "Content-Signal": {
    "description": "Compatibility AI usage preferences for deployed crawlers",
    "schema": {
      "type": "string",
      "examples": [
        "ai-train=yes, search=yes, ai-input=yes"
      ]
    }
  },
  "API-Version": {
    "description": "Selected public REST contract version",
    "schema": {
      "type": "string",
      "enum": [
        "1.0.0"
      ]
    }
  },
  "RateLimit-Policy": {
    "description": "Public REST quota policy: 1000 Worker requests per 60 seconds for each source and Cloudflare location",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Compatibility form of the current public REST request limit",
    "schema": {
      "type": "integer",
      "enum": [
        1000
      ]
    }
  },
  "ETag": {
    "description": "Entity tag for conditional requests",
    "schema": {
      "type": "string"
    }
  },
  "Cache-Control": {
    "description": "Caching directives",
    "schema": {
      "type": "string"
    }
  },
  "X-Total-Count": {
    "description": "Total number of items",
    "schema": {
      "type": "integer"
    }
  },
  "Link": {
    "description": "RFC 8288 Web Linking header with pagination links",
    "schema": {
      "type": "string"
    }
  },
  "Link-Template": {
    "description": "RFC 9652 Link-Template header with query parameter templates",
    "schema": {
      "type": "string"
    }
  },
  "Deprecation": {
    "description": "RFC 9745 lifecycle deprecation signal",
    "schema": {
      "type": "string"
    }
  },
  "Sunset": {
    "description": "RFC 8594 lifecycle sunset date (HTTP IMF-fixdate)",
    "schema": {
      "type": "string",
      "pattern": "^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$",
      "examples": [
        "Sun, 06 Sep 2026 17:40:13 GMT"
      ]
    }
  }
}

304

Not Modified

400

Invalid query or API version

429

Public REST request limit exceeded

Response headers
{
  "Retry-After": {
    "description": "Seconds before the request should be retried",
    "schema": {
      "type": "integer",
      "enum": [
        60
      ]
    }
  },
  "RateLimit": {
    "description": "Current quota state for the exhausted public-rest policy",
    "schema": {
      "type": "string"
    }
  },
  "Content-Usage": {
    "description": "IETF AIPREF usage preferences for this public content",
    "schema": {
      "type": "string",
      "examples": [
        "train-ai=y, search=y"
      ]
    }
  },
  "Content-Signal": {
    "description": "Compatibility AI usage preferences for deployed crawlers",
    "schema": {
      "type": "string",
      "examples": [
        "ai-train=yes, search=yes, ai-input=yes"
      ]
    }
  },
  "API-Version": {
    "description": "Selected public REST contract version",
    "schema": {
      "type": "string",
      "enum": [
        "1.0.0"
      ]
    }
  },
  "RateLimit-Policy": {
    "description": "Public REST quota policy: 1000 Worker requests per 60 seconds for each source and Cloudflare location",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Compatibility form of the current public REST request limit",
    "schema": {
      "type": "integer",
      "enum": [
        1000
      ]
    }
  }
}

Examples

Examples use synthetic fixture values. Replace fixture identifiers with public IDs returned by the service. Request bodies and precise locations are transient; keep them out of logs.

curl

curl --fail-with-body --max-time 30 --max-filesize 16777216 --head 'https://irvinebroque.com/api/events.json'

TypeScript

import { PublicApi } from '@irvinebroque/public-api';
const api = new PublicApi();
const result = await api.events.listHead({});
console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory.

CLI

irvinebroque events list-head

The SDK preserves status, headers, and the server envelope. A 304 has no fresh body. Errors retain structured problem details; ordinary error messages omit response details. Responses are limited to 16 MiB and requests time out after 30 seconds by default.