Reference

API reference

Every endpoint, parameter and field, generated from the OYSS OpenAPI document the service is validated against — so this page cannot describe an API that does not exist.

Base URL https://api.sidelineexchange.com/v1OYSS 0.1.0All responses snake_case

Conventions

The key decides the mode: A sk_test_… key reads and writes an isolated partition; sk_live_… touches production. There is no mode parameter, so there is none to get wrong.
Everything is snake_case: Ingest, read and management alike. batch_id, external_id, time_status — there is no camelCase surface anywhere.
Ids say what they are: A prefix and a ULID: fx_ fixture, tm_ team, cmp_ competition, ven_ venue, org_ organization. Passing the wrong kind fails on the prefix, not on a lookup.
Instants are UTC: Every timestamp is RFC 3339 ending in Z. Local time comes from the venue’s IANA zone; a fixture with no time yet carries date and time_status: tbd.
Pages are cursors, not offsets: Pass the cursor you were given back. A page never skips or repeats a row because something was inserted while you were reading.
Errors are problem documents: RFC 9457, with a stable type URI that resolves to a page explaining that exact error, and — for batches — an errors array pointing at each rejected observation.

Ingest

POST/observationsSecret key

Push a batch of observations

Accepts up to 1000 observations from one source. Idempotent per Idempotency-Key: replaying a batch with the same key returns the original receipt. Validation errors are reported per observation; the batch is accepted if at least one observation is valid.

Headers

Idempotency-Keystringrequired

8–128 characters

Request body · application/json

The payload a source pushes to POST /v1/observations. Each observation says: source X saw entity Y with these fields at time T.

sourcestringrequired

Source key registered to the caller's account, e.g. gotsport, or a feed key such as feed:ical:lakesidefc.

pattern ^[a-z0-9][a-z0-9._:-]{1,99}$

sent_atstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

observationsarray of Observationrequired

1–1000 items

Show 6 nested fields ›

typestringrequired

one oforganizationcompetitionteamvenuefixtureresultstat_line

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

observed_atstringoptional

When the source saw this state. Defaults to receipt time.

RFC 3339, UTC

confidencenumberoptional

Source's own confidence. Defaults to 1.0 for push sources.

0–1

deletedbooleanoptional

The source no longer has this entity. The hub marks it withdrawn from this source; it never deletes canonical data.

dataobjectrequired

Responses

202Batch accepted for processing.

Show the 4 fields it returns ›

batch_idstringrequired

acceptedintegerrequired

rejectedintegerrequired

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

pathstringoptional

messagestringoptional

400An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

401An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

413An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

429An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl -X POST "https://api.sidelineexchange.com/v1/observations" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: …" \
  -H "Content-Type: application/json" \
  -d @batch.json

Response shape · 202

{
  "batch_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "accepted": 1,
  "rejected": 1,
  "errors": [
    {
      "index": 1,
      "path": "/observations/3/data/start",
      "message": "must end in Z"
    }
  ]
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

Read

GET/fixturesAny key

List fixtures

Query parameters

teamstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

competitionstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

venuestringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

nearstringoptional

Fixtures at venues within a radius of a point — lat,lng or lat,lng,km (25 km by default, 250 at most). Counts as a filter on its own.

fromstringoptional

Inclusive lower bound on start (RFC 3339) or date.

tostringoptional

Exclusive upper bound on start (RFC 3339) or date.

statusarray of stringoptional

one ofscheduledpostponedcancelledcompletedin_progressforfeit

limitintegeroptional

default 100 · 1–500

cursorstringoptional

Responses

200A page of fixtures.headers: ETag, Cache-Control

Show the 2 fields it returns ›

dataarray of Fixturerequired

Show 22 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"fixture"required

sportstringrequired

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

kindstringrequired

one ofgamepracticetryoutscrimmageevent

competitionRefoptional

Show 2 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

divisionobjectoptional

Show 5 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

age_groupstringoptional

U-notation age group (U4–U19) or an open/adult marker.

pattern ^(U(0?[4-9]|1[0-9])|open|adult)$

genderstringoptional

one ofMFcoed

levelstringoptional

stageobjectoptional

Show 3 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

typestringoptional

startstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

endstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

datestring · dateoptional

time_zonestringoptional

IANA time zone name, e.g. America/Chicago.

pattern ^[A-Za-z_]+(/[A-Za-z_+-]+)+$|^UTC$

time_statusstringrequired

one ofconfirmedestimatedtbd

statusstringrequired

one ofscheduledpostponedcancelledcompletedin_progressforfeit

venueobjectoptional

Show 4 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

fieldstringoptional

geoarray of anyoptional

[latitude, longitude] in WGS-84 decimal degrees.

2–2 items

sidesarray of objectoptional

Show 2 nested fields ›

rolestringrequired

one ofhomeawayparticipant

teamRefrequired

Show 2 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

titlestringoptional

resultobjectoptional

A score for a fixture. Several results may be observed; the hub picks one by policy and keeps the rest.

Show 5 nested fields ›

scoresarray of objectrequired

1–2 items

Show 3 nested fields ›

rolestringrequired

one ofhomeawayparticipant

scoreintegerrequired

0–∞

penaltiesintegeroptional

Shoot-out score, if any.

0–∞

finalbooleanrequired

officialbooleanoptional

True when the host or a scoring partner marks the result official.

default false

periodstringoptional

Current period for in-progress results, e.g. 2H, Q3, T7.

0–20 characters

outcomestringoptional

one ofhome_winaway_windrawforfeit_homeforfeit_awayabandoned

provenancemap of Provenancerequired

Field name → provenance of the observation that won it.

external_idsmap of stringoptional

Source key → the source's external id for this fixture.

previousany | nulloptional

What the fixture said before its most recent headline change — a reschedule, a relocation, a cancellation, a postponement or a reinstatement. Null until one has happened. The full sequence is GET /v1/fixtures/{id}/history.

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

next_cursorstring | nulloptional

304Not modified (If-None-Match matched).

401An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/fixtures?team=…&limit=100&cursor=…" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "data": [
    {
      "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
      "type": "fixture",
      "sport": "soccer",
      "kind": "game",
      "competition": {
        "id": "cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE",
        "name": "Dallas Cup 2027"
      },
      "division": {
        "id": "div_01J7Y3M2K9QW8ZP4R6T1N0A5BF",
        "name": "2014 Boys Premier",
        "age_group": "U13",
        "gender": "M",
        "level": "Premier"
      },
      "stage": {
        "id": "stg_01J7Y3M2K9QW8ZP4R6T1N0A5BG",
        "name": "Pool B",
        "type": "pool"
      },
      "start": "2027-04-10T14:00:00Z",
      "end": "2027-04-10T14:00:00Z",
      "date": "2027-04-10",
      "time_zone": "America/Chicago",
      "time_status": "confirmed",
      "status": "scheduled",
      "venue": {
        "id": "ven_01J7Y3M2K9QW8ZP4R6T1N0A5BH",
        "name": "MoneyGram Soccer Park",
        "field": "Field 7",
        "geo": []
      },
      "sides": [
        {}
      ],
      "title": "Invalid parameter",
      "result": {
        "scores": [],
        "final": true,
        "official": false,
        "period": "FT",
        "outcome": "home_win"
      },
      "provenance": {
        "start": {}
      },
      "external_ids": {
        "start": "string"
      },
      "previous": "string",
      "updated_at": "2027-04-10T14:00:00Z",
      "version": 7
    }
  ],
  "next_cursor": "evt_01J7YAAAB4C5D6E7F8G9H0J1K2"
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/fixtures/{id}Any key

Get one fixture with provenance

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200The fixture.headers: ETag

Show the 22 fields it returns ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"fixture"required

sportstringrequired

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

kindstringrequired

one ofgamepracticetryoutscrimmageevent

competitionRefoptional

Show 2 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

divisionobjectoptional

Show 5 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

age_groupstringoptional

U-notation age group (U4–U19) or an open/adult marker.

pattern ^(U(0?[4-9]|1[0-9])|open|adult)$

genderstringoptional

one ofMFcoed

levelstringoptional

stageobjectoptional

Show 3 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

typestringoptional

startstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

endstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

datestring · dateoptional

time_zonestringoptional

IANA time zone name, e.g. America/Chicago.

pattern ^[A-Za-z_]+(/[A-Za-z_+-]+)+$|^UTC$

time_statusstringrequired

one ofconfirmedestimatedtbd

statusstringrequired

one ofscheduledpostponedcancelledcompletedin_progressforfeit

venueobjectoptional

Show 4 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

fieldstringoptional

geoarray of anyoptional

[latitude, longitude] in WGS-84 decimal degrees.

2–2 items

sidesarray of objectoptional

Show 2 nested fields ›

rolestringrequired

one ofhomeawayparticipant

teamRefrequired

Show 2 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

titlestringoptional

resultobjectoptional

A score for a fixture. Several results may be observed; the hub picks one by policy and keeps the rest.

Show 5 nested fields ›

scoresarray of objectrequired

1–2 items

Show 3 nested fields ›

rolestringrequired

one ofhomeawayparticipant

scoreintegerrequired

0–∞

penaltiesintegeroptional

Shoot-out score, if any.

0–∞

finalbooleanrequired

officialbooleanoptional

True when the host or a scoring partner marks the result official.

default false

periodstringoptional

Current period for in-progress results, e.g. 2H, Q3, T7.

0–20 characters

outcomestringoptional

one ofhome_winaway_windrawforfeit_homeforfeit_awayabandoned

provenancemap of Provenancerequired

Field name → provenance of the observation that won it.

external_idsmap of stringoptional

Source key → the source's external id for this fixture.

previousany | nulloptional

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

304Not modified.

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/fixtures/fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "type": "fixture",
  "sport": "soccer",
  "kind": "game",
  "competition": {
    "id": "cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE",
    "name": "Dallas Cup 2027"
  },
  "division": {
    "id": "div_01J7Y3M2K9QW8ZP4R6T1N0A5BF",
    "name": "2014 Boys Premier",
    "age_group": "U13",
    "gender": "M",
    "level": "Premier"
  },
  "stage": {
    "id": "stg_01J7Y3M2K9QW8ZP4R6T1N0A5BG",
    "name": "Pool B",
    "type": "pool"
  },
  "start": "2027-04-10T14:00:00Z",
  "end": "2027-04-10T14:00:00Z",
  "date": "2027-04-10",
  "time_zone": "America/Chicago",
  "time_status": "confirmed",
  "status": "scheduled",
  "venue": {
    "id": "ven_01J7Y3M2K9QW8ZP4R6T1N0A5BH",
    "name": "MoneyGram Soccer Park",
    "field": "Field 7",
    "geo": [
      "string"
    ]
  },
  "sides": [
    {
      "role": "home",
      "team": {
        "id": "tm_01J7Y3M2K9QW8ZP4R6T1N0A5BD",
        "name": "Lakeside FC 2014B Blue"
      }
    }
  ],
  "title": "Invalid parameter",
  "result": {
    "scores": [
      {
        "role": "home",
        "score": 1,
        "penalties": 1
      }
    ],
    "final": true,
    "official": false,
    "period": "FT",
    "outcome": "home_win"
  },
  "provenance": {
    "start": {
      "source": "gotsport",
      "observed_at": "2027-04-10T14:00:00Z",
      "confidence": 0.98,
      "observation_id": "obs_01J7Y3M2K9QW8ZP4R6T1N0A5BK"
    }
  },
  "external_ids": {
    "start": "string"
  },
  "previous": "string",
  "updated_at": "2027-04-10T14:00:00Z",
  "version": 7
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/fixtures/{id}/historyAny key

Every recorded change to a fixture

The fixture's history, oldest first: what it said before, what it says now, what kind of change that was (moved, rescheduled, cancelled, reinstated, withdrawn by a source), and the observation that caused it. This is how "why does it say Field 3A?" is answered without a support thread, and how a consumer learns that a game moved rather than that it changed.

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200The history.headers: ETag

Show the 2 fields it returns ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

dataarray of FixtureChangerequired

Show 12 nested fields ›

versionintegerrequired

1–∞

changed_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

kindstringrequired

What a change amounted to. relocated is a venue or field change; rescheduled a start, end, date or time-status change; withdrawn means one source stopped listing the fixture (the canonical row persists); reinstated means a cancelled or postponed fixture is scheduled again.

one ofcreatedupdatedrescheduledrelocatedpostponedcancelledcompletedreinstatedwithdrawn

changed_fieldsarray of stringrequired

beforeobjectoptional

The fields a family plans around, frozen at one version of the fixture.

Show 6 nested fields ›

startstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

endstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

datestring · dateoptional

time_statusstringrequired

one ofconfirmedestimatedtbd

statusstringrequired

one ofscheduledpostponedcancelledcompletedin_progressforfeit

venueobjectoptional

Show 3 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

fieldstringoptional

afterFixtureStaterequired

The fields a family plans around, frozen at one version of the fixture.

Show 6 nested fields ›

startstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

endstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

datestring · dateoptional

time_statusstringrequired

one ofconfirmedestimatedtbd

statusstringrequired

one ofscheduledpostponedcancelledcompletedin_progressforfeit

venueobjectoptional

Show 3 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

fieldstringoptional

sourcestringrequired

The source whose observation caused the change.

observation_idstring | nulloptional

change_groupstringrequired

Shared by every kind one observation produced, so a relocation and a reschedule from one edit are one notification.

venue_change_scopestring | nulloptional

field when the move stayed inside one complex (Field 3 → Field 3A); complex when the venue itself changed.

one offieldcomplex

distance_kmnumber | nulloptional

reasonstring | nulloptional

In words: "moved from Field 3 to Field 3A", "withdrawn by every source".

304Not modified.

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/fixtures/fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC/history" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "data": [
    {
      "version": 7,
      "changed_at": "2027-04-10T14:00:00Z",
      "kind": "created",
      "changed_fields": [
        "string"
      ],
      "before": {
        "start": "2027-04-10T14:00:00Z",
        "end": "2027-04-10T14:00:00Z",
        "date": "2027-04-10",
        "time_status": "confirmed",
        "status": "scheduled",
        "venue": {}
      },
      "after": {
        "start": "2027-04-10T14:00:00Z",
        "end": "2027-04-10T14:00:00Z",
        "date": "2027-04-10",
        "time_status": "confirmed",
        "status": "scheduled",
        "venue": {}
      },
      "source": "gotsport",
      "observation_id": "obs_01J7Y3M2K9QW8ZP4R6T1N0A5BK",
      "change_group": "string",
      "venue_change_scope": "field",
      "distance_km": 1,
      "reason": "string"
    }
  ]
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/venuesAny key

Find venues by name or by place

Venues across every source, merged: a complex two platforms name differently is one venue here. Filter by name (q), by state (region) or by distance from a point (near=lat,lng[,km], radius 25 km by default and 250 at most); with near, results come nearest first and carry distance_km. At least one filter is required.

Query parameters

qstringoptional

2–∞ characters

nearstringoptional

lat,lng or lat,lng,km.

regionstringoptional

Two-letter state or province code.

limitintegeroptional

default 100 · 1–500

Responses

200Matching venues, survivors only.

Show the 1 fields it returns ›

dataarray of Venuerequired

Show 11 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"venue"required

namestringrequired

addressobjectoptional

Show 6 nested fields ›

line1string | nulloptional

line2string | nulloptional

citystring | nulloptional

regionstring | nulloptional

postal_codestring | nulloptional

countrystring | nulloptional

geoarray of anyoptional

[latitude, longitude] in WGS-84 decimal degrees.

2–2 items

time_zonestring | nulloptional

fieldsarray of stringrequired

distance_kmnumber | nulloptional

Only with near: kilometres from the point asked about.

external_idsmap of stringrequired

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

400An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/venues?q=lakeside&limit=100" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "data": [
    {
      "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
      "type": "venue",
      "name": "Lakeside FC 2014B Blue",
      "address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "postal_code": "string",
        "country": "string"
      },
      "geo": [
        "string"
      ],
      "time_zone": "America/Chicago",
      "fields": [
        "string"
      ],
      "distance_km": 1,
      "external_ids": {
        "start": "string"
      },
      "updated_at": "2027-04-10T14:00:00Z",
      "version": 7
    }
  ]
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/venues/{id}Any key

Get one venue

A venue merged into another answers as its survivor, so an id a consumer stored keeps working.

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200The venue.headers: ETag

Show the 11 fields it returns ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"venue"required

namestringrequired

addressobjectoptional

Show 6 nested fields ›

line1string | nulloptional

line2string | nulloptional

citystring | nulloptional

regionstring | nulloptional

postal_codestring | nulloptional

countrystring | nulloptional

geoarray of anyoptional

[latitude, longitude] in WGS-84 decimal degrees.

2–2 items

time_zonestring | nulloptional

fieldsarray of stringrequired

distance_kmnumber | nulloptional

Only with near: kilometres from the point asked about.

external_idsmap of stringrequired

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

304Not modified.

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/venues/fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "type": "venue",
  "name": "Lakeside FC 2014B Blue",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "region": "string",
    "postal_code": "string",
    "country": "string"
  },
  "geo": [
    "string"
  ],
  "time_zone": "America/Chicago",
  "fields": [
    "string"
  ],
  "distance_km": 1,
  "external_ids": {
    "start": "string"
  },
  "updated_at": "2027-04-10T14:00:00Z",
  "version": 7
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/competitionsAny key

Browse competitions by sport, place and date

Every tournament and league season the hub holds, from every source, as one catalog. Filter by sport, kind, region (where it plays, or failing that where its host is), a date window (from/to, matching any competition that overlaps it), distance from a point (near), or name (q). Ordered by start date; undated competitions last. Page with cursor.

Query parameters

sportstringoptional

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

kindstringoptional

one oftournamentleagueshowcasecampfriendlyother

regionstringoptional

fromstring · dateoptional

tostring · dateoptional

nearstringoptional

lat,lng or lat,lng,km.

qstringoptional

2–∞ characters

limitintegeroptional

default 100 · 1–500

cursorstringoptional

Responses

200A page of competitions.

Show the 2 fields it returns ›

dataarray of Competitionrequired

Show 16 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"competition"required

namestringrequired

sportstringrequired

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

kindstringrequired

one oftournamentleagueshowcasecampfriendlyother

hostobjectoptional

Show 2 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

seasonstring | nulloptional

start_datestring | null · dateoptional

end_datestring | null · dateoptional

time_zonestring | nulloptional

websitestring | nulloptional

divisionsarray of objectrequired

Show 6 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringrequired

age_groupstring | nulloptional

genderstring | nulloptional

levelstring | nulloptional

stagesarray of objectrequired

Show 4 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringrequired

typestringrequired

orderintegerrequired

venuesarray of Venueoptional

Detail only — the distinct venues its fixtures play at. Absent on the list.

Show 11 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"venue"required

namestringrequired

addressobjectoptional

Show 6 nested fields ›

line1string | nulloptional

line2string | nulloptional

citystring | nulloptional

regionstring | nulloptional

postal_codestring | nulloptional

countrystring | nulloptional

geoarray of anyoptional

[latitude, longitude] in WGS-84 decimal degrees.

2–2 items

time_zonestring | nulloptional

fieldsarray of stringrequired

distance_kmnumber | nulloptional

Only with near: kilometres from the point asked about.

external_idsmap of stringrequired

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

external_idsmap of stringrequired

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

next_cursorstring | nulloptional

400An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/competitions?q=lakeside&limit=100&cursor=…" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "data": [
    {
      "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
      "type": "competition",
      "name": "Lakeside FC 2014B Blue",
      "sport": "soccer",
      "kind": "tournament",
      "host": {
        "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
        "name": "Lakeside FC 2014B Blue"
      },
      "season": "string",
      "start_date": "2027-04-10",
      "end_date": "2027-04-10",
      "time_zone": "America/Chicago",
      "website": "string",
      "divisions": [
        {}
      ],
      "venues": [
        {}
      ],
      "external_ids": {
        "start": "string"
      },
      "updated_at": "2027-04-10T14:00:00Z",
      "version": 7
    }
  ],
  "next_cursor": "evt_01J7YAAAB4C5D6E7F8G9H0J1K2"
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/competitions/{id}Any key

Get one competition with its divisions and venues

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200The competition, with `venues` — the distinct places its fixtures play.headers: ETag

Show the 16 fields it returns ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"competition"required

namestringrequired

sportstringrequired

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

kindstringrequired

one oftournamentleagueshowcasecampfriendlyother

hostobjectoptional

Show 2 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

seasonstring | nulloptional

start_datestring | null · dateoptional

end_datestring | null · dateoptional

time_zonestring | nulloptional

websitestring | nulloptional

divisionsarray of objectrequired

Show 6 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringrequired

age_groupstring | nulloptional

genderstring | nulloptional

levelstring | nulloptional

stagesarray of objectrequired

Show 4 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringrequired

typestringrequired

orderintegerrequired

venuesarray of Venueoptional

Detail only — the distinct venues its fixtures play at. Absent on the list.

Show 11 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"venue"required

namestringrequired

addressobjectoptional

Show 6 nested fields ›

line1string | nulloptional

line2string | nulloptional

citystring | nulloptional

regionstring | nulloptional

postal_codestring | nulloptional

countrystring | nulloptional

geoarray of anyoptional

[latitude, longitude] in WGS-84 decimal degrees.

2–2 items

time_zonestring | nulloptional

fieldsarray of stringrequired

distance_kmnumber | nulloptional

Only with near: kilometres from the point asked about.

external_idsmap of stringrequired

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

external_idsmap of stringrequired

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

304Not modified.

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/competitions/cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "type": "competition",
  "name": "Lakeside FC 2014B Blue",
  "sport": "soccer",
  "kind": "tournament",
  "host": {
    "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Lakeside FC 2014B Blue"
  },
  "season": "string",
  "start_date": "2027-04-10",
  "end_date": "2027-04-10",
  "time_zone": "America/Chicago",
  "website": "string",
  "divisions": [
    {
      "id": "div_01J7Y3M2K9QW8ZP4R6T1N0A5BF",
      "name": "2014 Boys Premier",
      "age_group": "U13",
      "gender": "string",
      "level": "Premier",
      "stages": [
        {}
      ]
    }
  ],
  "venues": [
    {
      "id": "ven_01J7Y3M2K9QW8ZP4R6T1N0A5BH",
      "type": "venue",
      "name": "MoneyGram Soccer Park",
      "address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "region": "string",
        "postal_code": "string",
        "country": "string"
      },
      "geo": [
        "string"
      ],
      "time_zone": "America/Chicago",
      "fields": [
        "string"
      ],
      "distance_km": 1,
      "external_ids": {
        "start": "string"
      },
      "updated_at": "2027-04-10T14:00:00Z",
      "version": 7
    }
  ],
  "external_ids": {
    "start": "string"
  },
  "updated_at": "2027-04-10T14:00:00Z",
  "version": 7
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/competitions/{id}/standingsAny key

Standings for every stage of a competition

Derived tables, one per stage, recomputed when results land. Honest about partial data (complete, as_of, missing_fixtures) and auditable — each row carries the tiebreak trace that explains its position, and derived_from names the fixture versions it came from.

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200One table per stage that has results.

Show the 15 fields it returns ›

stagestringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

typestringoptional

divisionstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

division_namestringoptional

competitionstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

completebooleanoptional

tiebreak_sourcestringoptional

one ofstagedefault

versionintegeroptional

as_ofstringoptional

RFC 3339, UTC

pointsstringoptional

Points per win-draw-loss, e.g. 3-1-0.

tiebreakersarray of stringoptional

missing_fixturesarray of stringoptional

derived_fromarray of stringoptional

fixture@version inputs

rowsarray of objectoptional

Show 13 nested fields ›

teamstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

team_namestringoptional

positionintegeroptional

playedintegeroptional

winsintegeroptional

drawsintegeroptional

lossesintegeroptional

goals_forintegeroptional

goals_againstintegeroptional

goal_diffintegeroptional

pointsintegeroptional

provisionalbooleanoptional

tracearray of stringoptional

The rules that placed this row, in order.

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/competitions/cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE/standings" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

[
  {
    "stage": "stg_01J7Y3M2K9QW8ZP4R6T1N0A5BG",
    "name": "Lakeside FC 2014B Blue",
    "type": "string",
    "division": "div_01J7Y3M2K9QW8ZP4R6T1N0A5BF",
    "division_name": "2014 Boys Premier",
    "competition": "cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE",
    "complete": true,
    "tiebreak_source": "stage",
    "version": 7,
    "as_of": "2027-04-10T14:00:00Z",
    "points": "3-1-0",
    "tiebreakers": [
      "string"
    ],
    "missing_fixtures": [
      "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC"
    ],
    "derived_from": [
      "string"
    ],
    "rows": [
      {
        "team": "tm_01J7Y3M2K9QW8ZP4R6T1N0A5BD",
        "team_name": "Lakeside FC 2014B Blue",
        "position": 1,
        "played": 1,
        "wins": 1,
        "draws": 1,
        "losses": 1,
        "goals_for": 1,
        "goals_against": 1,
        "goal_diff": 1,
        "points": 1,
        "provisional": true,
        "trace": []
      }
    ]
  }
]

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/stages/{id}/standingsAny key

The standings table for one stage

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200The table, with its tiebreak traces.

Show the 15 fields it returns ›

stagestringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

typestringoptional

divisionstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

division_namestringoptional

competitionstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

completebooleanoptional

tiebreak_sourcestringoptional

one ofstagedefault

versionintegeroptional

as_ofstringoptional

RFC 3339, UTC

pointsstringoptional

Points per win-draw-loss, e.g. 3-1-0.

tiebreakersarray of stringoptional

missing_fixturesarray of stringoptional

derived_fromarray of stringoptional

fixture@version inputs

rowsarray of objectoptional

Show 13 nested fields ›

teamstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

team_namestringoptional

positionintegeroptional

playedintegeroptional

winsintegeroptional

drawsintegeroptional

lossesintegeroptional

goals_forintegeroptional

goals_againstintegeroptional

goal_diffintegeroptional

pointsintegeroptional

provisionalbooleanoptional

tracearray of stringoptional

The rules that placed this row, in order.

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/stages/stg_01J7Y3M2K9QW8ZP4R6T1N0A5BG/standings" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "stage": "stg_01J7Y3M2K9QW8ZP4R6T1N0A5BG",
  "name": "Lakeside FC 2014B Blue",
  "type": "string",
  "division": "div_01J7Y3M2K9QW8ZP4R6T1N0A5BF",
  "division_name": "2014 Boys Premier",
  "competition": "cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE",
  "complete": true,
  "tiebreak_source": "stage",
  "version": 7,
  "as_of": "2027-04-10T14:00:00Z",
  "points": "3-1-0",
  "tiebreakers": [
    "string"
  ],
  "missing_fixtures": [
    "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC"
  ],
  "derived_from": [
    "string"
  ],
  "rows": [
    {
      "team": "tm_01J7Y3M2K9QW8ZP4R6T1N0A5BD",
      "team_name": "Lakeside FC 2014B Blue",
      "position": 1,
      "played": 1,
      "wins": 1,
      "draws": 1,
      "losses": 1,
      "goals_for": 1,
      "goals_against": 1,
      "goal_diff": 1,
      "points": 1,
      "provisional": true,
      "trace": [
        "string"
      ]
    }
  ]
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/teamsAny key

