# Organization API: Customer Portal: Services

> The 12 Organization API operations for services.

Source: https://docs.coritan.com/api/reference/organizations/customer-portal/services/

Part of [Customer Portal](/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/services`](#op-get-api-v1-orgs-org-slug-portal-services) | List my services |
| GET | [`/api/v1/orgs/{org_slug}/portal/services/live`](#op-get-api-v1-orgs-org-slug-portal-services-live) | What the customer's servers are doing right now, in one request |
| GET | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}`](#op-get-api-v1-orgs-org-slug-portal-services-service-id) | Get my service |
| POST | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/cancel`](#op-post-api-v1-orgs-org-slug-portal-services-service-id-cancel) | Cancel one of the customer's own services, now or at the end of term |
| POST | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/cancel-plan-change`](#op-post-api-v1-orgs-org-slug-portal-services-service-id-cancel-plan-change) | Cancel an unpaid upgrade so a different plan can be chosen |
| GET | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/cancel-preview`](#op-get-api-v1-orgs-org-slug-portal-services-service-id-cancel-preview) | What cancelling right now would return, before committing to it |
| POST | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/change-plan`](#op-post-api-v1-orgs-org-slug-portal-services-service-id-change-plan) | Change my service plan |
| GET | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/community-listing`](#op-get-api-v1-orgs-org-slug-portal-services-service-id-community-listing) | Get community listing |
| PUT | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/community-listing`](#op-put-api-v1-orgs-org-slug-portal-services-service-id-community-listing) | Upsert community listing |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/gameproxy`](#op-patch-api-v1-orgs-org-slug-portal-services-service-id-gameproxy) | Update join-address branding (MOTD/favicon) for a service's sidecar gameproxy route |
| GET | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/plan-preview`](#op-get-api-v1-orgs-org-slug-portal-services-service-id-plan-preview) | What a plan change costs today, before committing to it |
| GET | [`/api/v1/orgs/{org_slug}/portal/services/{service_id}/plans`](#op-get-api-v1-orgs-org-slug-portal-services-service-id-plans) | Sizes this service can move to |

### List my services {#op-get-api-v1-orgs-org-slug-portal-services}

`GET /api/v1/orgs/{org_slug}/portal/services`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status_filter` | query | string | no |  |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `50`. |
| `consistency` | query | string, one of `strong`, `eventual` | no | strong (default): read the primary, as a client that has just written must. eventual: an idle poll that may read a pooled replica; the page is still healed on the primary whenever it has something to heal. Default: `strong`. |

#### Responses

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

### What the customer's servers are doing right now, in one request {#op-get-api-v1-orgs-org-slug-portal-services-live}

`GET /api/v1/orgs/{org_slug}/portal/services/live`

What the customer's servers are doing right now, in one request.

Declared above ``/services/{service_id}`` deliberately: that route parses an
int, so "live" would 422 rather than reach this one.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `refresh` | query | boolean | no | Default: `False`. |
| `ids` | query | string | no | Comma-separated service ids to probe |

#### Responses

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

### Get my service {#op-get-api-v1-orgs-org-slug-portal-services-service-id}

`GET /api/v1/orgs/{org_slug}/portal/services/{service_id}`

#### Parameters

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

#### Responses

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

### Cancel one of the customer's own services, now or at the end of term {#op-post-api-v1-orgs-org-slug-portal-services-service-id-cancel}

`POST /api/v1/orgs/{org_slug}/portal/services/{service_id}/cancel`

Cancel one of the customer's own services, now or at the end of term.

The sequence lives in ``app.services.org_service_lifecycle`` so staff
cancelling on a customer's behalf run the very same one.

A cancellation keeps a paid container on the org's free plan when it sells
one. ``delete_server`` (with ``immediate``) is the panel's Delete Server,
which deletes it regardless; without ``immediate`` it is a 422.

#### Parameters

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

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `immediate` | boolean | no |
| `reason` | string or null | no |
| `keep_ipv4` | boolean | no |
| `keep_snapshot` | boolean | no |
| `delete_server` | boolean | no |

#### Responses

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

### Cancel an unpaid upgrade so a different plan can be chosen {#op-post-api-v1-orgs-org-slug-portal-services-service-id-cancel-plan-change}

`POST /api/v1/orgs/{org_slug}/portal/services/{service_id}/cancel-plan-change`

Cancel an unpaid upgrade so a different plan can be chosen.

#### Parameters

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

#### Responses

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

### What cancelling right now would return, before committing to it {#op-get-api-v1-orgs-org-slug-portal-services-service-id-cancel-preview}

`GET /api/v1/orgs/{org_slug}/portal/services/{service_id}/cancel-preview`

What cancelling right now would return, before committing to it.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `immediate` | query | boolean | no | Default: `True`. |

#### Responses

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

### Change my service plan {#op-post-api-v1-orgs-org-slug-portal-services-service-id-change-plan}

`POST /api/v1/orgs/{org_slug}/portal/services/{service_id}/change-plan`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `org_pricing_id` | integer | yes |

#### Responses

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

### Get community listing {#op-get-api-v1-orgs-org-slug-portal-services-service-id-community-listing}

`GET /api/v1/orgs/{org_slug}/portal/services/{service_id}/community-listing`

#### Parameters

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

#### Responses

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

### Upsert community listing {#op-put-api-v1-orgs-org-slug-portal-services-service-id-community-listing}

`PUT /api/v1/orgs/{org_slug}/portal/services/{service_id}/community-listing`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `display_name` | string or null | no |
| `slug` | string or null | no |
| `tagline` | string or null | no |
| `description` | string or null | no |
| `category` | string or null | no |
| `tags` | array of string or null | no |
| `website_url` | string or null | no |
| `discord_url` | string or null | no |
| `icon_data_uri` | string or null | no |
| `banner_data_uri` | string or null | no |
| `gallery` | array of string or null | no |
| `seo_title` | string or null | no |
| `seo_description` | string or null | no |
| `show_player_count` | boolean or null | no |
| `published` | boolean or null | no |

#### Responses

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

### Update join-address branding (MOTD/favicon) for a service's sidecar gameproxy route {#op-patch-api-v1-orgs-org-slug-portal-services-service-id-gameproxy}

`PATCH /api/v1/orgs/{org_slug}/portal/services/{service_id}/gameproxy`

Update join-address branding (MOTD/favicon) for a service's sidecar gameproxy route.

#### Parameters

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

#### Request body

`application/json` (required)

Type: Body.

#### Responses

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

### What a plan change costs today, before committing to it {#op-get-api-v1-orgs-org-slug-portal-services-service-id-plan-preview}

`GET /api/v1/orgs/{org_slug}/portal/services/{service_id}/plan-preview`

What a plan change costs today, before committing to it.

Charged on the days left in the current cycle, not the full price
difference: moving up on the last day of the month should cost a day.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `org_pricing_id` | query | integer | yes |

#### Responses

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

### Sizes this service can move to {#op-get-api-v1-orgs-org-slug-portal-services-service-id-plans}

`GET /api/v1/orgs/{org_slug}/portal/services/{service_id}/plans`

Sizes this service can move to.

Constrained to the same game, the same hardware tier and the same billing
cycle, so the list is genuinely "the same thing, bigger or smaller". Without
the game filter a Minecraft server was offered Terraria and Rust plans, and
without the cycle filter the same size appeared once per billing period.

#### Parameters

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

#### Responses

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