Badges | Orishare docs

Contribute to a badge

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.

customer_id*string

Length1 <= length <= 128

program_revision*integer

Range0 < value <= 9007199254740991

operation_key*string

Length1 <= length <= 200

expected_participation_id?string

The participation this command was confirmed on; refused with stale_write (reason participation_changed) when it is not the one the command acts on.

Length1 <= length <= 128

event_id*string

Length1 <= length <= 128

value*integer

Range0 <= value <= 9007199254740991

Response Body

`application/json`

curl -X POST "https://example.com/badges/string/contributions" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_example",    "program_revision": 2,    "operation_key": "operation-example",    "event_id": "evt_example",    "value": 1  }'

{  "id": "string",  "program_id": "string",  "customer_id": "string",  "participation_id": "string",  "state_revision": 0,  "execution_id": "string",  "outcome": "string",  "effects": [    null  ],  "transition_ids": [    "string"  ],  "grant_ids": [    "string"  ],  "revocation_ids": [    "string"  ],  "occurrence": "string",  "progress": "string",  "rank": "string",  "pending": true}

Grant a badge rank

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.

customer_id*string

Length1 <= length <= 128

program_revision*integer

Range0 < value <= 9007199254740991

operation_key*string

Length1 <= length <= 200

expected_participation_id?string

The participation this command was confirmed on; refused with stale_write (reason participation_changed) when it is not the one the command acts on.

Length1 <= length <= 128

event_id*string

Length1 <= length <= 128

rank_key?string

Length1 <= length <= 128

Response Body

`application/json`

curl -X POST "https://example.com/badges/string/grants" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_example",    "program_revision": 2,    "operation_key": "operation-example",    "event_id": "evt_example",    "rank_key": "bronze"  }'

{  "id": "string",  "program_id": "string",  "customer_id": "string",  "participation_id": "string",  "state_revision": 0,  "execution_id": "string",  "outcome": "string",  "effects": [    null  ],  "transition_ids": [    "string"  ],  "grant_ids": [    "string"  ],  "revocation_ids": [    "string"  ],  "occurrence": "string",  "progress": "string",  "rank": "string",  "pending": true}

Restore a revoked badge

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.

customer_id*string

Length1 <= length <= 128

program_revision*integer

Range0 < value <= 9007199254740991

operation_key*string

Length1 <= length <= 200

expected_participation_id?string

The participation this command was confirmed on; refused with stale_write (reason participation_changed) when it is not the one the command acts on.

Length1 <= length <= 128

event_id*string

Length1 <= length <= 128

revocation_id*string

Length1 <= length <= 128

Response Body

`application/json`

curl -X POST "https://example.com/badges/string/restores" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_example",    "program_revision": 2,    "operation_key": "operation-example",    "event_id": "evt_example",    "revocation_id": "brv_example"  }'

{  "id": "string",  "program_id": "string",  "customer_id": "string",  "participation_id": "string",  "state_revision": 0,  "execution_id": "string",  "outcome": "string",  "effects": [    null  ],  "transition_ids": [    "string"  ],  "grant_ids": [    "string"  ],  "revocation_ids": [    "string"  ],  "occurrence": "string",  "progress": "string",  "rank": "string",  "pending": true}

Revoke a badge for fraud

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.

customer_id*string

Length1 <= length <= 128

program_revision*integer

Range0 < value <= 9007199254740991

operation_key*string

Length1 <= length <= 200

expected_participation_id?string

The participation this command was confirmed on; refused with stale_write (reason participation_changed) when it is not the one the command acts on.

Length1 <= length <= 128

grant_id*string

Length1 <= length <= 128

reason*string

audit_evidence*

Response Body

`application/json`

curl -X POST "https://example.com/badges/string/revocations" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_example",    "program_revision": 2,    "operation_key": "operation-example",    "grant_id": "bgr_example",    "reason": "fraud",    "audit_evidence": {      "case_id": "case_example"    }  }'

{  "id": "string",  "program_id": "string",  "customer_id": "string",  "participation_id": "string",  "state_revision": 0,  "execution_id": "string",  "outcome": "string",  "effects": [    null  ],  "transition_ids": [    "string"  ],  "grant_ids": [    "string"  ],  "revocation_ids": [    "string"  ],  "occurrence": "string",  "progress": "string",  "rank": "string",  "pending": true}

Correct a retained badge contribution

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.

customer_id*string

Length1 <= length <= 128

program_revision*integer

Range0 < value <= 9007199254740991

operation_key*string

Length1 <= length <= 200

expected_participation_id?string

The participation this command was confirmed on; refused with stale_write (reason participation_changed) when it is not the one the command acts on.

Length1 <= length <= 128

contribution_id*string

Length1 <= length <= 128

amount?integer

Range0 < value <= 9007199254740991

fraction?string

Match^(?:0(?:\.\d+)?|1(?:\.0+)?)$

Lengthlength <= 14

reason*string

Length1 <= length <= 128

Response Body

`application/json`

curl -X POST "https://example.com/badges/string/corrections" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_example",    "program_revision": 2,    "operation_key": "operation-example",    "contribution_id": "pc_original",    "fraction": "1",    "reason": "Correct original contribution"  }'