Find teams by name

Name in, ids out — the entry point everything id-scoped hangs off. Public tier.

Query parameters

qstringrequired

2–∞ characters

limitintegeroptional

default 100 · 1–500

Responses

200Matching teams.

Show the 2 fields it returns ›

idstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

Request

curl "https://api.sidelineexchange.com/v1/teams?q=lakeside&limit=100" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

[
  {
    "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Lakeside FC 2014B Blue"
  }
]

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/competitions/{id}/export/fixtures.parquetSecret key

A competition's canonical fixtures as one Parquet file

Bulk export for notebooks and warehouses: one flat row per fixture with teams, venue, schedule and result columns. Secret keys only — bulk is not a widget concern.

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200The Parquet file.

403Publishable keys cannot export.

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/competitions/cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE/export/fixtures.parquet" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 404

{
  "type": "https://example.com/hooks/sideline",
  "title": "Invalid parameter",
  "status": 1,
  "detail": "team must be a tm_ id.",
  "instance": "/v1/fixtures",
  "errors": [
    {
      "index": 1,
      "path": "/observations/3/data/start",
      "message": "must end in Z"
    }
  ]
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/fixtures/{id}/statsAny key

Box-score lines for a fixture

Team lines are public tier. Player lines are PII tier — a secret key holding a participants:read grant from the team's organization, or they are withheld and player_lines_withheld says so. Publishable keys are structurally incapable of the player tier.

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200The visible lines.

Show the 3 fields it returns ›

fixturestringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

player_lines_withheldbooleanoptional

linesarray of objectoptional

Show 10 nested fields ›

idstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

teamstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

team_namestringoptional

playerstring | nulloptional

player_namestring | nulloptional

periodstring | nulloptional

sportstringoptional

statsmap of numberoptional

sourcestringoptional

versionintegeroptional

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/fixtures/fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC/stats" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "fixture": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "player_lines_withheld": true,
  "lines": [
    {
      "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
      "team": "tm_01J7Y3M2K9QW8ZP4R6T1N0A5BD",
      "team_name": "Lakeside FC 2014B Blue",
      "player": "string",
      "player_name": "Lakeside FC 2014B Blue",
      "period": "FT",
      "sport": "string",
      "stats": {
        "start": 1
      },
      "source": "gotsport",
      "version": 7
    }
  ]
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

GET/fixtures/{id}/resultsAny key

Every reported result for a fixture, losers included

Two scorers keep two books; the conflict policy picks one. This shows every report with its source and marks the one that won — provenance for scores, not just the winning value.

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200The reports.

Show the 3 fields it returns ›

fixturestringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

winning_sourcestring | nulloptional

reportedarray of objectoptional

Show 6 nested fields ›

sourcestringoptional

source_classstringoptional

observed_atstringoptional

RFC 3339, UTC

confidencenumberoptional

winningbooleanoptional

resultResultoptional

A score for a fixture. Several results may be observed; the hub picks one by policy and keeps the rest.

Show 5 nested fields ›

scoresarray of objectrequired

1–2 items

Show 3 nested fields ›

rolestringrequired

one ofhomeawayparticipant

scoreintegerrequired

0–∞

penaltiesintegeroptional

Shoot-out score, if any.

0–∞

finalbooleanrequired

officialbooleanoptional

True when the host or a scoring partner marks the result official.

default false

periodstringoptional

Current period for in-progress results, e.g. 2H, Q3, T7.

0–20 characters

outcomestringoptional

one ofhome_winaway_windrawforfeit_homeforfeit_awayabandoned

404An RFC 9457 problem.

Show the 6 fields it returns ›

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Request

curl "https://api.sidelineexchange.com/v1/fixtures/fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC/results" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "fixture": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "winning_source": "string",
  "reported": [
    {
      "source": "gotsport",
      "source_class": "authoritative_push",
      "observed_at": "2027-04-10T14:00:00Z",
      "confidence": 0.98,
      "winning": true,
      "result": {
        "scores": [],
        "final": true,
        "official": false,
        "period": "FT",
        "outcome": "home_win"
      }
    }
  ]
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

Sync

GET/changesAny key

Delta sync

Returns entity changes after cursor, oldest first. A consumer stores the returned next_cursor and never re-downloads a season. Cursors are opaque and valid for 30 days.

Query parameters

cursorstringoptional

limitintegeroptional

default 100 · 1–500

typesarray of stringoptional

one offixtureteamcompetitionvenueorganizationresult

Responses

200A page of changes.

Show the 2 fields it returns ›

dataarray of Changerequired

Show 6 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

typestringrequired

eventstringrequired

The oyss.* event type that produced this change.

versionintegerrequired

atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

changed_fieldsarray of stringoptional

next_cursorstringrequired

Request

curl "https://api.sidelineexchange.com/v1/changes?cursor=…&limit=100" \
  -H "Authorization: Bearer sk_test_…"

Response shape · 200

{
  "data": [
    {
      "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
      "type": "string",
      "event": "oyss.fixture.rescheduled",
      "version": 7,
      "at": "2027-04-10T14:00:00Z",
      "changed_fields": [
        "string"
      ]
    }
  ],
  "next_cursor": "evt_01J7YAAAB4C5D6E7F8G9H0J1K2"
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

Calendars

GET/teams/{id}/calendar.icsNo key

iCalendar feed for a team

Public, cacheable, no key required. Token-scoped feeds for non-public data are issued by the dashboard.

Path parameters

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Responses

200An iCalendar document.headers: ETag, Cache-Control

Webhooks

POST/subscriptionsSecret key

Register a webhook endpoint

Request body · application/json

urlstring · urirequired

eventsarray of stringrequired

1–∞ items

filtermap of stringoptional

Optional scope, e.g. {"competition": "cmp_…"} or {"team": "tm_…"}.

Responses

201Created. The signing secret is returned once.

Show the 7 fields it returns ›

urlstring · urirequired

eventsarray of stringrequired

1–∞ items

filtermap of stringoptional

Optional scope, e.g. {"competition": "cmp_…"} or {"team": "tm_…"}.

idstringrequired

modestringrequired

one oftestlive

secretstringrequired

HMAC-SHA256 signing secret, shown once.

created_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

Request

curl -X POST "https://api.sidelineexchange.com/v1/subscriptions" \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d @batch.json

Response shape · 201

{
  "url": "https://example.com/hooks/sideline",
  "events": [
    "string"
  ],
  "filter": {
    "start": "string"
  },
  "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "mode": "test",
  "secret": "whsec_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "created_at": "2027-04-10T14:00:00Z"
}

Drawn from the schema, field for field — the shape of a real response, not a recorded one.

The observation envelope

Every observation in a batch has the same envelope. What data must contain depends on type — one schema per type, listed below. Nothing else is accepted: an unknown type is rejected with a pointer to the field, not silently ignored.

typestringrequired

one oforganizationcompetitionteamvenuefixtureresultstat_line

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

observed_atstringoptional

When the source saw this state. Defaults to receipt time.

RFC 3339, UTC

confidencenumberoptional

Source's own confidence. Defaults to 1.0 for push sources.

0–1

deletedbooleanoptional

The source no longer has this entity. The hub marks it withdrawn from this source; it never deletes canonical data.

dataobjectrequired

What `data` holds, by type

▶type: "organization"A club, league, tournament host or governing body.

namestringrequired

1–200 characters

kindstringrequired

one ofclubleaguetournament_hostgoverning_bodyother

short_namestringoptional

0–50 characters

regionstringoptional

Free-text region, e.g. North Texas.

0–100 characters

countrystringoptional

pattern ^[A-Z]{2}$

websitestring · urioptional

sanctioningmap of stringoptional

Identifiers assigned by governing bodies, keyed by body (usys, usclub, ayso, uslacrosse, ...).

data shape

{
  "name": "Lakeside FC 2014B Blue",
  "kind": "club",
  "short_name": "Lakeside FC 2014B Blue",
  "region": "string",
  "country": "string",
  "website": "https://example.com/hooks/sideline",
  "sanctioning": {
    "start": "string"
  }
}

▶type: "competition"A tournament or a league season. The unit at which an authoritative source is designated.

namestringrequired

1–200 characters

sportstringrequired

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

kindstringrequired

one oftournamentleagueshowcasefriendly_seriesother

hostobjectoptional

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

seasonstringoptional

e.g. 2026-27 or Spring 2027.

0–40 characters

start_datestring · dateoptional

end_datestring · dateoptional

time_zonestringoptional

IANA time zone name, e.g. America/Chicago.

pattern ^[A-Za-z_]+(/[A-Za-z_+-]+)+$|^UTC$

websitestring · urioptional

divisionsarray of Divisionoptional

Show 6 nested fields ›

external_idstringoptional

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringrequired

0–120 characters

age_groupstringoptional

U-notation age group (U4–U19) or an open/adult marker.

pattern ^(U(0?[4-9]|1[0-9])|open|adult)$

genderstringoptional

one ofMFcoed

levelstringoptional

Competitive tier as named by the host, e.g. gold, premier, rec.

0–60 characters

stagesarray of objectoptional

Show 6 nested fields ›

external_idstringoptional

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringrequired

0–120 characters

typestringrequired

one ofpoolbracketround_robinleagueplayoffother

orderintegeroptional

0–∞

pointsstringoptional

Points per win-draw-loss, e.g. 3-1-0. 3-1-0 is common, not universal.

pattern ^\d{1,2}-\d{1,2}-\d{1,2}$

tiebreakersarray of stringoptional

Ordered rules: points, wins, goal_diff, goal_diff_capped:N, goals_for, goals_against, head_to_head:mini_table, head_to_head:pairwise_only, coin_toss. Unknown names are rejected at ingest, never skipped.

0–10 items

data shape

{
  "name": "Lakeside FC 2014B Blue",
  "sport": "soccer",
  "kind": "tournament",
  "host": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Lakeside FC 2014B Blue"
  },
  "season": "string",
  "start_date": "2027-04-10",
  "end_date": "2027-04-10",
  "time_zone": "America/Chicago",
  "website": "https://example.com/hooks/sideline",
  "divisions": [
    {
      "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
      "name": "2014 Boys Premier",
      "age_group": "U13",
      "gender": "M",
      "level": "Premier",
      "stages": [
        {}
      ]
    }
  ]
}

▶type: "team"A club team in a season. Identity = organization + age group + gender + name + season.

namestringrequired

Name as the source shows it, e.g. Lakeside FC 2014B Blue.

1–200 characters

organizationobjectoptional

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

sportstringoptional

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

age_groupstringoptional

U-notation age group (U4–U19) or an open/adult marker.

pattern ^(U(0?[4-9]|1[0-9])|open|adult)$

birth_yearintegeroptional

1990–2100

genderstringoptional

one ofMFcoed

seasonstringoptional

0–40 characters

levelstringoptional

0–60 characters

coachstringoptional

Head coach name as published by the source. Used only for resolution.

0–120 characters

colorsarray of stringoptional

0–3 items

sanctioningmap of stringoptional

Team identifiers assigned by governing bodies, keyed by body.

data shape

{
  "name": "Lakeside FC 2014B Blue",
  "organization": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Lakeside FC"
  },
  "sport": "soccer",
  "age_group": "U13",
  "birth_year": 1,
  "gender": "M",
  "season": "string",
  "level": "Premier",
  "coach": "string",
  "colors": [
    "string"
  ],
  "sanctioning": {
    "start": "string"
  }
}

▶type: "venue"A complex (park, school, facility). Fields within it are named on the fixture.

namestringrequired

1–200 characters

addressobjectoptional

Show 6 nested fields ›

line1stringoptional

0–200 characters

line2stringoptional

0–200 characters

citystringoptional

0–100 characters

regionstringoptional

State or province code.

0–10 characters

postal_codestringoptional

0–20 characters

countrystringoptional

pattern ^[A-Z]{2}$

geoarray of anyoptional

[latitude, longitude] in WGS-84 decimal degrees.

2–2 items

time_zonestringoptional

IANA time zone name, e.g. America/Chicago.

pattern ^[A-Za-z_]+(/[A-Za-z_+-]+)+$|^UTC$

fieldsarray of stringoptional

Named fields/courts/rinks within the complex, as the source labels them.

data shape

{
  "name": "Lakeside FC 2014B Blue",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "region": "string",
    "postal_code": "string",
    "country": "string"
  },
  "geo": [
    "string"
  ],
  "time_zone": "America/Chicago",
  "fields": [
    "string"
  ]
}

▶type: "fixture"Anything schedulable: a game, practice, tryout or team event.

kindstringrequired

one ofgamepracticetryoutscrimmageevent

sportstringrequired

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

competitionobjectoptional

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

divisionobjectoptional

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

stageobjectoptional

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

startstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

endstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

datestring · dateoptional

Local date when the time is not yet known (time_status = tbd).

time_zonestringoptional

IANA time zone name, e.g. America/Chicago.

pattern ^[A-Za-z_]+(/[A-Za-z_+-]+)+$|^UTC$

time_statusstringoptional

one ofconfirmedestimatedtbd

default "confirmed"

statusstringoptional

one ofscheduledpostponedcancelledcompletedin_progressforfeit

default "scheduled"

venueobjectoptional

Show 3 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

fieldstringoptional

0–60 characters

sidesarray of objectoptional

0–2 items

Show 2 nested fields ›

rolestringrequired

one ofhomeawayparticipant

teamobjectrequired

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

titlestringoptional

Display title for non-game fixtures (practice, event).

0–200 characters

notesstringoptional

0–2000 characters

resultResultoptional

A score for a fixture. Several results may be observed; the hub picks one by policy and keeps the rest.

Show 5 nested fields ›

scoresarray of objectrequired

