# Organization API: Org Game Network

> Every Organization API operation tagged Org Game Network.

Source: https://www.coritan.com/docs/api/reference/organizations/org-game-network/

Base URL: `https://api.coritan.com/api/v1`. Paths below are complete.

To try these requests in the browser, open the [interactive Organization API reference](https://api.coritan.com/docs/org).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/network/entitlements`](#op-get-api-v1-orgs-org-slug-network-entitlements) | Lists the purchases the network delivers, in the order they last changed |
| POST | [`/api/v1/orgs/{org_slug}/network/entitlements/{service_id}/delivery`](#op-post-api-v1-orgs-org-slug-network-entitlements-service-id-delivery) | Records how a purchase's delivery went |
| GET | [`/api/v1/orgs/{org_slug}/network/leaderboards`](#op-get-api-v1-orgs-org-slug-network-leaderboards) | The leaderboards as the backend last pushed them, each board's entries in rank order |
| PUT | [`/api/v1/orgs/{org_slug}/network/leaderboards`](#op-put-api-v1-orgs-org-slug-network-leaderboards) | Replaces the leaderboards: up to 30 boards of up to 100 entries each |
| GET | [`/api/v1/orgs/{org_slug}/network/market`](#op-get-api-v1-orgs-org-slug-network-market) | The market as the backend last pushed it |
| PUT | [`/api/v1/orgs/{org_slug}/network/market`](#op-put-api-v1-orgs-org-slug-network-market) | Replaces the market |
| POST | [`/api/v1/orgs/{org_slug}/network/players`](#op-post-api-v1-orgs-org-slug-network-players) | Records players the network has seen, so the website can look a name up |
| GET | [`/api/v1/orgs/{org_slug}/network/players/lookup`](#op-get-api-v1-orgs-org-slug-network-players-lookup) | Whether the network has seen a player with this name |
| GET | [`/api/v1/orgs/{org_slug}/network/status`](#op-get-api-v1-orgs-org-slug-network-status) | The network's status as the backend last pushed it, with the addresses players join on |
| PUT | [`/api/v1/orgs/{org_slug}/network/status`](#op-put-api-v1-orgs-org-slug-network-status) | Replaces the network's status |

### Lists the purchases the network delivers, in the order they last changed {#op-get-api-v1-orgs-org-slug-network-entitlements}

`GET /api/v1/orgs/{org_slug}/network/entitlements`

Lists the purchases the network delivers, in the order they last changed. They are the
organization's services of its `custom_standalone` products, ordered by `updated_at`, then
`service_id`. Each has the customer, the product, its `status` and `billing_cycle`, the
`config` the customer ordered with, its dates and the `delivery` you last recorded.
`next_cursor` reads the next page and is null on the last one. Recording a delivery, a
payment, a renewal or a cancellation moves a purchase to the end. Needs an organization
API key with `network:read`. 422 for a time, cursor or limit that is wrong.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `updated_after` | query | string (date-time) or null | no | Only purchases that changed at or after this time, in ISO 8601. Leave it out to start from the first. |
| `cursor` | query | string or null | no | The `next_cursor` of the page before, to read the next page. |
| `limit` | query | integer | no | Purchases a page, 1–500. Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Records how a purchase's delivery went {#op-post-api-v1-orgs-org-slug-network-entitlements-service-id-delivery}

`POST /api/v1/orgs/{org_slug}/network/entitlements/{service_id}/delivery`

Records how a purchase's delivery went. The `status` is `delivered`, `waiting` or
`failed`, with an optional `detail`. It is kept in the purchase's `config.delivery` as
`{"status", "at", "detail"}`, which the customer's account returns with the service,
replaces the delivery recorded before and is in the organization's audit log. Answers `{"entitlement"}` as the list shows it.
Needs an organization API key with `network:write`. 404 for a purchase that is not one of
the organization's `custom_standalone` services.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes | The purchase's `service_id` from the entitlements list. |
| `org_slug` | path | string | yes |  |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string, one of `delivered`, `waiting`, `failed` | yes | `delivered` once the player has it, `waiting` while it waits for them (until they next join, for instance), or `failed` when it could not be given. |
| `detail` | string or null | no | A sentence about this delivery, at most 300 characters. The customer can read it in their account, so write it for them. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The leaderboards as the backend last pushed them, each board's entries in rank order {#op-get-api-v1-orgs-org-slug-network-leaderboards}

`GET /api/v1/orgs/{org_slug}/network/leaderboards`

The leaderboards as the backend last pushed them, each board's entries in rank order.
Needs no auth. Coritan, browsers and caches each keep an answer for up to 15 seconds, so
a push can take up to a minute to show. Before the first push `boards` is empty and
`updated_at` is null; `stale` is true when the last push is more than five minutes old.
404 for an unknown organization.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Replaces the leaderboards: up to 30 boards of up to 100 entries each {#op-put-api-v1-orgs-org-slug-network-leaderboards}

`PUT /api/v1/orgs/{org_slug}/network/leaderboards`

Replaces the leaderboards: up to 30 boards of up to 100 entries each. Push them every
five to fifteen minutes. Needs an organization API key with `network:write`. Answers
`{"kind": "leaderboards", "updated_at"}`; 422 names the field that is wrong, 413 past
2 MB.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `boards` | array of Board | yes | Every board, at most 30, each `key` once, in the order the website shows them. The push replaces the last one. |
| `boards[].key` | string | yes | Your own ID for the board, such as `richest`: 1–64 letters, digits and `_ . : / -`. |
| `boards[].title` | string | yes | The board's title, as the website shows it. |
| `boards[].unit` | string, one of `money`, `count`, `duration`, `time` | yes | What `value` counts: `money`, `count`, `duration` in seconds, or `time` in milliseconds (a best time, such as a parkour run). |
| `boards[].entries` | array of BoardEntry | no | The board's top entries, at most 100. They are stored in `rank` order. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The market as the backend last pushed it {#op-get-api-v1-orgs-org-slug-network-market}

`GET /api/v1/orgs/{org_slug}/network/market`

The market as the backend last pushed it. It holds `items`, the `categories` they use
in the order they first appear, and `currency_symbol`. Needs no auth. Coritan, browsers and
caches each keep an answer for up to 15 seconds, so a push can take up to a minute to
show. Before the first push `items` is empty and `updated_at` is null; `stale` is true
when the last push is more than five minutes old. 404 for an unknown organization.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Replaces the market {#op-put-api-v1-orgs-org-slug-network-market}

`PUT /api/v1/orgs/{org_slug}/network/market`

Replaces the market. It holds every item with its sell and buy prices, its change over
24 hours and how many changed hands. An item left out leaves the market. Push it every
one to five minutes. Needs an organization API key with `network:write`. Answers
`{"kind": "market", "updated_at"}`; 422 for more than 1,000 items, two items with one
`key` or any other field that is wrong, which the answer names; 413 past 2 MB.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of MarketItem | yes | Every item on the market now, at most 1,000, each `key` once. The push replaces the last one, so an item you leave out leaves the market. |
| `items[].key` | string | yes | Your own ID for the item, such as `diamond`: 1–64 letters, digits and `_ . : / -`. |
| `items[].name` | string | yes | The item's name, as the website shows it. |
| `items[].category` | string or null | no | The group the website files the item under, such as `Ores`, or null. |
| `items[].sell` | number or null | no | What a player gets for selling one, or null when it cannot be sold. |
| `items[].buy` | number or null | no | What a player pays for one, or null when it cannot be bought. |
| `items[].change_24h` | number or null | no | How far the price moved over the last 24 hours, in percent (`-2.5` for down 2.5%), or null. |
| `items[].volume_24h` | number or null | no | How many changed hands over the last 24 hours, or null. |
| `currency_symbol` | string | no | The symbol the website shows with prices; `$` when left out. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Records players the network has seen, so the website can look a name up {#op-post-api-v1-orgs-org-slug-network-players}

`POST /api/v1/orgs/{org_slug}/network/players`

Records players the network has seen, so the website can look a name up. Each player
is kept once by UUID, with the name and edition of their latest sighting; a sighting
older than the one kept changes nothing. Send the players seen since the last push every
30 to 60 seconds, up to 1,000 a push. Needs an organization API key with `network:write`.
Answers `{"saved"}`, the number of distinct players; 422 names the field that is wrong.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `players` | array of PlayerSeen | yes | Players seen since your last push, at most 1,000. Send more in further pushes. |
| `players[].uuid` | string | yes | The player's UUID, with or without dashes. |
| `players[].name` | string | yes | The name the game shows, with the edition's prefix when it has one, such as `Steve`, `-Steve` or `.Steve`. |
| `players[].edition` | string, one of `java`, `java_offline`, `bedrock` | yes | `java`, `java_offline` for a non-premium Java Edition account, or `bedrock`. |
| `players[].last_seen` | string (date-time) | yes | When the player was last on the network, in ISO 8601. A time in the future counts as now. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Whether the network has seen a player with this name {#op-get-api-v1-orgs-org-slug-network-players-lookup}

`GET /api/v1/orgs/{org_slug}/network/players/lookup`

Whether the network has seen a player with this name. Answers `{"found": true,
"player": {"name", "uuid", "edition", "last_seen"}}` for the one seen most recently, or
`{"found": false}`. Needs no auth. Coritan, browsers and caches each keep an answer for
up to 15 seconds, so a new sighting can take up to a minute to show. 422 when the name
breaks the pattern; 404 for an unknown organization.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `name` | query | string | yes | The name to look up, in any case, with the edition's prefix when it has one, such as `-Steve`: an optional `-` or `.`, then 1–16 letters, digits and underscores. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The network's status as the backend last pushed it, with the addresses players join on {#op-get-api-v1-orgs-org-slug-network-status}

`GET /api/v1/orgs/{org_slug}/network/status`

The network's status as the backend last pushed it, with the addresses players join
on. Needs no auth. Coritan, browsers and caches each keep an answer for up to 15 seconds,
so a push can take up to a minute to show. Before the first push the values are null,
`regions` is empty and `updated_at` is null. `stale` is true when the last push is more
than five minutes old, or there has been none. 404 for an unknown organization.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Replaces the network's status {#op-put-api-v1-orgs-org-slug-network-status}

`PUT /api/v1/orgs/{org_slug}/network/status`

Replaces the network's status. It says whether the network is online, how many play,
the season and players per region. Push it every 15 to 60 seconds; the website calls the
status stale when the last push is more than five minutes old. Needs an organization API key with
`network:write`. Answers `{"kind": "status", "updated_at"}`; 422 names the field that
is wrong, 413 past 2 MB.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `online` | boolean | yes | Whether players can join the network now. |
| `players_online` | integer | yes | Players online across the network now. |
| `max_players` | integer or null | no | How many players the network takes at once, or null. |
| `version_label` | string or null | no | The game versions players can join with, as the website shows them, such as `1.21.x`, or null. |
| `season` | Season or null | no | The season running now, or null between seasons. |
| `season.name` | string | yes | The season's name, as players know it. |
| `season.started_at` | string (date-time) or null | no | When the season started, in ISO 8601. A time without an offset is taken as UTC. |
| `regions` | array of Region | no | Players online in each region, at most 20, each `key` once. Leave it out for a network with one region. |
| `regions[].key` | string | yes | Your own ID for the region: 1–64 letters, digits and `_ . : / -`. |
| `regions[].name` | string | yes | The region's name, as the website shows it. |
| `regions[].players_online` | integer | yes | Players online in this region now. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |