Regions & categories — API reference

Two read-only endpoints that return the full integer-id catalog used by filters.regions[] and filters.categories[] on forecasts and drivers. They are discovery only — submitting an id that isn't in the listing is not an error; the only enforced rule is integer range 1–9999.

For walkthroughs with curl / Python / Go, see the feature page: Regions & categories.

Common contract

Both endpoints share authentication, response shape, and error codes.

Authentication

Same as every /api/v1 route: send Authorization: Bearer with an API key (sk_ops_...) or a dashboard session token. See Authentication.

Availability

If the dimensions backend is not enabled for your account, both endpoints return 503 with {"error":"…"}. Contact [email protected] if you need this feature.

Success response

200 and JSON:

{
  "items": [
    {
      "id": 42,
      "name": "Example",
      "code": 100,
      "parent_id": null,
      "path": "/…",
      "latitude": 0.0,
      "longitude": 0.0
    }
  ]
}

• items is the complete listing — no pagination.
• Every entry includes integer id plus dimension-specific fields (names, codes, hierarchy).

Error codes

Code	Typical cause
401	Missing or invalid bearer token.
502	Dimensions backend unreachable or returned an error. The body is {"error":"…"} — contact [email protected] if it persists.
503	Dimensions backend not enabled for this account.

Regions

GET /api/v1/regions returns all regions, sorted by integer id ascending.

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  https://api.sybilion.dev/api/v1/regions \
  | jq '.items | length'

Categories

GET /api/v1/categories returns all categories, sorted by integer id ascending. Same envelope and error model as regions.

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  https://api.sybilion.dev/api/v1/categories \
  | jq '.items[0]'

See also

• Feature walkthrough with Python / Go tabs: Regions & categories
• Consumed by: POST /api/v1/forecasts and POST /api/v1/drivers via the filters object.
• Interactive OpenAPI — try both endpoints from Swagger when the dimensions backend is enabled.