1–2 items

Show 3 nested fields ›

rolestringrequired

one ofhomeawayparticipant

scoreintegerrequired

0–∞

penaltiesintegeroptional

Shoot-out score, if any.

0–∞

finalbooleanrequired

officialbooleanoptional

True when the host or a scoring partner marks the result official.

default false

periodstringoptional

Current period for in-progress results, e.g. 2H, Q3, T7.

0–20 characters

outcomestringoptional

one ofhome_winaway_windrawforfeit_homeforfeit_awayabandoned

urlstring · urioptional

Source page for this fixture, if public.

data shape

{
  "kind": "game",
  "sport": "soccer",
  "competition": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Dallas Cup 2027"
  },
  "division": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "2014 Boys Premier"
  },
  "stage": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Pool B"
  },
  "start": "2027-04-10T14:00:00Z",
  "end": "2027-04-10T14:00:00Z",
  "date": "2027-04-10",
  "time_zone": "America/Chicago",
  "time_status": "confirmed",
  "status": "scheduled",
  "venue": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "MoneyGram Soccer Park",
    "field": "Field 7"
  },
  "sides": [
    {
      "role": "home",
      "team": {
        "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
        "name": "Lakeside FC 2014B Blue"
      }
    }
  ],
  "title": "Invalid parameter",
  "notes": "string",
  "result": {
    "scores": [
      {
        "role": "home",
        "score": 1,
        "penalties": 1
      }
    ],
    "final": true,
    "official": false,
    "period": "FT",
    "outcome": "home_win"
  },
  "url": "https://example.com/hooks/sideline"
}

▶type: "result"A result observed for a fixture identified by the source's external id.

fixtureobjectrequired

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

resultResultrequired

A score for a fixture. Several results may be observed; the hub picks one by policy and keeps the rest.

Show 5 nested fields ›

scoresarray of objectrequired

1–2 items

Show 3 nested fields ›

rolestringrequired

one ofhomeawayparticipant

scoreintegerrequired

0–∞

penaltiesintegeroptional

Shoot-out score, if any.

0–∞

finalbooleanrequired

officialbooleanoptional

True when the host or a scoring partner marks the result official.

default false

periodstringoptional

Current period for in-progress results, e.g. 2H, Q3, T7.

0–20 characters

outcomestringoptional

one ofhome_winaway_windrawforfeit_homeforfeit_awayabandoned

data shape

{
  "fixture": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Lakeside FC 2014B Blue v Riverbend SC 14B Red"
  },
  "result": {
    "scores": [
      {
        "role": "home",
        "score": 1,
        "penalties": 1
      }
    ],
    "final": true,
    "official": false,
    "period": "FT",
    "outcome": "home_win"
  }
}

▶type: "stat_line"A box-score line for a fixture: team-level, or per player behind an organization grant. Player lines are PII tier — never served to a publishable key, never in an event payload.

fixtureobjectrequired

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

teamobjectrequired

Reference to another entity by the source's external id. Used inside observations.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–200 characters

playerobjectoptional

Present only for a player line. The token is the source's stable participant id; a display name is optional and grant-gated on the way out.

Show 2 nested fields ›

external_idstringrequired

A source's own identifier for an entity. Opaque to the hub; stable within the source.

1–256 characters

namestringoptional

0–120 characters

periodstringoptional

One period's line (e.g. 1H, Q3); absent means the whole game.

0–20 characters

sportstringrequired

one ofsoccerbaseball

statsobjectrequired

data shape

{
  "fixture": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Lakeside FC 2014B Blue v Riverbend SC 14B Red"
  },
  "team": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Lakeside FC 2014B Blue"
  },
  "player": {
    "external_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
    "name": "Lakeside FC 2014B Blue"
  },
  "period": "FT",
  "sport": "soccer",
  "stats": {}
}

Objects

Fixture

Canonical fixture with per-field provenance.

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

type"fixture"required

sportstringrequired

one ofsoccerbaseballsoftballbasketballvolleyballlacrossehockeyfootballrugbyfield_hockeyother

kindstringrequired

one ofgamepracticetryoutscrimmageevent

competitionRefoptional

Show 2 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

divisionobjectoptional

Show 5 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

age_groupstringoptional

U-notation age group (U4–U19) or an open/adult marker.

pattern ^(U(0?[4-9]|1[0-9])|open|adult)$

genderstringoptional

one ofMFcoed

levelstringoptional

stageobjectoptional

Show 3 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

typestringoptional

startstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

endstringoptional

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

datestring · dateoptional

time_zonestringoptional

IANA time zone name, e.g. America/Chicago.

pattern ^[A-Za-z_]+(/[A-Za-z_+-]+)+$|^UTC$

time_statusstringrequired

one ofconfirmedestimatedtbd

statusstringrequired

one ofscheduledpostponedcancelledcompletedin_progressforfeit

venueobjectoptional

Show 4 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

fieldstringoptional

geoarray of anyoptional

[latitude, longitude] in WGS-84 decimal degrees.

2–2 items

sidesarray of objectoptional

Show 2 nested fields ›

rolestringrequired

one ofhomeawayparticipant

teamRefrequired

Show 2 nested fields ›

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

titlestringoptional

resultobjectoptional

A score for a fixture. Several results may be observed; the hub picks one by policy and keeps the rest.

Show 5 nested fields ›

scoresarray of objectrequired

1–2 items

Show 3 nested fields ›

rolestringrequired

one ofhomeawayparticipant

scoreintegerrequired

0–∞

penaltiesintegeroptional

Shoot-out score, if any.

0–∞

finalbooleanrequired

officialbooleanoptional

True when the host or a scoring partner marks the result official.

default false

periodstringoptional

Current period for in-progress results, e.g. 2H, Q3, T7.

0–20 characters

outcomestringoptional

one ofhome_winaway_windrawforfeit_homeforfeit_awayabandoned

provenancemap of Provenancerequired

Field name → provenance of the observation that won it.

external_idsmap of stringoptional

Source key → the source's external id for this fixture.

previousany | nulloptional

updated_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

versionintegerrequired

1–∞

Fixture shape

