Orishare
API reference

List seasons

GET
/seasons

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Query Parameters

limit?integer
Range1 <= value <= 100
Default50
cursor?string
Lengthlength <= 2048

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/seasons"
{  "data": [    {      "id": "string",      "key": "string",      "name": "string",      "status": "draft",      "active_version_id": "string",      "version": 1    }  ],  "next_cursor": "string",  "has_more": true}

Create a season

POST
/seasons

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255
X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/seasons" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "key": "october",    "name": "October"  }'
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "active_version_id": "string",  "version": 1}

Read a season

GET
/seasons/{id}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/seasons/string"
{  "id": "string",  "key": "string",  "name": "string",  "status": "draft",  "active_version_id": "string",  "version": 1}

List immutable season versions

GET
/seasons/{id}/versions

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Query Parameters

limit?integer
Range1 <= value <= 100
Default50
cursor?string
Lengthlength <= 2048

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/seasons/string/versions"
{  "data": [    {      "id": "string",      "season_id": "string",      "version": 1,      "definition_hash": "string",      "starts_at": "2019-08-24T14:15:22Z",      "ends_at": "2019-08-24T14:15:22Z",      "admits_until": "2019-08-24T14:15:22Z",      "finalizes_at": "2019-08-24T14:15:22Z",      "definition": {        "schema": "orishare.season/v1",        "starts_at": "2019-08-24T14:15:22Z",        "ends_at": "2019-08-24T14:15:22Z",        "display": {          "title": "string",          "description": "string",          "image_url": "http://example.com",          "icon": "string",          "color": "string",          "sort_order": 0,          "hidden": false,          "locales": {}        },        "eligibility": {          "audience": [            "string"          ]        },        "admission": {          "grace_seconds": 0,          "max_lateness_seconds": 0        },        "settlement": {          "delay_seconds": 0        }      }    }  ],  "next_cursor": "string",  "has_more": true}

Publish an immutable season version

POST
/seasons/{id}/versions

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255
X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length
If-Match*string

Required revision, checked in the owning transaction.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/seasons/string/versions" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "definition": {      "schema": "orishare.season/v1",      "starts_at": "2026-10-01T00:00:00.000Z",      "ends_at": "2026-11-01T00:00:00.000Z",      "display": {        "title": "October"      },      "eligibility": {        "audience": []      },      "admission": {        "grace_seconds": 3600,        "max_lateness_seconds": 1800      },      "settlement": {        "delay_seconds": 60      }    }  }'
{  "season": {    "id": "string",    "key": "string",    "name": "string",    "status": "draft",    "active_version_id": "string",    "version": 1  },  "version": {    "id": "string",    "season_id": "string",    "version": 1,    "definition_hash": "string",    "starts_at": "2019-08-24T14:15:22Z",    "ends_at": "2019-08-24T14:15:22Z",    "admits_until": "2019-08-24T14:15:22Z",    "finalizes_at": "2019-08-24T14:15:22Z",    "definition": {      "schema": "orishare.season/v1",      "starts_at": "2019-08-24T14:15:22Z",      "ends_at": "2019-08-24T14:15:22Z",      "display": {        "title": "string",        "description": "string",        "image_url": "http://example.com",        "icon": "string",        "color": "string",        "sort_order": 0,        "hidden": false,        "locales": {}      },      "eligibility": {        "audience": [          "string"        ]      },      "admission": {        "grace_seconds": 0,        "max_lateness_seconds": 0      },      "settlement": {        "delay_seconds": 0      }    }  }}

Read an immutable season version

GET
/seasons/{id}/versions/{version_id}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length
version_id*string
Length1 <= length <= 255

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/seasons/string/versions/string"
{  "id": "string",  "season_id": "string",  "version": 1,  "definition_hash": "string",  "starts_at": "2019-08-24T14:15:22Z",  "ends_at": "2019-08-24T14:15:22Z",  "admits_until": "2019-08-24T14:15:22Z",  "finalizes_at": "2019-08-24T14:15:22Z",  "definition": {    "schema": "orishare.season/v1",    "starts_at": "2019-08-24T14:15:22Z",    "ends_at": "2019-08-24T14:15:22Z",    "display": {      "title": "string",      "description": "string",      "image_url": "http://example.com",      "icon": "string",      "color": "string",      "sort_order": 0,      "hidden": false,      "locales": {}    },    "eligibility": {      "audience": [        "string"      ]    },    "admission": {      "grace_seconds": 0,      "max_lateness_seconds": 0    },    "settlement": {      "delay_seconds": 0    }  }}

List season occurrences

GET
/seasons/{id}/occurrences

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Query Parameters

limit?integer
Range1 <= value <= 100
Default50
cursor?string
Lengthlength <= 2048

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/seasons/string/occurrences"
{  "data": [    {      "id": "string",      "season_id": "string",      "season_version_id": "string",      "occurrence_key": "string",      "starts_at": "2019-08-24T14:15:22Z",      "ends_at": "2019-08-24T14:15:22Z",      "admits_until": "2019-08-24T14:15:22Z",      "finalizes_at": "2019-08-24T14:15:22Z",      "status": "scheduled",      "revision": "string",      "cutoff_epoch": "string",      "sealed_at": "2019-08-24T14:15:22Z"    }  ],  "next_cursor": "string",  "has_more": true}

Materialize a pinned season occurrence

POST
/seasons/{id}/occurrences

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length

Header Parameters

Idempotency-Key*string

Required. Official clients generate a UUID when omitted by the caller.

Length1 <= length <= 255
X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length
If-Match*string

Required revision, checked in the owning transaction.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/seasons/string/occurrences" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "season_version_id": "sv_example",    "key": "october"  }'
{  "season": {    "id": "string",    "key": "string",    "name": "string",    "status": "draft",    "active_version_id": "string",    "version": 1  },  "occurrence": {    "id": "string",    "season_id": "string",    "season_version_id": "string",    "occurrence_key": "string",    "starts_at": "2019-08-24T14:15:22Z",    "ends_at": "2019-08-24T14:15:22Z",    "admits_until": "2019-08-24T14:15:22Z",    "finalizes_at": "2019-08-24T14:15:22Z",    "status": "scheduled",    "revision": "string",    "cutoff_epoch": "string",    "sealed_at": "2019-08-24T14:15:22Z"  }}

Read a season occurrence

GET
/seasons/{id}/occurrences/{occurrence_id}

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string
Length1 <= length
occurrence_id*string
Length1 <= length <= 255

Header Parameters

X-Orishare-Environment?string

Required for selected-environment authorization branches; API keys use their bound environment.

Length1 <= length
X-Orishare-Audit-Reason?string

Required for staff authorization. Records the reason for staff access.

Length1 <= length

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/seasons/string/occurrences/string"
{  "id": "string",  "season_id": "string",  "season_version_id": "string",  "occurrence_key": "string",  "starts_at": "2019-08-24T14:15:22Z",  "ends_at": "2019-08-24T14:15:22Z",  "admits_until": "2019-08-24T14:15:22Z",  "finalizes_at": "2019-08-24T14:15:22Z",  "status": "scheduled",  "revision": "string",  "cutoff_epoch": "string",  "sealed_at": "2019-08-24T14:15:22Z"}

Rules

Rules, immutable versions, publish, pause, simulate.

Segments

Static membership and dynamic segments computed from attributes, balances, tiers and activity.