{  "id": "string",  "program_id": "string",  "customer_id": "string",  "participation_id": "string",  "state_revision": 0,  "execution_id": "string",  "outcome": "string",  "effects": [    null  ],  "transition_ids": [    "string"  ],  "grant_ids": [    "string"  ],  "revocation_ids": [    "string"  ],  "occurrence": "string",  "progress": "string",  "rank": "string",  "pending": true}

Queue recognition-only badge backfill

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.

customer_id*string

Length1 <= length <= 128

program_revision*integer

Range0 < value <= 9007199254740991

operation_key*string

Length1 <= length <= 200

version_id*string

Length1 <= length <= 128

from*string

Match

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Formatdate-time

until*string

Match

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Formatdate-time

accepted_before*string

Match

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Formatdate-time

mode*string

expected_participation_id?string

The participation this command was confirmed on; refused with stale_write (reason participation_changed) when it is not the one the command acts on.

Length1 <= length <= 128

Response Body

`application/json`

curl -X POST "https://example.com/badges/string/backfills" \  -H "Idempotency-Key: string" \  -H "If-Match: string" \  -H "Content-Type: application/json" \  -d '{    "customer_id": "cust_example",    "program_revision": 2,    "operation_key": "backfill-example",    "version_id": "pv_example",    "from": "2026-09-01T00:00:00.000Z",    "until": "2026-09-02T00:00:00.000Z",    "accepted_before": "2026-09-03T00:00:00.000Z",    "mode": "recognition_only"  }'

{  "id": "string",  "program_id": "string",  "version_id": "string",  "participation_id": "string",  "status": "pending",  "mode": "recognition_only",  "state_revision": 0}

List badge programs

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Query Parameters

limit?integer

Range1 <= value <= 100

Default50

cursor?string

Lengthlength <= 2048

status?string

Value in

"draft"
"active"
"paused"
"ended"
"archived"

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`

curl -X GET "https://example.com/badges"

{  "data": [    {      "id": "string",      "environment_id": "string",      "kind": "badge",      "key": "string",      "name": "string",      "status": "draft",      "active_version_id": "string",      "authority": "legacy",      "legacy_table": "string",      "version": -9007199254740991,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "archived_at": "2019-08-24T14:15:22Z",      "rarity": [        {          "rank_key": "string",          "holders": 0,          "population": 0,          "rarity_percent": "string",          "rarity_tier": "common"        }      ]    }  ],  "next_cursor": "string",  "has_more": true}

Read a badge program

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`

curl -X GET "https://example.com/badges/string"

{  "id": "string",  "environment_id": "string",  "kind": "badge",  "key": "string",  "name": "string",  "status": "draft",  "active_version_id": "string",  "authority": "legacy",  "legacy_table": "string",  "version": -9007199254740991,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "archived_at": "2019-08-24T14:15:22Z",  "rarity": [    {      "rank_key": "string",      "holders": 0,      "population": 0,      "rarity_percent": "string",      "rarity_tier": "common"    }  ]}

List retained badge participations

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

customer_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`

curl -X GET "https://example.com/badges/string/participations"

{  "data": [    {      "id": "string",      "program_id": "string",      "program_version_id": "string",      "customer_id": "string",      "status": "enrolled",      "state_revision": "string",      "state": {        "schema": "orishare.mechanic-state/v1",        "revision": "string",        "kind": "badge",        "progress": "string",        "highest_rank": "string",        "occurrence": "string"      },      "effective_trust": "anonymous_claim",      "timezone": "string",      "timezone_source": "environment",      "tzdata_version": "string",      "enrolled_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z",      "standing": "current"    }  ],  "next_cursor": "string",  "has_more": true}

Read a retained badge participation

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

participation_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`

curl -X GET "https://example.com/badges/string/participations/string"

{  "id": "string",  "program_id": "string",  "program_version_id": "string",  "customer_id": "string",  "status": "enrolled",  "state_revision": "string",  "state": {    "schema": "orishare.mechanic-state/v1",    "revision": "string",    "kind": "badge",    "progress": "string",    "highest_rank": "string",    "occurrence": "string"  },  "effective_trust": "anonymous_claim",  "timezone": "string",  "timezone_source": "environment",  "tzdata_version": "string",  "enrolled_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "standing": "current"}

List the grants of a badge participation

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

participation_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`

curl -X GET "https://example.com/badges/string/participations/string/grants"

{  "data": [    {      "id": "string",      "rank_key": "string",      "occurrence": "string",      "created_at": "2019-08-24T14:15:22Z",      "revoked": true    }  ],  "next_cursor": "string",  "has_more": true}

List the revocations of a badge participation

Authorization

AuthorizationBearer <token>

Secret API key bound to an environment.

In: header

Path Parameters

id*string

Length1 <= length

participation_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`

curl -X GET "https://example.com/badges/string/participations/string/revocations"

{  "data": [    {      "id": "string",      "grant_id": "string",      "reason": "fraud",      "created_at": "2019-08-24T14:15:22Z",      "restored": true    }  ],  "next_cursor": "string",  "has_more": true}

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

501application/json

201application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

501application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

501application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

501application/json

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

501application/json

202application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

501application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

421application/json

422application/json

429application/json

500application/json

501application/json

200application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`