{
  "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "type": "fixture",
  "sport": "soccer",
  "kind": "game",
  "competition": {
    "id": "cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE",
    "name": "Dallas Cup 2027"
  },
  "division": {
    "id": "div_01J7Y3M2K9QW8ZP4R6T1N0A5BF",
    "name": "2014 Boys Premier",
    "age_group": "U13",
    "gender": "M",
    "level": "Premier"
  },
  "stage": {
    "id": "stg_01J7Y3M2K9QW8ZP4R6T1N0A5BG",
    "name": "Pool B",
    "type": "pool"
  },
  "start": "2027-04-10T14:00:00Z",
  "end": "2027-04-10T14:00:00Z",
  "date": "2027-04-10",
  "time_zone": "America/Chicago",
  "time_status": "confirmed",
  "status": "scheduled",
  "venue": {
    "id": "ven_01J7Y3M2K9QW8ZP4R6T1N0A5BH",
    "name": "MoneyGram Soccer Park",
    "field": "Field 7",
    "geo": [
      "string"
    ]
  },
  "sides": [
    {
      "role": "home",
      "team": {
        "id": "tm_01J7Y3M2K9QW8ZP4R6T1N0A5BD",
        "name": "Lakeside FC 2014B Blue"
      }
    }
  ],
  "title": "Invalid parameter",
  "result": {
    "scores": [
      {
        "role": "home",
        "score": 1,
        "penalties": 1
      }
    ],
    "final": true,
    "official": false,
    "period": "FT",
    "outcome": "home_win"
  },
  "provenance": {
    "start": {
      "source": "gotsport",
      "observed_at": "2027-04-10T14:00:00Z",
      "confidence": 0.98,
      "observation_id": "obs_01J7Y3M2K9QW8ZP4R6T1N0A5BK"
    }
  },
  "external_ids": {
    "start": "string"
  },
  "previous": "string",
  "updated_at": "2027-04-10T14:00:00Z",
  "version": 7
}

Standings

A derived table for one stage. Never hand-edited; a wrong table is a wrong result.

stagestringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

namestringoptional

typestringoptional

divisionstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

division_namestringoptional

competitionstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

completebooleanoptional

tiebreak_sourcestringoptional

one ofstagedefault

versionintegeroptional

as_ofstringoptional

RFC 3339, UTC

pointsstringoptional

Points per win-draw-loss, e.g. 3-1-0.

tiebreakersarray of stringoptional

missing_fixturesarray of stringoptional

derived_fromarray of stringoptional

fixture@version inputs

rowsarray of objectoptional

Show 13 nested fields ›

teamstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

team_namestringoptional

positionintegeroptional

playedintegeroptional

winsintegeroptional

drawsintegeroptional

lossesintegeroptional

goals_forintegeroptional

goals_againstintegeroptional

goal_diffintegeroptional

pointsintegeroptional

provisionalbooleanoptional

tracearray of stringoptional

The rules that placed this row, in order.

Standings shape

{
  "stage": "stg_01J7Y3M2K9QW8ZP4R6T1N0A5BG",
  "name": "Lakeside FC 2014B Blue",
  "type": "string",
  "division": "div_01J7Y3M2K9QW8ZP4R6T1N0A5BF",
  "division_name": "2014 Boys Premier",
  "competition": "cmp_01J7Y3M2K9QW8ZP4R6T1N0A5BE",
  "complete": true,
  "tiebreak_source": "stage",
  "version": 7,
  "as_of": "2027-04-10T14:00:00Z",
  "points": "3-1-0",
  "tiebreakers": [
    "string"
  ],
  "missing_fixtures": [
    "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC"
  ],
  "derived_from": [
    "string"
  ],
  "rows": [
    {
      "team": "tm_01J7Y3M2K9QW8ZP4R6T1N0A5BD",
      "team_name": "Lakeside FC 2014B Blue",
      "position": 1,
      "played": 1,
      "wins": 1,
      "draws": 1,
      "losses": 1,
      "goals_for": 1,
      "goals_against": 1,
      "goal_diff": 1,
      "points": 1,
      "provisional": true,
      "trace": [
        "string"
      ]
    }
  ]
}

Change

idstringrequired

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

typestringrequired

eventstringrequired

The oyss.* event type that produced this change.

versionintegerrequired

atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

changed_fieldsarray of stringoptional

Change shape

{
  "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "type": "string",
  "event": "oyss.fixture.rescheduled",
  "version": 7,
  "at": "2027-04-10T14:00:00Z",
  "changed_fields": [
    "string"
  ]
}

Subscription

urlstring · urirequired

eventsarray of stringrequired

1–∞ items

filtermap of stringoptional

Optional scope, e.g. {"competition": "cmp_…"} or {"team": "tm_…"}.

idstringrequired

modestringrequired

one oftestlive

secretstringrequired

HMAC-SHA256 signing secret, shown once.

created_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

Subscription shape

{
  "url": "https://example.com/hooks/sideline",
  "events": [
    "string"
  ],
  "filter": {
    "start": "string"
  },
  "id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "mode": "test",
  "secret": "whsec_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "created_at": "2027-04-10T14:00:00Z"
}

BatchReceipt

batch_idstringrequired

acceptedintegerrequired

rejectedintegerrequired

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

pathstringoptional

messagestringoptional

BatchReceipt shape

{
  "batch_id": "fx_01J7Y3M2K9QW8ZP4R6T1N0A5BC",
  "accepted": 1,
  "rejected": 1,
  "errors": [
    {
      "index": 1,
      "path": "/observations/3/data/start",
      "message": "must end in Z"
    }
  ]
}

Provenance

Where a canonical field's value came from.

sourcestringrequired

Source key, e.g. gotsport or web:dallascup.com.

observed_atstringrequired

RFC 3339 timestamp in UTC (must end in Z).

RFC 3339, UTC

confidencenumberoptional

0–1

observation_idstringoptional

Canonical hub identifier: a type prefix and a ULID.

a prefixed ULID, e.g. tm_01J7Y3M2K9QW8ZP4R6T1N0A5BC

Problem

typestring · urioptional

titlestringoptional

statusintegeroptional

detailstringoptional

instancestringoptional

errorsarray of objectoptional

Show 3 nested fields ›

indexintegeroptional

Observation index within the batch.

pathstringoptional

JSON pointer into the observation.

messagestringoptional

Problem shape

{
  "type": "https://example.com/hooks/sideline",
  "title": "Invalid parameter",
  "status": 1,
  "detail": "team must be a tm_ id.",
  "instance": "/v1/fixtures",
  "errors": [
    {
      "index": 1,
      "path": "/observations/3/data/start",
      "message": "must end in Z"
    }
  ]
}

Every error the API returns →Glossary →

API reference

Conventions

Ingest

Push a batch of observations

Headers

Request body · application/json

Responses

Read

List fixtures

Query parameters

Responses

Get one fixture with provenance

Path parameters

Responses

Every recorded change to a fixture

Path parameters

Responses

Find venues by name or by place

Query parameters

Responses

Get one venue

Path parameters

Responses

Browse competitions by sport, place and date

Query parameters

Responses

Get one competition with its divisions and venues

Path parameters

Responses

Standings for every stage of a competition

Path parameters

Responses

The standings table for one stage

Path parameters

Responses

Find teams by name

Query parameters

Responses

A competition's canonical fixtures as one Parquet file

Path parameters

Responses

Box-score lines for a fixture

Path parameters

Responses

Every reported result for a fixture, losers included

Path parameters

Responses

Sync

Delta sync

Query parameters

Responses

Calendars

iCalendar feed for a team

Path parameters

Responses

Webhooks

Register a webhook endpoint

Request body · application/json

Responses

The observation envelope

What data holds, by type

Objects

Fixture

Standings

Change

Subscription

BatchReceipt

Provenance

Problem

What `data` holds, by type