{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/api.runningcalendar.co.za" } ], "info": { "name": "RunningCalendar API Documentation", "_postman_id": "150e3373-87eb-4bea-a913-5755cd3cb77c", "description": "Read-only, server-to-server access to upcoming Southern African running events.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "Events", "description": "", "item": [ { "name": "List upcoming events", "request": { "url": { "host": "{{baseUrl}}", "path": "v1\/events", "query": [ { "key": "from", "value": "2026-07-01", "description": "ISO date \u2014 lower bound on the event date. Defaults to today. Ignored in sync mode.", "disabled": false }, { "key": "to", "value": "2026-12-31", "description": "ISO date \u2014 inclusive upper bound on the event date. Must be >= `from`. Ignored in sync mode.", "disabled": false }, { "key": "country", "value": "ZA", "description": "ISO2 country code. Defaults to all active Southern-African countries. Ignored in sync mode.", "disabled": false }, { "key": "province", "value": "gauteng", "description": "Province slug. Ignored in sync mode.", "disabled": false }, { "key": "city", "value": "cape-town", "description": "Town\/city slug. Ignored in sync mode.", "disabled": false }, { "key": "distance", "value": "10km,half-marathon", "description": "One or more distance band slugs, comma-separated. One of: ultra, marathon, 30km, half-marathon, 15km, 10km, 5km. Ignored in sync mode.", "disabled": false }, { "key": "updated_since", "value": "2026-06-01T00:00:00Z", "description": "ISO datetime \u2014 enables sync mode. Returns all editions changed at or after this timestamp.", "disabled": false }, { "key": "per_page", "value": "25", "description": "Page size, 1\u2013100 (hard-capped at 100). Defaults to 25.", "disabled": false }, { "key": "page", "value": "1", "description": "Page number.", "disabled": false } ], "raw": "{{baseUrl}}\/v1\/events?from=2026-07-01&to=2026-12-31&country=ZA&province=gauteng&city=cape-town&distance=10km%2Chalf-marathon&updated_since=2026-06-01T00%3A00%3A00Z&per_page=25&page=1" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"from\":\"2026-10-22T07:13:49\",\"to\":\"2052-11-14\",\"updated_since\":\"2026-10-22T07:13:49\",\"country\":\"ng\",\"province\":\"z\",\"city\":\"m\",\"distance\":\"architecto\",\"per_page\":22}" }, "description": "Returns a paginated list of upcoming, publicly-visible event editions,\nordered by date ascending. Mirrors the public website's visibility\nexactly. Every item carries links to its page on the website: `url` for\nyour website and `app_url` for your app, both tagged so the visits are\ncredited to your key, and an untagged `canonical_url` for matching.\n\nWhen `updated_since` is provided the endpoint switches to **sync mode**:\nit returns every edition whose `updated_at >= updated_since`, regardless\nof visibility, so a consumer can replay all changes since its last poll.\nEach item carries a `sync_status` field \u2014 `\"active\"` means the edition\nis currently live on the calendar; `\"removed\"` means it was changed but\nis no longer publicly visible (draft, cancelled, or past). A `removed`\nitem carries only `id`, `slug`, `sync_status`, and `updated_at` \u2014 never\nfull event data \u2014 to avoid leaking non-public content. Browse filters\n(`country`, `province`, `city`, `distance`) are ignored in sync mode;\nonly `updated_since` and pagination apply.\n\n**Known sync limitations:**\n- Hard deletes are not reported. `EventEdition` has no soft-deletes, so\n a hard-deleted row never surfaces as `removed`. Reliable delete-sync\n would require adding `SoftDeletes` to `EventEdition` \u2014 out of scope.\n- Time-based expiry is not a change event. An edition that simply became\n past does not get a new `updated_at`, so it will not surface as\n `removed` from the passage of time alone. Expire past events locally\n using the `date` field you already hold.\n- Boundary de-dup. The filter is inclusive (`>=`). Checkpoint on the max\n `updated_at` seen and re-request with it, de-duplicating by `id` (a\n handful of repeats at the timestamp boundary is expected and harmless)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Cape Town Marathon\",\"slug\":\"cape-town-marathon\",\"date\":\"2026-10-18\",\"end_date\":null,\"summary\":\"The 2026 Cape Town Marathon takes place on Sunday, 18 October 2026, at Green Point, Cape Town. It is a single 42.2km road race. Online entries are open.\",\"organiser\":{\"name\":\"Cape Town Marathon NPC\",\"url\":\"https:\/\/runningcalendar.co.za\/organisers\/cape-town-marathon-npc?utm_source=example&utm_medium=referral&utm_campaign=events_api\",\"app_url\":\"https:\/\/runningcalendar.co.za\/organisers\/cape-town-marathon-npc?utm_source=example&utm_medium=app&utm_campaign=events_api\"},\"races\":[{\"name\":\"42.2km\",\"distance_metres\":42195,\"distance_label\":\"Marathon\",\"race_type\":\"road\",\"start_time\":\"06:00\",\"race_fee_from\":250.0,\"race_fee_currency\":\"ZAR\"}],\"venue\":{\"town\":\"Cape Town\",\"province\":\"Western Cape\",\"country_iso2\":\"ZA\",\"lat\":-33.9249,\"lng\":18.4241},\"image_url\":\"https:\/\/media.runningcalendar.co.za\/7441\/cape-town-marathon-logo.png\",\"verification_status\":\"verified\",\"url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026?utm_source=example&utm_medium=referral&utm_campaign=events_api\",\"app_url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026?utm_source=example&utm_medium=app&utm_campaign=events_api\",\"canonical_url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026\"}],\"links\":{\"first\":\"...\",\"last\":\"...\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"per_page\":25,\"total\":1,\"source\":\"RunningCalendar\",\"docs_url\":\"https:\/\/api.runningcalendar.co.za\/docs\"}}", "name": "Success" }, { "header": [], "code": 200, "body": "{\"data\":[{\"id\":1,\"name\":\"Cape Town Marathon\",\"slug\":\"cape-town-marathon\",\"date\":\"2026-10-18\",\"end_date\":null,\"summary\":\"The 2026 Cape Town Marathon takes place on Sunday, 18 October 2026, at Green Point, Cape Town. It is a single 42.2km road race. Online entries are open.\",\"organiser\":{\"name\":\"Cape Town Marathon NPC\",\"url\":\"https:\/\/runningcalendar.co.za\/organisers\/cape-town-marathon-npc?utm_source=example&utm_medium=referral&utm_campaign=events_api\",\"app_url\":\"https:\/\/runningcalendar.co.za\/organisers\/cape-town-marathon-npc?utm_source=example&utm_medium=app&utm_campaign=events_api\"},\"races\":[{\"name\":\"42.2km\",\"distance_metres\":42195,\"distance_label\":\"Marathon\",\"race_type\":\"road\",\"start_time\":\"06:00\",\"race_fee_from\":null,\"race_fee_currency\":null}],\"venue\":{\"town\":\"Cape Town\",\"province\":\"Western Cape\",\"country_iso2\":\"ZA\",\"lat\":-33.9249,\"lng\":18.4241},\"image_url\":\"https:\/\/media.runningcalendar.co.za\/7441\/cape-town-marathon-logo.png\",\"verification_status\":\"verified\",\"url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026?utm_source=example&utm_medium=referral&utm_campaign=events_api\",\"app_url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026?utm_source=example&utm_medium=app&utm_campaign=events_api\",\"canonical_url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026\",\"sync_status\":\"active\",\"updated_at\":\"2026-06-01T08:00:00Z\"},{\"id\":2,\"slug\":\"old-cancelled-race\",\"sync_status\":\"removed\",\"updated_at\":\"2026-06-01T09:00:00Z\"}],\"links\":{\"first\":\"...\",\"last\":\"...\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"per_page\":25,\"total\":2,\"source\":\"RunningCalendar\",\"docs_url\":\"https:\/\/api.runningcalendar.co.za\/docs\"}}", "name": "Sync mode (updated_since)" }, { "header": [], "code": 401, "body": "{\"error\":{\"code\":\"unauthenticated\",\"message\":\"Invalid API key.\"}}", "name": "Missing or invalid key" }, { "header": [], "code": 429, "body": "{\"error\":{\"code\":\"rate_limited\",\"message\":\"Too many requests.\"}}", "name": "Rate limited" } ] }, { "name": "Fetch a single event", "request": { "url": { "host": "{{baseUrl}}", "path": "v1\/events\/:idOrSlug", "query": [], "raw": "{{baseUrl}}\/v1\/events\/:idOrSlug", "variable": [ { "id": "idOrSlug", "key": "idOrSlug", "value": "cape-town-marathon", "description": "The numeric edition id or the event slug." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Looks up one event edition by numeric id or by event slug. Applies the\nexact same visibility scope as the list \u2014 a draft, unpublished, hidden,\nor past edition returns 404 (never a leak). The payload uses the same\nbasic fields as a list item." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":1,\"name\":\"Cape Town Marathon\",\"slug\":\"cape-town-marathon\",\"date\":\"2026-10-18\",\"end_date\":null,\"summary\":\"The 2026 Cape Town Marathon takes place on Sunday, 18 October 2026, at Green Point, Cape Town. It is a single 42.2km road race. Online entries are open.\",\"organiser\":{\"name\":\"Cape Town Marathon NPC\",\"url\":\"https:\/\/runningcalendar.co.za\/organisers\/cape-town-marathon-npc?utm_source=example&utm_medium=referral&utm_campaign=events_api\",\"app_url\":\"https:\/\/runningcalendar.co.za\/organisers\/cape-town-marathon-npc?utm_source=example&utm_medium=app&utm_campaign=events_api\"},\"races\":[{\"name\":\"42.2km\",\"distance_metres\":42195,\"distance_label\":\"Marathon\",\"race_type\":\"road\",\"start_time\":\"06:00\",\"race_fee_from\":250.0,\"race_fee_currency\":\"ZAR\"}],\"venue\":{\"town\":\"Cape Town\",\"province\":\"Western Cape\",\"country_iso2\":\"ZA\",\"lat\":-33.9249,\"lng\":18.4241},\"image_url\":\"https:\/\/media.runningcalendar.co.za\/7441\/cape-town-marathon-logo.png\",\"verification_status\":\"verified\",\"url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026?utm_source=example&utm_medium=referral&utm_campaign=events_api\",\"app_url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026?utm_source=example&utm_medium=app&utm_campaign=events_api\",\"canonical_url\":\"https:\/\/runningcalendar.co.za\/events\/cape-town-marathon\/2026\"}}", "name": "Found" }, { "header": [], "code": 404, "body": "{\"error\":{\"code\":\"not_found\",\"message\":\"Resource not found.\"}}", "name": "Not found \/ not visible" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }