# Coritan Docs

# Coritan API

> Automate what the dashboard does with the Coritan REST API, and find its base URL, credentials, formats and full reference.

Source: https://www.coritan.com/docs/api/

The Coritan API lets a script or an agent do what you do in the [dashboard](https://www.coritan.com/dashboard): order and manage services, pay invoices, edit DNS records and write to support. It is a REST API over HTTPS that takes and returns JSON, and the dashboard is built on the same endpoints.

Every request goes to one base URL:

```text
https://api.coritan.com/api/v1
```

## The two APIs

Client API
: Your own account: services, billing, DNS, support and everything else the dashboard shows you. Its paths start with `/api/v1`, such as `/api/v1/services/`, and it takes the access token you get by signing in.

Organization API
: An [organization](/docs/organizations/) that sells Coritan services under its own brand. Its members manage it with their own access token, and its storefront and its customers use it too. Its paths start with `/api/v1/orgs/{org_slug}`, where `{org_slug}` is the organization's short name.

[Authentication](/docs/api/authentication/) lists which credential each part of either API accepts.

## Make a first request

Sign in with [`POST /auth/login`](/docs/api/reference/client/authentication/#op-post-api-v1-auth-login) to get an access token, as [Make your first API request](/docs/get-started/first-steps-with-the-api/) shows step by step. Put the token in `CORITAN_TOKEN`, then read your account:

```bash
curl https://api.coritan.com/api/v1/auth/me \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "id": 4821,
  "email": "alex@example.com",
  "first_name": "Alex",
  "last_name": "Morgan",
  "status": "active",
  "credit_balance": 25.0,
  "currency": "USD"
}
```

A request without a valid token answers `401` or `403` with a `detail` that says why ([Errors](/docs/api/errors/)).

## How the API behaves

- [Authentication](/docs/api/authentication/): access and refresh tokens, how long they last, and the keys some parts of the Organization API take.
- [Errors](/docs/api/errors/): the status codes and the shapes of `detail`.
- [Rate limits](/docs/api/rate-limits/): how many requests you can send, and what to do with a `429`.
- [Pagination and filtering](/docs/api/pagination/): how lists are paged and filtered.
- [Idempotent requests](/docs/api/idempotency/): the `Idempotency-Key` header, so a retried payment or order happens once.

## Reference

The [API reference](/docs/api/reference/) lists every operation with its parameters, request body and responses, generated from the API itself:

- [Client API reference](/docs/api/reference/client/)
- [Organization API reference](/docs/api/reference/organizations/)

Each API also has an interactive reference, where you can send requests from the browser: [the Client API](https://api.coritan.com/docs) and [the Organization API](https://api.coritan.com/docs/org).

## Read these docs as text

Every page of these docs is also plain Markdown, for a script or an AI agent to read:

| What | Where |
| --- | --- |
| One page as Markdown | Add `index.md` to the page's address, such as [`/docs/api/rate-limits/index.md`](/docs/api/rate-limits/index.md) |
| A list of every page | [`/docs/llms.txt`](/docs/llms.txt) |
| Every guide in one file | [`/docs/llms-full.txt`](/docs/llms-full.txt) |
| The API guides and the whole reference in one file | [`/docs/api/llms-full.txt`](/docs/api/llms-full.txt) |
| A search | `https://www.coritan.com/docs/search.json?q=backups` answers with up to 12 results, each with its `title`, `url`, `section` and a `snippet` |

## Billing and availability

The API is free to use. You pay for the services you order through it, exactly as in the dashboard ([Billing](/docs/billing/)). The API is open to every account, and an organization's API is open to its members.

# Authentication

> Which credential each part of the Coritan API accepts, how to get and refresh an access token, and what API keys do today.

Source: https://www.coritan.com/docs/api/authentication/

Each route of the Coritan API takes one kind of credential, and the part of the API it belongs to decides which. This page lists each credential, the header it goes in, how you get it and how long it lasts. A few routes take none, such as [`GET /auth/turnstile`](/docs/api/reference/client/authentication/#op-get-api-v1-auth-turnstile) and the list of locations.

## Credentials by part of the API

| Part of the API | Paths | Credential | Header |
| --- | --- | --- | --- |
| Client API | `/api/v1/...`, except the paths below | Your access token | `Authorization: Bearer <token>` |
| Organization API | `/api/v1/orgs/{org_slug}/...` | A member's access token, or a staff console token | `Authorization: Bearer <token>` |
| Customer portal and storefront checkout | `/api/v1/orgs/{org_slug}/portal/...`, and the storefront's order and checkout routes | A customer token | `Authorization: Bearer <token>` |
| Commerce API | `/api/v1/orgs/{org_slug}/commerce/...` | A member's access token or staff console token, or an organization API key | `Authorization: Bearer <token>` or `X-API-Key: <key>` |
| Store API | `/api/v1/orgs/{org_slug}/store/...` | The store's publishable key, plus a customer token on the routes for a signed-in shopper | `x-publishable-api-key: <key>`, and `Authorization: Bearer <token>` |
| SMTP Relay send API | `/api/v1/mail/send` and `/api/v1/mail/send/limits` | A send API key | `X-Api-Key: <key>` |

[Access and refresh tokens](#access-and-refresh-tokens), [Organization credentials](#organization-credentials) and [Other keys](#other-keys) describe each credential.

## Access and refresh tokens

Sign in with [`POST /auth/login`](/docs/api/reference/client/authentication/#op-post-api-v1-auth-login), sending `email` and `password` as JSON. [Make your first API request](/docs/get-started/first-steps-with-the-api/) walks through it with curl. The answer holds `access_token`, `refresh_token`, `token_type` (`bearer`) and `expires_in`.

Access token
: Proves who you are on every Client API request, and on the Organization API for each organization you are a member of. It lasts 30 minutes unless Coritan changes the setting, and `expires_in` gives its lifetime in seconds.

Refresh token
: Gets a new pair from [`POST /auth/refresh`](/docs/api/reference/client/authentication/#op-post-api-v1-auth-refresh) with the body `{"refresh_token": "..."}`, with no password, verification check or second factor. It lasts 30 days unless Coritan changes the setting. Each new pair holds a refresh token with a full lifetime; the one you sent keeps working until its own expiry.

Pending token
: What the sign-in answers when [two-factor authentication](/docs/account/two-factor-authentication/) is on: `mfa_required: true` and an `mfa_token` that lasts 10 minutes (`expires_in: 600`). Send it as the bearer token to [`POST /auth/mfa/verify`](/docs/api/reference/client/authentication-mfa/#op-post-api-v1-auth-mfa-verify) with `{"code": "123456"}`, and the answer holds the access and refresh tokens. Every other route refuses it with `401` and `"error": "mfa_required"`.

Changing or resetting the password stops every token issued before it, and a suspended or closed account cannot use any token. The API has no sign-out route. [Sign out and end sessions](/docs/account/sessions/) explains how to stop a token working.

## Organization credentials

Member access token
: The same access token as the Client API. It reaches an organization's routes when you are its owner or a member, and your [role](/docs/organizations/roles-and-permissions/) decides what it may do. Without membership, a route answers `403` `Not a member of this organization`.

Staff console token
: A console session for one organization, from [`POST /orgs/{org_slug}/staff/auth/login`](/docs/api/reference/organizations/customer-authentication/staff/#op-post-api-v1-orgs-org-slug-staff-auth-login) with your Coritan email and password. Its tokens start with `ost_`. The access token lasts 24 hours, and [`POST /orgs/{org_slug}/staff/auth/refresh`](/docs/api/reference/organizations/customer-authentication/staff/#op-post-api-v1-orgs-org-slug-staff-auth-refresh) swaps the refresh token, which lasts 30 days, for a new pair. It reaches every route a member's access token reaches. The actions that move money or end things also need a *step-up* in the last 10 minutes, which only a console session has: [Confirm it is you](/docs/organizations/staff-console/sign-in/#confirm-it-is-you) lists them.

Customer token
: A customer of an organization's storefront, from [`POST /orgs/{org_slug}/auth/login`](/docs/api/reference/organizations/customer-authentication/auth/#op-post-api-v1-orgs-org-slug-auth-login). The access token lasts 24 hours and the refresh token 30 days, and [`POST /orgs/{org_slug}/auth/refresh`](/docs/api/reference/organizations/customer-authentication/auth/#op-post-api-v1-orgs-org-slug-auth-refresh) swaps them for a new pair. [Sign in your storefront's customers](/docs/organizations/storefront/customer-sign-in/) has the details. A customer token never reaches the routes for members.

Organization API key
: Lets your own systems call the [Commerce API](/docs/organizations/storefront/commerce-api/) without a person signing in. An owner or admin creates it with [`POST /orgs/{org_slug}/api-keys`](/docs/api/reference/organizations/api-keys/#op-post-api-v1-orgs-org-slug-api-keys); it starts with `ct_`, and the answer shows it once. Its scopes decide which routes it reaches, it has an hourly request limit (4,000 by default), and it can have a list of addresses it may be used from. No route outside the Commerce API reads it. [Create organization API keys](/docs/organizations/api-keys/) lists the scopes.

Publishable key
: Names a store to the [Store API](/docs/organizations/storefront/store-api/), which serves shoppers, so the key can sit in your storefront's code. Create one with [`POST /orgs/{org_slug}/commerce/publishable-keys`](/docs/api/reference/organizations/commerce/commerce/#op-post-api-v1-orgs-org-slug-commerce-publishable-keys). A test key starts with `pk_test_`. A live key starts with `pk_live_`, and works once the store is live.

## Other keys

Send API key
: Sends mail through one SMTP Relay service over HTTPS, and does nothing else. Create it on the relay, as [Manage send API keys](/docs/mail/smtp-relay/api-keys/) shows; it starts with `mk_`. The send API reads it from `X-Api-Key` only, never from `Authorization`. [Send email over HTTPS](/docs/mail/smtp-relay/send-with-the-api/) has the requests.

Account API key
: The keys on the **API keys** tab of **Settings**, which start with `ct_`. No route accepts them yet: sent as a bearer token, one answers `401` `Invalid or expired token`. Use an access token instead. [Manage API keys](/docs/account/api-keys/) explains what the keys are for today.

## The verification check

Coritan can put a verification check (Cloudflare Turnstile) on the forms that sign people in or give something away for free. [`GET /auth/turnstile`](/docs/api/reference/client/authentication/#op-get-api-v1-auth-turnstile) says whether it is on:

```json
{"enabled": true, "site_key": "..."}
```

While it is on, these routes also need a `turnstile_token` in the body. Only the check on a web page makes one, so a script cannot sign in with a password while the check is on.

| API | Routes |
| --- | --- |
| Client API | `POST /auth/login`, `POST /auth/register`, `POST /auth/forgot-password`, `POST /auth/reset-password`, and `POST /services/order` for a plan that costs nothing |
| Organization API | `POST /orgs/{org_slug}/auth/register`, `POST /orgs/{org_slug}/staff/auth/login`, `POST /orgs/{org_slug}/staff/auth/forgot-password`, and a storefront order for a plan that costs nothing |

Without a token, or with one that did not pass, the route answers `403` with `{"detail": {"error": "turnstile_failed", "message": "Verification required"}}`. The `message` is `Verification failed` for a token that did not pass.

## Authentication errors

| Status | `detail` | Meaning |
| --- | --- | --- |
| `403` | `Not authenticated` | A Client API route got no `Authorization` header. |
| `403` | `Invalid authentication credentials` | The `Authorization` header does not start with `Bearer`. |
| `401` | `Invalid or expired token` | The token is not one Coritan issued, or it has expired. Refresh it, or sign in again. |
| `401` | `Invalid token type` | A refresh token was sent where an access token belongs. |
| `401` | `Invalid refresh token` | `POST /auth/refresh` was sent a token that is not a refresh token. |
| `401` | `{"error": "mfa_required", ...}` | A pending token was sent to a route other than the two-factor routes. Finish the sign-in first. |
| `401` | `Token invalidated by password change` | The password changed after the token was issued. Sign in again. |
| `403` | `Account is suspended or closed` | The account cannot sign in or use a token. |
| `401` | `Missing bearer token` | An Organization API route got no `Authorization: Bearer` header. |
| `403` | `Not a member of this organization` | The token is valid, but you are not a member of that organization. |
| `404` | `Organization not found` | No active organization has that slug. With an organization API key, the slug is not the key's organization. |
| `401` | `Token expired` | A staff console token has expired. Refresh it. |
| `403` | `{"error": "reauth_required", ...}` | The action needs a step-up, and the last one was more than 10 minutes ago. |
| `401` | `Invalid API key` | A Commerce API request sent an `X-API-Key` that is wrong or revoked. |
| `403` | `API key is not allowed from this address` | The request came from an address outside the organization API key's allow-list. |
| `403` | `Organization inactive` | The organization API key's organization is not active. |
| `403` | `{"error": "scope_required", ...}` | The organization API key lacks the scope the route needs. The `message` names it. |
| `401` | `{"error": "publishable_key_required", ...}` | A Store API request had no `x-publishable-api-key` header. |
| `401` | `{"error": "invalid_publishable_key", ...}` | The publishable key is wrong, revoked, or belongs to another store. |
| `401` | `X-Api-Key header required` | A send API request had no `X-Api-Key` header. |

[Errors](/docs/api/errors/) describes the shapes of `detail`, and [Rate limits](/docs/api/rate-limits/) the `429` that too many failed sign-ins bring.

## API

- `POST /api/v1/auth/login`: Login (https://www.coritan.com/docs/api/reference/client/authentication/#op-post-api-v1-auth-login)
- `POST /api/v1/auth/refresh`: Refresh (https://www.coritan.com/docs/api/reference/client/authentication/#op-post-api-v1-auth-refresh)
- `GET /api/v1/auth/turnstile`: Turnstile config (https://www.coritan.com/docs/api/reference/client/authentication/#op-get-api-v1-auth-turnstile)

# Errors

> The status codes and error bodies the Coritan API returns, the fields to read in each, and what to do about them.

Source: https://www.coritan.com/docs/api/errors/

A request that fails answers with a status code of `400` or more and a JSON body. Read the status code first: it says what kind of failure it is. The body's `detail` field then says what went wrong, in one of the three shapes below.

## The error body

### A sentence

Most errors carry one sentence, written to be shown to a person:

```json
{"detail": "Invoice not found"}
```

Branch on the status code, not on the words.

### An object with a code

Errors that a program is expected to act on carry an object. `error` is a code to branch on, `message` is the sentence to show, and some codes add fields of their own:

```json
{
  "detail": {
    "error": "rate_limited",
    "message": "Too many requests for this action. Please wait and try again.",
    "action": "container.power",
    "retry_after_seconds": 60
  }
}
```

A few errors name the code `reason` instead of `error`, such as a locked server:

```json
{"detail": {"reason": "server_locked", "message": "We have locked this server because activity on it broke our acceptable use policy, and our team is reviewing it. ..."}}
```

A feature your plan does not include answers `403` with the feature and `upgrade_required`:

```json
{
  "detail": {
    "feature": "backups",
    "reason": "free_plan",
    "message": "Backups are not included on the free plan. Upgrade to a paid plan, or download your world from the file manager.",
    "upgrade_required": true
  }
}
```

Some orders that fail a check of their settings answer `422` with a list of sentences: `{"detail": {"errors": ["..."]}}`.

### A list of field errors

A body, query or path value that is missing or has the wrong type answers `422` with one entry for each field. `loc` says where the field is, and `msg` what is wrong with it:

```json
{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "password"],
      "msg": "Field required",
      "input": {"email": "alex@example.com"}
    }
  ]
}
```

## Status codes

| Status | Meaning | What to do |
| --- | --- | --- |
| `400` | The request is well formed, but it cannot be carried out as sent. `detail` says why. | Change the request. |
| `401` | The credential is missing, expired, or the wrong kind for the route. | Refresh the token or sign in again, as [Authentication](/docs/api/authentication/) describes. |
| `402` | A payment did not complete, such as a card the bank declined. | Read `detail`, then pay with another method. |
| `403` | You may not do this: your role or plan does not allow it, the account is suspended, or the record belongs to someone else. A Client API request with no `Authorization` header also answers `403` `Not authenticated`. | Check the credential and what it may do. Do not retry unchanged. |
| `404` | The path or the record does not exist, or it belongs to another account. | Check the ID and the path. |
| `409` | The request conflicts with the record's state: a name is taken, the same action is already running, or the record is being deleted. | Read the record again, then decide. |
| `413` | A file or a body is larger than the route accepts. `detail` gives the limit. | Send less. |
| `422` | A field is missing or not valid. | Fix the fields `detail` names. |
| `423` | The server is locked, and `detail.reason` is `server_locked`. The lock does not delete your files. | Reply to the support ticket that came with the lock. |
| `429` | Too many requests. | Wait as long as `Retry-After` says. [Rate limits](/docs/api/rate-limits/) lists the limits. |
| `500` | Something failed on Coritan's side. `detail` is `Internal server error`. | Retry later. If it keeps failing, [contact support](/docs/support/) with the time and the request. |
| `502` | A system the API depends on refused or failed, such as a payment provider or a domain registrar. `detail` says which. | Retry later. |
| `503` | The API or one of its services is not available right now. | Retry after the `Retry-After` header, or later when there is none. |

A `503` while the API starts up has its own body, and asks you to wait two seconds with `Retry-After: 2`:

```json
{"detail": "Service unavailable: database not ready", "status": "not_ready"}
```

## Error codes

These codes in `detail.error` or `detail.reason` come up on many routes. The page for each product lists the ones it adds.

| Code | Status | Meaning |
| --- | --- | --- |
| `turnstile_failed` | `403` | The verification check is on, and `turnstile_token` is missing or did not pass. |
| `mfa_required` | `401` | A pending token from a sign-in with two-factor authentication was sent to a route that needs a full sign-in. |
| `reauth_required` | `403` | An Organization API action needs a step-up in the last 10 minutes. `max_age_seconds` says how long one lasts. |
| `rate_limited` | `429` | An action's own budget is spent. `action` names it, and `retry_after_seconds` gives the length of its window. |
| `free_limit_reached` | `409` | You already have the most of that free plan an account may hold. Remove one, or choose a paid plan. |
| `free_tier_paused` | `503` | Free servers are at capacity, so a storefront takes no orders for them right now. |
| `plan_not_sold_here` | `403` | The plan cannot be ordered through this API. |
| `server_locked` | `423` | The server is locked while Coritan reviews it. |
| `server_deleting` | `409` | The server is being deleted, so it takes no more actions. |

The Commerce API and the Store API answer every error with an object like this, with codes such as `not_found`, `invalid`, `conflict`, `forbidden`, `commerce_not_enabled`, `scope_required` and `idempotency_key_reused`. [Authentication](/docs/api/authentication/#authentication-errors) lists the codes about credentials, and [Idempotent requests](/docs/api/idempotency/) the codes about repeated requests.

## Errors from in front of the API

The proxy in front of the API can refuse a request before the API sees it. Its answers carry `error` at the top level and no `detail`:

| Status | Body | Meaning |
| --- | --- | --- |
| `429` | `{"error":"Too many requests"}` | Your address sent too many requests or opened too many connections. `Retry-After` is `1`. |
| `413` | `{"error":"Request body too large"}` | The body is larger than the proxy accepts. |

Handle both bodies: read `detail` when it is there, and `error` when it is not.

# Rate limits

> How many requests the Coritan API accepts, the tighter limits on sign-in and some actions, and how to handle a 429 response.

Source: https://www.coritan.com/docs/api/rate-limits/

The Coritan API limits how many requests it takes from one address, how many failed sign-ins it accepts, and how often you can repeat an action that costs a lot to carry out. A request over any limit answers `429 Too Many Requests`, and the `Retry-After` header says how many seconds to wait.

## Requests from one address

| Limit | What it counts | Answer |
| --- | --- | --- |
| 2,400 requests a minute | Every API request from one IP address in the last 60 seconds | `429` with `{"detail": "Rate limit exceeded"}`. `Retry-After` is the number of seconds until the oldest of those requests is a minute old. |
| 200 requests a second, in bursts of up to 400 | Every request from one IP address, counted by the proxy in front of the API | `429` with `{"error":"Too many requests"}` and `Retry-After: 1`. |
| 128 connections | Open connections from one IP address to the proxy | The proxy closes a new connection without an answer. |

The proxy's limits are its defaults, and Coritan can change them. When the proxy refuses 8 requests in a row from one address, it blocks that address for 5 minutes. While the block lasts, every request answers `429` and every new connection is closed, so do not retry at once after a `429`.

## Sign-in attempts

Only failures count towards these limits: an answer of `401` or `403`. A sign-in that works costs nothing.

| Limit | Routes | Answer |
| --- | --- | --- |
| 40 failed attempts a minute, from one IP address, on each route | `POST /auth/login`, `POST /auth/register` and `POST /auth/refresh`; on an organization, `POST /orgs/{org_slug}/auth/login`, `/auth/register` and `/auth/forgot-password`, and `POST /orgs/{org_slug}/staff/auth/login` and `/staff/auth/forgot-password` | `429` with `{"detail": "Too many authentication attempts. Please try again later."}` and `Retry-After: 60`. |

`POST /auth/forgot-password` always answers `200`, so it has a budget that counts every request instead: 10 in 15 minutes from one IP address, and 3 in 15 minutes for one email address. Checking a two-factor code has one too, as the next table shows.

## Actions with their own budget

These actions start work that takes time or resources on Coritan's side, so each has a budget of its own on top of the limits above. The budget counts your requests for one server, instance or route, or for your whole account where the table says so.

| Action | Routes | Budget |
| --- | --- | --- |
| `container.power` | `POST /client/servers/{uuid}/power` | 24 a minute |
| `container.wake` | `POST /client/servers/{uuid}/wake` | 48 a minute |
| `container.backup` | `POST /client/servers/{uuid}/backups` | 8 in 5 minutes |
| `container.backup_restore` | `POST /client/servers/{uuid}/backups/{backup_uuid}/restore` | 8 in 5 minutes |
| `container.file_compress` | `POST /client/servers/{uuid}/files/compress` and `/files/decompress` | 24 a minute |
| `container.file_pull` | `POST /client/servers/{uuid}/files/pull` | 24 a minute |
| `container.import` | `POST /client/servers/{uuid}/import/start` and `/import/test-connection` | 12 in 5 minutes |
| `container.software` | The routes under `/client/servers/{uuid}/software/` that install, change or update software | 8 in 10 minutes |
| `container.database` | `POST /client/servers/{uuid}/databases` | 24 a minute |
| `vps.power` | `POST /client/vps/{uuid}/power` | 24 a minute |
| `vps.rebuild` | `POST /client/vps/{uuid}/rebuild` | 8 in 10 minutes |
| `vps.backup` | `POST /client/vps/{uuid}/backups` | 8 in 5 minutes |
| `vps.backup_restore` | `POST /client/vps/{uuid}/backups/{backup_id}/restore` | 8 in 5 minutes |
| `custom_domain.link` | `POST /client/external-servers/{service_id}/custom-domain` and `POST /gameproxy/routes/{route_id}/custom-domain` | 12 an hour |
| `custom_domain.verify` | The same two routes with `/verify` added | 12 an hour |
| `external_server.update` | `PATCH /client/external-servers/{service_id}` | 30 in 5 minutes |
| `external_server.probe` | `POST /client/external-servers/{service_id}/test` | 20 a minute, for your account |
| `platform_domains.availability` | `GET /client/platform-domains/availability` | 60 a minute, for your account |
| `platform_domains.claim` | `POST /client/platform-domains/claims` | 6 an hour, for your account |
| `crypto.deposit_check` | `POST /billing/crypto/check` | 12 a minute, for your account |
| `storefront.free_order` | `POST /services/order` for a plan that costs nothing | 12 in 10 minutes, for your account |
| `user.mfa_verify` | `POST /auth/mfa/verify`, `/auth/mfa/enable`, `/auth/mfa/disable` and `/auth/mfa/recovery-codes` together | 10 in 5 minutes, for your account |
| `apps.create` | `POST /client/apps`, and `POST /orgs/{org_slug}/apps` for an organization | 20 an hour, for the account or organization that will own the app |
| `apps.write` | Every request that changes an app under `/client/apps/` or `/orgs/{org_slug}/apps/`: creating, changing or deleting it, its variables, domains, deployments and webhook secret | 120 an hour, for each person or API key |
| `apps.deploy` | `POST .../{app_uuid}/deployments`, `POST .../{app_uuid}/redeploy` and a rollback | 30 in 10 minutes, for each app |
| `apps.domain_verify` | `POST .../{app_uuid}/domains/{hostname}/verify` | 30 in 10 minutes, for each app |

The matching routes of an organization's customer portal, under `/orgs/{org_slug}/portal/`, have the same budgets for each customer. The staff console has budgets of its own on actions such as charges, refunds, credit and exports.

Over a budget, the action answers:

```json
{
  "detail": {
    "error": "rate_limited",
    "message": "Too many requests for this action. Please wait and try again.",
    "action": "container.power",
    "retry_after_seconds": 60
  }
}
```

`retry_after_seconds` and the `Retry-After` header both give the length of the whole window. Waiting that long always frees the budget.

Apps answers the same way without `action`, and its `message` names what ran out, such as `Too many deployments of this app. Wait a few minutes.`

## Organization API keys and the Store API

Organization API key
: Each key has its own limit, set when it is created: 4,000 requests in any 60 minutes by default. Over it, the Commerce API answers `429` with `API key rate limit exceeded` and `Retry-After: 3600`. [Create organization API keys](/docs/organizations/api-keys/) sets the limit.

Store API payments
: Starting a payment and completing a cart each allow 20 tries for one cart in 10 minutes, and 60 from one IP address for one store. Over either, the Store API answers `429` with `"error": "rate_limited"`, the message `Too many payment attempts for this cart. Try again in a few minutes.` and `Retry-After: 600`.

SMTP Relay has sending limits of its own, which [SMTP Relay sending limits](/docs/mail/smtp-relay/sending-limits/) describes.

## Handle a 429

- Read `Retry-After`, a whole number of seconds, and send nothing more to that route until it has passed.
- When an answer has no `Retry-After`, wait 1 second, then double the wait after each `429` up to a minute, with a random part added so that many clients do not retry at the same moment.
- Never retry in a loop without a wait: 8 refusals in a row block your address for 5 minutes.
- Poll less often, and read a list once instead of one record at a time ([Pagination and filtering](/docs/api/pagination/)).
- When you retry a payment or an order after a `429` or a lost connection, send the same `Idempotency-Key`, so that it happens only once ([Idempotent requests](/docs/api/idempotency/)).

# Pagination and filtering

> How list endpoints page their results with limit and offset or with page numbers, and how to read the total.

Source: https://www.coritan.com/docs/api/pagination/

List endpoints answer one page of results at a time. Each list takes one of four sets of paging parameters, and many take filters as well. The [API reference](/docs/api/reference/) gives the parameters of every route. This page lists the conventions, the page sizes of the main lists, and how to read a total.

## Paging parameters

| Parameters | First page | Next page | Used by |
| --- | --- | --- | --- |
| `limit` and `offset` | `offset=0` | Add `limit` to `offset`. | `GET /services/` and `GET /payments/disputes` in the Client API, and most lists in the Organization API, the Commerce API and the Store API |
| `page` and `limit` | `page=1` | Add 1 to `page`. | Invoices, transactions, a service's events and support conversations in the Client API |
| `page` and `per_page` | `page=1` | Add 1 to `page`. | DNS zones and records, proxy routes, SSL certificates and products in the Client API, and services in the customer portal |
| `before_id` and `limit` | Leave out `before_id`. | Send the last answer's `next_before_id` as `before_id`. | Events, promotions, gift cards and fulfilment provider logs in the Commerce API |

`page` starts at 1, and page `n` skips the first `(n - 1) × limit` results (or `(n - 1) × per_page`). A page past the last one answers an empty list.

Lists come newest first unless the tables below say otherwise. Invoices, transactions, customers and Commerce orders break a tie on the ID, so while nothing changes, every row appears on exactly one page. On a list sorted newest first, a row added while you page pushes the others down by one, and the next page then starts with the last row of the page before. Skip IDs you already hold.

## Page sizes

Leave out `limit` or `per_page` to get the default. On most lists, a value above the largest size, or below 1, answers `422`, and the entry in `detail` names the parameter and the largest size:

```json
{
  "detail": [
    {
      "type": "less_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 200",
      "input": "500",
      "ctx": {"le": 200}
    }
  ]
}
```

### Client API

| List | Route | Paging | Default | Largest |
| --- | --- | --- | --- | --- |
| Services | [`GET /services/`](/docs/api/reference/client/services/#op-get-api-v1-services) | `limit`, `offset` | 100 | 500 |
| A service's events | [`GET /services/{service_ref}/events`](/docs/api/reference/client/services/#op-get-api-v1-services-service-ref-events) | `page`, `limit` | 50 | 200 |
| Invoices | [`GET /billing/invoices`](/docs/api/reference/client/billing/#op-get-api-v1-billing-invoices) | `page`, `limit` | 50 | 200 |
| Transactions | [`GET /billing/transactions`](/docs/api/reference/client/billing/#op-get-api-v1-billing-transactions) | `page`, `limit` | 50 | 200 |
| Disputes | [`GET /payments/disputes`](/docs/api/reference/client/payments/#op-get-api-v1-payments-disputes) | `limit`, `offset` | 50 | 100 |
| DNS zones, in order of domain | [`GET /dns/zones`](/docs/api/reference/client/dns/#op-get-api-v1-dns-zones) | `page`, `per_page` | 25 | 100 |
| A zone's records, in order of name, then type | [`GET /dns/zones/{zone_id}/records`](/docs/api/reference/client/dns/#op-get-api-v1-dns-zones-zone-id-records) | `page`, `per_page` | 100 | 1,000 |
| Proxy routes | [`GET /proxy/routes`](/docs/api/reference/client/reverse-proxy/#op-get-api-v1-proxy-routes) | `page`, `per_page` | 50 | 200 |
| SSL certificates | [`GET /ssl/certificates`](/docs/api/reference/client/ssl/#op-get-api-v1-ssl-certificates) | `page`, `per_page` | 25 | 100 |
| Products, in the order the catalogue shows them | [`GET /products/`](/docs/api/reference/client/catalog/#op-get-api-v1-products) | `page`, `per_page` | 100 | 200 |
| Support conversations, latest activity first | [`GET /chat/conversations`](/docs/api/reference/client/support/#op-get-api-v1-chat-conversations) | `page`, `limit` | 20 | 100 |
| Messages in a conversation, oldest first | [`GET /chat/conversations/{conversation_id}/messages`](/docs/api/reference/client/support/#op-get-api-v1-chat-conversations-conversation-id-messages) | `before_id`, `after_id`, `limit` | 50 | 100 |

[`GET /billing/crypto/deposits`](/docs/api/reference/client/billing/#op-get-api-v1-billing-crypto-deposits) takes `limit` alone (50 by default, at most 200) and answers the newest deposits, with no way to ask for older ones.

### Organization API and customer portal

| List | Route | Paging | Default | Largest |
| --- | --- | --- | --- | --- |
| Customers | [`GET /orgs/{org_slug}/customers`](/docs/api/reference/organizations/customers/customers/#op-get-api-v1-orgs-org-slug-customers) | `limit`, `offset` | 50 | 200 |
| Invoices | [`GET /orgs/{org_slug}/invoices`](/docs/api/reference/organizations/billing-payouts/invoices/#op-get-api-v1-orgs-org-slug-invoices) | `limit`, `offset` | 50 | 500, cut down |
| Audit log | [`GET /orgs/{org_slug}/audit-log`](/docs/api/reference/organizations/organizations-members/audit-log/#op-get-api-v1-orgs-org-slug-audit-log) | `limit`, `offset` | 50 | 200 |
| A customer's services | [`GET /orgs/{org_slug}/portal/services`](/docs/api/reference/organizations/customer-portal/services/#op-get-api-v1-orgs-org-slug-portal-services) | `page`, `per_page` | 50 | 200 |
| A customer's invoices | [`GET /orgs/{org_slug}/portal/invoices`](/docs/api/reference/organizations/customer-portal/invoices/#op-get-api-v1-orgs-org-slug-portal-invoices) | `limit`, `offset` | 50 | 500, cut down |
| A customer's transactions | [`GET /orgs/{org_slug}/portal/transactions`](/docs/api/reference/organizations/customer-portal/transactions/#op-get-api-v1-orgs-org-slug-portal-transactions) | `limit`, `offset` | 50 | 500, cut down |

Where the table says *cut down*, a larger `limit` does not fail: the list answers 500 results instead.

### Commerce API and Store API

| List | Route | Paging | Default | Largest |
| --- | --- | --- | --- | --- |
| Orders | [`GET /orgs/{org_slug}/commerce/orders`](/docs/api/reference/organizations/commerce/commerce/#op-get-api-v1-orgs-org-slug-commerce-orders) | `limit`, `offset` | 50 | 200 |
| Products, most recently changed first | [`GET /orgs/{org_slug}/commerce/products`](/docs/api/reference/organizations/catalog-services/commerce/#op-get-api-v1-orgs-org-slug-commerce-products) | `limit`, `offset` | 50 | 200 |
| Events | [`GET /orgs/{org_slug}/commerce/events`](/docs/api/reference/organizations/commerce/commerce/#op-get-api-v1-orgs-org-slug-commerce-events) | `before_id`, `limit` | 50 | 200 |
| Promotions | [`GET /orgs/{org_slug}/commerce/promotions`](/docs/api/reference/organizations/commerce/commerce/#op-get-api-v1-orgs-org-slug-commerce-promotions) | `before_id`, `limit` | 50 | 200 |
| Gift cards | [`GET /orgs/{org_slug}/commerce/gift-cards`](/docs/api/reference/organizations/commerce/commerce/#op-get-api-v1-orgs-org-slug-commerce-gift-cards) | `before_id`, `limit` | 50 | 200 |
| Store products | [`GET /orgs/{org_slug}/store/products`](/docs/api/reference/organizations/catalog-services/store/#op-get-api-v1-orgs-org-slug-store-products) | `limit`, `offset` | 20 | 100 |
| Store collections, in the store's order | [`GET /orgs/{org_slug}/store/collections`](/docs/api/reference/organizations/commerce-store-api/#op-get-api-v1-orgs-org-slug-store-collections) | `limit`, `offset` | 50 | 100 |

Store products come newest first by default. `order` changes that: `-created_at`, `created_at`, `-title` or `title`.

## Totals

Most lists answer a bare JSON array with no total. Those below say how many results match.

| Lists | How to get the total | Answer |
| --- | --- | --- |
| Invoices and transactions in the Client API | Add `with_total=true`. | `{"items": [...], "total": 12, "page": 1, "limit": 50, "counts": {...}}` |
| Customers and invoices in the Organization API, and invoices and transactions in the customer portal | Add `with_total=true`. | `{"items": [...], "total": 12, "limit": 50, "offset": 0, "counts": {...}}` |
| Proxy routes | Always there. | `{"routes": [...], "total": 12, "page": 1, "per_page": 50}` |
| SSL certificates | Always there. | `{"certificates": [...], "total": 12}` |
| Lists in the Commerce API and the Store API that take `offset` | Always there. | The results under a name such as `orders`, with `count`, `limit` and `offset` |

`total` and `count` are the number of results the filters match, across every page. `counts` gives the number for each status or type as if no status or type filter were set, with `all` for the whole list. Invoices add `open`, which is unpaid and overdue together, and Client API transactions add `credit`, which is credit added and credit used together. Organization invoices also carry `outstanding`: what the open invoices owe, for each currency.

## Filters

A filter narrows the list before it is cut into pages, so `total` and every page reflect it. A filter the route does not know is ignored.

| Filter | Lists | What it matches |
| --- | --- | --- |
| `status` | Services | One status: `pending`, `provisioning`, `active`, `suspended`, `pending_termination`, `terminated` or `failed`. |
| `resource_type` | Services | `vps` (or `cloud_compute`), `container`, `ip` (or `floating_ip`), `mail` or `smtp_relay`. Another word answers `422` with `"error": "invalid_resource_type"` and the accepted words in `allowed`. |
| `tag` | Services | Services with that tag. |
| `status_filter` | Invoices | `open`, `draft`, `unpaid`, `paid`, `cancelled`, `refunded` or `overdue`. |
| `type_filter` | Transactions | `payment`, `refund`, `credit`, `credit_add` or `credit_deduct`. In the customer portal: `payment`, `refund`, `chargeback`, `credit_add` or `credit_deduct`. |
| `record_type` and `name` | A zone's records | One record type, in any case, and one exact record name. |
| `status`, `priority` and `q` | Support conversations | `status` takes `open`, `awaiting_customer`, `awaiting_agent`, `in_progress`, `on_hold` or `closed`, and `open` matches every conversation that is not closed. `priority` takes `low`, `medium`, `high` or `critical`. `q` searches the subject and the latest message, and `#` followed by a number finds that conversation. |
| `q` | Organization customers, portal invoices and Commerce orders | Search text: a customer's email, name, handle, company or number; an invoice number; or an order number such as `#1001`, an order ID or part of an email. |
| `placed_from` and `placed_to` | Commerce orders | A date and time range. `placed_to` itself is left out. |

`resource_type`, `type_filter`, `priority` and the Client API's `status_filter` answer `422` for a word they do not list. The other filters match nothing when no result has the value you send. The reference for each route lists the rest of its filters.

## Walk every page

Ask for pages until one holds fewer results than you asked for, or until you have `total` results. This reads every service, 100 at a time:

```bash
offset=0
while :; do
  page=$(curl -s "https://api.coritan.com/api/v1/services/?limit=100&offset=$offset" \
    -H "Authorization: Bearer $CORITAN_TOKEN")
  echo "$page" | jq -c '.[]'
  [ "$(echo "$page" | jq length)" -lt 100 ] && break
  offset=$((offset + 100))
done
```

On a list that uses `before_id`, stop when `next_before_id` is `null`.

## Read new messages

Messages in a support conversation page by ID rather than by position:

No parameters
: The latest `limit` messages, oldest first.

`before_id`
: The latest `limit` messages older than that message ID, oldest first. Send the ID of the first message you hold to read further back.

`after_id`
: Up to `limit` messages newer than that message ID, oldest first. Send the ID of the last message you hold to fetch only what is new.

Internal notes from Coritan's team never appear in the list. Poll no more often than you need to: [Rate limits](/docs/api/rate-limits/) applies to every request.

When you poll `GET /orgs/{org_slug}/portal/services` for changes, add `consistency=eventual`. The answer may miss a change made a moment ago, so leave it out on the first read after a change of your own.

# Idempotent requests

> Send an Idempotency-Key header so that retrying a payment or an order does not charge you or order twice.

Source: https://www.coritan.com/docs/api/idempotency/

Some requests must happen only once: a payment, an order, a new database. When the connection drops before the answer arrives, you cannot tell whether the request went through. Send a key with the request, and a retry with the same key answers what the first request did instead of doing it again.

## Send a key

- Make a new random key for each operation you mean to happen once. A UUID fits every route on this page, and `uuidgen` prints one.
- Send the same key, with the same body, on every retry of that operation.
- Wait for an answer, or for your client to time out, before you retry.
- Make a new key for a new operation, including a second try after a card is declined.

```bash
KEY=$(uuidgen)
curl -X POST https://api.coritan.com/api/v1/payments/invoices/5011/charge \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"payment_method_id": 812}'
```

To retry, run the same command with the same `$KEY`.

## Routes that take a key

| Route | Where the key goes | Format | How long it counts |
| --- | --- | --- | --- |
| [`POST /payments/invoices/{invoice_id}/charge`](/docs/api/reference/client/payments/#op-post-api-v1-payments-invoices-invoice-id-charge), and the older `/pay` | `Idempotency-Key` header | Up to 255 characters | For as long as the payment attempt exists, with no expiry |
| [`POST /services/order`](/docs/api/reference/client/services/#op-post-api-v1-services-order) for a floating IP | `idempotency_key` in the body, required | 1–64 letters, digits, dots, underscores, colons or hyphens | Until the order fails, is cancelled or expires |
| [`POST /client/servers/{uuid}/databases`](/docs/api/reference/client/container-apps/servers-databases/#op-post-api-v1-client-servers-uuid-databases) | `Idempotency-Key` header, or `idempotency_key` in the body | Letters, digits, hyphens and underscores. Other characters are dropped, and only the first 64 count. | Until the database is deleted |
| [`POST /chat/conversations`](/docs/api/reference/client/support/#op-post-api-v1-chat-conversations) and [`POST /chat/conversations/{conversation_id}/messages`](/docs/api/reference/client/support/#op-post-api-v1-chat-conversations-conversation-id-messages) | `client_request_id` in the body | Up to 64 characters | For as long as the conversation or the message exists |
| [`POST /orgs/{org_slug}/storefront/order`](/docs/api/reference/organizations/storefront/storefront/#op-post-api-v1-orgs-org-slug-storefront-order) | `Idempotency-Key` header | Only the first 128 characters count | No expiry |
| [`POST /orgs/{org_slug}/portal/services/{service_id}/change-plan`](/docs/api/reference/organizations/customer-portal/services/#op-post-api-v1-orgs-org-slug-portal-services-service-id-change-plan) | `Idempotency-Key` header | Only the first 128 characters count | While its answer still describes the service |
| [`POST /orgs/{org_slug}/portal/ips/order`](/docs/api/reference/organizations/customer-portal/ips/#op-post-api-v1-orgs-org-slug-portal-ips-order) | `idempotency_key` in the body, required | 1–64 letters, digits, dots, underscores, colons or hyphens | Until the order fails, is cancelled or expires |
| [`POST /orgs/{org_slug}/portal/servers/{uuid}/databases`](/docs/api/reference/organizations/customer-portal/servers-databases/#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases) and [`POST /orgs/{org_slug}/staff/servers/{uuid}/databases`](/docs/api/reference/organizations/org-staff-containers/staff/#op-post-api-v1-orgs-org-slug-staff-servers-uuid-databases) | `Idempotency-Key` header, or `idempotency_key` in the body | Up to 64 characters | Until the database is deleted |
| [`POST /orgs/{org_slug}/store/carts/{cart_id}/complete`](/docs/api/reference/organizations/commerce-store-api/#op-post-api-v1-orgs-org-slug-store-carts-cart-id-complete) | `Idempotency-Key` header | Up to 128 characters. A longer key answers `422`. | 24 hours |

## What a repeat answers

Payments
: The first payment attempt as it is now, with the same `id`. Nothing is charged a second time. Once that payment has paid the whole invoice, a repeat answers `400` with `No remaining balance on invoice` instead, so read the invoice to confirm it is paid. A declined attempt stays declined under its key: send a new key to try again.

Floating IP orders
: The first order. `POST /services/order` sets `message` to `Order already submitted` within two minutes of the first request, and to `Replayed existing IP order` once the order has an invoice. `POST /orgs/{org_slug}/portal/ips/order` adds `"replay": true`. [Order a floating IP](/docs/floating-ips/order-a-floating-ip/) describes the order and its statuses.

Databases
: The database the first request created on that server, with its password. When the first request stopped part way, the repeat finishes creating it.

Support conversations and messages
: The conversation or the message the first request created.

Storefront orders
: The answer the first request received.

Plan changes
: The answer the first request received, while it still describes the service: an upgrade whose invoice is still waiting to be paid, or a change to the plan the service is still on. Otherwise the request runs again, so a key you send after moving to another plan asks for the change again.

Store API cart completion
: The status and the body the first request received. Completing a cart that already has its order answers that order again, with or without a key.

When the first request answered an error, a retry with the same key runs the request again.

## Errors

| Status | Answer | What it means |
| --- | --- | --- |
| `409` | `An identical IP order is already in progress; retry in a moment` | The first floating IP order with this key is still running. Wait a moment and send it again. |
| `409` | `Order already in progress` | The first storefront order with this key is still running. |
| `409` | `Plan change already in progress` | The first plan change with this key is still running. |
| `409` | `"error": "idempotency_in_progress"` | The first cart completion with this key is still running. |
| `409` | `"error": "idempotency_key_reused"` and `This Idempotency-Key was used for a different request.` | The key was used to complete another cart. Make a new key. |
| `409` | `"error": "database_busy"` and `That database is being deleted` | The database this key created is being deleted. Make a new key. |
| `422` | `idempotency_key is required for IP orders` | A floating IP order was sent without a key. |
| `422` | A message that starts `idempotency_key must be` | The key has a character or a length a floating IP order does not accept. |

Make a new key for each different storefront order or plan change. A key sent again with a different product, plan, hostname or `config` fails.

## Repeated orders without a key

`POST /services/order` also catches a repeat that carries no key. An order for the same product, price and `hostname` as one you placed in the last two minutes answers that first order, with `message` set to `Order already submitted`, while the first is still `pending`. This holds for every product, and for a floating IP order whatever key it sends. Other products accept `idempotency_key` and ignore it. To order two services on the same plan at once, give each its own `hostname`. [Order a service](/docs/get-started/order-a-service/) describes the order and its answer.

`POST /orgs/{org_slug}/storefront/order` does the same for an organization's customers, with or without a key, and marks the answer `"replayed": true`.

## Routes without a key

Other routes take no key, and a repeat is a new request. Before you retry one whose answer you did not receive, read the record it changes: list your invoices to see whether a payment went through, or your services to see whether an order arrived.

The customer portal's [`POST /orgs/{org_slug}/portal/invoices/{invoice_id}/charge`](/docs/api/reference/organizations/customer-portal/invoices/#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-charge) takes no key. Once the invoice is paid, it answers `404` with `Invoice not found or already paid`.

# Client API reference

> Every operation of the Client API, generated from the API: 549 operations in 23 areas.

Source: https://www.coritan.com/docs/api/reference/client/

Every operation of the Client API, by area. Base URL: `https://api.coritan.com/api/v1`.

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

| Area | Operations | What it covers |
| --- | --- | --- |
| [Authentication](/docs/api/reference/client/authentication/) | 17 | Register, login, refresh tokens, and manage your profile. |
| [Catalog](/docs/api/reference/client/catalog/) | 6 | Browse sellable products and plan options. |
| [Services](/docs/api/reference/client/services/) | 8 | Order and manage provisioned services (lifecycle, actions, cancel, plan changes). |
| [Billing](/docs/api/reference/client/billing/) | 20 | Invoices, credit balance, top-ups, and hourly billing controls. |
| [Payments](/docs/api/reference/client/payments/) | 21 | Payment methods, checkout sessions, and available gateways. |
| [DNS](/docs/api/reference/client/dns/) | 39 | Authoritative DNS zones, records, DNSSEC, and per-zone query stats. |
| [SSL](/docs/api/reference/client/ssl/) | 8 | Certificate inventory and issuance, plus HTTP-01 / DNS challenge workflows for domain validation. |
| [Domains](/docs/api/reference/client/domains/) | 12 | Domain search, registration, renewals, nameservers, and locks. |
| [Reverse Proxy](/docs/api/reference/client/reverse-proxy/) | 12 | User-managed reverse-proxy routes (TLS, upstreams, WAF settings). |
| [Game Proxy](/docs/api/reference/client/game-proxy/) | 11 | Game join addresses on the platform's join domain: names, branding and custom domains. |
| [External Servers](/docs/api/reference/client/external-servers/) | 10 | Put a server you host yourself behind the game proxy: connection, tests and branding. |
| [Platform Domains](/docs/api/reference/client/platform-domains/) | 5 | Names claimed under the platform's customer suffixes, such as example.coritan.gg. |
| [Container Apps](/docs/api/reference/client/container-apps/) | 116 | Container Apps that run any image or template (MariaDB, Redis, nginx, and more). |
| [Apps](/docs/api/reference/client/apps/) | 22 | Apps built once from a git repository or an image and run as replicas in the regions you choose: deployments, build logs, rollbacks, environment variables and domains. |
| [Cloud Compute](/docs/api/reference/client/cloud-compute/) | 33 | Cloud Compute VM instances (power, console, backups, and details). |
| [Floating IPs](/docs/api/reference/client/floating-ips/) | 12 | Allocate and attach floating IPs to eligible services. |
| [Shield](/docs/api/reference/client/shield/) | 6 | Client-facing DDoS scrubber status and attack events for your IPs. |
| [Object Storage](/docs/api/reference/client/object-storage/) | 14 | S3-compatible buckets, access keys, objects and usage for Object Storage services. |
| [Mail](/docs/api/reference/client/mail/) | 149 | Mail Hosting (domains, mailboxes, aliases), SMTP Relay (credentials, API keys, webhooks, suppressions, events) and the mail tenants an account owns. |
| [Mail Send API](/docs/api/reference/client/mail-send-api/) | 4 | Send a message through an SMTP Relay service over HTTPS. |
| [Support](/docs/api/reference/client/support/) | 13 | Conversational support chat (threads and messages). |
| [Authentication MFA](/docs/api/reference/client/authentication-mfa/) | 6 |  |
| [Resource Tags](/docs/api/reference/client/resource-tags/) | 5 | User-defined labels on services, Cloud Compute instances, Container Apps, and other resources. |

# Client API: Authentication

> Register, login, refresh tokens, and manage your profile.

Source: https://www.coritan.com/docs/api/reference/client/authentication/

Register, login, refresh tokens, and manage your profile. Bearer auth uses the access JWT from login.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/auth/forgot-password`](#op-post-api-v1-auth-forgot-password) | Issue a reset link by email |
| POST | [`/api/v1/auth/login`](#op-post-api-v1-auth-login) | Login |
| GET | [`/api/v1/auth/mailbox-availability`](#op-get-api-v1-auth-mailbox-availability) | Live check behind the sign-up form's username field |
| GET | [`/api/v1/auth/mailbox-domain`](#op-get-api-v1-auth-mailbox-domain) | Mailbox domain |
| GET | [`/api/v1/auth/me`](#op-get-api-v1-auth-me) | Get me |
| PUT | [`/api/v1/auth/me`](#op-put-api-v1-auth-me) | Update me |
| GET | [`/api/v1/auth/me/api-keys`](#op-get-api-v1-auth-me-api-keys) | List keys |
| POST | [`/api/v1/auth/me/api-keys`](#op-post-api-v1-auth-me-api-keys) | Create key |
| DELETE | [`/api/v1/auth/me/api-keys/{key_id}`](#op-delete-api-v1-auth-me-api-keys-key-id) | Revoke key |
| POST | [`/api/v1/auth/me/password`](#op-post-api-v1-auth-me-password) | Change password |
| GET | [`/api/v1/auth/me/staff-link`](#op-get-api-v1-auth-me-staff-link) | Get staff link |
| POST | [`/api/v1/auth/me/staff-link`](#op-post-api-v1-auth-me-staff-link) | Redeem staff link |
| DELETE | [`/api/v1/auth/me/staff-link`](#op-delete-api-v1-auth-me-staff-link) | Remove staff link |
| POST | [`/api/v1/auth/refresh`](#op-post-api-v1-auth-refresh) | Refresh |
| POST | [`/api/v1/auth/register`](#op-post-api-v1-auth-register) | Register |
| POST | [`/api/v1/auth/reset-password`](#op-post-api-v1-auth-reset-password) | Reset password |
| GET | [`/api/v1/auth/turnstile`](#op-get-api-v1-auth-turnstile) | Turnstile config |

### Issue a reset link by email {#op-post-api-v1-auth-forgot-password}

`POST /api/v1/auth/forgot-password`

Issue a reset link by email. The answer is the same whether or not the
address has an account, so the form cannot be used to probe for one.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) | yes |
| `turnstile_token` | string or null | no |

#### Responses

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

### Login {#op-post-api-v1-auth-login}

`POST /api/v1/auth/login`

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) | yes |
| `password` | string | yes |
| `turnstile_token` | string or null | no |

#### Responses

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

### Live check behind the sign-up form's username field {#op-get-api-v1-auth-mailbox-availability}

`GET /api/v1/auth/mailbox-availability`

Live check behind the sign-up form's username field.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `local_part` | query | string | yes |

#### Responses

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

### Mailbox domain {#op-get-api-v1-auth-mailbox-domain}

`GET /api/v1/auth/mailbox-domain`

Whether this storefront offers a mailbox on its own mail domain at
sign-up, and which domain. Public: the form reads it before anyone has an
account.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get me {#op-get-api-v1-auth-me}

`GET /api/v1/auth/me`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `company` | string or null |
| `status` | string |
| `billing_mode` | string |
| `credit_balance` | number |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `created_at` | string (date-time) |

### Update me {#op-put-api-v1-auth-me}

`PUT /api/v1/auth/me`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `company` | string or null |
| `status` | string |
| `billing_mode` | string |
| `credit_balance` | number |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `created_at` | string (date-time) |

### List keys {#op-get-api-v1-auth-me-api-keys}

`GET /api/v1/auth/me/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Default: `200`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].label` | string |
| `[].permissions` | array of string or null |
| `[].ip_whitelist` | array of string or null |
| `[].is_active` | boolean |
| `[].last_used_at` | string (date-time) or null |
| `[].created_at` | string (date-time) |

### Create key {#op-post-api-v1-auth-me-api-keys}

`POST /api/v1/auth/me/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | yes |
| `permissions` | array of string or null | no |
| `ip_whitelist` | array of string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `label` | string |
| `permissions` | array of string or null |
| `ip_whitelist` | array of string or null |
| `is_active` | boolean |
| `last_used_at` | string (date-time) or null |
| `created_at` | string (date-time) |
| `raw_key` | string |

### Revoke key {#op-delete-api-v1-auth-me-api-keys-key-id}

`DELETE /api/v1/auth/me/api-keys/{key_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `key_id` | path | integer | yes |

#### Responses

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

### Change password {#op-post-api-v1-auth-me-password}

`POST /api/v1/auth/me/password`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `current_password` | string | yes |
| `new_password` | string | yes |

#### Responses

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

### Get staff link {#op-get-api-v1-auth-me-staff-link}

`GET /api/v1/auth/me/staff-link`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Redeem staff link {#op-post-api-v1-auth-me-staff-link}

`POST /api/v1/auth/me/staff-link`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

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

### Remove staff link {#op-delete-api-v1-auth-me-staff-link}

`DELETE /api/v1/auth/me/staff-link`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Refresh {#op-post-api-v1-auth-refresh}

`POST /api/v1/auth/refresh`

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `refresh_token` | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `access_token` | string |
| `refresh_token` | string |
| `token_type` | string |
| `expires_in` | integer |

### Register {#op-post-api-v1-auth-register}

`POST /api/v1/auth/register`

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) or null | no |
| `mailbox_local_part` | string or null | no |
| `recovery_email` | string (email) or null | no |
| `password` | string | yes |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `turnstile_token` | string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `access_token` | string |
| `refresh_token` | string |
| `token_type` | string |
| `expires_in` | integer |

### Reset password {#op-post-api-v1-auth-reset-password}

`POST /api/v1/auth/reset-password`

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `token` | string | yes |
| `new_password` | string | yes |
| `turnstile_token` | string or null | no |

#### Responses

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

### Turnstile config {#op-get-api-v1-auth-turnstile}

`GET /api/v1/auth/turnstile`

Public: whether the platform's auth and order forms must render the
Turnstile widget, and with which site key (no auth).

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

# Client API: Catalog

> Browse sellable products and plan options.

Source: https://www.coritan.com/docs/api/reference/client/catalog/

Browse sellable products and plan options. Listing is public and needs no auth.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/containers/catalog`](#op-get-api-v1-client-containers-catalog) | Browse platform specializations available for deploy composition |
| GET | [`/api/v1/client/containers/catalog/{slug}/compose`](#op-get-api-v1-client-containers-catalog-slug-compose) | Get software versions + recommended runtimes for a specialization |
| GET | [`/api/v1/locations`](#op-get-api-v1-locations) | List locations |
| GET | [`/api/v1/locations/availability`](#op-get-api-v1-locations-availability) | Locations availability |
| GET | [`/api/v1/products/`](#op-get-api-v1-products) | List products |
| GET | [`/api/v1/products/{product_id}`](#op-get-api-v1-products-product-id) | Get product |

### Browse platform specializations available for deploy composition {#op-get-api-v1-client-containers-catalog}

`GET /api/v1/client/containers/catalog`

Browse platform specializations available for deploy composition.

Carries the same icons, colours and grouping as the org storefront's
``storefront/specializations`` and the panel's Software tab, so the
platform order page does not have to draw a Paper server with a generic
terminal glyph. The MCJars lookup is cached and never blocks once warm.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `category` | query | string or null | no |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].uuid` | string |
| `[].slug` | string or null |
| `[].name` | string |
| `[].description` | string or null |
| `[].runtime_template_slug` | string or null |
| `[].org_id` | integer or null |
| `[].default_variables` | object or null |
| `[].metadata` | object or null |
| `[].category` | string or null |
| `[].versioned` | boolean |
| `[].version_variable` | string or null |
| `[].version_source_slug` | string or null |
| `[].software_identifier` | string or null |
| `[].runtime_family` | string or null |
| `[].icon_url` | string or null |
| `[].color` | string or null |
| `[].group` | string or null |
| `[].deprecated` | boolean |

### Get software versions + recommended runtimes for a specialization {#op-get-api-v1-client-containers-catalog-slug-compose}

`GET /api/v1/client/containers/catalog/{slug}/compose`

Get software versions + recommended runtimes for a specialization.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `slug` | path | string | yes |  |
| `supported_only` | query | boolean | no | Default: `True`. |
| `include_snapshots` | query | boolean | no | Default: `False`. |
| `limit` | query | integer | no | Default: `200`. |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `slug` | string or null |
| `uuid` | string |
| `name` | string |
| `description` | string or null |
| `runtime_template_slug` | string or null |
| `default_variables` | object or null |
| `metadata` | object or null |
| `category` | string or null |
| `versioned` | boolean |
| `version_variable` | string or null |
| `version_source_slug` | string or null |
| `software_identifier` | string or null |
| `adapter_type` | string or null |
| `runtime_family` | string or null |
| `versions` | array of CatalogVersionOption |
| `versions[].version_id` | string |
| `versions[].name` | string |
| `versions[].release_date` | string or null |
| `versions[].supported` | boolean or null |
| `versions[].required_java` | integer or null |
| `versions[].build_number` | integer or null |
| `versions[].recommended_runtime_slug` | string or null |
| `versions[].recommended_runtime_uuid` | string or null |
| `versions[].recommended_runtime_name` | string or null |
| `versions[].game_versions` | array of string |
| `versions[].metadata` | object or null |
| `versions[].runtime_template_slug` | string or null |
| `versions[].runtime_template_uuid` | string or null |
| `runtime_versions` | array of CatalogVersionOption |
| `runtime_versions[].version_id` | string |
| `runtime_versions[].name` | string |
| `runtime_versions[].release_date` | string or null |
| `runtime_versions[].supported` | boolean or null |
| `runtime_versions[].required_java` | integer or null |
| `runtime_versions[].build_number` | integer or null |
| `runtime_versions[].recommended_runtime_slug` | string or null |
| `runtime_versions[].recommended_runtime_uuid` | string or null |
| `runtime_versions[].recommended_runtime_name` | string or null |
| `runtime_versions[].game_versions` | array of string |
| `runtime_versions[].metadata` | object or null |
| `runtime_versions[].runtime_template_slug` | string or null |
| `runtime_versions[].runtime_template_uuid` | string or null |
| `runtimes` | array of CatalogRuntimeOption |
| `runtimes[].uuid` | string |
| `runtimes[].slug` | string |
| `runtimes[].name` | string |
| `runtimes[].docker_image` | string or null |
| `runtimes[].description` | string or null |
| `defaults` | Defaults |

### List locations {#op-get-api-v1-locations}

`GET /api/v1/locations`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `active_only` | query | boolean | no | Default: `True`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].code` | string |
| `[].name` | string |
| `[].country_code` | string |
| `[].timezone` | string or null |
| `[].latitude` | number or null |
| `[].longitude` | number or null |
| `[].lb_region_code` | string or null |
| `[].sort_order` | integer |
| `[].is_active` | boolean |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Locations availability {#op-get-api-v1-locations-availability}

`GET /api/v1/locations/availability`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `module` | query | string | yes | vps or container |
| `hardware_tier_id` | query | integer or null | no |  |
| `template_id` | query | integer or null | no | VPS OS template id |
| `memory_mb` | query | integer | no | Default: `512`. |
| `disk_gb` | query | integer | no | VPS disk GB Default: `10`. |
| `disk_mb` | query | integer | no | Container disk MB Default: `10240`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].code` | string |
| `[].name` | string |
| `[].country_code` | string |
| `[].available` | boolean |
| `[].reason` | string or null |

### List products {#op-get-api-v1-products}

`GET /api/v1/products/`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `group` | query | string | no |  |
| `hardware_tier` | query | string | no |  |
| `hardware_tier_id` | query | integer | no |  |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `100`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].name` | string |
| `[].slug` | string |
| `[].description` | string or null |
| `[].group_name` | string or null |
| `[].module_name` | string |
| `[].hardware_tier_id` | integer or null |
| `[].hardware_tier` | HardwareTierSummary or null |
| `[].hardware_tier.id` | integer |
| `[].hardware_tier.slug` | string |
| `[].hardware_tier.name` | string |
| `[].hardware_tier.code` | string |
| `[].hardware_tier.description` | string or null |
| `[].status` | string |
| `[].config_schema` | object or null |
| `[].sort_order` | integer |
| `[].stock_limit` | integer or null |
| `[].metadata` | object or null |
| `[].pricing` | array of PricingResponse |
| `[].pricing[].id` | integer |
| `[].pricing[].product_id` | integer |
| `[].pricing[].name` | string |
| `[].pricing[].billing_cycle` | string |
| `[].pricing[].price` | number |
| `[].pricing[].setup_fee` | number |
| `[].pricing[].currency` | string |
| `[].pricing[].is_active` | boolean |
| `[].pricing[].sort_order` | integer |
| `[].pricing[].metadata` | object or null |
| `[].pricing[].created_at` | string (date-time) |
| `[].config_options` | array of ConfigOptionResponse |
| `[].config_options[].id` | integer |
| `[].config_options[].product_id` | integer |
| `[].config_options[].field_name` | string |
| `[].config_options[].label` | string |
| `[].config_options[].field_type` | string |
| `[].config_options[].options` | object or null |
| `[].config_options[].default_value` | string or null |
| `[].config_options[].required` | boolean |
| `[].config_options[].price_modifier` | number |
| `[].config_options[].sort_order` | integer |
| `[].is_orderable_now` | boolean or null |
| `[].stock_status` | string or null |
| `[].availability_reason` | string or null |
| `[].group_is_orderable_now` | boolean or null |
| `[].group_stock_status` | string or null |
| `[].locations` | array of ProductLocationAvailability |
| `[].locations[].id` | integer |
| `[].locations[].code` | string |
| `[].locations[].name` | string |
| `[].locations[].country_code` | string |
| `[].locations[].available` | boolean |
| `[].locations[].orderable` | boolean |
| `[].locations[].reason` | string or null |
| `[].created_at` | string (date-time) |

### Get product {#op-get-api-v1-products-product-id}

`GET /api/v1/products/{product_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `name` | string |
| `slug` | string |
| `description` | string or null |
| `group_name` | string or null |
| `module_name` | string |
| `hardware_tier_id` | integer or null |
| `hardware_tier` | HardwareTierSummary or null |
| `hardware_tier.id` | integer |
| `hardware_tier.slug` | string |
| `hardware_tier.name` | string |
| `hardware_tier.code` | string |
| `hardware_tier.description` | string or null |
| `status` | string |
| `config_schema` | object or null |
| `sort_order` | integer |
| `stock_limit` | integer or null |
| `metadata` | object or null |
| `pricing` | array of PricingResponse |
| `pricing[].id` | integer |
| `pricing[].product_id` | integer |
| `pricing[].name` | string |
| `pricing[].billing_cycle` | string |
| `pricing[].price` | number |
| `pricing[].setup_fee` | number |
| `pricing[].currency` | string |
| `pricing[].is_active` | boolean |
| `pricing[].sort_order` | integer |
| `pricing[].metadata` | object or null |
| `pricing[].created_at` | string (date-time) |
| `config_options` | array of ConfigOptionResponse |
| `config_options[].id` | integer |
| `config_options[].product_id` | integer |
| `config_options[].field_name` | string |
| `config_options[].label` | string |
| `config_options[].field_type` | string |
| `config_options[].options` | object or null |
| `config_options[].default_value` | string or null |
| `config_options[].required` | boolean |
| `config_options[].price_modifier` | number |
| `config_options[].sort_order` | integer |
| `is_orderable_now` | boolean or null |
| `stock_status` | string or null |
| `availability_reason` | string or null |
| `group_is_orderable_now` | boolean or null |
| `group_stock_status` | string or null |
| `locations` | array of ProductLocationAvailability |
| `locations[].id` | integer |
| `locations[].code` | string |
| `locations[].name` | string |
| `locations[].country_code` | string |
| `locations[].available` | boolean |
| `locations[].orderable` | boolean |
| `locations[].reason` | string or null |
| `created_at` | string (date-time) |

# Client API: Services

> Order and manage provisioned services (lifecycle, actions, cancel, plan changes).

Source: https://www.coritan.com/docs/api/reference/client/services/

Order and manage provisioned services (lifecycle, actions, cancel, plan changes).

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/services/`](#op-get-api-v1-services) | List services |
| POST | [`/api/v1/services/order`](#op-post-api-v1-services-order) | Order a platform service, and any add-ons bought with it |
| GET | [`/api/v1/services/{service_ref}`](#op-get-api-v1-services-service-ref) | Fetch a service by numeric id OR underlying resource UUID (instance/server/IP) |
| POST | [`/api/v1/services/{service_ref}/actions`](#op-post-api-v1-services-service-ref-actions) | Execute action |
| POST | [`/api/v1/services/{service_ref}/cancel`](#op-post-api-v1-services-service-ref-cancel) | Cancel service |
| POST | [`/api/v1/services/{service_ref}/change-plan`](#op-post-api-v1-services-service-ref-change-plan) | Change plan |
| GET | [`/api/v1/services/{service_ref}/events`](#op-get-api-v1-services-service-ref-events) | Get events |
| GET | [`/api/v1/services/{service_ref}/upgrade-preview`](#op-get-api-v1-services-service-ref-upgrade-preview) | Preview plan change |

### List services {#op-get-api-v1-services}

`GET /api/v1/services/`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | string | no |  |
| `tag` | query | string | no | Filter by resource tag |
| `resource_type` | query | string | no | Filter by underlying product module. Aliases: cloud_compute→vps, container_apps→container, floating_ip→ip |
| `limit` | query | integer | no | Default: `100`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type | Description |
| --- | --- | --- |
| `[].id` | integer |  |
| `[].user_id` | integer |  |
| `[].product_id` | integer |  |
| `[].pricing_id` | integer |  |
| `[].hostname` | string or null |  |
| `[].status` | string |  |
| `[].billing_cycle` | string |  |
| `[].amount` | number |  |
| `[].next_due_date` | string (date-time) or null |  |
| `[].config` | object or null |  |
| `[].module_data` | object or null |  |
| `[].suspension_reason` | string or null |  |
| `[].provisioned_at` | string (date-time) or null |  |
| `[].created_at` | string (date-time) |  |
| `[].updated_at` | string (date-time) |  |
| `[].product_name` | string or null |  |
| `[].product_slug` | string or null |  |
| `[].module_name` | string or null |  |
| `[].pricing_name` | string or null |  |
| `[].termination_date` | string (date-time) or null |  |
| `[].monthly_cap` | number or null |  |
| `[].hourly_usage_this_month` | number or null |  |
| `[].hourly_cap_reached` | boolean or null |  |
| `[].tags` | array of string |  |
| `[].resource` | ServiceResourceSummary or null | Underlying VPS / Container App / Floating IP summary (DB-backed) |
| `[].resource.type` | string | Module resource type: vps \| container \| ip \| external_server |
| `[].resource.label` | string or null | Human label: hostname, server name, or IP/CIDR |
| `[].resource.status` | string or null | Resource-level status (not billing status) |
| `[].resource.address` | string or null | Primary reachability address (IP, IP:port, or CIDR) |
| `[].resource.detail` | Detail | Module-specific fields (uuids, node, plan, attach state, …) |

### Order a platform service, and any add-ons bought with it {#op-post-api-v1-services-order}

`POST /api/v1/services/order`

Order a platform service, and any add-ons bought with it.

The handler checks every add-on before it writes anything. One that the
order cannot take refuses the whole order with 422 and
``{"errors": [<sentence>]}``, and the handler creates nothing:

* the parent decides which add-ons it takes. An instance takes Floating
  IP, DDoS Shield, Mail Hosting and SMTP Relay; a server takes those and
  Snapshot Storage; a floating IP takes DDoS Shield; a mail plan takes
  SMTP Relay. Any other product takes none;
* the add-on product exists and is active. It is not the free plan, and
  it is not a product that goes on a service the customer already has,
  such as an SMTP Relay dedicated IP;
* its price belongs to it, is active and costs more than $0. Without a
  ``pricing_id`` the order takes the price with the parent's billing
  cycle, else the monthly price, else the first active price. An hourly
  price needs the same deposit as an hourly service;
* an order takes one each of DDoS Shield, Mail Hosting, SMTP Relay and
  Snapshot Storage, up to 4 floating IPs for an instance and one /32 for
  a server. Only a floating IP takes a quantity above 1;
* an instance takes floating IPs only with its included IPv4
  (``order_ipv4``), which stays its free primary address;
* DDoS Shield needs an address in the order: the instance's included
  IPv4, a floating IP add-on on a server, or the floating IP being
  ordered. The order names those addresses itself, so its config may not
  set ``ip_service_ids``;
* each add-on's config passes the checks an order of that product on its
  own passes, and its config options change its price the same way. A
  floating IP comes from the parent's location unless it names a pool.

Each add-on becomes a pending service of the parent's owner, with
``addon_of_service_id`` in its config, and the parent's config lists them
in ``addon_service_ids``. When any of them needs a first payment, the
parent, its included IP and the add-ons share one first invoice, and
credit pays it once. Every service then provisions on its own job, queued
when that invoice is paid, or at once when nothing is owed. Once the
services are up, the floating IPs attach to the parent and the Shield
profile protects the addresses. A replayed order answers with the add-ons
it created the first time and creates nothing.

DDoS Shield ordered on its own may name in ``ip_service_ids`` only the
customer's own floating IPs that are not terminated or cancelled.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_id` | integer | yes |  |
| `pricing_id` | integer | yes |  |
| `hostname` | string or null | no |  |
| `config` | object or null | no |  |
| `idempotency_key` | string or null | no | Replay key for IP orders (double-submit / multi-tab) |
| `turnstile_token` | string or null | no |  |
| `addons` | array of ServiceOrderAddon | no | Up to 8 products bought with this one. Cloud Compute takes Floating IP, DDoS Shield, Mail Hosting and SMTP Relay. Container Apps takes Floating IP, DDoS Shield, Snapshot Storage, Mail Hosting and SMTP Relay. Floating IP takes DDoS Shield. Mail Hosting takes SMTP Relay. When the API cannot take one add-on, it refuses the whole order and creates nothing. |
| `addons[].product_id` | integer | yes | The add-on product. |
| `addons[].pricing_id` | integer or null | no | One of the add-on's active prices. Leave it out to take the price with the parent's billing cycle, else the monthly price, else the first active price. |
| `addons[].quantity` | integer | no | How many to order. Only a floating IP may be more than 1, and each one becomes its own service. |
| `addons[].config` | object or null | no | The add-on's own config, as an order for that product on its own takes it. A floating IP comes from the parent's location unless config.pool_id names a pool. A DDoS Shield add-on takes profile_name (up to 40 characters), protection_mode, default_action, per_source_pps and aggregate_pps. The order sets the addresses it protects, so the API refuses ip_service_ids. |

#### Responses

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

Fields of a `201` response:

| Field | Type | Description |
| --- | --- | --- |
| `service` | ServiceResponse |  |
| `service.id` | integer |  |
| `service.user_id` | integer |  |
| `service.product_id` | integer |  |
| `service.pricing_id` | integer |  |
| `service.hostname` | string or null |  |
| `service.status` | string |  |
| `service.billing_cycle` | string |  |
| `service.amount` | number |  |
| `service.next_due_date` | string (date-time) or null |  |
| `service.config` | object or null |  |
| `service.module_data` | object or null |  |
| `service.suspension_reason` | string or null |  |
| `service.provisioned_at` | string (date-time) or null |  |
| `service.created_at` | string (date-time) |  |
| `service.updated_at` | string (date-time) |  |
| `service.product_name` | string or null |  |
| `service.product_slug` | string or null |  |
| `service.module_name` | string or null |  |
| `service.pricing_name` | string or null |  |
| `service.termination_date` | string (date-time) or null |  |
| `service.monthly_cap` | number or null |  |
| `service.hourly_usage_this_month` | number or null |  |
| `service.hourly_cap_reached` | boolean or null |  |
| `service.tags` | array of string |  |
| `service.resource` | ServiceResourceSummary or null | Underlying VPS / Container App / Floating IP summary (DB-backed) |
| `invoice_id` | integer or null |  |
| `requires_payment` | boolean |  |
| `checkout_available` | boolean |  |
| `amount_due` | string or null |  |
| `message` | string or null |  |
| `addons` | array of ServiceResponse | The services created for the order's add-ons, in the order the client listed them, one per unit of quantity. A replayed order lists the add-ons it created the first time. |
| `addons[].id` | integer |  |
| `addons[].user_id` | integer |  |
| `addons[].product_id` | integer |  |
| `addons[].pricing_id` | integer |  |
| `addons[].hostname` | string or null |  |
| `addons[].status` | string |  |
| `addons[].billing_cycle` | string |  |
| `addons[].amount` | number |  |
| `addons[].next_due_date` | string (date-time) or null |  |
| `addons[].config` | object or null |  |
| `addons[].module_data` | object or null |  |
| `addons[].suspension_reason` | string or null |  |
| `addons[].provisioned_at` | string (date-time) or null |  |
| `addons[].created_at` | string (date-time) |  |
| `addons[].updated_at` | string (date-time) |  |
| `addons[].product_name` | string or null |  |
| `addons[].product_slug` | string or null |  |
| `addons[].module_name` | string or null |  |
| `addons[].pricing_name` | string or null |  |
| `addons[].termination_date` | string (date-time) or null |  |
| `addons[].monthly_cap` | number or null |  |
| `addons[].hourly_usage_this_month` | number or null |  |
| `addons[].hourly_cap_reached` | boolean or null |  |
| `addons[].tags` | array of string |  |
| `addons[].resource` | ServiceResourceSummary or null | Underlying VPS / Container App / Floating IP summary (DB-backed) |

### Fetch a service by numeric id OR underlying resource UUID (instance/server/IP) {#op-get-api-v1-services-service-ref}

`GET /api/v1/services/{service_ref}`

Fetch a service by numeric id OR underlying resource UUID (instance/server/IP).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type | Description |
| --- | --- | --- |
| `id` | integer |  |
| `user_id` | integer |  |
| `product_id` | integer |  |
| `pricing_id` | integer |  |
| `hostname` | string or null |  |
| `status` | string |  |
| `billing_cycle` | string |  |
| `amount` | number |  |
| `next_due_date` | string (date-time) or null |  |
| `config` | object or null |  |
| `module_data` | object or null |  |
| `suspension_reason` | string or null |  |
| `provisioned_at` | string (date-time) or null |  |
| `created_at` | string (date-time) |  |
| `updated_at` | string (date-time) |  |
| `product_name` | string or null |  |
| `product_slug` | string or null |  |
| `module_name` | string or null |  |
| `pricing_name` | string or null |  |
| `termination_date` | string (date-time) or null |  |
| `monthly_cap` | number or null |  |
| `hourly_usage_this_month` | number or null |  |
| `hourly_cap_reached` | boolean or null |  |
| `tags` | array of string |  |
| `resource` | ServiceResourceSummary or null | Underlying VPS / Container App / Floating IP summary (DB-backed) |
| `resource.type` | string | Module resource type: vps \| container \| ip \| external_server |
| `resource.label` | string or null | Human label: hostname, server name, or IP/CIDR |
| `resource.status` | string or null | Resource-level status (not billing status) |
| `resource.address` | string or null | Primary reachability address (IP, IP:port, or CIDR) |
| `resource.detail` | Detail | Module-specific fields (uuids, node, plan, attach state, …) |

### Execute action {#op-post-api-v1-services-service-ref-actions}

`POST /api/v1/services/{service_ref}/actions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `action` | string | yes |
| `params` | object or null | no |

#### Responses

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

### Cancel service {#op-post-api-v1-services-service-ref-cancel}

`POST /api/v1/services/{service_ref}/cancel`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

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

#### Responses

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

### Change plan {#op-post-api-v1-services-service-ref-change-plan}

`POST /api/v1/services/{service_ref}/change-plan`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `change_type` | string |
| `net_amount` | number |
| `credit_amount` | number |
| `charge_amount` | number |
| `credit_issued` | number |
| `days_remaining` | integer |
| `invoice_id` | integer or null |
| `status` | string or null |
| `message` | string or null |

### Get events {#op-get-api-v1-services-service-ref-events}

`GET /api/v1/services/{service_ref}/events`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_ref` | path | string | yes |  |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].event_type` | string |
| `[].actor_type` | string |
| `[].actor_id` | integer or null |
| `[].description` | string or null |
| `[].metadata` | object or null |
| `[].created_at` | string (date-time) |

### Preview plan change {#op-get-api-v1-services-service-ref-upgrade-preview}

`GET /api/v1/services/{service_ref}/upgrade-preview`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_ref` | path | string | yes |
| `new_pricing_id` | query | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `credit_amount` | number |
| `charge_amount` | number |
| `net_amount` | number |
| `credit_estimate` | number |
| `creditable_days` | integer |
| `days_remaining` | integer |
| `days_in_cycle` | integer |
| `change_type` | string |

# Client API: Billing

> Invoices, credit balance, top-ups, and hourly billing controls.

Source: https://www.coritan.com/docs/api/reference/client/billing/

Invoices, credit balance, top-ups, and hourly billing controls.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/billing/credit`](#op-get-api-v1-billing-credit) | Get credit |
| GET | [`/api/v1/billing/crypto/address`](#op-get-api-v1-billing-crypto-address) | This user's permanent deposit address for the network's chain family |
| GET | [`/api/v1/billing/crypto/assets`](#op-get-api-v1-billing-crypto-assets) | Assets we can accept right now |
| POST | [`/api/v1/billing/crypto/check`](#op-post-api-v1-billing-crypto-check) | Look for this customer's payment now, and say where it stands |
| GET | [`/api/v1/billing/crypto/deposits`](#op-get-api-v1-billing-crypto-deposits) | Deposit history, including transfers still confirming |
| GET | [`/api/v1/billing/crypto/deposits/{deposit_id}`](#op-get-api-v1-billing-crypto-deposits-deposit-id) | One deposit, for polling while it confirms |
| GET | [`/api/v1/billing/crypto/plan`](#op-get-api-v1-billing-crypto-plan) | Every way to pay this amount in crypto, cheapest first |
| GET | [`/api/v1/billing/crypto/quote`](#op-get-api-v1-billing-crypto-quote) | How much to send for a target USD credit, itemised |
| GET | [`/api/v1/billing/hourly-eligibility`](#op-get-api-v1-billing-hourly-eligibility) | Check hourly eligibility |
| GET | [`/api/v1/billing/invoices`](#op-get-api-v1-billing-invoices) | Newest first, ties by id so a page boundary never repeats or skips a row |
| GET | [`/api/v1/billing/invoices/{invoice_id}`](#op-get-api-v1-billing-invoices-invoice-id) | Get invoice |
| POST | [`/api/v1/billing/invoices/{invoice_id}/apply-credit`](#op-post-api-v1-billing-invoices-invoice-id-apply-credit) | Apply account credit to an unpaid invoice (unlocks provision / plan change when paid) |
| POST | [`/api/v1/billing/topup/checkout`](#op-post-api-v1-billing-topup-checkout) | Hosted checkout to buy USD account credit without a saved payment method |
| GET | [`/api/v1/billing/topup/config`](#op-get-api-v1-billing-topup-config) | Get topup config |
| PUT | [`/api/v1/billing/topup/config`](#op-put-api-v1-billing-topup-config) | Update topup config |
| POST | [`/api/v1/billing/topup/confirm-payment`](#op-post-api-v1-billing-topup-confirm-payment) | Finalize a top-up PaymentIntent after SCA and credit the user balance |
| POST | [`/api/v1/billing/topup/manual`](#op-post-api-v1-billing-topup-manual) | Manually top up credit balance by charging a payment method |
| POST | [`/api/v1/billing/topup/pay-intent`](#op-post-api-v1-billing-topup-pay-intent) | Create an in-page Stripe Payment Element intent for a credit top-up |
| POST | [`/api/v1/billing/topup/paypal-capture`](#op-post-api-v1-billing-topup-paypal-capture) | Capture an approved PayPal order and credit the platform user balance |
| GET | [`/api/v1/billing/transactions`](#op-get-api-v1-billing-transactions) | As listinvoices: newest first, ties by id, withtotal for a TransactionPage |

### Get credit {#op-get-api-v1-billing-credit}

`GET /api/v1/billing/credit`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `balance` | number |
| `currency` | string |
| `recent_transactions` | array of CreditLedgerEntry |
| `recent_transactions[].id` | integer |
| `recent_transactions[].amount` | number |
| `recent_transactions[].balance_after` | number |
| `recent_transactions[].description` | string |
| `recent_transactions[].created_at` | string (date-time) |

### This user's permanent deposit address for the network's chain family {#op-get-api-v1-billing-crypto-address}

`GET /api/v1/billing/crypto/address`

This user's permanent deposit address for the network's chain family.

Uses the write session because a first call issues an address. Repeat calls
return the same one.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `network` | query | string | yes | Network key, e.g. base or bitcoin |

#### Responses

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

### Assets we can accept right now {#op-get-api-v1-billing-crypto-assets}

`GET /api/v1/billing/crypto/assets`

Assets we can accept right now.

Excludes anything enabled but unpriced, since a deposit to it would be held
rather than credited.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Look for this customer's payment now, and say where it stands {#op-post-api-v1-billing-crypto-check}

`POST /api/v1/billing/crypto/check`

Look for this customer's payment now, and say where it stands.

What the refresh button calls, and what the wallet and invoice panels poll
while they are open. Before this the panels could only re-read the database
and wait for the background scan to notice. A customer who had just paid
had no way to ask, and the honest answer to "is it there yet" was "wait".

Rate limited because it reads the chain, which is spending money on the
customer's behalf. The chain read is separately throttled inside, so several
tabs polling on their own timers cost one read rather than one each; below
that threshold this still answers with current deposit state, which is what
was actually being asked for.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json`

Type: object or null.

#### Responses

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

### Deposit history, including transfers still confirming {#op-get-api-v1-billing-crypto-deposits}

`GET /api/v1/billing/crypto/deposits`

Deposit history, including transfers still confirming.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

### One deposit, for polling while it confirms {#op-get-api-v1-billing-crypto-deposits-deposit-id}

`GET /api/v1/billing/crypto/deposits/{deposit_id}`

One deposit, for polling while it confirms.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deposit_id` | path | integer | yes |

#### Responses

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

### Every way to pay this amount in crypto, cheapest first {#op-get-api-v1-billing-crypto-plan}

`GET /api/v1/billing/crypto/plan`

Every way to pay this amount in crypto, cheapest first.

Answers the question a customer has ("how much do I send to end up with
$X?") instead of showing a rate and a spread and leaving the arithmetic
to them. Each option states what it credits, which is never
below the target, and says outright when a chain's fee would eat the
deposit.

``invoice_id`` targets the invoice's outstanding balance instead of a bare
amount, so the figure shown is the one that settles it.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `amount` | query | number or string | yes |
| `invoice_id` | query | integer or null | no |

#### Responses

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

### How much to send for a target USD credit, itemised {#op-get-api-v1-billing-crypto-quote}

`GET /api/v1/billing/crypto/quote`

How much to send for a target USD credit, itemised.

Quoting records an intent, which is what lets the deposit be credited at
the rate shown here and applied to ``invoice_id`` when it lands, instead
of arriving as a balance the customer then has to spend by hand.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `network` | query | string | yes |
| `asset` | query | string | yes |
| `amount` | query | number or string | yes |
| `invoice_id` | query | integer or null | no |

#### Responses

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

### Check hourly eligibility {#op-get-api-v1-billing-hourly-eligibility}

`GET /api/v1/billing/hourly-eligibility`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Newest first, ties by id so a page boundary never repeats or skips a row {#op-get-api-v1-billing-invoices}

`GET /api/v1/billing/invoices`

Newest first, ties by id so a page boundary never repeats or skips a row.

The bare list is the answer every existing caller reads; ``with_total``
wraps the same page in ``InvoicePage``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `50`. |
| `status_filter` | query | string or null | no |  |
| `with_total` | query | boolean | no | Default: `False`. |

#### Responses

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

### Get invoice {#op-get-api-v1-billing-invoices-invoice-id}

`GET /api/v1/billing/invoices/{invoice_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `invoice_number` | string |
| `user_id` | integer |
| `subtotal` | number |
| `tax` | number |
| `total` | number |
| `amount_paid` | number |
| `currency` | string |
| `status` | string |
| `due_date` | string (date-time) |
| `paid_at` | string (date-time) or null |
| `notes` | string or null |
| `items` | array of InvoiceItemResponse |
| `items[].id` | integer |
| `items[].service_id` | integer or null |
| `items[].description` | string |
| `items[].item_type` | string |
| `items[].quantity` | number |
| `items[].unit_price` | number |
| `items[].total` | number |
| `created_at` | string (date-time) |

### Apply account credit to an unpaid invoice (unlocks provision / plan change when paid) {#op-post-api-v1-billing-invoices-invoice-id-apply-credit}

`POST /api/v1/billing/invoices/{invoice_id}/apply-credit`

Apply account credit to an unpaid invoice (unlocks provision / plan change when paid).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |

#### Responses

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

### Hosted checkout to buy USD account credit without a saved payment method {#op-post-api-v1-billing-topup-checkout}

`POST /api/v1/billing/topup/checkout`

Hosted checkout to buy USD account credit without a saved payment method.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `amount` | number or string | yes |
| `currency` | string or null | no |
| `gateway_name` | string or null | no |
| `return_url` | string or null | no |
| `cancel_url` | string or null | no |

#### Responses

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

### Get topup config {#op-get-api-v1-billing-topup-config}

`GET /api/v1/billing/topup/config`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `auto_topup_enabled` | boolean |
| `auto_topup_threshold` | string |
| `auto_topup_amount` | string |
| `credit_balance` | string |
| `total_deposited` | string |
| `hourly_billing_unlocked` | boolean |

### Update topup config {#op-put-api-v1-billing-topup-config}

`PUT /api/v1/billing/topup/config`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |
| `threshold` | number or string or null | no |
| `amount` | number or string or null | no |

#### Responses

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

### Finalize a top-up PaymentIntent after SCA and credit the user balance {#op-post-api-v1-billing-topup-confirm-payment}

`POST /api/v1/billing/topup/confirm-payment`

Finalize a top-up PaymentIntent after SCA and credit the user balance.

USD credit comes from PaymentIntent metadata ``base_amount`` (set at
checkout/charge). Optional client ``amount`` may assert within $0.02.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `gateway_name` | query | string | yes |
| `payment_intent_id` | query | string | yes |
| `amount` | query | number or string or null | no |
| `currency` | query | string or null | no |

#### Responses

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

### Manually top up credit balance by charging a payment method {#op-post-api-v1-billing-topup-manual}

`POST /api/v1/billing/topup/manual`

Manually top up credit balance by charging a payment method.

``data.amount`` is always USD. The gateway is charged in the user's
preferred pay currency via admin FX rates (same path as auto-topup).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `amount` | number or string | yes |
| `payment_method_id` | integer | yes |

#### Responses

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

### Create an in-page Stripe Payment Element intent for a credit top-up {#op-post-api-v1-billing-topup-pay-intent}

`POST /api/v1/billing/topup/pay-intent`

Create an in-page Stripe Payment Element intent for a credit top-up.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `amount` | number or string | yes |
| `currency` | string or null | no |
| `gateway_name` | string or null | no |
| `save_method` | boolean | no |

#### Responses

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

### Capture an approved PayPal order and credit the platform user balance {#op-post-api-v1-billing-topup-paypal-capture}

`POST /api/v1/billing/topup/paypal-capture`

Capture an approved PayPal order and credit the platform user balance.

USD credit is derived from the order (``custom_id=topup:<usd>``), not the
client ``amount`` alone. Optional ``amount`` may assert within $0.02.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | query | string | yes |
| `gateway_name` | query | string | yes |
| `amount` | query | number or string or null | no |
| `currency` | query | string or null | no |

#### Responses

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

### As listinvoices: newest first, ties by id, withtotal for a TransactionPage {#op-get-api-v1-billing-transactions}

`GET /api/v1/billing/transactions`

As ``list_invoices``: newest first, ties by id, ``with_total`` for a
``TransactionPage``. ``type_filter=credit`` is credit added or used.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `50`. |
| `type_filter` | query | string or null | no |  |
| `with_total` | query | boolean | no | Default: `False`. |

#### Responses

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

# Client API: Payments

> Payment methods, checkout sessions, and available gateways.

Source: https://www.coritan.com/docs/api/reference/client/payments/

Payment methods, checkout sessions, and available gateways.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/payments/attempts`](#op-get-api-v1-payments-attempts) | List payment attempts |
| GET | [`/api/v1/payments/countries`](#op-get-api-v1-payments-countries) | Countries a customer can bill from, with the one we think they are in |
| GET | [`/api/v1/payments/currencies`](#op-get-api-v1-payments-currencies) | Payment currencies a customer can actually be charged in |
| GET | [`/api/v1/payments/disputes`](#op-get-api-v1-payments-disputes) | List disputes tied to the caller's payment attempts / invoices only |
| GET | [`/api/v1/payments/gateways`](#op-get-api-v1-payments-gateways) | List live gateway accounts, optionally filtered by pay currency |
| GET | [`/api/v1/payments/geo-currency`](#op-get-api-v1-payments-geo-currency) | Unauthenticated country → suggested pay currency (clamped to enabled) |
| POST | [`/api/v1/payments/invoices/{invoice_id}/charge`](#op-post-api-v1-payments-invoices-invoice-id-charge) | Canonical saved-method charge for an invoice (alias of /pay) |
| POST | [`/api/v1/payments/invoices/{invoice_id}/checkout`](#op-post-api-v1-payments-invoices-invoice-id-checkout) | Create invoice checkout |
| POST | [`/api/v1/payments/invoices/{invoice_id}/confirm-payment`](#op-post-api-v1-payments-invoices-invoice-id-confirm-payment) | Finalize a platform invoice charge after customer completes SCA |
| GET | [`/api/v1/payments/invoices/{invoice_id}/gateways`](#op-get-api-v1-payments-invoices-invoice-id-gateways) | List invoice gateways |
| POST | [`/api/v1/payments/invoices/{invoice_id}/pay`](#op-post-api-v1-payments-invoices-invoice-id-pay) | Charge a saved payment method for an invoice (legacy path; prefer /charge) |
| POST | [`/api/v1/payments/invoices/{invoice_id}/pay-intent`](#op-post-api-v1-payments-invoices-invoice-id-pay-intent) | Create an in-page Stripe Payment Element intent for an invoice |
| POST | [`/api/v1/payments/invoices/{invoice_id}/paypal-capture`](#op-post-api-v1-payments-invoices-invoice-id-paypal-capture) | Capture an approved PayPal order for a platform invoice |
| GET | [`/api/v1/payments/methods`](#op-get-api-v1-payments-methods) | List payment methods |
| POST | [`/api/v1/payments/methods/confirm`](#op-post-api-v1-payments-methods-confirm) | Confirm payment method |
| POST | [`/api/v1/payments/methods/setup`](#op-post-api-v1-payments-methods-setup) | Setup payment method |
| DELETE | [`/api/v1/payments/methods/{method_id}`](#op-delete-api-v1-payments-methods-method-id) | Remove payment method |
| PUT | [`/api/v1/payments/methods/{method_id}/default`](#op-put-api-v1-payments-methods-method-id-default) | Set default payment method |
| GET | [`/api/v1/payments/payment-config`](#op-get-api-v1-payments-payment-config) | Eligible gateway accounts + non-secret public config for embedded UIs |
| GET | [`/api/v1/payments/preference`](#op-get-api-v1-payments-preference) | Get payment preference |
| PATCH | [`/api/v1/payments/preference`](#op-patch-api-v1-payments-preference) | Update payment preference |

### List payment attempts {#op-get-api-v1-payments-attempts}

`GET /api/v1/payments/attempts`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].invoice_id` | integer or null |
| `[].user_id` | integer or null |
| `[].user_email` | string or null |
| `[].gateway_name` | string |
| `[].gateway_config_id` | integer or null |
| `[].payment_method_id` | integer or null |
| `[].amount` | integer |
| `[].currency` | string |
| `[].base_amount` | string or null |
| `[].fx_rate` | string or null |
| `[].status` | string |
| `[].gateway_reference` | string or null |
| `[].error_message` | string or null |
| `[].decline_type` | string or null |
| `[].decline_code` | string or null |
| `[].is_auto_charge` | boolean or null |
| `[].charge_schedule_id` | integer or null |
| `[].idempotency_key` | string or null |
| `[].refunded_amount` | integer or null |
| `[].created_at` | string (date-time) |
| `[].completed_at` | string (date-time) or null |
| `[].gateway_response` | object or null |
| `[].client_secret` | string or null |

### Countries a customer can bill from, with the one we think they are in {#op-get-api-v1-payments-countries}

`GET /api/v1/payments/countries`

Countries a customer can bill from, with the one we think they are in.

Served rather than shipped in the bundle so the picker, the currency
default and gateway routing cannot drift apart.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Payment currencies a customer can actually be charged in {#op-get-api-v1-payments-currencies}

`GET /api/v1/payments/currencies`

Payment currencies a customer can actually be charged in.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### List disputes tied to the caller's payment attempts / invoices only {#op-get-api-v1-payments-disputes}

`GET /api/v1/payments/disputes`

List disputes tied to the caller's payment attempts / invoices only.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

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

### List live gateway accounts, optionally filtered by pay currency {#op-get-api-v1-payments-gateways}

`GET /api/v1/payments/gateways`

List live gateway accounts, optionally filtered by pay currency.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `currency` | query | string or null | no |
| `country` | query | string or null | no |

#### Responses

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

### Unauthenticated country → suggested pay currency (clamped to enabled) {#op-get-api-v1-payments-geo-currency}

`GET /api/v1/payments/geo-currency`

Unauthenticated country → suggested pay currency (clamped to enabled).

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Canonical saved-method charge for an invoice (alias of /pay) {#op-post-api-v1-payments-invoices-invoice-id-charge}

`POST /api/v1/payments/invoices/{invoice_id}/charge`

Canonical saved-method charge for an invoice (alias of ``/pay``).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `payment_method_id` | integer | yes |
| `amount_cents` | integer or null | no |
| `currency` | string or null | no |
| `amount_usd` | number or string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `invoice_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `gateway_name` | string |
| `gateway_config_id` | integer or null |
| `payment_method_id` | integer or null |
| `amount` | integer |
| `currency` | string |
| `base_amount` | string or null |
| `fx_rate` | string or null |
| `status` | string |
| `gateway_reference` | string or null |
| `error_message` | string or null |
| `decline_type` | string or null |
| `decline_code` | string or null |
| `is_auto_charge` | boolean or null |
| `charge_schedule_id` | integer or null |
| `idempotency_key` | string or null |
| `refunded_amount` | integer or null |
| `created_at` | string (date-time) |
| `completed_at` | string (date-time) or null |
| `gateway_response` | object or null |
| `client_secret` | string or null |

### Create invoice checkout {#op-post-api-v1-payments-invoices-invoice-id-checkout}

`POST /api/v1/payments/invoices/{invoice_id}/checkout`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `gateway_name` | string | yes |
| `return_url` | string | yes |
| `cancel_url` | string | yes |
| `amount_cents` | integer or null | no |
| `currency` | string or null | no |
| `amount_usd` | number or string or null | no |

#### Responses

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

### Finalize a platform invoice charge after customer completes SCA {#op-post-api-v1-payments-invoices-invoice-id-confirm-payment}

`POST /api/v1/payments/invoices/{invoice_id}/confirm-payment`

Finalize a platform invoice charge after customer completes SCA.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `gateway_name` | query | string | yes |
| `payment_intent_id` | query | string | yes |
| `currency` | query | string or null | no |

#### Responses

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

### List invoice gateways {#op-get-api-v1-payments-invoices-invoice-id-gateways}

`GET /api/v1/payments/invoices/{invoice_id}/gateways`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `currency` | query | string or null | no |
| `country` | query | string or null | no |

#### Responses

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

### Charge a saved payment method for an invoice (legacy path; prefer /charge) {#op-post-api-v1-payments-invoices-invoice-id-pay}

`POST /api/v1/payments/invoices/{invoice_id}/pay`

Charge a saved payment method for an invoice (legacy path; prefer ``/charge``).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `payment_method_id` | integer | yes |
| `amount_cents` | integer or null | no |
| `currency` | string or null | no |
| `amount_usd` | number or string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `invoice_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `gateway_name` | string |
| `gateway_config_id` | integer or null |
| `payment_method_id` | integer or null |
| `amount` | integer |
| `currency` | string |
| `base_amount` | string or null |
| `fx_rate` | string or null |
| `status` | string |
| `gateway_reference` | string or null |
| `error_message` | string or null |
| `decline_type` | string or null |
| `decline_code` | string or null |
| `is_auto_charge` | boolean or null |
| `charge_schedule_id` | integer or null |
| `idempotency_key` | string or null |
| `refunded_amount` | integer or null |
| `created_at` | string (date-time) |
| `completed_at` | string (date-time) or null |
| `gateway_response` | object or null |
| `client_secret` | string or null |

### Create an in-page Stripe Payment Element intent for an invoice {#op-post-api-v1-payments-invoices-invoice-id-pay-intent}

`POST /api/v1/payments/invoices/{invoice_id}/pay-intent`

Create an in-page Stripe Payment Element intent for an invoice.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `gateway_name` | string or null | no |
| `currency` | string or null | no |
| `country_code` | string or null | no |
| `amount_usd` | number or string or null | no |
| `save_method` | boolean or null | no |

#### Responses

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

### Capture an approved PayPal order for a platform invoice {#op-post-api-v1-payments-invoices-invoice-id-paypal-capture}

`POST /api/v1/payments/invoices/{invoice_id}/paypal-capture`

Capture an approved PayPal order for a platform invoice.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `order_id` | query | string | yes |
| `gateway_name` | query | string | yes |
| `currency` | query | string or null | no |

#### Responses

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

### List payment methods {#op-get-api-v1-payments-methods}

`GET /api/v1/payments/methods`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].gateway_name` | string |
| `[].gateway_config_id` | integer or null |
| `[].currency` | string or null |
| `[].method_type` | string |
| `[].display_label` | string |
| `[].brand` | string or null |
| `[].last4` | string or null |
| `[].expires_month` | integer or null |
| `[].expires_year` | integer or null |
| `[].email` | string or null |
| `[].is_default` | boolean |
| `[].is_active` | boolean |
| `[].created_at` | string (date-time) |

### Confirm payment method {#op-post-api-v1-payments-methods-confirm}

`POST /api/v1/payments/methods/confirm`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `gateway_name` | string | yes |
| `session_id` | string | yes |
| `set_as_default` | boolean | no |
| `callback_data` | object or null | no |
| `currency` | string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `gateway_name` | string |
| `gateway_config_id` | integer or null |
| `currency` | string or null |
| `method_type` | string |
| `display_label` | string |
| `brand` | string or null |
| `last4` | string or null |
| `expires_month` | integer or null |
| `expires_year` | integer or null |
| `email` | string or null |
| `is_default` | boolean |
| `is_active` | boolean |
| `created_at` | string (date-time) |

### Setup payment method {#op-post-api-v1-payments-methods-setup}

`POST /api/v1/payments/methods/setup`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `gateway_name` | string or null | no |
| `currency` | string or null | no |
| `country_code` | string or null | no |
| `return_url` | string | yes |
| `cancel_url` | string | yes |

#### Responses

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

### Remove payment method {#op-delete-api-v1-payments-methods-method-id}

`DELETE /api/v1/payments/methods/{method_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `method_id` | path | integer | yes |

#### Responses

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

### Set default payment method {#op-put-api-v1-payments-methods-method-id-default}

`PUT /api/v1/payments/methods/{method_id}/default`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `method_id` | path | integer | yes |

#### Responses

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

### Eligible gateway accounts + non-secret public config for embedded UIs {#op-get-api-v1-payments-payment-config}

`GET /api/v1/payments/payment-config`

Eligible gateway accounts + non-secret public config for embedded UIs.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `currency` | query | string or null | no |
| `country` | query | string or null | no |

#### Responses

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

### Get payment preference {#op-get-api-v1-payments-preference}

`GET /api/v1/payments/preference`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Update payment preference {#op-patch-api-v1-payments-preference}

`PATCH /api/v1/payments/preference`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `currency` | string or null | no |
| `country_code` | string or null | no |
| `auto_pay_enabled` | boolean or null | no |

#### Responses

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

# Client API: DNS

> Authoritative DNS zones, records, DNSSEC, and per-zone query stats.

Source: https://www.coritan.com/docs/api/reference/client/dns/

Authoritative DNS zones, records, DNSSEC, and per-zone query stats.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/dns/lb-regions`](#op-get-api-v1-dns-lb-regions) | List DNS LB regions |
| GET | [`/api/v1/dns/zones`](#op-get-api-v1-dns-zones) | List zones |
| POST | [`/api/v1/dns/zones`](#op-post-api-v1-dns-zones) | Create zone |
| GET | [`/api/v1/dns/zones/{zone_id}`](#op-get-api-v1-dns-zones-zone-id) | Get zone |
| PATCH | [`/api/v1/dns/zones/{zone_id}`](#op-patch-api-v1-dns-zones-zone-id) | Update zone |
| DELETE | [`/api/v1/dns/zones/{zone_id}`](#op-delete-api-v1-dns-zones-zone-id) | Delete zone |
| GET | [`/api/v1/dns/zones/{zone_id}/dnssec`](#op-get-api-v1-dns-zones-zone-id-dnssec) | Get DNSSEC info |
| GET | [`/api/v1/dns/zones/{zone_id}/export`](#op-get-api-v1-dns-zones-zone-id-export) | Export zone |
| POST | [`/api/v1/dns/zones/{zone_id}/import`](#op-post-api-v1-dns-zones-zone-id-import) | Import zone |
| GET | [`/api/v1/dns/zones/{zone_id}/lb-pools`](#op-get-api-v1-dns-zones-zone-id-lb-pools) | List LB pools |
| POST | [`/api/v1/dns/zones/{zone_id}/lb-pools`](#op-post-api-v1-dns-zones-zone-id-lb-pools) | Create LB pool |
| GET | [`/api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}`](#op-get-api-v1-dns-zones-zone-id-lb-pools-pool-id) | Get LB pool |
| PATCH | [`/api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}`](#op-patch-api-v1-dns-zones-zone-id-lb-pools-pool-id) | Update LB pool |
| DELETE | [`/api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}`](#op-delete-api-v1-dns-zones-zone-id-lb-pools-pool-id) | Delete LB pool |
| POST | [`/api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}/members`](#op-post-api-v1-dns-zones-zone-id-lb-pools-pool-id-members) | Create LB member |
| PATCH | [`/api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}`](#op-patch-api-v1-dns-zones-zone-id-lb-pools-pool-id-members-member-id) | Update LB member |
| DELETE | [`/api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}`](#op-delete-api-v1-dns-zones-zone-id-lb-pools-pool-id-members-member-id) | Delete LB member |
| POST | [`/api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}/health-check`](#op-post-api-v1-dns-zones-zone-id-lb-pools-pool-id-members-member-id-health-check) | Health check LB member |
| GET | [`/api/v1/dns/zones/{zone_id}/load-balancers`](#op-get-api-v1-dns-zones-zone-id-load-balancers) | List load balancers |
| POST | [`/api/v1/dns/zones/{zone_id}/load-balancers`](#op-post-api-v1-dns-zones-zone-id-load-balancers) | Create load balancer |
| GET | [`/api/v1/dns/zones/{zone_id}/load-balancers/{lb_id}`](#op-get-api-v1-dns-zones-zone-id-load-balancers-lb-id) | Get load balancer |
| PATCH | [`/api/v1/dns/zones/{zone_id}/load-balancers/{lb_id}`](#op-patch-api-v1-dns-zones-zone-id-load-balancers-lb-id) | Update load balancer |
| DELETE | [`/api/v1/dns/zones/{zone_id}/load-balancers/{lb_id}`](#op-delete-api-v1-dns-zones-zone-id-load-balancers-lb-id) | Delete load balancer |
| POST | [`/api/v1/dns/zones/{zone_id}/load-balancers/{lb_id}/preview`](#op-post-api-v1-dns-zones-zone-id-load-balancers-lb-id-preview) | Preview load balancer |
| GET | [`/api/v1/dns/zones/{zone_id}/pools`](#op-get-api-v1-dns-zones-zone-id-pools) | List origin pools |
| POST | [`/api/v1/dns/zones/{zone_id}/pools`](#op-post-api-v1-dns-zones-zone-id-pools) | Create origin pool |
| GET | [`/api/v1/dns/zones/{zone_id}/pools/{pool_id}`](#op-get-api-v1-dns-zones-zone-id-pools-pool-id) | Get origin pool |
| PATCH | [`/api/v1/dns/zones/{zone_id}/pools/{pool_id}`](#op-patch-api-v1-dns-zones-zone-id-pools-pool-id) | Update origin pool |
| DELETE | [`/api/v1/dns/zones/{zone_id}/pools/{pool_id}`](#op-delete-api-v1-dns-zones-zone-id-pools-pool-id) | Delete origin pool |
| POST | [`/api/v1/dns/zones/{zone_id}/pools/{pool_id}/members`](#op-post-api-v1-dns-zones-zone-id-pools-pool-id-members) | Create origin member |
| PATCH | [`/api/v1/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}`](#op-patch-api-v1-dns-zones-zone-id-pools-pool-id-members-member-id) | Update origin member |
| DELETE | [`/api/v1/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}`](#op-delete-api-v1-dns-zones-zone-id-pools-pool-id-members-member-id) | Delete origin member |
| POST | [`/api/v1/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}/health-check`](#op-post-api-v1-dns-zones-zone-id-pools-pool-id-members-member-id-health-check) | Health check origin member |
| GET | [`/api/v1/dns/zones/{zone_id}/records`](#op-get-api-v1-dns-zones-zone-id-records) | List records |
| POST | [`/api/v1/dns/zones/{zone_id}/records`](#op-post-api-v1-dns-zones-zone-id-records) | Create record |
| GET | [`/api/v1/dns/zones/{zone_id}/records/{record_id}`](#op-get-api-v1-dns-zones-zone-id-records-record-id) | Get record |
| PUT | [`/api/v1/dns/zones/{zone_id}/records/{record_id}`](#op-put-api-v1-dns-zones-zone-id-records-record-id) | Update record |
| DELETE | [`/api/v1/dns/zones/{zone_id}/records/{record_id}`](#op-delete-api-v1-dns-zones-zone-id-records-record-id) | Delete record |
| GET | [`/api/v1/dns/zones/{zone_id}/stats`](#op-get-api-v1-dns-zones-zone-id-stats) | Get zone stats |

### List DNS LB regions {#op-get-api-v1-dns-lb-regions}

`GET /api/v1/dns/lb-regions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### List zones {#op-get-api-v1-dns-zones}

`GET /api/v1/dns/zones`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `25`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].service_id` | integer or null |
| `[].user_id` | integer |
| `[].org_id` | integer or null |
| `[].domain` | string |
| `[].status` | string |
| `[].dnssec_enabled` | boolean |
| `[].serial` | integer |
| `[].soa_email` | string |
| `[].record_count` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create zone {#op-post-api-v1-dns-zones}

`POST /api/v1/dns/zones`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `service_id` | integer or null |
| `user_id` | integer |
| `org_id` | integer or null |
| `domain` | string |
| `status` | string |
| `dnssec_enabled` | boolean |
| `serial` | integer |
| `soa_email` | string |
| `record_count` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Get zone {#op-get-api-v1-dns-zones-zone-id}

`GET /api/v1/dns/zones/{zone_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `service_id` | integer or null |
| `user_id` | integer |
| `org_id` | integer or null |
| `domain` | string |
| `status` | string |
| `dnssec_enabled` | boolean |
| `serial` | integer |
| `soa_email` | string |
| `record_count` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update zone {#op-patch-api-v1-dns-zones-zone-id}

`PATCH /api/v1/dns/zones/{zone_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `soa_email` | string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `service_id` | integer or null |
| `user_id` | integer |
| `org_id` | integer or null |
| `domain` | string |
| `status` | string |
| `dnssec_enabled` | boolean |
| `serial` | integer |
| `soa_email` | string |
| `record_count` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete zone {#op-delete-api-v1-dns-zones-zone-id}

`DELETE /api/v1/dns/zones/{zone_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Responses

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

### Get DNSSEC info {#op-get-api-v1-dns-zones-zone-id-dnssec}

`GET /api/v1/dns/zones/{zone_id}/dnssec`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `enabled` | boolean |
| `algorithm` | string |
| `ksk_key_tag` | integer or null |
| `zsk_key_tag` | integer or null |
| `ds_records` | array of string |
| `zsk_rotated_at` | string (date-time) or null |

### Export zone {#op-get-api-v1-dns-zones-zone-id-export}

`GET /api/v1/dns/zones/{zone_id}/export`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Responses

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

### Import zone {#op-post-api-v1-dns-zones-zone-id-import}

`POST /api/v1/dns/zones/{zone_id}/import`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `zone_file` | string | yes |

#### Responses

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

### List LB pools {#op-get-api-v1-dns-zones-zone-id-lb-pools}

`GET /api/v1/dns/zones/{zone_id}/lb-pools`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].zone_id` | integer |
| `[].name` | string |
| `[].description` | string or null |
| `[].hostname` | string or null |
| `[].algorithm` | string |
| `[].ttl` | integer |
| `[].session_affinity` | string |
| `[].primary_location_code` | string or null |
| `[].enabled` | boolean |
| `[].members` | array of LbMemberResponse |
| `[].members[].id` | integer |
| `[].members[].pool_id` | integer |
| `[].members[].address` | string |
| `[].members[].address_type` | string |
| `[].members[].weight` | integer |
| `[].members[].priority` | integer |
| `[].members[].enabled` | boolean |
| `[].members[].health_mode` | string |
| `[].members[].health_port` | integer or null |
| `[].members[].health_path` | string |
| `[].members[].health_interval_s` | integer |
| `[].members[].health_timeout_s` | integer |
| `[].members[].health_status` | string |
| `[].members[].last_check_at` | string (date-time) or null |
| `[].members[].last_error` | string or null |
| `[].members[].created_at` | string (date-time) |
| `[].members[].updated_at` | string (date-time) |
| `[].healthy_members` | integer or null |
| `[].total_members` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create LB pool {#op-post-api-v1-dns-zones-zone-id-lb-pools}

`POST /api/v1/dns/zones/{zone_id}/lb-pools`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `description` | string or null | no |
| `hostname` | string or null | no |
| `algorithm` | string | no |
| `ttl` | integer | no |
| `session_affinity` | string | no |
| `primary_location_code` | string or null | no |
| `enabled` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Get LB pool {#op-get-api-v1-dns-zones-zone-id-lb-pools-pool-id}

`GET /api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update LB pool {#op-patch-api-v1-dns-zones-zone-id-lb-pools-pool-id}

`PATCH /api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `description` | string or null | no |
| `algorithm` | string or null | no |
| `ttl` | integer or null | no |
| `session_affinity` | string or null | no |
| `primary_location_code` | string or null | no |
| `enabled` | boolean or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete LB pool {#op-delete-api-v1-dns-zones-zone-id-lb-pools-pool-id}

`DELETE /api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |

#### Responses

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

### Create LB member {#op-post-api-v1-dns-zones-zone-id-lb-pools-pool-id-members}

`POST /api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}/members`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |
| `address_type` | string | no |
| `weight` | integer | no |
| `priority` | integer | no |
| `enabled` | boolean | no |
| `health_mode` | string | no |
| `health_port` | integer or null | no |
| `health_path` | string | no |
| `health_interval_s` | integer | no |
| `health_timeout_s` | integer | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update LB member {#op-patch-api-v1-dns-zones-zone-id-lb-pools-pool-id-members-member-id}

`PATCH /api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string or null | no |
| `weight` | integer or null | no |
| `priority` | integer or null | no |
| `enabled` | boolean or null | no |
| `health_mode` | string or null | no |
| `health_port` | integer or null | no |
| `health_path` | string or null | no |
| `health_interval_s` | integer or null | no |
| `health_timeout_s` | integer or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete LB member {#op-delete-api-v1-dns-zones-zone-id-lb-pools-pool-id-members-member-id}

`DELETE /api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |

#### Responses

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

### Health check LB member {#op-post-api-v1-dns-zones-zone-id-lb-pools-pool-id-members-member-id-health-check}

`POST /api/v1/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}/health-check`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### List load balancers {#op-get-api-v1-dns-zones-zone-id-load-balancers}

`GET /api/v1/dns/zones/{zone_id}/load-balancers`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].zone_id` | integer |
| `[].name` | string |
| `[].hostname` | string |
| `[].enabled` | boolean |
| `[].ttl` | integer |
| `[].session_affinity` | string |
| `[].steering_policy` | string |
| `[].location_strategy` | string |
| `[].fallback_pool_id` | integer or null |
| `[].default_pools` | array of integer |
| `[].location_pools` | Location Pools |
| `[].country_pools` | Country Pools |
| `[].region_pools` | Region Pools |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create load balancer {#op-post-api-v1-dns-zones-zone-id-load-balancers}

`POST /api/v1/dns/zones/{zone_id}/load-balancers`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `hostname` | string | yes |
| `ttl` | integer | no |
| `session_affinity` | string | no |
| `steering_policy` | string | no |
| `location_strategy` | string | no |
| `default_pools` | array of integer | no |
| `fallback_pool_id` | integer or null | no |
| `location_pools` | Location Pools | no |
| `country_pools` | Country Pools | no |
| `region_pools` | Region Pools | no |
| `enabled` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `hostname` | string |
| `enabled` | boolean |
| `ttl` | integer |
| `session_affinity` | string |
| `steering_policy` | string |
| `location_strategy` | string |
| `fallback_pool_id` | integer or null |
| `default_pools` | array of integer |
| `location_pools` | Location Pools |
| `country_pools` | Country Pools |
| `region_pools` | Region Pools |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Get load balancer {#op-get-api-v1-dns-zones-zone-id-load-balancers-lb-id}

`GET /api/v1/dns/zones/{zone_id}/load-balancers/{lb_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `lb_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `hostname` | string |
| `enabled` | boolean |
| `ttl` | integer |
| `session_affinity` | string |
| `steering_policy` | string |
| `location_strategy` | string |
| `fallback_pool_id` | integer or null |
| `default_pools` | array of integer |
| `location_pools` | Location Pools |
| `country_pools` | Country Pools |
| `region_pools` | Region Pools |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update load balancer {#op-patch-api-v1-dns-zones-zone-id-load-balancers-lb-id}

`PATCH /api/v1/dns/zones/{zone_id}/load-balancers/{lb_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `lb_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `hostname` | string or null | no |
| `ttl` | integer or null | no |
| `session_affinity` | string or null | no |
| `steering_policy` | string or null | no |
| `location_strategy` | string or null | no |
| `default_pools` | array of integer or null | no |
| `fallback_pool_id` | integer or null | no |
| `location_pools` | object or null | no |
| `country_pools` | object or null | no |
| `region_pools` | object or null | no |
| `enabled` | boolean or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `hostname` | string |
| `enabled` | boolean |
| `ttl` | integer |
| `session_affinity` | string |
| `steering_policy` | string |
| `location_strategy` | string |
| `fallback_pool_id` | integer or null |
| `default_pools` | array of integer |
| `location_pools` | Location Pools |
| `country_pools` | Country Pools |
| `region_pools` | Region Pools |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete load balancer {#op-delete-api-v1-dns-zones-zone-id-load-balancers-lb-id}

`DELETE /api/v1/dns/zones/{zone_id}/load-balancers/{lb_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `lb_id` | path | integer | yes |

#### Responses

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

### Preview load balancer {#op-post-api-v1-dns-zones-zone-id-load-balancers-lb-id-preview}

`POST /api/v1/dns/zones/{zone_id}/load-balancers/{lb_id}/preview`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `lb_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from_location` | string or null | no |
| `from_ip` | string or null | no |
| `qtype` | string | no |

#### Responses

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

### List origin pools {#op-get-api-v1-dns-zones-zone-id-pools}

`GET /api/v1/dns/zones/{zone_id}/pools`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].zone_id` | integer |
| `[].name` | string |
| `[].description` | string or null |
| `[].hostname` | string or null |
| `[].algorithm` | string |
| `[].ttl` | integer |
| `[].session_affinity` | string |
| `[].primary_location_code` | string or null |
| `[].enabled` | boolean |
| `[].members` | array of LbMemberResponse |
| `[].members[].id` | integer |
| `[].members[].pool_id` | integer |
| `[].members[].address` | string |
| `[].members[].address_type` | string |
| `[].members[].weight` | integer |
| `[].members[].priority` | integer |
| `[].members[].enabled` | boolean |
| `[].members[].health_mode` | string |
| `[].members[].health_port` | integer or null |
| `[].members[].health_path` | string |
| `[].members[].health_interval_s` | integer |
| `[].members[].health_timeout_s` | integer |
| `[].members[].health_status` | string |
| `[].members[].last_check_at` | string (date-time) or null |
| `[].members[].last_error` | string or null |
| `[].members[].created_at` | string (date-time) |
| `[].members[].updated_at` | string (date-time) |
| `[].healthy_members` | integer or null |
| `[].total_members` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create origin pool {#op-post-api-v1-dns-zones-zone-id-pools}

`POST /api/v1/dns/zones/{zone_id}/pools`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `description` | string or null | no |
| `hostname` | string or null | no |
| `algorithm` | string | no |
| `ttl` | integer | no |
| `session_affinity` | string | no |
| `primary_location_code` | string or null | no |
| `enabled` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Get origin pool {#op-get-api-v1-dns-zones-zone-id-pools-pool-id}

`GET /api/v1/dns/zones/{zone_id}/pools/{pool_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update origin pool {#op-patch-api-v1-dns-zones-zone-id-pools-pool-id}

`PATCH /api/v1/dns/zones/{zone_id}/pools/{pool_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `description` | string or null | no |
| `algorithm` | string or null | no |
| `ttl` | integer or null | no |
| `session_affinity` | string or null | no |
| `primary_location_code` | string or null | no |
| `enabled` | boolean or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete origin pool {#op-delete-api-v1-dns-zones-zone-id-pools-pool-id}

`DELETE /api/v1/dns/zones/{zone_id}/pools/{pool_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |

#### Responses

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

### Create origin member {#op-post-api-v1-dns-zones-zone-id-pools-pool-id-members}

`POST /api/v1/dns/zones/{zone_id}/pools/{pool_id}/members`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |
| `address_type` | string | no |
| `weight` | integer | no |
| `priority` | integer | no |
| `enabled` | boolean | no |
| `health_mode` | string | no |
| `health_port` | integer or null | no |
| `health_path` | string | no |
| `health_interval_s` | integer | no |
| `health_timeout_s` | integer | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update origin member {#op-patch-api-v1-dns-zones-zone-id-pools-pool-id-members-member-id}

`PATCH /api/v1/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string or null | no |
| `weight` | integer or null | no |
| `priority` | integer or null | no |
| `enabled` | boolean or null | no |
| `health_mode` | string or null | no |
| `health_port` | integer or null | no |
| `health_path` | string or null | no |
| `health_interval_s` | integer or null | no |
| `health_timeout_s` | integer or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete origin member {#op-delete-api-v1-dns-zones-zone-id-pools-pool-id-members-member-id}

`DELETE /api/v1/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |

#### Responses

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

### Health check origin member {#op-post-api-v1-dns-zones-zone-id-pools-pool-id-members-member-id-health-check}

`POST /api/v1/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}/health-check`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### List records {#op-get-api-v1-dns-zones-zone-id-records}

`GET /api/v1/dns/zones/{zone_id}/records`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `zone_id` | path | integer | yes |  |
| `record_type` | query | string | no |  |
| `name` | query | string | no |  |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `100`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].zone_id` | integer |
| `[].name` | string |
| `[].record_type` | string |
| `[].content` | string |
| `[].ttl` | integer |
| `[].priority` | integer or null |
| `[].weight` | integer or null |
| `[].port` | integer or null |
| `[].proxied` | boolean |
| `[].comment` | string or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create record {#op-post-api-v1-dns-zones-zone-id-records}

`POST /api/v1/dns/zones/{zone_id}/records`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `record_type` | string | yes |
| `content` | string | yes |
| `ttl` | integer | no |
| `priority` | integer or null | no |
| `weight` | integer or null | no |
| `port` | integer or null | no |
| `proxied` | boolean | no |
| `comment` | string or null | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `record_type` | string |
| `content` | string |
| `ttl` | integer |
| `priority` | integer or null |
| `weight` | integer or null |
| `port` | integer or null |
| `proxied` | boolean |
| `comment` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Get record {#op-get-api-v1-dns-zones-zone-id-records-record-id}

`GET /api/v1/dns/zones/{zone_id}/records/{record_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `record_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `record_type` | string |
| `content` | string |
| `ttl` | integer |
| `priority` | integer or null |
| `weight` | integer or null |
| `port` | integer or null |
| `proxied` | boolean |
| `comment` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update record {#op-put-api-v1-dns-zones-zone-id-records-record-id}

`PUT /api/v1/dns/zones/{zone_id}/records/{record_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `record_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `content` | string or null | no |
| `ttl` | integer or null | no |
| `priority` | integer or null | no |
| `weight` | integer or null | no |
| `port` | integer or null | no |
| `proxied` | boolean or null | no |
| `comment` | string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `record_type` | string |
| `content` | string |
| `ttl` | integer |
| `priority` | integer or null |
| `weight` | integer or null |
| `port` | integer or null |
| `proxied` | boolean |
| `comment` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete record {#op-delete-api-v1-dns-zones-zone-id-records-record-id}

`DELETE /api/v1/dns/zones/{zone_id}/records/{record_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `record_id` | path | integer | yes |

#### Responses

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

### Get zone stats {#op-get-api-v1-dns-zones-zone-id-stats}

`GET /api/v1/dns/zones/{zone_id}/stats`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `zone_id` | path | integer | yes |  |
| `hours` | query | integer | no | Default: `24`. |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `zone_id` | integer |
| `period_hours` | integer |
| `total_queries` | integer |
| `noerror` | integer |
| `nxdomain` | integer |
| `servfail` | integer |
| `by_type` | By Type |
| `hourly` | array of object |

# Client API: SSL

> Certificate inventory and issuance, plus HTTP-01 / DNS challenge workflows for domain validation.

Source: https://www.coritan.com/docs/api/reference/client/ssl/

Certificate inventory and issuance, plus HTTP-01 / DNS challenge workflows for domain validation.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/ssl/certificates`](#op-get-api-v1-ssl-certificates) | List SSL certificates for the authenticated user |
| POST | [`/api/v1/ssl/certificates`](#op-post-api-v1-ssl-certificates) | Request SSL certificate issuance for a domain owned by the user |
| DELETE | [`/api/v1/ssl/certificates/{domain}`](#op-delete-api-v1-ssl-certificates-domain) | Revoke/deactivate an SSL certificate for a domain |
| POST | [`/api/v1/ssl/certificates/{domain}/renew`](#op-post-api-v1-ssl-certificates-domain-renew) | Request certificate renewal for a domain |
| GET | [`/api/v1/ssl/certificates/{domain}/status`](#op-get-api-v1-ssl-certificates-domain-status) | Get SSL certificate status for a domain |
| POST | [`/api/v1/ssl/challenges/start`](#op-post-api-v1-ssl-challenges-start) | Start an SSL challenge for a domain |
| POST | [`/api/v1/ssl/challenges/{domain}/complete`](#op-post-api-v1-ssl-challenges-domain-complete) | Finalize verification and trigger certificate issuance |
| GET | [`/api/v1/ssl/challenges/{domain}/status`](#op-get-api-v1-ssl-challenges-domain-status) | Check the current verification status for a domain |

### List SSL certificates for the authenticated user {#op-get-api-v1-ssl-certificates}

`GET /api/v1/ssl/certificates`

List SSL certificates for the authenticated user.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `25`. |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `certificates` | array of SSLCertificateResponse |
| `certificates[].id` | integer |
| `certificates[].domain` | string |
| `certificates[].route_id` | integer or null |
| `certificates[].zone_id` | integer or null |
| `certificates[].status` | string |
| `certificates[].issuer` | string or null |
| `certificates[].challenge_method` | string or null |
| `certificates[].issued_at` | string (date-time) or null |
| `certificates[].expires_at` | string (date-time) or null |
| `certificates[].last_renewal_at` | string (date-time) or null |
| `certificates[].renewal_attempts` | integer |
| `certificates[].error_message` | string or null |
| `certificates[].created_at` | string (date-time) or null |
| `certificates[].san_domains` | array of string |
| `certificates[].serial` | string or null |
| `certificates[].fingerprint_sha256` | string or null |
| `certificates[].requested_provider` | string or null |
| `certificates[].failover_from` | array of string |
| `total` | integer |

### Request SSL certificate issuance for a domain owned by the user {#op-post-api-v1-ssl-certificates}

`POST /api/v1/ssl/certificates`

Request SSL certificate issuance for a domain owned by the user.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `route_id` | integer or null | no |
| `challenge_method` | string or null | no |

#### Responses

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

### Revoke/deactivate an SSL certificate for a domain {#op-delete-api-v1-ssl-certificates-domain}

`DELETE /api/v1/ssl/certificates/{domain}`

Revoke/deactivate an SSL certificate for a domain.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Request certificate renewal for a domain {#op-post-api-v1-ssl-certificates-domain-renew}

`POST /api/v1/ssl/certificates/{domain}/renew`

Request certificate renewal for a domain.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Get SSL certificate status for a domain {#op-get-api-v1-ssl-certificates-domain-status}

`GET /api/v1/ssl/certificates/{domain}/status`

Get SSL certificate status for a domain.

The certificate is the newest for the name itself, else for the parent's
wildcard (every claimed platform name carries one), else for the zone's
own wildcard, which carries the apex as a SAN (``certificate_lookup``).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `domain` | string |
| `has_certificate` | boolean |
| `certificate` | SSLCertificateResponse or null |
| `certificate.id` | integer |
| `certificate.domain` | string |
| `certificate.route_id` | integer or null |
| `certificate.zone_id` | integer or null |
| `certificate.status` | string |
| `certificate.issuer` | string or null |
| `certificate.challenge_method` | string or null |
| `certificate.issued_at` | string (date-time) or null |
| `certificate.expires_at` | string (date-time) or null |
| `certificate.last_renewal_at` | string (date-time) or null |
| `certificate.renewal_attempts` | integer |
| `certificate.error_message` | string or null |
| `certificate.created_at` | string (date-time) or null |
| `certificate.san_domains` | array of string |
| `certificate.serial` | string or null |
| `certificate.fingerprint_sha256` | string or null |
| `certificate.requested_provider` | string or null |
| `certificate.failover_from` | array of string |
| `rate_limit` | SSLRateLimitResponse or null |
| `rate_limit.registered_domain` | string |
| `rate_limit.issued_last_7_days` | integer |
| `rate_limit.limit` | integer |
| `rate_limit.remaining` | integer |
| `rate_limit.allowed` | boolean |
| `wildcard` | boolean |

### Start an SSL challenge for a domain {#op-post-api-v1-ssl-challenges-start}

`POST /api/v1/ssl/challenges/start`

Start an SSL challenge for a domain. Returns method-specific instructions.

Methods:
- auto: automatically selects the best method
- dns_automatic: uses platform-managed DNS (requires DNS zone)
- dns_manual: returns TXT record for user to add to their external DNS
- http: verifies domain is pointed to this server, issues via HTTP-01

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `method` | string | no |

#### Responses

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

### Finalize verification and trigger certificate issuance {#op-post-api-v1-ssl-challenges-domain-complete}

`POST /api/v1/ssl/challenges/{domain}/complete`

Finalize verification and trigger certificate issuance.
For HTTP method: verifies domain points to server, then issues via HTTP-01.
For dns_manual: verifies TXT record exists, then issues via DNS-01.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Check the current verification status for a domain {#op-get-api-v1-ssl-challenges-domain-status}

`GET /api/v1/ssl/challenges/{domain}/status`

Check the current verification status for a domain.
Performs real-time DNS/IP resolution checks.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

# Client API: Domains

> Domain search, registration, renewals, nameservers, and locks.

Source: https://www.coritan.com/docs/api/reference/client/domains/

Domain search, registration, renewals, nameservers, and locks.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/domains/pricing`](#op-get-api-v1-domains-pricing) | Get available TLD pricing |
| POST | [`/api/v1/domains/register`](#op-post-api-v1-domains-register) | Register a new domain name |
| GET | [`/api/v1/domains/registrations`](#op-get-api-v1-domains-registrations) | List user's domain registrations |
| GET | [`/api/v1/domains/registrations/{reg_id}`](#op-get-api-v1-domains-registrations-reg-id) | Get details of a specific domain registration |
| GET | [`/api/v1/domains/registrations/{reg_id}/auth-code`](#op-get-api-v1-domains-registrations-reg-id-auth-code) | Get the EPP/auth code for domain transfer out |
| PUT | [`/api/v1/domains/registrations/{reg_id}/auto-renew`](#op-put-api-v1-domains-registrations-reg-id-auto-renew) | Toggle auto-renewal for a domain |
| PUT | [`/api/v1/domains/registrations/{reg_id}/lock`](#op-put-api-v1-domains-registrations-reg-id-lock) | Lock or unlock a domain |
| PUT | [`/api/v1/domains/registrations/{reg_id}/nameservers`](#op-put-api-v1-domains-registrations-reg-id-nameservers) | Update nameservers for a domain |
| POST | [`/api/v1/domains/registrations/{reg_id}/renew`](#op-post-api-v1-domains-registrations-reg-id-renew) | Request domain renewal |
| PUT | [`/api/v1/domains/registrations/{reg_id}/whois-privacy`](#op-put-api-v1-domains-registrations-reg-id-whois-privacy) | Toggle WHOIS privacy for a domain |
| POST | [`/api/v1/domains/search`](#op-post-api-v1-domains-search) | Check domain availability and pricing (includes markup) |
| POST | [`/api/v1/domains/transfer`](#op-post-api-v1-domains-transfer) | Initiate an inbound domain transfer |

### Get available TLD pricing {#op-get-api-v1-domains-pricing}

`GET /api/v1/domains/pricing`

Get available TLD pricing.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].tld` | string |
| `[].register_price` | string |
| `[].renew_price` | string |
| `[].transfer_price` | string or null |
| `[].currency` | string |

### Register a new domain name {#op-post-api-v1-domains-register}

`POST /api/v1/domains/register`

Register a new domain name. Charges user credit balance first, then provisions.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `duration` | integer | no |
| `nameservers` | array of string or null | no |
| `auto_ssl` | boolean | no |
| `auto_proxy` | boolean | no |
| `whois_privacy` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `domain` | string |
| `status` | string |
| `registered_at` | string (date-time) or null |
| `expires_at` | string (date-time) or null |
| `nameservers` | array of string or null |
| `whois_privacy` | boolean |
| `locked` | boolean |
| `auto_renew` | boolean |
| `auto_ssl` | boolean |
| `auto_proxy` | boolean |
| `dns_zone_id` | integer or null |
| `proxy_route_id` | integer or null |
| `ssl_certificate_id` | integer or null |

### List user's domain registrations {#op-get-api-v1-domains-registrations}

`GET /api/v1/domains/registrations`

List user's domain registrations.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `25`. |
| `status` | query | string | no |  |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `registrations` | array of DomainRegistrationResponse |
| `registrations[].id` | integer |
| `registrations[].domain` | string |
| `registrations[].status` | string |
| `registrations[].registered_at` | string (date-time) or null |
| `registrations[].expires_at` | string (date-time) or null |
| `registrations[].nameservers` | array of string or null |
| `registrations[].whois_privacy` | boolean |
| `registrations[].locked` | boolean |
| `registrations[].auto_renew` | boolean |
| `registrations[].auto_ssl` | boolean |
| `registrations[].auto_proxy` | boolean |
| `registrations[].dns_zone_id` | integer or null |
| `registrations[].proxy_route_id` | integer or null |
| `registrations[].ssl_certificate_id` | integer or null |
| `total` | integer |

### Get details of a specific domain registration {#op-get-api-v1-domains-registrations-reg-id}

`GET /api/v1/domains/registrations/{reg_id}`

Get details of a specific domain registration.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reg_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `domain` | string |
| `status` | string |
| `registered_at` | string (date-time) or null |
| `expires_at` | string (date-time) or null |
| `nameservers` | array of string or null |
| `whois_privacy` | boolean |
| `locked` | boolean |
| `auto_renew` | boolean |
| `auto_ssl` | boolean |
| `auto_proxy` | boolean |
| `dns_zone_id` | integer or null |
| `proxy_route_id` | integer or null |
| `ssl_certificate_id` | integer or null |

### Get the EPP/auth code for domain transfer out {#op-get-api-v1-domains-registrations-reg-id-auth-code}

`GET /api/v1/domains/registrations/{reg_id}/auth-code`

Get the EPP/auth code for domain transfer out.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reg_id` | path | integer | yes |

#### Responses

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

### Toggle auto-renewal for a domain {#op-put-api-v1-domains-registrations-reg-id-auto-renew}

`PUT /api/v1/domains/registrations/{reg_id}/auto-renew`

Toggle auto-renewal for a domain.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reg_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Lock or unlock a domain {#op-put-api-v1-domains-registrations-reg-id-lock}

`PUT /api/v1/domains/registrations/{reg_id}/lock`

Lock or unlock a domain.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reg_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Update nameservers for a domain {#op-put-api-v1-domains-registrations-reg-id-nameservers}

`PUT /api/v1/domains/registrations/{reg_id}/nameservers`

Update nameservers for a domain.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reg_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `nameservers` | array of string | yes |

#### Responses

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

### Request domain renewal {#op-post-api-v1-domains-registrations-reg-id-renew}

`POST /api/v1/domains/registrations/{reg_id}/renew`

Request domain renewal.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reg_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `duration` | integer | no |

#### Responses

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

### Toggle WHOIS privacy for a domain {#op-put-api-v1-domains-registrations-reg-id-whois-privacy}

`PUT /api/v1/domains/registrations/{reg_id}/whois-privacy`

Toggle WHOIS privacy for a domain.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reg_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Check domain availability and pricing (includes markup) {#op-post-api-v1-domains-search}

`POST /api/v1/domains/search`

Check domain availability and pricing (includes markup).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `domain` | string |
| `available` | boolean |
| `price` | string or null |
| `currency` | string |
| `premium` | boolean |

### Initiate an inbound domain transfer {#op-post-api-v1-domains-transfer}

`POST /api/v1/domains/transfer`

Initiate an inbound domain transfer.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `auth_code` | string | yes |

#### Responses

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

# Client API: Reverse Proxy

> User-managed reverse-proxy routes (TLS, upstreams, WAF settings).

Source: https://www.coritan.com/docs/api/reference/client/reverse-proxy/

User-managed reverse-proxy routes (TLS, upstreams, WAF settings).

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/proxy/routes`](#op-get-api-v1-proxy-routes) | List proxy routes owned by the current user |
| POST | [`/api/v1/proxy/routes`](#op-post-api-v1-proxy-routes) | Create a proxy route for a domain you own |
| POST | [`/api/v1/proxy/routes/connect-domain`](#op-post-api-v1-proxy-routes-connect-domain) | Connect a user's domain to their container server |
| GET | [`/api/v1/proxy/routes/{route_id}`](#op-get-api-v1-proxy-routes-route-id) | Get details of a proxy route you own |
| PATCH | [`/api/v1/proxy/routes/{route_id}`](#op-patch-api-v1-proxy-routes-route-id) | Update a proxy route you own |
| DELETE | [`/api/v1/proxy/routes/{route_id}`](#op-delete-api-v1-proxy-routes-route-id) | Delete a proxy route you own |
| POST | [`/api/v1/proxy/routes/{route_id}/error-page/preview`](#op-post-api-v1-proxy-routes-route-id-error-page-preview) | Render the page visitors would see, for a block that is not saved yet |
| GET | [`/api/v1/proxy/routes/{route_id}/redirect-rules`](#op-get-api-v1-proxy-routes-route-id-redirect-rules) | List redirect rules for a route you own |
| POST | [`/api/v1/proxy/routes/{route_id}/redirect-rules`](#op-post-api-v1-proxy-routes-route-id-redirect-rules) | Create a redirect rule for a route you own |
| PATCH | [`/api/v1/proxy/routes/{route_id}/redirect-rules/{rule_id}`](#op-patch-api-v1-proxy-routes-route-id-redirect-rules-rule-id) | Update a redirect rule for a route you own |
| DELETE | [`/api/v1/proxy/routes/{route_id}/redirect-rules/{rule_id}`](#op-delete-api-v1-proxy-routes-route-id-redirect-rules-rule-id) | Delete a redirect rule for a route you own |
| POST | [`/api/v1/proxy/routes/{route_id}/ssl`](#op-post-api-v1-proxy-routes-route-id-ssl) | Request SSL certificate issuance for a proxy route you own |

### List proxy routes owned by the current user {#op-get-api-v1-proxy-routes}

`GET /api/v1/proxy/routes`

List proxy routes owned by the current user.

The list stays slim: what the Proxies list and the website's WAF tab
show for a row, so neither reads a route or a certificate per row. That
is the origin and whether it speaks TLS, the redirect, the extra origins,
the switches, development mode as the edge reads it and the certificate
``GET /ssl/certificates/{domain}/status`` would name. Origin protocol,
gRPC, and outbound PROXY are on create/update and the detail ``SELECT *``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `50`. |

#### Responses

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

### Create a proxy route for a domain you own {#op-post-api-v1-proxy-routes}

`POST /api/v1/proxy/routes`

Create a proxy route for a domain you own.
Ownership is verified via domain registration or DNS zone.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `upstream_host` | string or null | no |
| `upstream_port` | integer | no |
| `upstream_ssl` | boolean | no |
| `force_https` | boolean | no |
| `websocket_enabled` | boolean | no |
| `waf_enabled` | boolean | no |
| `send_proxy_protocol` | boolean | no |
| `upstream_protocol` | string | no |
| `grpc_enabled` | boolean | no |
| `max_body_size_mb` | integer | no |
| `timeout_seconds` | integer | no |
| `auto_ssl` | boolean | no |
| `redirect_to` | string or null | no |
| `redirect_status_code` | integer | no |
| `redirect_preserve_path` | boolean | no |
| `redirect_preserve_query` | boolean | no |
| `strip_path_prefix` | string or null | no |
| `upstream_path_prefix` | string or null | no |
| `custom_headers` | any or null | no |
| `upstream_backends` | any or null | no |

#### Responses

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

### Connect a user's domain to their container server {#op-post-api-v1-proxy-routes-connect-domain}

`POST /api/v1/proxy/routes/connect-domain`

Connect a user's domain to their container server.
Creates or updates a proxy route pointing the domain at the container's IP/port,
and optionally provisions an SSL certificate.

Requirements:
- User must own the domain (via registration or DNS zone)
- User must own the server

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `server_uuid` | string | yes |
| `domain` | string | yes |
| `auto_ssl` | boolean | no |

#### Responses

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

### Get details of a proxy route you own {#op-get-api-v1-proxy-routes-route-id}

`GET /api/v1/proxy/routes/{route_id}`

Get details of a proxy route you own.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Responses

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

### Update a proxy route you own {#op-patch-api-v1-proxy-routes-route-id}

`PATCH /api/v1/proxy/routes/{route_id}`

Update a proxy route you own.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `upstream_host` | string or null | no |
| `upstream_port` | integer or null | no |
| `upstream_ssl` | boolean or null | no |
| `force_https` | boolean or null | no |
| `websocket_enabled` | boolean or null | no |
| `waf_enabled` | boolean or null | no |
| `send_proxy_protocol` | boolean or null | no |
| `upstream_protocol` | string or null | no |
| `grpc_enabled` | boolean or null | no |
| `max_body_size_mb` | integer or null | no |
| `timeout_seconds` | integer or null | no |
| `redirect_to` | string or null | no |
| `redirect_status_code` | integer or null | no |
| `redirect_preserve_path` | boolean or null | no |
| `redirect_preserve_query` | boolean or null | no |
| `strip_path_prefix` | string or null | no |
| `upstream_path_prefix` | string or null | no |
| `custom_headers` | any or null | no |
| `upstream_backends` | any or null | no |
| `development_mode` | boolean or null | no |
| `development_mode_minutes` | integer or null | no |
| `error_page` | any or null | no |

#### Responses

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

### Delete a proxy route you own {#op-delete-api-v1-proxy-routes-route-id}

`DELETE /api/v1/proxy/routes/{route_id}`

Delete a proxy route you own.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Responses

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

### Render the page visitors would see, for a block that is not saved yet {#op-post-api-v1-proxy-routes-route-id-error-page-preview}

`POST /api/v1/proxy/routes/{route_id}/error-page/preview`

Render the page visitors would see, for a block that is not saved yet.

``error_page: null`` shows the inherited page instead, so the console can
put "with" and "without" side by side.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `error_page` | any or null | no |
| `status` | integer | no |

#### Responses

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

### List redirect rules for a route you own {#op-get-api-v1-proxy-routes-route-id-redirect-rules}

`GET /api/v1/proxy/routes/{route_id}/redirect-rules`

List redirect rules for a route you own.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Responses

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

### Create a redirect rule for a route you own {#op-post-api-v1-proxy-routes-route-id-redirect-rules}

`POST /api/v1/proxy/routes/{route_id}/redirect-rules`

Create a redirect rule for a route you own.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `source_pattern` | string | yes |
| `match_type` | string | no |
| `target_url` | string | yes |
| `status_code` | integer | no |
| `preserve_query` | boolean | no |
| `priority` | integer | no |
| `enabled` | boolean | no |

#### Responses

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

### Update a redirect rule for a route you own {#op-patch-api-v1-proxy-routes-route-id-redirect-rules-rule-id}

`PATCH /api/v1/proxy/routes/{route_id}/redirect-rules/{rule_id}`

Update a redirect rule for a route you own.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |
| `rule_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `source_pattern` | string or null | no |
| `match_type` | string or null | no |
| `target_url` | string or null | no |
| `status_code` | integer or null | no |
| `preserve_query` | boolean or null | no |
| `priority` | integer or null | no |
| `enabled` | boolean or null | no |

#### Responses

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

### Delete a redirect rule for a route you own {#op-delete-api-v1-proxy-routes-route-id-redirect-rules-rule-id}

`DELETE /api/v1/proxy/routes/{route_id}/redirect-rules/{rule_id}`

Delete a redirect rule for a route you own.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |
| `rule_id` | path | integer | yes |

#### Responses

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

### Request SSL certificate issuance for a proxy route you own {#op-post-api-v1-proxy-routes-route-id-ssl}

`POST /api/v1/proxy/routes/{route_id}/ssl`

Request SSL certificate issuance for a proxy route you own.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Responses

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

# Client API: Game Proxy

> Game join addresses on the platform's join domain: names, branding and custom domains.

Source: https://www.coritan.com/docs/api/reference/client/game-proxy/

Game join addresses on the platform's join domain: names, branding and custom domains.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/gameproxy/availability`](#op-post-api-v1-gameproxy-availability) | Claim check on the write primary so create/delete races cannot lie |
| POST | [`/api/v1/gameproxy/name-suggestions`](#op-post-api-v1-gameproxy-name-suggestions) | Name suggestions |
| GET | [`/api/v1/gameproxy/policy`](#op-get-api-v1-gameproxy-policy) | Storefront-facing effective policy (auto-provision + base domain) |
| GET | [`/api/v1/gameproxy/routes`](#op-get-api-v1-gameproxy-routes) | List my routes |
| POST | [`/api/v1/gameproxy/routes`](#op-post-api-v1-gameproxy-routes) | Order path preferred; this creates a route bound to an existing service for power users |
| PATCH | [`/api/v1/gameproxy/routes/{route_id}`](#op-patch-api-v1-gameproxy-routes-route-id) | Update my route branding |
| GET | [`/api/v1/gameproxy/routes/{route_id}/custom-domain`](#op-get-api-v1-gameproxy-routes-route-id-custom-domain) | Vanity CNAME state for this route's join address |
| POST | [`/api/v1/gameproxy/routes/{route_id}/custom-domain`](#op-post-api-v1-gameproxy-routes-route-id-custom-domain) | Link route custom domain |
| PATCH | [`/api/v1/gameproxy/routes/{route_id}/custom-domain`](#op-patch-api-v1-gameproxy-routes-route-id-custom-domain) | Show the vanity hostname, or the hosted one, in the public server list |
| DELETE | [`/api/v1/gameproxy/routes/{route_id}/custom-domain`](#op-delete-api-v1-gameproxy-routes-route-id-custom-domain) | Unlink route custom domain |
| POST | [`/api/v1/gameproxy/routes/{route_id}/custom-domain/verify`](#op-post-api-v1-gameproxy-routes-route-id-custom-domain-verify) | Check the CNAME now rather than waiting for the next maintenance pass |

### Claim check on the write primary so create/delete races cannot lie {#op-post-api-v1-gameproxy-availability}

`POST /api/v1/gameproxy/availability`

Claim check on the write primary so create/delete races cannot lie.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_id` | query | integer or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `subdomain` | string | yes |
| `base_domain` | string or null | no |

#### Responses

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

### Name suggestions {#op-post-api-v1-gameproxy-name-suggestions}

`POST /api/v1/gameproxy/name-suggestions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_id` | query | integer or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `count` | integer | no |
| `base_domain` | string or null | no |

#### Responses

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

### Storefront-facing effective policy (auto-provision + base domain) {#op-get-api-v1-gameproxy-policy}

`GET /api/v1/gameproxy/policy`

Storefront-facing effective policy (auto-provision + base domain).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_id` | query | integer or null | no |

#### Responses

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

### List my routes {#op-get-api-v1-gameproxy-routes}

`GET /api/v1/gameproxy/routes`

The user's game routes, each with ``custom_domain``: the answer
``GET /gameproxy/routes/{id}/custom-domain`` gives for it, read for the
whole list at once.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Order path preferred; this creates a route bound to an existing service for power users {#op-post-api-v1-gameproxy-routes}

`POST /api/v1/gameproxy/routes`

Order path preferred; this creates a route bound to an existing service for power users.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `subdomain` | string | yes |
| `base_domain` | string or null | no |
| `display_name` | string or null | no |
| `mode` | string | no |
| `upstream_service_id` | integer or null | no |
| `upstream_host` | string or null | no |
| `upstream_port` | integer or null | no |
| `location_id` | integer or null | no |
| `proxy_protocol` | boolean | no |
| `real_ip` | boolean or null | no |
| `description` | string or null | no |
| `org_id` | integer or null | no |
| `online_motd` | string or null | no |
| `offline_motd` | string or null | no |
| `favicon` | string or null | no |
| `version_name` | string or null | no |
| `status_cache_ttl_seconds` | integer or null | no |

#### Responses

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

### Update my route branding {#op-patch-api-v1-gameproxy-routes-route-id}

`PATCH /api/v1/gameproxy/routes/{route_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `online_motd` | string or null | no |
| `offline_motd` | string or null | no |
| `favicon` | string or null | no |
| `version_name` | string or null | no |
| `display_name` | string or null | no |
| `description` | string or null | no |
| `status_cache_ttl_seconds` | integer or null | no |
| `clear_favicon` | boolean | no |
| `clear_online_motd` | boolean | no |
| `clear_offline_motd` | boolean | no |

#### Responses

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

### Vanity CNAME state for this route's join address {#op-get-api-v1-gameproxy-routes-route-id-custom-domain}

`GET /api/v1/gameproxy/routes/{route_id}/custom-domain`

Vanity CNAME state for this route's join address.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Responses

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

### Link route custom domain {#op-post-api-v1-gameproxy-routes-route-id-custom-domain}

`POST /api/v1/gameproxy/routes/{route_id}/custom-domain`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `subdomain` | string | no |
| `include_in_list` | boolean | no |

#### Responses

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

### Show the vanity hostname, or the hosted one, in the public server list {#op-patch-api-v1-gameproxy-routes-route-id-custom-domain}

`PATCH /api/v1/gameproxy/routes/{route_id}/custom-domain`

Show the vanity hostname, or the hosted one, in the public server list.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `include_in_list` | boolean | yes |

#### Responses

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

### Unlink route custom domain {#op-delete-api-v1-gameproxy-routes-route-id-custom-domain}

`DELETE /api/v1/gameproxy/routes/{route_id}/custom-domain`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Responses

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

### Check the CNAME now rather than waiting for the next maintenance pass {#op-post-api-v1-gameproxy-routes-route-id-custom-domain-verify}

`POST /api/v1/gameproxy/routes/{route_id}/custom-domain/verify`

Check the CNAME now rather than waiting for the next maintenance pass.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `route_id` | path | integer | yes |

#### Responses

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

# Client API: External Servers

> Put a server you host yourself behind the game proxy: connection, tests and branding.

Source: https://www.coritan.com/docs/api/reference/client/external-servers/

Put a server you host yourself behind the game proxy: connection, tests and branding.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/external-servers`](#op-get-api-v1-client-external-servers) | List external servers |
| GET | [`/api/v1/client/external-servers/regions`](#op-get-api-v1-client-external-servers-regions) | Regions a new or existing external server can be served from |
| GET | [`/api/v1/client/external-servers/{service_id}`](#op-get-api-v1-client-external-servers-service-id) | Get external server |
| PATCH | [`/api/v1/client/external-servers/{service_id}`](#op-patch-api-v1-client-external-servers-service-id) | Change where players are forwarded, how, and through which region |
| GET | [`/api/v1/client/external-servers/{service_id}/custom-domain`](#op-get-api-v1-client-external-servers-service-id-custom-domain) | Get custom domain |
| POST | [`/api/v1/client/external-servers/{service_id}/custom-domain`](#op-post-api-v1-client-external-servers-service-id-custom-domain) | Link custom domain |
| PATCH | [`/api/v1/client/external-servers/{service_id}/custom-domain`](#op-patch-api-v1-client-external-servers-service-id-custom-domain) | Show the vanity hostname, or the hosted one, in the public server list |
| DELETE | [`/api/v1/client/external-servers/{service_id}/custom-domain`](#op-delete-api-v1-client-external-servers-service-id-custom-domain) | Unlink custom domain |
| POST | [`/api/v1/client/external-servers/{service_id}/custom-domain/verify`](#op-post-api-v1-client-external-servers-service-id-custom-domain-verify) | Check the CNAME now rather than waiting for the next maintenance pass |
| POST | [`/api/v1/client/external-servers/{service_id}/test`](#op-post-api-v1-client-external-servers-service-id-test) | Status-ping the backend now and record the answer |

### List external servers {#op-get-api-v1-client-external-servers}

`GET /api/v1/client/external-servers`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Regions a new or existing external server can be served from {#op-get-api-v1-client-external-servers-regions}

`GET /api/v1/client/external-servers/regions`

Regions a new or existing external server can be served from.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get external server {#op-get-api-v1-client-external-servers-service-id}

`GET /api/v1/client/external-servers/{service_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Change where players are forwarded, how, and through which region {#op-patch-api-v1-client-external-servers-service-id}

`PATCH /api/v1/client/external-servers/{service_id}`

Change where players are forwarded, how, and through which region.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `upstream_host` | string or null | no |
| `upstream_port` | integer or null | no |
| `proxy_protocol` | boolean or null | no |
| `real_ip` | boolean or null | no |
| `mode` | string or null | no |
| `bedrock_bridge` | boolean or null | no |
| `location_id` | integer or null | no |
| `display_name` | string or null | no |

#### Responses

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

### Get custom domain {#op-get-api-v1-client-external-servers-service-id-custom-domain}

`GET /api/v1/client/external-servers/{service_id}/custom-domain`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Link custom domain {#op-post-api-v1-client-external-servers-service-id-custom-domain}

`POST /api/v1/client/external-servers/{service_id}/custom-domain`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `subdomain` | string | no |
| `include_in_list` | boolean | no |

#### Responses

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

### Show the vanity hostname, or the hosted one, in the public server list {#op-patch-api-v1-client-external-servers-service-id-custom-domain}

`PATCH /api/v1/client/external-servers/{service_id}/custom-domain`

Show the vanity hostname, or the hosted one, in the public server list.
This is the same switch the org portal has, for platform-direct customers.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `include_in_list` | boolean | yes |

#### Responses

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

### Unlink custom domain {#op-delete-api-v1-client-external-servers-service-id-custom-domain}

`DELETE /api/v1/client/external-servers/{service_id}/custom-domain`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Check the CNAME now rather than waiting for the next maintenance pass {#op-post-api-v1-client-external-servers-service-id-custom-domain-verify}

`POST /api/v1/client/external-servers/{service_id}/custom-domain/verify`

Check the CNAME now rather than waiting for the next maintenance pass.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Status-ping the backend now and record the answer {#op-post-api-v1-client-external-servers-service-id-test}

`POST /api/v1/client/external-servers/{service_id}/test`

Status-ping the backend now and record the answer.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

# Client API: Platform Domains

> Names claimed under the platform's customer suffixes, such as example.coritan.gg.

Source: https://www.coritan.com/docs/api/reference/client/platform-domains/

Names claimed under the platform's customer suffixes, such as `example.coritan.gg`.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-domains`](#op-get-api-v1-client-platform-domains) | Overview |
| GET | [`/api/v1/client/platform-domains/availability`](#op-get-api-v1-client-platform-domains-availability) | Check availability |
| POST | [`/api/v1/client/platform-domains/claims`](#op-post-api-v1-client-platform-domains-claims) | Create claim |
| DELETE | [`/api/v1/client/platform-domains/claims/{claim_id}`](#op-delete-api-v1-client-platform-domains-claims-claim-id) | Delete claim |
| POST | [`/api/v1/client/platform-domains/claims/{claim_id}/certificate`](#op-post-api-v1-client-platform-domains-claims-claim-id-certificate) | (Re)queue the .<claim wildcard certificate |

### Overview {#op-get-api-v1-client-platform-domains}

`GET /api/v1/client/platform-domains`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Check availability {#op-get-api-v1-client-platform-domains-availability}

`GET /api/v1/client/platform-domains/availability`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `label` | query | string | yes |
| `suffix` | query | string or null | no |

#### Responses

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

### Create claim {#op-post-api-v1-client-platform-domains-claims}

`POST /api/v1/client/platform-domains/claims`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | yes |
| `suffix` | string or null | no |

#### Responses

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

### Delete claim {#op-delete-api-v1-client-platform-domains-claims-claim-id}

`DELETE /api/v1/client/platform-domains/claims/{claim_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `claim_id` | path | integer | yes |

#### Responses

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

### (Re)queue the .<claim wildcard certificate {#op-post-api-v1-client-platform-domains-claims-claim-id-certificate}

`POST /api/v1/client/platform-domains/claims/{claim_id}/certificate`

(Re)queue the ``*.<claim>`` wildcard certificate. Claims request it on
creation; this is for a claim made before the suffix was delegated, or
after a failed order.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `claim_id` | path | integer | yes |

#### Responses

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

# Client API: Container Apps

> Container Apps that run any image or template (MariaDB, Redis, nginx, and more).

Source: https://www.coritan.com/docs/api/reference/client/container-apps/

Container Apps that run any image or template (MariaDB, Redis, nginx, and more). Paths remain under `/api/v1/client/servers`.

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

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

## Pages in this area

| Page | Operations |
| --- | --- |
| [Servers](/docs/api/reference/client/container-apps/servers/) | 12 |
| [Allocations](/docs/api/reference/client/container-apps/servers-allocations/) | 7 |
| [Backups](/docs/api/reference/client/container-apps/servers-backups/) | 6 |
| [Databases](/docs/api/reference/client/container-apps/servers-databases/) | 6 |
| [Files](/docs/api/reference/client/container-apps/servers-files/) | 13 |
| [Import](/docs/api/reference/client/container-apps/servers-import/) | 5 |
| [Rules](/docs/api/reference/client/container-apps/servers-rules/) | 4 |
| [Schedules](/docs/api/reference/client/container-apps/servers-schedules/) | 11 |
| [Snapshots](/docs/api/reference/client/container-apps/servers-snapshots/) | 5 |
| [Software](/docs/api/reference/client/container-apps/servers-software/) | 35 |
| [Users](/docs/api/reference/client/container-apps/servers-users/) | 4 |
| [Snapshots](/docs/api/reference/client/container-apps/snapshots/) | 7 |
| [Timezones](/docs/api/reference/client/container-apps/timezones/) | 1 |

# Client API: Container Apps: Servers

> The 12 Client API operations for servers.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers`](#op-get-api-v1-client-servers) | List servers owned by or accessible to current user |
| GET | [`/api/v1/client/servers/live`](#op-get-api-v1-client-servers-live) | State and usage for the servers on the list, one request instead of one per server |
| GET | [`/api/v1/client/servers/{uuid}`](#op-get-api-v1-client-servers-uuid) | Get server details |
| POST | [`/api/v1/client/servers/{uuid}/command`](#op-post-api-v1-client-servers-uuid-command) | Execute a command on the server |
| POST | [`/api/v1/client/servers/{uuid}/power`](#op-post-api-v1-client-servers-uuid-power) | Execute power action (start, stop, restart, kill) |
| GET | [`/api/v1/client/servers/{uuid}/resources`](#op-get-api-v1-client-servers-uuid-resources) | Get server resource usage and limits |
| GET | [`/api/v1/client/servers/{uuid}/sftp`](#op-get-api-v1-client-servers-uuid-sftp) | Connection details for this server's SFTP login |
| GET | [`/api/v1/client/servers/{uuid}/sleep`](#op-get-api-v1-client-servers-uuid-sleep) | Sleep and start-queue state for a free server |
| GET | [`/api/v1/client/servers/{uuid}/status-ping`](#op-get-api-v1-client-servers-uuid-status-ping) | Ask the game itself who is online |
| GET | [`/api/v1/client/servers/{uuid}/updates`](#op-get-api-v1-client-servers-uuid-updates) | Get available updates for server software |
| POST | [`/api/v1/client/servers/{uuid}/wake`](#op-post-api-v1-client-servers-uuid-wake) | Ask for a sleeping free server to be started |
| GET | [`/api/v1/client/servers/{uuid}/websocket`](#op-get-api-v1-client-servers-uuid-websocket) | Get WebSocket token and endpoint for console access |

### List servers owned by or accessible to current user {#op-get-api-v1-client-servers}

`GET /api/v1/client/servers`

List servers owned by or accessible to current user.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tag` | query | string or null | no | Filter by resource tag |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string |
| `[].uuidShort` | string or null |
| `[].name` | string |
| `[].owner_id` | integer |
| `[].service_id` | integer or null |
| `[].template_uuid` | string or null |
| `[].template_name` | string or null |
| `[].template_slug` | string or null |
| `[].docker_image` | string or null |
| `[].startup_command` | string or null |
| `[].memory_mb` | integer |
| `[].boost_memory_mb` | integer or null |
| `[].disk_mb` | integer |
| `[].cpu_percent` | integer |
| `[].io_weight` | integer or null |
| `[].swap_mb` | integer or null |
| `[].allocation_limit` | integer or null |
| `[].database_limit` | integer or null |
| `[].backup_limit` | integer or null |
| `[].node_id` | integer or null |
| `[].node_name` | string or null |
| `[].node_fqdn` | string or null |
| `[].owner_email` | string or null |
| `[].location` | string or null |
| `[].location_id` | integer or null |
| `[].location_name` | string or null |
| `[].location_country_code` | string or null |
| `[].cpu_model` | string or null |
| `[].storage_type` | string or null |
| `[].network_speed` | string or null |
| `[].installed_os` | string or null |
| `[].allocation_id` | integer or null |
| `[].ip_address` | string or null |
| `[].port` | integer or null |
| `[].join_address` | string or null |
| `[].players_online` | integer or null |
| `[].usage` | object or null |
| `[].uptime_seconds` | integer or null |
| `[].variables` | object or null |
| `[].recipe_uuid` | string or null |
| `[].specialization_slug` | string or null |
| `[].specialization_name` | string or null |
| `[].status` | string |
| `[].last_error` | string or null |
| `[].last_error_at` | string (date-time) or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |
| `[].tags` | array of string |
| `[].sleep_policy` | string or null |
| `[].sleep` | object or null |
| `[].entitlements` | array of object or null |
| `[].install` | object or null |
| `[].power` | object or null |
| `[].lock` | object or null |
| `[].base_memory_mb` | integer or null |
| `[].memory_boost` | object or null |

### State and usage for the servers on the list, one request instead of one per server {#op-get-api-v1-client-servers-live}

`GET /api/v1/client/servers/live`

State and usage for the servers on the list, one request instead of one per server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuids` | query | string or null | no | Comma-separated server UUIDs; default is the newest |

#### Responses

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

### Get server details {#op-get-api-v1-client-servers-uuid}

`GET /api/v1/client/servers/{uuid}`

Get server details.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `uuidShort` | string or null |
| `name` | string |
| `owner_id` | integer |
| `service_id` | integer or null |
| `template_uuid` | string or null |
| `template_name` | string or null |
| `template_slug` | string or null |
| `docker_image` | string or null |
| `startup_command` | string or null |
| `memory_mb` | integer |
| `boost_memory_mb` | integer or null |
| `disk_mb` | integer |
| `cpu_percent` | integer |
| `io_weight` | integer or null |
| `swap_mb` | integer or null |
| `allocation_limit` | integer or null |
| `database_limit` | integer or null |
| `backup_limit` | integer or null |
| `node_id` | integer or null |
| `node_name` | string or null |
| `node_fqdn` | string or null |
| `owner_email` | string or null |
| `location` | string or null |
| `location_id` | integer or null |
| `location_name` | string or null |
| `location_country_code` | string or null |
| `cpu_model` | string or null |
| `storage_type` | string or null |
| `network_speed` | string or null |
| `installed_os` | string or null |
| `allocation_id` | integer or null |
| `ip_address` | string or null |
| `port` | integer or null |
| `join_address` | string or null |
| `players_online` | integer or null |
| `usage` | object or null |
| `uptime_seconds` | integer or null |
| `variables` | object or null |
| `recipe_uuid` | string or null |
| `specialization_slug` | string or null |
| `specialization_name` | string or null |
| `status` | string |
| `last_error` | string or null |
| `last_error_at` | string (date-time) or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `tags` | array of string |
| `sleep_policy` | string or null |
| `sleep` | object or null |
| `entitlements` | array of object or null |
| `install` | object or null |
| `power` | object or null |
| `lock` | object or null |
| `base_memory_mb` | integer or null |
| `memory_boost` | object or null |

### Execute a command on the server {#op-post-api-v1-client-servers-uuid-command}

`POST /api/v1/client/servers/{uuid}/command`

Execute a command on the server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `command` | query | string | yes |

#### Responses

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

### Execute power action (start, stop, restart, kill) {#op-post-api-v1-client-servers-uuid-power}

`POST /api/v1/client/servers/{uuid}/power`

Execute power action (start, stop, restart, kill).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `signal` | string | yes |

#### Responses

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

### Get server resource usage and limits {#op-get-api-v1-client-servers-uuid-resources}

`GET /api/v1/client/servers/{uuid}/resources`

Get server resource usage and limits.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Connection details for this server's SFTP login {#op-get-api-v1-client-servers-uuid-sftp}

`GET /api/v1/client/servers/{uuid}/sftp`

Connection details for this server's SFTP login.

Built here rather than in the browser: Wings validates the username's shape
before it calls the panel, so a client assembling its own can be rejected on
the node with nothing to show for it.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `host` | string |
| `port` | integer |
| `username` | string |

### Sleep and start-queue state for a free server {#op-get-api-v1-client-servers-uuid-sleep}

`GET /api/v1/client/servers/{uuid}/sleep`

Sleep and start-queue state for a free server.

``sleeps_at`` is absolute so a client counts down locally rather than polling
for a ticking number.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `sleep` | Sleep |
| `entitlements` | array of object |

### Ask the game itself who is online {#op-get-api-v1-client-servers-uuid-status-ping}

`GET /api/v1/client/servers/{uuid}/status-ping`

Ask the game itself who is online. Best-effort; never fails the request.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `reachable` | boolean |
| `players_online` | integer or null |
| `players_max` | integer or null |
| `sample` | array of string |
| `version` | string or null |
| `protocol` | integer or null |
| `motd` | string or null |
| `favicon` | string or null |
| `latency_ms` | integer or null |

### Get available updates for server software {#op-get-api-v1-client-servers-uuid-updates}

`GET /api/v1/client/servers/{uuid}/updates`

Get available updates for server software.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Ask for a sleeping free server to be started {#op-post-api-v1-client-servers-uuid-wake}

`POST /api/v1/client/servers/{uuid}/wake`

Ask for a sleeping free server to be started.

First in line with headroom starts in this request so the customer is not
left waiting on a worker poll. Otherwise the row stays queued and a tick
job releases it when the node has room.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `turnstile_token` | string or null | no |

#### Responses

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

### Get WebSocket token and endpoint for console access {#op-get-api-v1-client-servers-uuid-websocket}

`GET /api/v1/client/servers/{uuid}/websocket`

Get WebSocket token and endpoint for console access.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `token` | string |
| `socket` | string |

# Client API: Container Apps: Allocations

> The 7 Client API operations for allocations.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-allocations/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/allocations`](#op-get-api-v1-client-servers-uuid-allocations) | List primary + extra ports for this server |
| POST | [`/api/v1/client/servers/{uuid}/allocations`](#op-post-api-v1-client-servers-uuid-allocations) | Create server allocation |
| GET | [`/api/v1/client/servers/{uuid}/allocations/available-ports`](#op-get-api-v1-client-servers-uuid-allocations-available-ports) | Free ports on this server's node (node-wide, not shared across servers) |
| GET | [`/api/v1/client/servers/{uuid}/allocations/rules`](#op-get-api-v1-client-servers-uuid-allocations-rules) | Allocation rules |
| DELETE | [`/api/v1/client/servers/{uuid}/allocations/{allocation_id}`](#op-delete-api-v1-client-servers-uuid-allocations-allocation-id) | Release an extra port |
| POST | [`/api/v1/client/servers/{uuid}/allocations/{allocation_id}/primary`](#op-post-api-v1-client-servers-uuid-allocations-allocation-id-primary) | Mark an existing port as the primary allocation |
| POST | [`/api/v1/client/servers/{uuid}/allocations/{allocation_id}/publish-port`](#op-post-api-v1-client-servers-uuid-allocations-allocation-id-publish-port) | Set allocation publish port |

### List primary + extra ports for this server {#op-get-api-v1-client-servers-uuid-allocations}

`GET /api/v1/client/servers/{uuid}/allocations`

List primary + extra ports for this server. Requires allocation.read for subusers.

``publish_ip`` / ``effective_port`` / ``endpoint`` are where each port is
reachable once a floating IP is attached; ``ip`` / ``port`` stay the node
inventory.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].node_id` | integer |
| `[].ip` | string |
| `[].port` | integer |
| `[].publish_port` | integer or null |
| `[].publish_ip` | string or null |
| `[].effective_port` | integer or null |
| `[].endpoint` | string or null |
| `[].dedicated` | boolean |
| `[].server_id` | integer or null |
| `[].assigned` | boolean |
| `[].is_primary` | boolean or null |
| `[].notes` | string or null |
| `[].purpose` | string or null |
| `[].label` | string or null |
| `[].managed` | boolean |
| `[].created_at` | string (date-time) or null |

### Create server allocation {#op-post-api-v1-client-servers-uuid-allocations}

`POST /api/v1/client/servers/{uuid}/allocations`

Allocate an extra port: the lowest free port or a specific free port in
10000–40000 on the node, or, with ``on_dedicated_ip``, any free unprivileged
port on the server's own floating IP. The server's allocation_limit caps
the node range. Subusers need allocation.create.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `port` | integer or null | no |
| `notes` | string or null | no |
| `on_dedicated_ip` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `node_id` | integer |
| `ip` | string |
| `port` | integer |
| `publish_port` | integer or null |
| `publish_ip` | string or null |
| `effective_port` | integer or null |
| `endpoint` | string or null |
| `dedicated` | boolean |
| `server_id` | integer or null |
| `assigned` | boolean |
| `is_primary` | boolean or null |
| `notes` | string or null |
| `purpose` | string or null |
| `label` | string or null |
| `managed` | boolean |
| `created_at` | string (date-time) or null |

### Free ports on this server's node (node-wide, not shared across servers) {#op-get-api-v1-client-servers-uuid-allocations-available-ports}

`GET /api/v1/client/servers/{uuid}/allocations/available-ports`

Free ports on this server's node (node-wide, not shared across servers).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

### Allocation rules {#op-get-api-v1-client-servers-uuid-allocations-rules}

`GET /api/v1/client/servers/{uuid}/allocations/rules`

Limits and defaults around this server's ports: the node-range limit, the
rules for ports on its dedicated IP (when one is attached) and which default
port its players type. The list route stays a bare array for compatibility.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Release an extra port {#op-delete-api-v1-client-servers-uuid-allocations-allocation-id}

`DELETE /api/v1/client/servers/{uuid}/allocations/{allocation_id}`

Release an extra port. Cannot delete the primary allocation.
Subusers need allocation.delete.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |

#### Responses

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

### Mark an existing port as the primary allocation {#op-post-api-v1-client-servers-uuid-allocations-allocation-id-primary}

`POST /api/v1/client/servers/{uuid}/allocations/{allocation_id}/primary`

Mark an existing port as the primary allocation. Needs allocation.update.

The primary is what the process binds as ``SERVER_PORT`` and what the brand
hostname routes to, so Wings is re-synced, the route re-pointed and a running
server restarts onto it; the ``publish`` block says what happened.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |

#### Responses

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

### Set allocation publish port {#op-post-api-v1-client-servers-uuid-allocations-allocation-id-publish-port}

`POST /api/v1/client/servers/{uuid}/allocations/{allocation_id}/publish-port`

Publish a port on the game's default port (25565 / 19132) of the attached
floating IP, or clear it. Wings rebinds and a running server restarts, as on
attach; the ``publish`` block says what happened. Needs allocation.update.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `port` | integer or null | no |

#### Responses

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

# Client API: Container Apps: Backups

> The 6 Client API operations for backups.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-backups/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/backups`](#op-get-api-v1-client-servers-uuid-backups) | List backups for a server |
| POST | [`/api/v1/client/servers/{uuid}/backups`](#op-post-api-v1-client-servers-uuid-backups) | Create a new backup |
| DELETE | [`/api/v1/client/servers/{uuid}/backups/{backup_uuid}`](#op-delete-api-v1-client-servers-uuid-backups-backup-uuid) | Delete a backup |
| GET | [`/api/v1/client/servers/{uuid}/backups/{backup_uuid}/download`](#op-get-api-v1-client-servers-uuid-backups-backup-uuid-download) | A short-lived signed URL the browser fetches the archive from directly |
| POST | [`/api/v1/client/servers/{uuid}/backups/{backup_uuid}/lock`](#op-post-api-v1-client-servers-uuid-backups-backup-uuid-lock) | Keep a backup, or release it |
| POST | [`/api/v1/client/servers/{uuid}/backups/{backup_uuid}/restore`](#op-post-api-v1-client-servers-uuid-backups-backup-uuid-restore) | Restore from a backup |

### List backups for a server {#op-get-api-v1-client-servers-uuid-backups}

`GET /api/v1/client/servers/{uuid}/backups`

List backups for a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string |
| `[].server_id` | integer |
| `[].name` | string |
| `[].ignored_files` | array of string or null |
| `[].is_locked` | boolean |
| `[].size_bytes` | integer |
| `[].status` | string |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create a new backup {#op-post-api-v1-client-servers-uuid-backups}

`POST /api/v1/client/servers/{uuid}/backups`

Create a new backup.

Closed once snapshots are on. Kept as a route rather than removed so an
existing integration gets an explanation instead of a 404 that reads as a
bug in their own code.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `ignored_files` | array of string or null | no |
| `is_locked` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `ignored_files` | array of string or null |
| `is_locked` | boolean |
| `size_bytes` | integer |
| `status` | string |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete a backup {#op-delete-api-v1-client-servers-uuid-backups-backup-uuid}

`DELETE /api/v1/client/servers/{uuid}/backups/{backup_uuid}`

Delete a backup.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |

#### Responses

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

### A short-lived signed URL the browser fetches the archive from directly {#op-get-api-v1-client-servers-uuid-backups-backup-uuid-download}

`GET /api/v1/client/servers/{uuid}/backups/{backup_uuid}/download`

A short-lived signed URL the browser fetches the archive from directly.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |

#### Responses

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

### Keep a backup, or release it {#op-post-api-v1-client-servers-uuid-backups-backup-uuid-lock}

`POST /api/v1/client/servers/{uuid}/backups/{backup_uuid}/lock`

Keep a backup, or release it. A locked backup cannot be deleted.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |

#### Responses

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

### Restore from a backup {#op-post-api-v1-client-servers-uuid-backups-backup-uuid-restore}

`POST /api/v1/client/servers/{uuid}/backups/{backup_uuid}/restore`

Restore from a backup.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |

#### Responses

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

# Client API: Container Apps: Databases

> The 6 Client API operations for databases.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-databases/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/databases`](#op-get-api-v1-client-servers-uuid-databases) | List databases for a server |
| POST | [`/api/v1/client/servers/{uuid}/databases`](#op-post-api-v1-client-servers-uuid-databases) | Create a new database |
| DELETE | [`/api/v1/client/servers/{uuid}/databases/{db_id}`](#op-delete-api-v1-client-servers-uuid-databases-db-id) | Delete a database |
| GET | [`/api/v1/client/servers/{uuid}/databases/{db_id}/credentials`](#op-get-api-v1-client-servers-uuid-databases-db-id-credentials) | Reveal the stored password for a database on this server |
| POST | [`/api/v1/client/servers/{uuid}/databases/{db_id}/retry`](#op-post-api-v1-client-servers-uuid-databases-db-id-retry) | Retry a failed or stuck database operation |
| POST | [`/api/v1/client/servers/{uuid}/databases/{db_id}/rotate-password`](#op-post-api-v1-client-servers-uuid-databases-db-id-rotate-password) | Rotate database password |

### List databases for a server {#op-get-api-v1-client-servers-uuid-databases}

`GET /api/v1/client/servers/{uuid}/databases`

List databases for a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string or null |
| `[].server_id` | integer or null |
| `[].database_host_id` | integer |
| `[].name` | string |
| `[].username` | string |
| `[].password` | string or null |
| `[].remote` | string or null |
| `[].remote_connect_string` | string or null |
| `[].max_connections` | integer |
| `[].host` | string or null |
| `[].port` | integer or null |
| `[].host_name` | string or null |
| `[].uri` | string or null |
| `[].jdbc` | string or null |
| `[].status` | string |
| `[].status_message` | string or null |
| `[].last_error` | string or null |
| `[].operation` | string or null |
| `[].busy` | boolean |
| `[].colocated` | boolean or null |
| `[].db_name` | string or null |
| `[].created_at` | string (date-time) or null |
| `[].updated_at` | string (date-time) or null |

### Create a new database {#op-post-api-v1-client-servers-uuid-databases}

`POST /api/v1/client/servers/{uuid}/databases`

Create a new database.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `database_host_id` | integer or null | no |
| `name_suffix` | string | no |
| `remote` | string | no |
| `idempotency_key` | string or null | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string or null |
| `server_id` | integer or null |
| `database_host_id` | integer |
| `name` | string |
| `username` | string |
| `password` | string or null |
| `remote` | string or null |
| `remote_connect_string` | string or null |
| `max_connections` | integer |
| `host` | string or null |
| `port` | integer or null |
| `host_name` | string or null |
| `uri` | string or null |
| `jdbc` | string or null |
| `status` | string |
| `status_message` | string or null |
| `last_error` | string or null |
| `operation` | string or null |
| `busy` | boolean |
| `colocated` | boolean or null |
| `db_name` | string or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |

### Delete a database {#op-delete-api-v1-client-servers-uuid-databases-db-id}

`DELETE /api/v1/client/servers/{uuid}/databases/{db_id}`

Delete a database.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `db_id` | path | integer | yes |

#### Responses

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

### Reveal the stored password for a database on this server {#op-get-api-v1-client-servers-uuid-databases-db-id-credentials}

`GET /api/v1/client/servers/{uuid}/databases/{db_id}/credentials`

Reveal the stored password for a database on this server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `db_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string or null |
| `server_id` | integer or null |
| `database_host_id` | integer |
| `name` | string |
| `username` | string |
| `password` | string or null |
| `remote` | string or null |
| `remote_connect_string` | string or null |
| `max_connections` | integer |
| `host` | string or null |
| `port` | integer or null |
| `host_name` | string or null |
| `uri` | string or null |
| `jdbc` | string or null |
| `status` | string |
| `status_message` | string or null |
| `last_error` | string or null |
| `operation` | string or null |
| `busy` | boolean |
| `colocated` | boolean or null |
| `db_name` | string or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |

### Retry a failed or stuck database operation {#op-post-api-v1-client-servers-uuid-databases-db-id-retry}

`POST /api/v1/client/servers/{uuid}/databases/{db_id}/retry`

Retry a failed or stuck database operation.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `db_id` | path | integer | yes |

#### Responses

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

### Rotate database password {#op-post-api-v1-client-servers-uuid-databases-db-id-rotate-password}

`POST /api/v1/client/servers/{uuid}/databases/{db_id}/rotate-password`

Rotate database password.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `db_id` | path | integer | yes |

#### Responses

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

# Client API: Container Apps: Files

> The 13 Client API operations for files.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-files/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/client/servers/{uuid}/files/chmod`](#op-post-api-v1-client-servers-uuid-files-chmod) | Set the mode of files under root: [{"file": name, "mode": "0644"}] |
| POST | [`/api/v1/client/servers/{uuid}/files/compress`](#op-post-api-v1-client-servers-uuid-files-compress) | Create a compressed archive of files |
| GET | [`/api/v1/client/servers/{uuid}/files/contents`](#op-get-api-v1-client-servers-uuid-files-contents) | Get contents of a file |
| POST | [`/api/v1/client/servers/{uuid}/files/copy`](#op-post-api-v1-client-servers-uuid-files-copy) | Duplicate a file next to itself; Wings picks the name copy suffix |
| POST | [`/api/v1/client/servers/{uuid}/files/decompress`](#op-post-api-v1-client-servers-uuid-files-decompress) | Extract an archive on the server |
| POST | [`/api/v1/client/servers/{uuid}/files/delete`](#op-post-api-v1-client-servers-uuid-files-delete) | Delete a file |
| GET | [`/api/v1/client/servers/{uuid}/files/download`](#op-get-api-v1-client-servers-uuid-files-download) | Stream one file from Wings through the platform, as an attachment |
| GET | [`/api/v1/client/servers/{uuid}/files/list`](#op-get-api-v1-client-servers-uuid-files-list) | List files in a server directory |
| POST | [`/api/v1/client/servers/{uuid}/files/mkdir`](#op-post-api-v1-client-servers-uuid-files-mkdir) | Create a folder name under root |
| POST | [`/api/v1/client/servers/{uuid}/files/pull`](#op-post-api-v1-client-servers-uuid-files-pull) | Download and save a file from a URL |
| POST | [`/api/v1/client/servers/{uuid}/files/rename`](#op-post-api-v1-client-servers-uuid-files-rename) | Rename a file |
| POST | [`/api/v1/client/servers/{uuid}/files/upload`](#op-post-api-v1-client-servers-uuid-files-upload) | Multipart upload proxied to Wings, so the browser never talks to the node |
| POST | [`/api/v1/client/servers/{uuid}/files/write`](#op-post-api-v1-client-servers-uuid-files-write) | Write content to a file |

### Set the mode of files under root: [{"file": name, "mode": "0644"}] {#op-post-api-v1-client-servers-uuid-files-chmod}

`POST /api/v1/client/servers/{uuid}/files/chmod`

Set the mode of files under ``root``: ``[{"file": name, "mode": "0644"}]``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of object | yes |

#### Responses

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

### Create a compressed archive of files {#op-post-api-v1-client-servers-uuid-files-compress}

`POST /api/v1/client/servers/{uuid}/files/compress`

Create a compressed archive of files.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `paths` | array of string | yes |
| `archive_name` | string | yes |

#### Responses

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

### Get contents of a file {#op-get-api-v1-client-servers-uuid-files-contents}

`GET /api/v1/client/servers/{uuid}/files/contents`

Get contents of a file.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `path` | query | string | yes |

#### Responses

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

### Duplicate a file next to itself; Wings picks the name copy suffix {#op-post-api-v1-client-servers-uuid-files-copy}

`POST /api/v1/client/servers/{uuid}/files/copy`

Duplicate a file next to itself; Wings picks the ``name copy`` suffix.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `location` | string | yes |

#### Responses

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

### Extract an archive on the server {#op-post-api-v1-client-servers-uuid-files-decompress}

`POST /api/v1/client/servers/{uuid}/files/decompress`

Extract an archive on the server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `archive_path` | string | yes |
| `destination` | string | yes |

#### Responses

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

### Delete a file {#op-post-api-v1-client-servers-uuid-files-delete}

`POST /api/v1/client/servers/{uuid}/files/delete`

Delete a file.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `path` | string | yes |

#### Responses

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

### Stream one file from Wings through the platform, as an attachment {#op-get-api-v1-client-servers-uuid-files-download}

`GET /api/v1/client/servers/{uuid}/files/download`

Stream one file from Wings through the platform, as an attachment.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `path` | query | string | yes |

#### Responses

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

### List files in a server directory {#op-get-api-v1-client-servers-uuid-files-list}

`GET /api/v1/client/servers/{uuid}/files/list`

List files in a server directory.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `directory` | query | string | no | Default: `/`. |

#### Responses

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

### Create a folder name under root {#op-post-api-v1-client-servers-uuid-files-mkdir}

`POST /api/v1/client/servers/{uuid}/files/mkdir`

Create a folder ``name`` under ``root``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `name` | string | yes |

#### Responses

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

### Download and save a file from a URL {#op-post-api-v1-client-servers-uuid-files-pull}

`POST /api/v1/client/servers/{uuid}/files/pull`

Download and save a file from a URL.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `destination_path` | string | yes |
| `filename` | string or null | no |

#### Responses

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

### Rename a file {#op-post-api-v1-client-servers-uuid-files-rename}

`POST /api/v1/client/servers/{uuid}/files/rename`

Rename a file.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `old_path` | string | yes |
| `new_path` | string | yes |

#### Responses

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

### Multipart upload proxied to Wings, so the browser never talks to the node {#op-post-api-v1-client-servers-uuid-files-upload}

`POST /api/v1/client/servers/{uuid}/files/upload`

Multipart upload proxied to Wings, so the browser never talks to the node.

A batch is written file by file; when a later file fails after earlier
ones landed, the response names both lists rather than failing the whole
request, so a retry does not have to guess what is already on disk.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `directory` | query | string | no | Default: `/`. |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `files` | array of string (binary) | yes |

#### Responses

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

### Write content to a file {#op-post-api-v1-client-servers-uuid-files-write}

`POST /api/v1/client/servers/{uuid}/files/write`

Write content to a file.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `path` | string | yes |
| `content` | string | no |
| `expected_hash` | string or null | no |

#### Responses

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

# Client API: Container Apps: Import

> The 5 Client API operations for import.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-import/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/import/current`](#op-get-api-v1-client-servers-uuid-import-current) | Active import, or a recently finished one, so a refresh can resume the UI |
| POST | [`/api/v1/client/servers/{uuid}/import/start`](#op-post-api-v1-client-servers-uuid-import-start) | Queue a remote tree copy onto this server |
| GET | [`/api/v1/client/servers/{uuid}/import/status/{import_id}`](#op-get-api-v1-client-servers-uuid-import-status-import-id) | Poll an import the caller started |
| POST | [`/api/v1/client/servers/{uuid}/import/test-connection`](#op-post-api-v1-client-servers-uuid-import-test-connection) | Probe a remote SFTP/FTP host and count files without writing anything |
| DELETE | [`/api/v1/client/servers/{uuid}/import/{import_id}`](#op-delete-api-v1-client-servers-uuid-import-import-id) | Stop a pending or in-progress import |

### Active import, or a recently finished one, so a refresh can resume the UI {#op-get-api-v1-client-servers-uuid-import-current}

`GET /api/v1/client/servers/{uuid}/import/current`

Active import, or a recently finished one, so a refresh can resume the UI.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Queue a remote tree copy onto this server {#op-post-api-v1-client-servers-uuid-import-start}

`POST /api/v1/client/servers/{uuid}/import/start`

Queue a remote tree copy onto this server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `type` | string | yes |
| `remote_host` | string | yes |
| `remote_port` | integer or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `base_path` | string | no |
| `truncate` | boolean | no |

#### Responses

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

### Poll an import the caller started {#op-get-api-v1-client-servers-uuid-import-status-import-id}

`GET /api/v1/client/servers/{uuid}/import/status/{import_id}`

Poll an import the caller started. Replica first; a miss re-asks the primary.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `import_id` | path | string | yes |

#### Responses

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

### Probe a remote SFTP/FTP host and count files without writing anything {#op-post-api-v1-client-servers-uuid-import-test-connection}

`POST /api/v1/client/servers/{uuid}/import/test-connection`

Probe a remote SFTP/FTP host and count files without writing anything.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `type` | string | yes |
| `remote_host` | string | yes |
| `remote_port` | integer or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `base_path` | string | no |
| `truncate` | boolean | no |

#### Responses

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

### Stop a pending or in-progress import {#op-delete-api-v1-client-servers-uuid-import-import-id}

`DELETE /api/v1/client/servers/{uuid}/import/{import_id}`

Stop a pending or in-progress import.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `import_id` | path | string | yes |

#### Responses

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

# Client API: Container Apps: Rules

> The 4 Client API operations for rules.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-rules/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/rules`](#op-get-api-v1-client-servers-uuid-rules) | List rules for a server |
| POST | [`/api/v1/client/servers/{uuid}/rules`](#op-post-api-v1-client-servers-uuid-rules) | Create a new rule |
| PUT | [`/api/v1/client/servers/{uuid}/rules/{rule_uuid}`](#op-put-api-v1-client-servers-uuid-rules-rule-uuid) | Update a rule |
| DELETE | [`/api/v1/client/servers/{uuid}/rules/{rule_uuid}`](#op-delete-api-v1-client-servers-uuid-rules-rule-uuid) | Delete a rule |

### List rules for a server {#op-get-api-v1-client-servers-uuid-rules}

`GET /api/v1/client/servers/{uuid}/rules`

List rules for a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string |
| `[].server_id` | integer |
| `[].name` | string |
| `[].trigger_type` | string |
| `[].trigger_config` | Trigger Config |
| `[].conditions` | array of any or object or null |
| `[].actions` | array of any or object |
| `[].enabled` | boolean |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) or null |
| `[].last_triggered_at` | string (date-time) or null |

### Create a new rule {#op-post-api-v1-client-servers-uuid-rules}

`POST /api/v1/client/servers/{uuid}/rules`

Create a new rule.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `trigger_type` | string | yes |
| `trigger_config` | Trigger Config | no |
| `conditions` | array of any or object or null | no |
| `actions` | array of any or object | yes |
| `enabled` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `trigger_type` | string |
| `trigger_config` | Trigger Config |
| `conditions` | array of any or object or null |
| `actions` | array of any or object |
| `enabled` | boolean |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `last_triggered_at` | string (date-time) or null |

### Update a rule {#op-put-api-v1-client-servers-uuid-rules-rule-uuid}

`PUT /api/v1/client/servers/{uuid}/rules/{rule_uuid}`

Update a rule.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `rule_uuid` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `trigger_type` | string or null | no |
| `trigger_config` | object or null | no |
| `conditions` | array of any or object or null | no |
| `actions` | array of any or object or null | no |
| `enabled` | boolean or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `trigger_type` | string |
| `trigger_config` | Trigger Config |
| `conditions` | array of any or object or null |
| `actions` | array of any or object |
| `enabled` | boolean |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `last_triggered_at` | string (date-time) or null |

### Delete a rule {#op-delete-api-v1-client-servers-uuid-rules-rule-uuid}

`DELETE /api/v1/client/servers/{uuid}/rules/{rule_uuid}`

Delete a rule.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `rule_uuid` | path | string | yes |

#### Responses

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

# Client API: Container Apps: Schedules

> The 11 Client API operations for schedules.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-schedules/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/schedules`](#op-get-api-v1-client-servers-uuid-schedules) | List schedules for a server |
| POST | [`/api/v1/client/servers/{uuid}/schedules`](#op-post-api-v1-client-servers-uuid-schedules) | Create a new schedule, optionally with its whole task pipeline |
| GET | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}`](#op-get-api-v1-client-servers-uuid-schedules-schedule-uuid) | Get a schedule |
| PUT | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}`](#op-put-api-v1-client-servers-uuid-schedules-schedule-uuid) | Update a schedule |
| DELETE | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}`](#op-delete-api-v1-client-servers-uuid-schedules-schedule-uuid) | Delete a schedule |
| POST | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/execute`](#op-post-api-v1-client-servers-uuid-schedules-schedule-uuid-execute) | Queue a schedule to run now, without changing its next scheduled run |
| GET | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/runs`](#op-get-api-v1-client-servers-uuid-schedules-schedule-uuid-runs) | Recent runs of a schedule, newest first, with the outcome of every step |
| POST | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/tasks`](#op-post-api-v1-client-servers-uuid-schedules-schedule-uuid-tasks) | Append a task to a schedule's pipeline |
| POST | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/tasks/reorder`](#op-post-api-v1-client-servers-uuid-schedules-schedule-uuid-tasks-reorder) | Set the order tasks run in |
| PUT | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/tasks/{task_id}`](#op-put-api-v1-client-servers-uuid-schedules-schedule-uuid-tasks-task-id) | Edit a task in place |
| DELETE | [`/api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/tasks/{task_id}`](#op-delete-api-v1-client-servers-uuid-schedules-schedule-uuid-tasks-task-id) | Remove a task from a schedule |

### List schedules for a server {#op-get-api-v1-client-servers-uuid-schedules}

`GET /api/v1/client/servers/{uuid}/schedules`

List schedules for a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string |
| `[].server_id` | integer |
| `[].name` | string |
| `[].cron_minute` | string |
| `[].cron_hour` | string |
| `[].cron_day_of_month` | string |
| `[].cron_month` | string |
| `[].cron_day_of_week` | string |
| `[].is_active` | boolean |
| `[].only_when_online` | boolean |
| `[].is_processing` | boolean |
| `[].timezone` | string |
| `[].catch_up` | boolean |
| `[].revision` | integer |
| `[].current_run_id` | string or null |
| `[].last_run_status` | string or null |
| `[].next_run_at` | string (date-time) or null |
| `[].last_run_at` | string (date-time) or null |
| `[].last_run_failed` | boolean |
| `[].last_failure_message` | string or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) or null |
| `[].tasks` | array of TaskResponse |
| `[].tasks[].id` | integer |
| `[].tasks[].sequence_id` | integer |
| `[].tasks[].action` | string |
| `[].tasks[].payload` | Payload |
| `[].tasks[].time_offset` | integer |
| `[].tasks[].continue_on_failure` | boolean |
| `[].tasks[].is_queued` | boolean |

### Create a new schedule, optionally with its whole task pipeline {#op-post-api-v1-client-servers-uuid-schedules}

`POST /api/v1/client/servers/{uuid}/schedules`

Create a new schedule, optionally with its whole task pipeline.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `cron_minute` | string | yes |
| `cron_hour` | string | yes |
| `cron_day_of_month` | string | yes |
| `cron_month` | string | yes |
| `cron_day_of_week` | string | yes |
| `is_active` | boolean | no |
| `only_when_online` | boolean | no |
| `timezone` | string | no |
| `catch_up` | boolean | no |
| `tasks` | array of TaskCreate or null | no |
| `tasks[].action` | string | yes |
| `tasks[].payload` | object or null | no |
| `tasks[].time_offset` | integer | no |
| `tasks[].sequence_id` | integer or null | no |
| `tasks[].continue_on_failure` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `cron_minute` | string |
| `cron_hour` | string |
| `cron_day_of_month` | string |
| `cron_month` | string |
| `cron_day_of_week` | string |
| `is_active` | boolean |
| `only_when_online` | boolean |
| `is_processing` | boolean |
| `timezone` | string |
| `catch_up` | boolean |
| `revision` | integer |
| `current_run_id` | string or null |
| `last_run_status` | string or null |
| `next_run_at` | string (date-time) or null |
| `last_run_at` | string (date-time) or null |
| `last_run_failed` | boolean |
| `last_failure_message` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `tasks` | array of TaskResponse |
| `tasks[].id` | integer |
| `tasks[].sequence_id` | integer |
| `tasks[].action` | string |
| `tasks[].payload` | Payload |
| `tasks[].time_offset` | integer |
| `tasks[].continue_on_failure` | boolean |
| `tasks[].is_queued` | boolean |

### Get a schedule {#op-get-api-v1-client-servers-uuid-schedules-schedule-uuid}

`GET /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}`

Get a schedule.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `cron_minute` | string |
| `cron_hour` | string |
| `cron_day_of_month` | string |
| `cron_month` | string |
| `cron_day_of_week` | string |
| `is_active` | boolean |
| `only_when_online` | boolean |
| `is_processing` | boolean |
| `timezone` | string |
| `catch_up` | boolean |
| `revision` | integer |
| `current_run_id` | string or null |
| `last_run_status` | string or null |
| `next_run_at` | string (date-time) or null |
| `last_run_at` | string (date-time) or null |
| `last_run_failed` | boolean |
| `last_failure_message` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `tasks` | array of TaskResponse |
| `tasks[].id` | integer |
| `tasks[].sequence_id` | integer |
| `tasks[].action` | string |
| `tasks[].payload` | Payload |
| `tasks[].time_offset` | integer |
| `tasks[].continue_on_failure` | boolean |
| `tasks[].is_queued` | boolean |

### Update a schedule {#op-put-api-v1-client-servers-uuid-schedules-schedule-uuid}

`PUT /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}`

Update a schedule.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `cron_minute` | string or null | no |
| `cron_hour` | string or null | no |
| `cron_day_of_month` | string or null | no |
| `cron_month` | string or null | no |
| `cron_day_of_week` | string or null | no |
| `is_active` | boolean or null | no |
| `only_when_online` | boolean or null | no |
| `timezone` | string or null | no |
| `catch_up` | boolean or null | no |
| `revision` | integer or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `cron_minute` | string |
| `cron_hour` | string |
| `cron_day_of_month` | string |
| `cron_month` | string |
| `cron_day_of_week` | string |
| `is_active` | boolean |
| `only_when_online` | boolean |
| `is_processing` | boolean |
| `timezone` | string |
| `catch_up` | boolean |
| `revision` | integer |
| `current_run_id` | string or null |
| `last_run_status` | string or null |
| `next_run_at` | string (date-time) or null |
| `last_run_at` | string (date-time) or null |
| `last_run_failed` | boolean |
| `last_failure_message` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `tasks` | array of TaskResponse |
| `tasks[].id` | integer |
| `tasks[].sequence_id` | integer |
| `tasks[].action` | string |
| `tasks[].payload` | Payload |
| `tasks[].time_offset` | integer |
| `tasks[].continue_on_failure` | boolean |
| `tasks[].is_queued` | boolean |

### Delete a schedule {#op-delete-api-v1-client-servers-uuid-schedules-schedule-uuid}

`DELETE /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}`

Delete a schedule.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |

#### Responses

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

### Queue a schedule to run now, without changing its next scheduled run {#op-post-api-v1-client-servers-uuid-schedules-schedule-uuid-execute}

`POST /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/execute`

Queue a schedule to run now, without changing its next scheduled run.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `revision` | integer or null | no |

#### Responses

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

### Recent runs of a schedule, newest first, with the outcome of every step {#op-get-api-v1-client-servers-uuid-schedules-schedule-uuid-runs}

`GET /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/runs`

Recent runs of a schedule, newest first, with the outcome of every step.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `schedule_uuid` | path | string | yes |  |
| `limit` | query | integer | no | Default: `20`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].uuid` | string |
| `[].trigger` | string |
| `[].status` | string |
| `[].started_at` | string (date-time) or null |
| `[].finished_at` | string (date-time) or null |
| `[].failure_message` | string or null |
| `[].created_at` | string (date-time) or null |
| `[].steps` | array of ScheduleRunStepResponse |
| `[].steps[].task_id` | integer |
| `[].steps[].sequence_id` | integer |
| `[].steps[].action` | string |
| `[].steps[].payload` | Payload |
| `[].steps[].time_offset` | integer |
| `[].steps[].continue_on_failure` | boolean |
| `[].steps[].status` | string |
| `[].steps[].started_at` | string (date-time) or null |
| `[].steps[].finished_at` | string (date-time) or null |
| `[].steps[].error` | string or null |

### Append a task to a schedule's pipeline {#op-post-api-v1-client-servers-uuid-schedules-schedule-uuid-tasks}

`POST /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/tasks`

Append a task to a schedule's pipeline.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `action` | string | yes |
| `payload` | object or null | no |
| `time_offset` | integer | no |
| `sequence_id` | integer or null | no |
| `continue_on_failure` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `sequence_id` | integer |
| `action` | string |
| `payload` | Payload |
| `time_offset` | integer |
| `continue_on_failure` | boolean |
| `is_queued` | boolean |

### Set the order tasks run in {#op-post-api-v1-client-servers-uuid-schedules-schedule-uuid-tasks-reorder}

`POST /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/tasks/reorder`

Set the order tasks run in.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `task_ids` | array of integer | yes |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].sequence_id` | integer |
| `[].action` | string |
| `[].payload` | Payload |
| `[].time_offset` | integer |
| `[].continue_on_failure` | boolean |
| `[].is_queued` | boolean |

### Edit a task in place {#op-put-api-v1-client-servers-uuid-schedules-schedule-uuid-tasks-task-id}

`PUT /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/tasks/{task_id}`

Edit a task in place.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `task_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `action` | string or null | no |
| `payload` | object or null | no |
| `time_offset` | integer or null | no |
| `sequence_id` | integer or null | no |
| `continue_on_failure` | boolean or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `sequence_id` | integer |
| `action` | string |
| `payload` | Payload |
| `time_offset` | integer |
| `continue_on_failure` | boolean |
| `is_queued` | boolean |

### Remove a task from a schedule {#op-delete-api-v1-client-servers-uuid-schedules-schedule-uuid-tasks-task-id}

`DELETE /api/v1/client/servers/{uuid}/schedules/{schedule_uuid}/tasks/{task_id}`

Remove a task from a schedule.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `task_id` | path | integer | yes |

#### Responses

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

# Client API: Container Apps: Snapshots

> The 5 Client API operations for snapshots.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-snapshots/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/snapshots`](#op-get-api-v1-client-servers-uuid-snapshots) | List snapshots |
| POST | [`/api/v1/client/servers/{uuid}/snapshots`](#op-post-api-v1-client-servers-uuid-snapshots) | Take a snapshot of this server |
| GET | [`/api/v1/client/servers/{uuid}/snapshots/estimate`](#op-get-api-v1-client-servers-uuid-snapshots-estimate) | How much of the allowance a snapshot of this server would use |
| GET | [`/api/v1/client/servers/{uuid}/snapshots/seed`](#op-get-api-v1-client-servers-uuid-snapshots-seed) | The restore a server ordered from a snapshot is waiting on, or got |
| POST | [`/api/v1/client/servers/{uuid}/snapshots/seed/retry`](#op-post-api-v1-client-servers-uuid-snapshots-seed-retry) | Run a failed seed again |

### List snapshots {#op-get-api-v1-client-servers-uuid-snapshots}

`GET /api/v1/client/servers/{uuid}/snapshots`

Snapshots taken from this server or, with ``scope=account``, every
snapshot the account holds, each judged for restoring onto *this* server.

The account scope is what lets a customer standing on their new Ashburn
server see the snapshot they took in Frankfurt, without leaving the panel.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `scope` | query | string | no | Default: `this`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string |
| `[].name` | string |
| `[].kind` | string |
| `[].status` | string |
| `[].size_bytes` | integer |
| `[].is_locked` | boolean |
| `[].created_by` | string |
| `[].reason` | string or null |
| `[].region` | string or null |
| `[].checksum` | string or null |
| `[].checksum_type` | string or null |
| `[].error` | string or null |
| `[].hold_reason` | string or null |
| `[].source_id` | integer or null |
| `[].source_uuid` | string or null |
| `[].source_server_name` | string or null |
| `[].source_name` | string or null |
| `[].source_location` | string or null |
| `[].source_used_bytes` | integer or null |
| `[].source_deleted` | boolean |
| `[].egg_id` | integer or null |
| `[].software` | SnapshotSoftware or null |
| `[].software.slug` | string or null |
| `[].software.name` | string or null |
| `[].software.mcjars_type` | string or null |
| `[].software.loader` | string or null |
| `[].software.loader_family` | string or null |
| `[].software.game` | string or null |
| `[].software.edition` | string or null |
| `[].software.version` | string or null |
| `[].software.runtime_template_slug` | string or null |
| `[].software.docker_image` | string or null |
| `[].software.modpack` | object or null |
| `[].software.memory_mb` | integer or null |
| `[].software.disk_mb` | integer or null |
| `[].software.inferred` | boolean |
| `[].software_label` | string |
| `[].software_slug` | string or null |
| `[].software_version` | string or null |
| `[].compatibility` | SnapshotCompatibility or null |
| `[].compatibility.level` | string |
| `[].compatibility.reason` | string |
| `[].is_source` | boolean or null |
| `[].schedule_uuid` | string or null |
| `[].schedule_name` | string or null |
| `[].created_at` | string (date-time) |
| `[].completed_at` | string (date-time) or null |

### Take a snapshot of this server {#op-post-api-v1-client-servers-uuid-snapshots}

`POST /api/v1/client/servers/{uuid}/snapshots`

Take a snapshot of this server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `ignored_files` | array of string or null | no |
| `is_locked` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `name` | string |
| `kind` | string |
| `status` | string |
| `size_bytes` | integer |
| `is_locked` | boolean |
| `created_by` | string |
| `reason` | string or null |
| `region` | string or null |
| `checksum` | string or null |
| `checksum_type` | string or null |
| `error` | string or null |
| `hold_reason` | string or null |
| `source_id` | integer or null |
| `source_uuid` | string or null |
| `source_server_name` | string or null |
| `source_name` | string or null |
| `source_location` | string or null |
| `source_used_bytes` | integer or null |
| `source_deleted` | boolean |
| `egg_id` | integer or null |
| `software` | SnapshotSoftware or null |
| `software.slug` | string or null |
| `software.name` | string or null |
| `software.mcjars_type` | string or null |
| `software.loader` | string or null |
| `software.loader_family` | string or null |
| `software.game` | string or null |
| `software.edition` | string or null |
| `software.version` | string or null |
| `software.runtime_template_slug` | string or null |
| `software.docker_image` | string or null |
| `software.modpack` | object or null |
| `software.memory_mb` | integer or null |
| `software.disk_mb` | integer or null |
| `software.inferred` | boolean |
| `software_label` | string |
| `software_slug` | string or null |
| `software_version` | string or null |
| `compatibility` | SnapshotCompatibility or null |
| `compatibility.level` | string |
| `compatibility.reason` | string |
| `is_source` | boolean or null |
| `schedule_uuid` | string or null |
| `schedule_name` | string or null |
| `created_at` | string (date-time) |
| `completed_at` | string (date-time) or null |

### How much of the allowance a snapshot of this server would use {#op-get-api-v1-client-servers-uuid-snapshots-estimate}

`GET /api/v1/client/servers/{uuid}/snapshots/estimate`

How much of the allowance a snapshot of this server would use.

Its own endpoint rather than a field on the listing: the figure is read
live from Wings, so folding it in would make the snapshots tab as slow as
the slowest node on the fleet, on every load, to answer a question only
the create dialog asks.

An over-estimate on purpose: the server's current *uncompressed* disk
usage. An archive is never larger than what it archives, so a creation
that fits on this number cannot push the account over, which is the
property the retention policy depends on.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### The restore a server ordered from a snapshot is waiting on, or got {#op-get-api-v1-client-servers-uuid-snapshots-seed}

`GET /api/v1/client/servers/{uuid}/snapshots/seed`

The restore a server ordered from a snapshot is waiting on, or got.

Null for a server ordered the ordinary way. The panel shows "restoring
your snapshot" while it is pending or running, and the reason with a retry
when it failed.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `uuid` | string |
| `snapshot_uuid` | string |
| `snapshot_name` | string or null |
| `snapshot_software_label` | string |
| `snapshot_size_bytes` | integer or null |
| `status` | string |
| `error` | string or null |
| `attempts` | integer |
| `created_at` | string (date-time) or null |
| `started_at` | string (date-time) or null |
| `finished_at` | string (date-time) or null |

### Run a failed seed again {#op-post-api-v1-client-servers-uuid-snapshots-seed-retry}

`POST /api/v1/client/servers/{uuid}/snapshots/seed/retry`

Run a failed seed again. The snapshot is unharmed by a failed restore.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `uuid` | string |
| `snapshot_uuid` | string |
| `snapshot_name` | string or null |
| `snapshot_software_label` | string |
| `snapshot_size_bytes` | integer or null |
| `status` | string |
| `error` | string or null |
| `attempts` | integer |
| `created_at` | string (date-time) or null |
| `started_at` | string (date-time) or null |
| `finished_at` | string (date-time) or null |

# Client API: Container Apps: Software

> The 35 Client API operations for software.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-software/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/software`](#op-get-api-v1-client-servers-uuid-software) | List installed software records for a server |
| GET | [`/api/v1/client/servers/{uuid}/software/addons`](#op-get-api-v1-client-servers-uuid-software-addons) | Every addon in the folders the server loads from, tracked or hand-uploaded |
| DELETE | [`/api/v1/client/servers/{uuid}/software/addons/records/{record_uuid}`](#op-delete-api-v1-client-servers-uuid-software-addons-records-record-uuid) | Drop a tracking record whose files are gone, without touching the disk |
| POST | [`/api/v1/client/servers/{uuid}/software/addons/remove`](#op-post-api-v1-client-servers-uuid-software-addons-remove) | Delete one addon from disk, through the tracked uninstall when it has a record |
| POST | [`/api/v1/client/servers/{uuid}/software/addons/toggle`](#op-post-api-v1-client-servers-uuid-software-addons-toggle) | Switch one addon file on or off (Foo.jar <- Foo.jar.disabled) |
| POST | [`/api/v1/client/servers/{uuid}/software/bedrock`](#op-post-api-v1-client-servers-uuid-software-bedrock) | Turn Bedrock crossplay on or off for a Java server |
| GET | [`/api/v1/client/servers/{uuid}/software/bedrock/packs`](#op-get-api-v1-client-servers-uuid-software-bedrock-packs) | Behavior and resource packs on disk, which are active in the world, and importable uploads |
| POST | [`/api/v1/client/servers/{uuid}/software/bedrock/packs/disable-all`](#op-post-api-v1-client-servers-uuid-software-bedrock-packs-disable-all) | Empty the world's activation lists so it boots on vanilla content; folders stay |
| POST | [`/api/v1/client/servers/{uuid}/software/bedrock/packs/import`](#op-post-api-v1-client-servers-uuid-software-bedrock-packs-import) | Queue an import of an uploaded .mcaddon / .mcpack / .zip already on the server |
| POST | [`/api/v1/client/servers/{uuid}/software/bedrock/packs/{pack_uuid}/active`](#op-post-api-v1-client-servers-uuid-software-bedrock-packs-pack-uuid-active) | Add a pack to, or drop it from, the world's activation list |
| POST | [`/api/v1/client/servers/{uuid}/software/bedrock/packs/{pack_uuid}/remove`](#op-post-api-v1-client-servers-uuid-software-bedrock-packs-pack-uuid-remove) | Deactivate a pack, delete its folder, and drop its tracking row |
| PUT | [`/api/v1/client/servers/{uuid}/software/bedrock/texturepack-required`](#op-put-api-v1-client-servers-uuid-software-bedrock-texturepack-required) | Texturepack-required: players must accept the resource packs to join |
| GET | [`/api/v1/client/servers/{uuid}/software/catalog`](#op-get-api-v1-client-servers-uuid-software-catalog) | Server software the machine can be switched to, grouped for display |
| GET | [`/api/v1/client/servers/{uuid}/software/catalog/{key}/versions`](#op-get-api-v1-client-servers-uuid-software-catalog-key-versions) | Installable versions for one catalog entry, with runtime recommendations |
| GET | [`/api/v1/client/servers/{uuid}/software/catalog/{key}/versions/{version}/builds`](#op-get-api-v1-client-servers-uuid-software-catalog-key-versions-version-builds) | Publisher builds of one game version: the loader versions for Fabric/Forge |
| POST | [`/api/v1/client/servers/{uuid}/software/change`](#op-post-api-v1-client-servers-uuid-software-change) | Switch the server to different software, or a different version of it |
| GET | [`/api/v1/client/servers/{uuid}/software/context`](#op-get-api-v1-client-servers-uuid-software-context) | Return loader/game-version context for marketplace tab gating |
| GET | [`/api/v1/client/servers/{uuid}/software/dependencies/{source_uuid}/{identifier}`](#op-get-api-v1-client-servers-uuid-software-dependencies-source-uuid-identifier) | What a version requires, named, with what is already installed marked |
| POST | [`/api/v1/client/servers/{uuid}/software/install`](#op-post-api-v1-client-servers-uuid-software-install) | Queue a software install job |
| GET | [`/api/v1/client/servers/{uuid}/software/installs`](#op-get-api-v1-client-servers-uuid-software-installs) | List recent software install jobs for a server |
| GET | [`/api/v1/client/servers/{uuid}/software/installs/{install_uuid}`](#op-get-api-v1-client-servers-uuid-software-installs-install-uuid) | Get a single software install job |
| POST | [`/api/v1/client/servers/{uuid}/software/installs/{install_uuid}/cancel`](#op-post-api-v1-client-servers-uuid-software-installs-install-uuid-cancel) | Cancel a queued software install |
| POST | [`/api/v1/client/servers/{uuid}/software/installs/{install_uuid}/retry`](#op-post-api-v1-client-servers-uuid-software-installs-install-uuid-retry) | Queue a fresh install job with the same parameters as a failed one |
| GET | [`/api/v1/client/servers/{uuid}/software/jvm`](#op-get-api-v1-client-servers-uuid-software-jvm) | The heap slider and the allowlisted startup flags, as the panel shows them |
| PATCH | [`/api/v1/client/servers/{uuid}/software/jvm`](#op-patch-api-v1-client-servers-uuid-software-jvm) | Move the heap, pick startup flags from the catalog, or reset both |
| GET | [`/api/v1/client/servers/{uuid}/software/resource-pack`](#op-get-api-v1-client-servers-uuid-software-resource-pack) | The server resource pack as server.properties declares it |
| PUT | [`/api/v1/client/servers/{uuid}/software/resource-pack`](#op-put-api-v1-client-servers-uuid-software-resource-pack) | Point players at a pack, from a URL or a marketplace resource pack version |
| DELETE | [`/api/v1/client/servers/{uuid}/software/resource-pack`](#op-delete-api-v1-client-servers-uuid-software-resource-pack) | Stop offering a server resource pack |
| POST | [`/api/v1/client/servers/{uuid}/software/safe-mode`](#op-post-api-v1-client-servers-uuid-software-safe-mode) | Arm a one-shot --safeMode start (vanilla datapack only), optionally starting now |
| POST | [`/api/v1/client/servers/{uuid}/software/search`](#op-post-api-v1-client-servers-uuid-software-search) | Search available software (JSON body preferred; query params kept for back-compat) |
| GET | [`/api/v1/client/servers/{uuid}/software/sources`](#op-get-api-v1-client-servers-uuid-software-sources) | List enabled software sources for a kind |
| GET | [`/api/v1/client/servers/{uuid}/software/updates`](#op-get-api-v1-client-servers-uuid-software-updates) | Newer compatible builds for the addons the marketplace installed |
| GET | [`/api/v1/client/servers/{uuid}/software/versions/{source_uuid}/{identifier}`](#op-get-api-v1-client-servers-uuid-software-versions-source-uuid-identifier) | Get available versions for software |
| DELETE | [`/api/v1/client/servers/{uuid}/software/{record_uuid}`](#op-delete-api-v1-client-servers-uuid-software-record-uuid) | Uninstall a tracked software artifact |
| POST | [`/api/v1/client/servers/{uuid}/software/{record_uuid}/update`](#op-post-api-v1-client-servers-uuid-software-record-uuid-update) | Queue an in-place update: the old file is removed, the new build installed |

### List installed software records for a server {#op-get-api-v1-client-servers-uuid-software}

`GET /api/v1/client/servers/{uuid}/software`

List installed software records for a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Every addon in the folders the server loads from, tracked or hand-uploaded {#op-get-api-v1-client-servers-uuid-software-addons}

`GET /api/v1/client/servers/{uuid}/software/addons`

Every addon in the folders the server loads from, tracked or hand-uploaded.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `kind` | query | string or null | no | plugin, mod or datapack; omit for every kind |

#### Responses

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

### Drop a tracking record whose files are gone, without touching the disk {#op-delete-api-v1-client-servers-uuid-software-addons-records-record-uuid}

`DELETE /api/v1/client/servers/{uuid}/software/addons/records/{record_uuid}`

Drop a tracking record whose files are gone, without touching the disk.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `record_uuid` | path | string | yes |

#### Responses

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

### Delete one addon from disk, through the tracked uninstall when it has a record {#op-post-api-v1-client-servers-uuid-software-addons-remove}

`POST /api/v1/client/servers/{uuid}/software/addons/remove`

Delete one addon from disk, through the tracked uninstall when it has a record.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### Switch one addon file on or off (Foo.jar <- Foo.jar.disabled) {#op-post-api-v1-client-servers-uuid-software-addons-toggle}

`POST /api/v1/client/servers/{uuid}/software/addons/toggle`

Switch one addon file on or off (``Foo.jar`` <-> ``Foo.jar.disabled``).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### Turn Bedrock crossplay on or off for a Java server {#op-post-api-v1-client-servers-uuid-software-bedrock}

`POST /api/v1/client/servers/{uuid}/software/bedrock`

Turn Bedrock crossplay on or off for a Java server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### Behavior and resource packs on disk, which are active in the world, and importable uploads {#op-get-api-v1-client-servers-uuid-software-bedrock-packs}

`GET /api/v1/client/servers/{uuid}/software/bedrock/packs`

Behavior and resource packs on disk, which are active in the world, and importable uploads.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Empty the world's activation lists so it boots on vanilla content; folders stay {#op-post-api-v1-client-servers-uuid-software-bedrock-packs-disable-all}

`POST /api/v1/client/servers/{uuid}/software/bedrock/packs/disable-all`

Empty the world's activation lists so it boots on vanilla content; folders stay.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Queue an import of an uploaded .mcaddon / .mcpack / .zip already on the server {#op-post-api-v1-client-servers-uuid-software-bedrock-packs-import}

`POST /api/v1/client/servers/{uuid}/software/bedrock/packs/import`

Queue an import of an uploaded ``.mcaddon`` / ``.mcpack`` / ``.zip`` already on the server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### Add a pack to, or drop it from, the world's activation list {#op-post-api-v1-client-servers-uuid-software-bedrock-packs-pack-uuid-active}

`POST /api/v1/client/servers/{uuid}/software/bedrock/packs/{pack_uuid}/active`

Add a pack to, or drop it from, the world's activation list.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `pack_uuid` | 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. |

### Deactivate a pack, delete its folder, and drop its tracking row {#op-post-api-v1-client-servers-uuid-software-bedrock-packs-pack-uuid-remove}

`POST /api/v1/client/servers/{uuid}/software/bedrock/packs/{pack_uuid}/remove`

Deactivate a pack, delete its folder, and drop its tracking row.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `pack_uuid` | path | string | yes |

#### Responses

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

### Texturepack-required: players must accept the resource packs to join {#op-put-api-v1-client-servers-uuid-software-bedrock-texturepack-required}

`PUT /api/v1/client/servers/{uuid}/software/bedrock/texturepack-required`

``texturepack-required``: players must accept the resource packs to join.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### Server software the machine can be switched to, grouped for display {#op-get-api-v1-client-servers-uuid-software-catalog}

`GET /api/v1/client/servers/{uuid}/software/catalog`

Server software the machine can be switched to, grouped for display.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Installable versions for one catalog entry, with runtime recommendations {#op-get-api-v1-client-servers-uuid-software-catalog-key-versions}

`GET /api/v1/client/servers/{uuid}/software/catalog/{key}/versions`

Installable versions for one catalog entry, with runtime recommendations.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `key` | path | string | yes |  |
| `limit` | query | integer | no | Default: `200`. |
| `include_unsupported` | query | boolean | no | Default: `False`. |

#### Responses

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

### Publisher builds of one game version: the loader versions for Fabric/Forge {#op-get-api-v1-client-servers-uuid-software-catalog-key-versions-version-builds}

`GET /api/v1/client/servers/{uuid}/software/catalog/{key}/versions/{version}/builds`

Publisher builds of one game version: the loader versions for Fabric/Forge.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `key` | path | string | yes |
| `version` | path | string | yes |

#### Responses

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

### Switch the server to different software, or a different version of it {#op-post-api-v1-client-servers-uuid-software-change}

`POST /api/v1/client/servers/{uuid}/software/change`

Switch the server to different software, or a different version of it.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### Return loader/game-version context for marketplace tab gating {#op-get-api-v1-client-servers-uuid-software-context}

`GET /api/v1/client/servers/{uuid}/software/context`

Return loader/game-version context for marketplace tab gating.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### What a version requires, named, with what is already installed marked {#op-get-api-v1-client-servers-uuid-software-dependencies-source-uuid-identifier}

`GET /api/v1/client/servers/{uuid}/software/dependencies/{source_uuid}/{identifier}`

What a version requires, named, with what is already installed marked.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `source_uuid` | path | string | yes |  |
| `identifier` | path | string | yes |  |
| `version` | query | string | no | The version whose dependencies to resolve; latest resolves as the installer would Default: `latest`. |
| `kind` | query | string or null | no |  |

#### Responses

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

### Queue a software install job {#op-post-api-v1-client-servers-uuid-software-install}

`POST /api/v1/client/servers/{uuid}/software/install`

Queue a software install job.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `source_uuid` | query | string or null | no |
| `identifier` | query | string or null | no |
| `software_id` | query | string or null | no |
| `version` | query | string or null | no |
| `kind` | query | string or null | no |

#### Request body

`application/json`

Type: object or null.

#### Responses

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

### List recent software install jobs for a server {#op-get-api-v1-client-servers-uuid-software-installs}

`GET /api/v1/client/servers/{uuid}/software/installs`

List recent software install jobs for a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `status` | query | string or null | no |

#### Responses

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

### Get a single software install job {#op-get-api-v1-client-servers-uuid-software-installs-install-uuid}

`GET /api/v1/client/servers/{uuid}/software/installs/{install_uuid}`

Get a single software install job.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `install_uuid` | path | string | yes |

#### Responses

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

### Cancel a queued software install {#op-post-api-v1-client-servers-uuid-software-installs-install-uuid-cancel}

`POST /api/v1/client/servers/{uuid}/software/installs/{install_uuid}/cancel`

Cancel a queued software install.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `install_uuid` | path | string | yes |

#### Responses

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

### Queue a fresh install job with the same parameters as a failed one {#op-post-api-v1-client-servers-uuid-software-installs-install-uuid-retry}

`POST /api/v1/client/servers/{uuid}/software/installs/{install_uuid}/retry`

Queue a fresh install job with the same parameters as a failed one.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `install_uuid` | path | string | yes |

#### Responses

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

### The heap slider and the allowlisted startup flags, as the panel shows them {#op-get-api-v1-client-servers-uuid-software-jvm}

`GET /api/v1/client/servers/{uuid}/software/jvm`

The heap slider and the allowlisted startup flags, as the panel shows them.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Move the heap, pick startup flags from the catalog, or reset both {#op-patch-api-v1-client-servers-uuid-software-jvm}

`PATCH /api/v1/client/servers/{uuid}/software/jvm`

Move the heap, pick startup flags from the catalog, or reset both. Applies on restart.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### The server resource pack as server.properties declares it {#op-get-api-v1-client-servers-uuid-software-resource-pack}

`GET /api/v1/client/servers/{uuid}/software/resource-pack`

The server resource pack as ``server.properties`` declares it.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Point players at a pack, from a URL or a marketplace resource pack version {#op-put-api-v1-client-servers-uuid-software-resource-pack}

`PUT /api/v1/client/servers/{uuid}/software/resource-pack`

Point players at a pack, from a URL or a marketplace resource pack version.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### Stop offering a server resource pack {#op-delete-api-v1-client-servers-uuid-software-resource-pack}

`DELETE /api/v1/client/servers/{uuid}/software/resource-pack`

Stop offering a server resource pack.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Arm a one-shot --safeMode start (vanilla datapack only), optionally starting now {#op-post-api-v1-client-servers-uuid-software-safe-mode}

`POST /api/v1/client/servers/{uuid}/software/safe-mode`

Arm a one-shot ``--safeMode`` start (vanilla datapack only), optionally starting now.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | 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. |

### Search available software (JSON body preferred; query params kept for back-compat) {#op-post-api-v1-client-servers-uuid-software-search}

`POST /api/v1/client/servers/{uuid}/software/search`

Search available software (JSON body preferred; query params kept for back-compat).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `query` | query | string or null | no |  |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `20`. |
| `source_uuid` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `sort` | query | string or null | no |  |

#### Request body

`application/json`

Type: object or null.

#### Responses

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

### List enabled software sources for a kind {#op-get-api-v1-client-servers-uuid-software-sources}

`GET /api/v1/client/servers/{uuid}/software/sources`

List enabled software sources for a kind.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `kind` | query | string or null | no |

#### Responses

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

### Newer compatible builds for the addons the marketplace installed {#op-get-api-v1-client-servers-uuid-software-updates}

`GET /api/v1/client/servers/{uuid}/software/updates`

Newer compatible builds for the addons the marketplace installed.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `kind` | query | string or null | no |  |
| `include_current` | query | boolean | no | Also return addons already on the newest build Default: `False`. |

#### Responses

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

### Get available versions for software {#op-get-api-v1-client-servers-uuid-software-versions-source-uuid-identifier}

`GET /api/v1/client/servers/{uuid}/software/versions/{source_uuid}/{identifier}`

Get available versions for software.

Plugin and mod lookups default to builds that fit this server's loader and
game version; each row carries ``compatible`` and ``incompatible_reason``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `source_uuid` | path | string | yes |  |
| `identifier` | path | string | yes |  |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `50`. |
| `loaders` | query | string or null | no | Comma-separated loaders |
| `game_versions` | query | string or null | no | Comma-separated game versions |
| `kind` | query | string or null | no | Content kind; datapacks ignore the server loader |
| `include_incompatible` | query | boolean | no | List builds for other loaders / game versions too, flagged Default: `False`. |

#### Responses

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

### Uninstall a tracked software artifact {#op-delete-api-v1-client-servers-uuid-software-record-uuid}

`DELETE /api/v1/client/servers/{uuid}/software/{record_uuid}`

Uninstall a tracked software artifact.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `record_uuid` | path | string | yes |

#### Responses

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

### Queue an in-place update: the old file is removed, the new build installed {#op-post-api-v1-client-servers-uuid-software-record-uuid-update}

`POST /api/v1/client/servers/{uuid}/software/{record_uuid}/update`

Queue an in-place update: the old file is removed, the new build installed.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `record_uuid` | path | string | yes |

#### Request body

`application/json`

Type: object or null.

#### Responses

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

# Client API: Container Apps: Users

> The 4 Client API operations for users.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/servers-users/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/servers/{uuid}/users`](#op-get-api-v1-client-servers-uuid-users) | List subusers for a server |
| POST | [`/api/v1/client/servers/{uuid}/users`](#op-post-api-v1-client-servers-uuid-users) | Add a subuser to a server |
| PUT | [`/api/v1/client/servers/{uuid}/users/{subuser_id}`](#op-put-api-v1-client-servers-uuid-users-subuser-id) | Update subuser permissions |
| DELETE | [`/api/v1/client/servers/{uuid}/users/{subuser_id}`](#op-delete-api-v1-client-servers-uuid-users-subuser-id) | Remove a subuser from a server |

### List subusers for a server {#op-get-api-v1-client-servers-uuid-users}

`GET /api/v1/client/servers/{uuid}/users`

List subusers for a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].server_id` | integer |
| `[].user_id` | integer |
| `[].permissions` | array of string |
| `[].created_at` | string (date-time) |
| `[].email` | string or null |
| `[].name` | string or null |

### Add a subuser to a server {#op-post-api-v1-client-servers-uuid-users}

`POST /api/v1/client/servers/{uuid}/users`

Add a subuser to a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `user_id` | integer | yes |
| `permissions` | array of string | yes |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `server_id` | integer |
| `user_id` | integer |
| `permissions` | array of string |
| `created_at` | string (date-time) |
| `email` | string or null |
| `name` | string or null |

### Update subuser permissions {#op-put-api-v1-client-servers-uuid-users-subuser-id}

`PUT /api/v1/client/servers/{uuid}/users/{subuser_id}`

Update subuser permissions.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `subuser_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `permissions` | array of string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `server_id` | integer |
| `user_id` | integer |
| `permissions` | array of string |
| `created_at` | string (date-time) |
| `email` | string or null |
| `name` | string or null |

### Remove a subuser from a server {#op-delete-api-v1-client-servers-uuid-users-subuser-id}

`DELETE /api/v1/client/servers/{uuid}/users/{subuser_id}`

Remove a subuser from a server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `subuser_id` | path | integer | yes |

#### Responses

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

# Client API: Container Apps: Snapshots

> The 7 Client API operations for snapshots.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/snapshots/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/snapshots`](#op-get-api-v1-client-snapshots) | Every snapshot this account holds, across every server it has had |
| GET | [`/api/v1/client/snapshots/allowance`](#op-get-api-v1-client-snapshots-allowance) | The account's snapshot meter |
| GET | [`/api/v1/client/snapshots/{snapshot_uuid}`](#op-get-api-v1-client-snapshots-snapshot-uuid) | One snapshot, for the order form that was handed its uuid in a link |
| DELETE | [`/api/v1/client/snapshots/{snapshot_uuid}`](#op-delete-api-v1-client-snapshots-snapshot-uuid) | Delete a snapshot and the archive behind it |
| GET | [`/api/v1/client/snapshots/{snapshot_uuid}/download`](#op-get-api-v1-client-snapshots-snapshot-uuid-download) | A signed URL for the archive itself |
| POST | [`/api/v1/client/snapshots/{snapshot_uuid}/lock`](#op-post-api-v1-client-snapshots-snapshot-uuid-lock) | Keep a snapshot, or release it |
| POST | [`/api/v1/client/snapshots/{snapshot_uuid}/restore`](#op-post-api-v1-client-snapshots-snapshot-uuid-restore) | Restore a snapshot onto one of this account's servers |

### Every snapshot this account holds, across every server it has had {#op-get-api-v1-client-snapshots}

`GET /api/v1/client/snapshots`

Every snapshot this account holds, across every server it has had.

Not scoped to a server on purpose, and the reason the table is owned by the
account: after a service ends there is no server to ask.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string |
| `[].name` | string |
| `[].kind` | string |
| `[].status` | string |
| `[].size_bytes` | integer |
| `[].is_locked` | boolean |
| `[].created_by` | string |
| `[].reason` | string or null |
| `[].region` | string or null |
| `[].checksum` | string or null |
| `[].checksum_type` | string or null |
| `[].error` | string or null |
| `[].hold_reason` | string or null |
| `[].source_id` | integer or null |
| `[].source_uuid` | string or null |
| `[].source_server_name` | string or null |
| `[].source_name` | string or null |
| `[].source_location` | string or null |
| `[].source_used_bytes` | integer or null |
| `[].source_deleted` | boolean |
| `[].egg_id` | integer or null |
| `[].software` | SnapshotSoftware or null |
| `[].software.slug` | string or null |
| `[].software.name` | string or null |
| `[].software.mcjars_type` | string or null |
| `[].software.loader` | string or null |
| `[].software.loader_family` | string or null |
| `[].software.game` | string or null |
| `[].software.edition` | string or null |
| `[].software.version` | string or null |
| `[].software.runtime_template_slug` | string or null |
| `[].software.docker_image` | string or null |
| `[].software.modpack` | object or null |
| `[].software.memory_mb` | integer or null |
| `[].software.disk_mb` | integer or null |
| `[].software.inferred` | boolean |
| `[].software_label` | string |
| `[].software_slug` | string or null |
| `[].software_version` | string or null |
| `[].compatibility` | SnapshotCompatibility or null |
| `[].compatibility.level` | string |
| `[].compatibility.reason` | string |
| `[].is_source` | boolean or null |
| `[].schedule_uuid` | string or null |
| `[].schedule_name` | string or null |
| `[].created_at` | string (date-time) |
| `[].completed_at` | string (date-time) or null |

### The account's snapshot meter {#op-get-api-v1-client-snapshots-allowance}

`GET /api/v1/client/snapshots/allowance`

The account's snapshot meter.

A write session because it recomputes and caches: the alternative is a
meter that disagrees with what a creation attempt will decide, which is
worse than the write.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `allowance_bytes` | integer |
| `used_bytes` | integer |
| `available_bytes` | integer |
| `bonus_bytes` | integer |
| `over` | boolean |
| `cleanup_at` | string (date-time) or null |
| `over_since` | string (date-time) or null |
| `breakdown` | array of object |

### One snapshot, for the order form that was handed its uuid in a link {#op-get-api-v1-client-snapshots-snapshot-uuid}

`GET /api/v1/client/snapshots/{snapshot_uuid}`

One snapshot, for the order form that was handed its uuid in a link.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `name` | string |
| `kind` | string |
| `status` | string |
| `size_bytes` | integer |
| `is_locked` | boolean |
| `created_by` | string |
| `reason` | string or null |
| `region` | string or null |
| `checksum` | string or null |
| `checksum_type` | string or null |
| `error` | string or null |
| `hold_reason` | string or null |
| `source_id` | integer or null |
| `source_uuid` | string or null |
| `source_server_name` | string or null |
| `source_name` | string or null |
| `source_location` | string or null |
| `source_used_bytes` | integer or null |
| `source_deleted` | boolean |
| `egg_id` | integer or null |
| `software` | SnapshotSoftware or null |
| `software.slug` | string or null |
| `software.name` | string or null |
| `software.mcjars_type` | string or null |
| `software.loader` | string or null |
| `software.loader_family` | string or null |
| `software.game` | string or null |
| `software.edition` | string or null |
| `software.version` | string or null |
| `software.runtime_template_slug` | string or null |
| `software.docker_image` | string or null |
| `software.modpack` | object or null |
| `software.memory_mb` | integer or null |
| `software.disk_mb` | integer or null |
| `software.inferred` | boolean |
| `software_label` | string |
| `software_slug` | string or null |
| `software_version` | string or null |
| `compatibility` | SnapshotCompatibility or null |
| `compatibility.level` | string |
| `compatibility.reason` | string |
| `is_source` | boolean or null |
| `schedule_uuid` | string or null |
| `schedule_name` | string or null |
| `created_at` | string (date-time) |
| `completed_at` | string (date-time) or null |

### Delete a snapshot and the archive behind it {#op-delete-api-v1-client-snapshots-snapshot-uuid}

`DELETE /api/v1/client/snapshots/{snapshot_uuid}`

Delete a snapshot and the archive behind it.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### A signed URL for the archive itself {#op-get-api-v1-client-snapshots-snapshot-uuid-download}

`GET /api/v1/client/snapshots/{snapshot_uuid}/download`

A signed URL for the archive itself.

Never gated on owing money. "Pay to get your data" is legally
uncomfortable in the EU and reputationally worse, and the revenue it could
recover is one month of a plan the customer has already left.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Keep a snapshot, or release it {#op-post-api-v1-client-snapshots-snapshot-uuid-lock}

`POST /api/v1/client/snapshots/{snapshot_uuid}/lock`

Keep a snapshot, or release it.

A lock stops rotation and an accidental delete. It does not exempt the
snapshot from the retention sweep, so it cannot be used to hold storage
after a downgrade.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `name` | string |
| `kind` | string |
| `status` | string |
| `size_bytes` | integer |
| `is_locked` | boolean |
| `created_by` | string |
| `reason` | string or null |
| `region` | string or null |
| `checksum` | string or null |
| `checksum_type` | string or null |
| `error` | string or null |
| `hold_reason` | string or null |
| `source_id` | integer or null |
| `source_uuid` | string or null |
| `source_server_name` | string or null |
| `source_name` | string or null |
| `source_location` | string or null |
| `source_used_bytes` | integer or null |
| `source_deleted` | boolean |
| `egg_id` | integer or null |
| `software` | SnapshotSoftware or null |
| `software.slug` | string or null |
| `software.name` | string or null |
| `software.mcjars_type` | string or null |
| `software.loader` | string or null |
| `software.loader_family` | string or null |
| `software.game` | string or null |
| `software.edition` | string or null |
| `software.version` | string or null |
| `software.runtime_template_slug` | string or null |
| `software.docker_image` | string or null |
| `software.modpack` | object or null |
| `software.memory_mb` | integer or null |
| `software.disk_mb` | integer or null |
| `software.inferred` | boolean |
| `software_label` | string |
| `software_slug` | string or null |
| `software_version` | string or null |
| `compatibility` | SnapshotCompatibility or null |
| `compatibility.level` | string |
| `compatibility.reason` | string |
| `is_source` | boolean or null |
| `schedule_uuid` | string or null |
| `schedule_name` | string or null |
| `created_at` | string (date-time) |
| `completed_at` | string (date-time) or null |

### Restore a snapshot onto one of this account's servers {#op-post-api-v1-client-snapshots-snapshot-uuid-restore}

`POST /api/v1/client/snapshots/{snapshot_uuid}/restore`

Restore a snapshot onto one of this account's servers.

Addressed by snapshot rather than by server because the target is a choice.
The permission is checked against the *target* server, because that is the
one being overwritten and the one a subuser was or was not trusted with.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `target_server_uuid` | string or null | no |
| `truncate` | boolean | no |
| `allow_mismatch` | boolean | no |

#### Responses

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

# Client API: Container Apps: Timezones

> The 1 Client API operations for timezones.

Source: https://www.coritan.com/docs/api/reference/client/container-apps/timezones/

Part of [Container Apps](/docs/api/reference/client/container-apps/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/timezones`](#op-get-api-v1-client-timezones) | Every zone this platform can resolve, west to east, with its old names |

### Every zone this platform can resolve, west to east, with its old names {#op-get-api-v1-client-timezones}

`GET /api/v1/client/timezones`

Every zone this platform can resolve, west to east, with its old names.

A picker built from the browser offers names the API then rejects: Chrome
reports CLDR's ids, and for a dozen zones those are the pre-rename IANA
names, which only resolve where the backward-compatibility links are
installed. This is the list the API will actually accept, so a form built
from it cannot drift from the server.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `version` | string |
| `zones` | array of TimezoneOption |
| `zones[].name` | string |
| `zones[].region` | string |
| `zones[].city` | string |
| `zones[].offset` | string |
| `zones[].offset_minutes` | integer |
| `aliases` | Aliases |

# Client API: Apps

> Apps built once from a git repository or an image and run as replicas in the regions you choose: deployments, build logs, rollbacks, environment variables and domains.

Source: https://www.coritan.com/docs/api/reference/client/apps/

Apps built once from a git repository or an image and run as replicas in the regions you choose: deployments, build logs, rollbacks, environment variables and domains. Paths are under `/api/v1/client/apps`.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/apps`](#op-get-api-v1-client-apps) | List apps |
| POST | [`/api/v1/client/apps`](#op-post-api-v1-client-apps) | Create an app and, unless deploy is false, its first deployment |
| GET | [`/api/v1/client/apps/regions`](#op-get-api-v1-client-apps-regions) | Regions |
| GET | [`/api/v1/client/apps/{app_uuid}`](#op-get-api-v1-client-apps-app-uuid) | Get one app with its domains, recent deployments and current replicas |
| PATCH | [`/api/v1/client/apps/{app_uuid}`](#op-patch-api-v1-client-apps-app-uuid) | Change an app's settings |
| DELETE | [`/api/v1/client/apps/{app_uuid}`](#op-delete-api-v1-client-apps-app-uuid) | Delete app |
| GET | [`/api/v1/client/apps/{app_uuid}/deployments`](#op-get-api-v1-client-apps-app-uuid-deployments) | List an app's deployments, newest first, a page at a time |
| POST | [`/api/v1/client/apps/{app_uuid}/deployments`](#op-post-api-v1-client-apps-app-uuid-deployments) | Create app deployment |
| GET | [`/api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}`](#op-get-api-v1-client-apps-app-uuid-deployments-deployment-uuid) | Get one deployment of an app, with each of its replicas |
| POST | [`/api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/cancel`](#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-cancel) | Cancel a deployment that is still queued, building or deploying |
| GET | [`/api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/log`](#op-get-api-v1-client-apps-app-uuid-deployments-deployment-uuid-log) | The end of the deployment's build log (secrets redacted as it was written) |
| POST | [`/api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`](#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-rollback) | Rollback app |
| GET | [`/api/v1/client/apps/{app_uuid}/domains`](#op-get-api-v1-client-apps-app-uuid-domains) | List an app's domains: its platform name first, then its custom domains |
| POST | [`/api/v1/client/apps/{app_uuid}/domains`](#op-post-api-v1-client-apps-app-uuid-domains) | Add a custom domain |
| DELETE | [`/api/v1/client/apps/{app_uuid}/domains/{hostname}`](#op-delete-api-v1-client-apps-app-uuid-domains-hostname) | Remove a custom domain from an app |
| POST | [`/api/v1/client/apps/{app_uuid}/domains/{hostname}/verify`](#op-post-api-v1-client-apps-app-uuid-domains-hostname-verify) | Look for the domain's TXT record |
| GET | [`/api/v1/client/apps/{app_uuid}/env`](#op-get-api-v1-client-apps-app-uuid-env) | List an app's environment variables without their values |
| PUT | [`/api/v1/client/apps/{app_uuid}/env`](#op-put-api-v1-client-apps-app-uuid-env) | Set many variables; a variable given without value keeps its saved one |
| PUT | [`/api/v1/client/apps/{app_uuid}/env/{key}`](#op-put-api-v1-client-apps-app-uuid-env-key) | Set one environment variable, creating it when it is new |
| DELETE | [`/api/v1/client/apps/{app_uuid}/env/{key}`](#op-delete-api-v1-client-apps-app-uuid-env-key) | Delete one environment variable |
| POST | [`/api/v1/client/apps/{app_uuid}/redeploy`](#op-post-api-v1-client-apps-app-uuid-redeploy) | Redeploy app |
| POST | [`/api/v1/client/apps/{app_uuid}/webhook/rotate`](#op-post-api-v1-client-apps-app-uuid-webhook-rotate) | A new secret for the push webhook, shown once; the old one stops verifying at once |

### List apps {#op-get-api-v1-client-apps}

`GET /api/v1/client/apps`

The caller's apps, newest first, each with its current deployment,
replica counts and domains.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

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

### Create an app and, unless deploy is false, its first deployment {#op-post-api-v1-client-apps}

`POST /api/v1/client/apps`

Create an app and, unless ``deploy`` is false, its first deployment.
An app whose first deployment cannot start yet is still created, with
the reason in ``deploy_error``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `repo_url` | string or null | no |  |
| `repo_branch` | string or null | no |  |
| `repo_subdir` | string or null | no |  |
| `repo_token` | string or null | no | Write only; an empty string removes it |
| `image_ref` | string or null | no |  |
| `framework` | string or null | no |  |
| `install_command` | string or null | no |  |
| `build_command` | string or null | no |  |
| `start_command` | string or null | no |  |
| `dockerfile_path` | string or null | no |  |
| `port` | integer or null | no |  |
| `health_check_path` | string or null | no |  |
| `instance_size` | string or null | no |  |
| `regions` | array of string or null | no |  |
| `min_replicas` | integer or null | no |  |
| `max_replicas` | integer or null | no |  |
| `slug` | string or null | no | The name on the platform; derived from name when left out |
| `source_type` | string | no |  |
| `env` | array of EnvVarIn or null | no |  |
| `env[].key` | string | yes |  |
| `env[].value` | string or null | no | Left out: the saved value is kept |
| `env[].secret` | boolean or null | no | Redacted from build logs; new variables default to true |
| `env[].target` | string or null | no |  |
| `deploy` | boolean | no | Start the first deployment at once |

#### Responses

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

### Regions {#op-get-api-v1-client-apps-regions}

`GET /api/v1/client/apps/regions`

What the create form offers: the regions that can run apps now,
the instance sizes, the replica bounds and the owner's app limit.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get one app with its domains, recent deployments and current replicas {#op-get-api-v1-client-apps-app-uuid}

`GET /api/v1/client/apps/{app_uuid}`

Get one app with its domains, recent deployments and current replicas.
``deployments`` holds the five newest and ``deployments_total`` counts
them all; ``replicas`` are those of the deployment that serves the app,
failed ones left out. Another owner's app answers 404, as one that does
not exist does.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Responses

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

### Change an app's settings {#op-patch-api-v1-client-apps-app-uuid}

`PATCH /api/v1/client/apps/{app_uuid}`

Change an app's settings. ``redeploy_required`` and
``rebuild_required`` say whether running replicas pick the change up
only with a new deployment or a new build.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string or null | no |  |
| `repo_url` | string or null | no |  |
| `repo_branch` | string or null | no |  |
| `repo_subdir` | string or null | no |  |
| `repo_token` | string or null | no | Write only; an empty string removes it |
| `image_ref` | string or null | no |  |
| `framework` | string or null | no |  |
| `install_command` | string or null | no |  |
| `build_command` | string or null | no |  |
| `start_command` | string or null | no |  |
| `dockerfile_path` | string or null | no |  |
| `port` | integer or null | no |  |
| `health_check_path` | string or null | no |  |
| `instance_size` | string or null | no |  |
| `regions` | array of string or null | no |  |
| `min_replicas` | integer or null | no |  |
| `max_replicas` | integer or null | no |  |

#### Responses

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

### Delete app {#op-delete-api-v1-client-apps-app-uuid}

`DELETE /api/v1/client/apps/{app_uuid}`

Delete the app: deployments on their way are canceled, its routes
and domains removed, its replicas drained and their servers removed,
its environment and secrets erased. It cannot be undone.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |  |
| `confirm` | query | string | yes | The app's name on the platform, typed to confirm |
| `reason` | query | string or null | no |  |

#### Responses

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

### List an app's deployments, newest first, a page at a time {#op-get-api-v1-client-apps-app-uuid-deployments}

`GET /api/v1/client/apps/{app_uuid}/deployments`

List an app's deployments, newest first, a page at a time.
``limit`` takes 1 to 100 (20 when left out) and ``total`` counts every
deployment. Each one carries its status, source, build and replica
counts.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |  |
| `limit` | query | integer | no | Default: `20`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

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

### Create app deployment {#op-post-api-v1-client-apps-app-uuid-deployments}

`POST /api/v1/client/apps/{app_uuid}/deployments`

Deploy: a git app builds ``git_ref`` (its branch when left out); an
image app runs ``image_ref`` (its own when left out). A branch or
commit for an image app, or an image for a git app, is refused with
``source_mismatch`` rather than ignored.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `git_ref` | string or null | no | Branch, tag or commit; the app's branch when left out |
| `git_sha` | string or null | no |  |
| `image_ref` | string or null | no | An image app's reference; the app's when left out |

#### Responses

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

### Get one deployment of an app, with each of its replicas {#op-get-api-v1-client-apps-app-uuid-deployments-deployment-uuid}

`GET /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}`

Get one deployment of an app, with each of its replicas.
``replica_list`` gives each replica's region, state, failed health checks
in a row and last error. A deployment of another app answers 404.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `deployment_uuid` | path | string (uuid) | yes |

#### Responses

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

### Cancel a deployment that is still queued, building or deploying {#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-cancel}

`POST /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/cancel`

Cancel a deployment that is still queued, building or deploying.
Its build stops and its replicas are removed, and the deployment that
serves the app goes on serving. A deployment that has finished answers
409.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `deployment_uuid` | path | string (uuid) | yes |

#### Responses

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

### The end of the deployment's build log (secrets redacted as it was written) {#op-get-api-v1-client-apps-app-uuid-deployments-deployment-uuid-log}

`GET /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/log`

The end of the deployment's build log (secrets redacted as it was
written). An image deployment has none.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `deployment_uuid` | path | string (uuid) | yes |

#### Responses

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

### Rollback app {#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-rollback}

`POST /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`

A new deployment of this earlier ready deployment's image; its
replicas that still have servers are started again instead of placed.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `deployment_uuid` | path | string (uuid) | yes |

#### Responses

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

### List an app's domains: its platform name first, then its custom domains {#op-get-api-v1-client-apps-app-uuid-domains}

`GET /api/v1/client/apps/{app_uuid}/domains`

List an app's domains: its platform name first, then its custom domains.
Each says whether it is verified and whether its certificate is issued,
and an unverified one carries the TXT record to publish in
``verification``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Responses

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

### Add a custom domain {#op-post-api-v1-client-apps-app-uuid-domains}

`POST /api/v1/client/apps/{app_uuid}/domains`

Add a custom domain. It gets no route until the TXT record in
``verification`` is published and checked.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |

#### Responses

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

### Remove a custom domain from an app {#op-delete-api-v1-client-apps-app-uuid-domains-hostname}

`DELETE /api/v1/client/apps/{app_uuid}/domains/{hostname}`

Remove a custom domain from an app. The hostname stops reaching the
app, and its route and certificate are deleted. The platform name cannot
be removed (409 ``platform_domain``), and a hostname the app does not
have answers 404.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `hostname` | path | string | yes |

#### Responses

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

### Look for the domain's TXT record {#op-post-api-v1-client-apps-app-uuid-domains-hostname-verify}

`POST /api/v1/client/apps/{app_uuid}/domains/{hostname}/verify`

Look for the domain's TXT record. Found: the domain is verified, its
route is created and, once replicas serve it, its certificate ordered.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `hostname` | path | string | yes |

#### Responses

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

### List an app's environment variables without their values {#op-get-api-v1-client-apps-app-uuid-env}

`GET /api/v1/client/apps/{app_uuid}/env`

List an app's environment variables without their values.
Each key comes with its ``target``, whether it is ``secret`` and, for a
value of eight characters or more, its last four as ``hint``.
``readable`` is false when a saved value can no longer be read; set it
again.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Responses

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

### Set many variables; a variable given without value keeps its saved one {#op-put-api-v1-client-apps-app-uuid-env}

`PUT /api/v1/client/apps/{app_uuid}/env`

Set many variables; a variable given without ``value`` keeps its
saved one. With ``replace`` every variable not listed is deleted.
Changes reach replicas with the next deployment.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `vars` | array of EnvVarIn | yes |  |
| `vars[].key` | string | yes |  |
| `vars[].value` | string or null | no | Left out: the saved value is kept |
| `vars[].secret` | boolean or null | no | Redacted from build logs; new variables default to true |
| `vars[].target` | string or null | no |  |
| `replace` | boolean | no | Delete every variable not in vars |

#### Responses

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

### Set one environment variable, creating it when it is new {#op-put-api-v1-client-apps-app-uuid-env-key}

`PUT /api/v1/client/apps/{app_uuid}/env/{key}`

Set one environment variable, creating it when it is new.
A new variable needs a ``value`` and is secret unless ``secret`` is
false; leave ``value`` out to keep the saved one while ``secret`` or
``target`` change. A key the platform sets itself, such as ``PORT`` or
one starting ``CORITAN_``, is refused with 422. Replicas get the change
with the next deployment.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `key` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `value` | string or null | no |
| `secret` | boolean or null | no |
| `target` | string or null | no |

#### Responses

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

### Delete one environment variable {#op-delete-api-v1-client-apps-app-uuid-env-key}

`DELETE /api/v1/client/apps/{app_uuid}/env/{key}`

Delete one environment variable. Running replicas keep it until the
next deployment. A key the app does not have answers 404.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `key` | path | string | yes |

#### Responses

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

### Redeploy app {#op-post-api-v1-client-apps-app-uuid-redeploy}

`POST /api/v1/client/apps/{app_uuid}/redeploy`

Deploy the current version again (picking up environment, size,
region and replica changes), or build the branch afresh with ``rebuild``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rebuild` | boolean | no | Build the branch again instead of reusing the current image |

#### Responses

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

### A new secret for the push webhook, shown once; the old one stops verifying at once {#op-post-api-v1-client-apps-app-uuid-webhook-rotate}

`POST /api/v1/client/apps/{app_uuid}/webhook/rotate`

A new secret for the push webhook, shown once; the old one stops
verifying at once.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |

#### Responses

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

# Client API: Cloud Compute

> Cloud Compute VM instances (power, console, backups, and details).

Source: https://www.coritan.com/docs/api/reference/client/cloud-compute/

Cloud Compute VM instances (power, console, backups, and details). Paths remain under `/api/v1/client/vps`.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/vps`](#op-get-api-v1-client-vps) | List all VPS instances owned by the current user |
| GET | [`/api/v1/client/vps/templates`](#op-get-api-v1-client-vps-templates) | OS templates ready for order/rebuild: enabled and ready on at least one active node |
| GET | [`/api/v1/client/vps/{uuid}`](#op-get-api-v1-client-vps-uuid) | Get VPS instance details including template metadata |
| GET | [`/api/v1/client/vps/{uuid}/backups`](#op-get-api-v1-client-vps-uuid-backups) | List backups for this instance |
| POST | [`/api/v1/client/vps/{uuid}/backups`](#op-post-api-v1-client-vps-uuid-backups) | Create a new backup of this instance |
| DELETE | [`/api/v1/client/vps/{uuid}/backups/{backup_id}`](#op-delete-api-v1-client-vps-uuid-backups-backup-id) | Delete a backup |
| POST | [`/api/v1/client/vps/{uuid}/backups/{backup_id}/restore`](#op-post-api-v1-client-vps-uuid-backups-backup-id-restore) | Restore from a backup |
| GET | [`/api/v1/client/vps/{uuid}/bandwidth`](#op-get-api-v1-client-vps-uuid-bandwidth) | Get current billing period bandwidth usage vs plan traffic allotment (TB) |
| POST | [`/api/v1/client/vps/{uuid}/cloud-init/regenerate`](#op-post-api-v1-client-vps-uuid-cloud-init-regenerate) | Regenerate cloud init |
| GET | [`/api/v1/client/vps/{uuid}/config`](#op-get-api-v1-client-vps-uuid-config) | Get instance config |
| GET | [`/api/v1/client/vps/{uuid}/console`](#op-get-api-v1-client-vps-uuid-console) | Mint a VNC console session (WebSocket path + RFB password) |
| GET | [`/api/v1/client/vps/{uuid}/credentials`](#op-get-api-v1-client-vps-uuid-credentials) | Username + whether a password is stored (no plaintext) |
| GET | [`/api/v1/client/vps/{uuid}/graphs`](#op-get-api-v1-client-vps-uuid-graphs) | Get RRD graph data from Proxmox |
| GET | [`/api/v1/client/vps/{uuid}/guest`](#op-get-api-v1-client-vps-uuid-guest) | Get guest info |
| PATCH | [`/api/v1/client/vps/{uuid}/hostname`](#op-patch-api-v1-client-vps-uuid-hostname) | Patch hostname |
| GET | [`/api/v1/client/vps/{uuid}/ips`](#op-get-api-v1-client-vps-uuid-ips) | Get instance IPs |
| POST | [`/api/v1/client/vps/{uuid}/name`](#op-post-api-v1-client-vps-uuid-name) | Name instance |
| POST | [`/api/v1/client/vps/{uuid}/power`](#op-post-api-v1-client-vps-uuid-power) | Execute a power action on the VPS |
| GET | [`/api/v1/client/vps/{uuid}/ptr`](#op-get-api-v1-client-vps-uuid-ptr) | Reverse DNS of every address attached to the instance |
| PATCH | [`/api/v1/client/vps/{uuid}/ptr`](#op-patch-api-v1-client-vps-uuid-ptr) | Set the reverse DNS of one attached address (the primary by default) |
| POST | [`/api/v1/client/vps/{uuid}/rebuild`](#op-post-api-v1-client-vps-uuid-rebuild) | Rebuild the VPS with a new OS template |
| POST | [`/api/v1/client/vps/{uuid}/rescue/enter`](#op-post-api-v1-client-vps-uuid-rescue-enter) | Rescue enter |
| POST | [`/api/v1/client/vps/{uuid}/rescue/exit`](#op-post-api-v1-client-vps-uuid-rescue-exit) | Rescue exit |
| GET | [`/api/v1/client/vps/{uuid}/rescue/media`](#op-get-api-v1-client-vps-uuid-rescue-media) | Rescue media |
| POST | [`/api/v1/client/vps/{uuid}/reset-password`](#op-post-api-v1-client-vps-uuid-reset-password) | Reset the root/admin password |
| POST | [`/api/v1/client/vps/{uuid}/resize-preview`](#op-post-api-v1-client-vps-uuid-resize-preview) | Capacity/mode preview for a plan change resize (billing via /services change-plan) |
| GET | [`/api/v1/client/vps/{uuid}/snapshots`](#op-get-api-v1-client-vps-uuid-snapshots) | List snapshots |
| POST | [`/api/v1/client/vps/{uuid}/snapshots`](#op-post-api-v1-client-vps-uuid-snapshots) | Create snapshot |
| DELETE | [`/api/v1/client/vps/{uuid}/snapshots/{snapshot_id}`](#op-delete-api-v1-client-vps-uuid-snapshots-snapshot-id) | Delete snapshot |
| POST | [`/api/v1/client/vps/{uuid}/snapshots/{snapshot_id}/rollback`](#op-post-api-v1-client-vps-uuid-snapshots-snapshot-id-rollback) | Rollback snapshot |
| PUT | [`/api/v1/client/vps/{uuid}/ssh-keys`](#op-put-api-v1-client-vps-uuid-ssh-keys) | Put SSH keys |
| GET | [`/api/v1/client/vps/{uuid}/status`](#op-get-api-v1-client-vps-uuid-status) | Get real-time VM status from Proxmox (enriched) |
| GET | [`/api/v1/client/vps/{uuid}/tasks`](#op-get-api-v1-client-vps-uuid-tasks) | Get instance tasks |

### List all VPS instances owned by the current user {#op-get-api-v1-client-vps}

`GET /api/v1/client/vps`

List all VPS instances owned by the current user.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tag` | query | string or null | no |

#### Responses

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

### OS templates ready for order/rebuild: enabled and ready on at least one active node {#op-get-api-v1-client-vps-templates}

`GET /api/v1/client/vps/templates`

OS templates ready for order/rebuild: enabled and ready on at least one active node.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get VPS instance details including template metadata {#op-get-api-v1-client-vps-uuid}

`GET /api/v1/client/vps/{uuid}`

Get VPS instance details including template metadata.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### List backups for this instance {#op-get-api-v1-client-vps-uuid-backups}

`GET /api/v1/client/vps/{uuid}/backups`

List backups for this instance.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create a new backup of this instance {#op-post-api-v1-client-vps-uuid-backups}

`POST /api/v1/client/vps/{uuid}/backups`

Create a new backup of this instance.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `note` | string or null | no |
| `mode` | string | no |
| `compress` | string | no |

#### Responses

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

### Delete a backup {#op-delete-api-v1-client-vps-uuid-backups-backup-id}

`DELETE /api/v1/client/vps/{uuid}/backups/{backup_id}`

Delete a backup.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_id` | path | integer | yes |

#### Responses

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

### Restore from a backup {#op-post-api-v1-client-vps-uuid-backups-backup-id-restore}

`POST /api/v1/client/vps/{uuid}/backups/{backup_id}/restore`

Restore from a backup. This will restart the VPS.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_id` | path | integer | yes |

#### Responses

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

### Get current billing period bandwidth usage vs plan traffic allotment (TB) {#op-get-api-v1-client-vps-uuid-bandwidth}

`GET /api/v1/client/vps/{uuid}/bandwidth`

Get current billing period bandwidth usage vs plan traffic allotment (TB).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Regenerate cloud init {#op-post-api-v1-client-vps-uuid-cloud-init-regenerate}

`POST /api/v1/client/vps/{uuid}/cloud-init/regenerate`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Get instance config {#op-get-api-v1-client-vps-uuid-config}

`GET /api/v1/client/vps/{uuid}/config`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Mint a VNC console session (WebSocket path + RFB password) {#op-get-api-v1-client-vps-uuid-console}

`GET /api/v1/client/vps/{uuid}/console`

Mint a VNC console session (WebSocket path + RFB password).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Username + whether a password is stored (no plaintext) {#op-get-api-v1-client-vps-uuid-credentials}

`GET /api/v1/client/vps/{uuid}/credentials`

Username + whether a password is stored (no plaintext).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Get RRD graph data from Proxmox {#op-get-api-v1-client-vps-uuid-graphs}

`GET /api/v1/client/vps/{uuid}/graphs`

Get RRD graph data from Proxmox.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `timeframe` | query | string | no | Default: `hour`. |

#### Responses

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

### Get guest info {#op-get-api-v1-client-vps-uuid-guest}

`GET /api/v1/client/vps/{uuid}/guest`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Patch hostname {#op-patch-api-v1-client-vps-uuid-hostname}

`PATCH /api/v1/client/vps/{uuid}/hostname`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |
| `reboot` | boolean | no |

#### Responses

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

### Get instance IPs {#op-get-api-v1-client-vps-uuid-ips}

`GET /api/v1/client/vps/{uuid}/ips`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Name instance {#op-post-api-v1-client-vps-uuid-name}

`POST /api/v1/client/vps/{uuid}/name`

Give the instance a name in a zone the customer holds: A and AAAA
records for its addresses, optionally the same name as reverse DNS and as
the guest hostname.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |
| `set_ptr` | boolean | no |
| `set_hostname` | boolean | no |

#### Responses

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

### Execute a power action on the VPS {#op-post-api-v1-client-vps-uuid-power}

`POST /api/v1/client/vps/{uuid}/power`

Execute a power action on the VPS.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `action` | string | yes |

#### Responses

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

### Reverse DNS of every address attached to the instance {#op-get-api-v1-client-vps-uuid-ptr}

`GET /api/v1/client/vps/{uuid}/ptr`

Reverse DNS of every address attached to the instance.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Set the reverse DNS of one attached address (the primary by default) {#op-patch-api-v1-client-vps-uuid-ptr}

`PATCH /api/v1/client/vps/{uuid}/ptr`

Set the reverse DNS of one attached address (the primary by default).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |
| `address` | string or null | no |

#### Responses

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

### Rebuild the VPS with a new OS template {#op-post-api-v1-client-vps-uuid-rebuild}

`POST /api/v1/client/vps/{uuid}/rebuild`

Rebuild the VPS with a new OS template. This destroys all data.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

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

#### Responses

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

### Rescue enter {#op-post-api-v1-client-vps-uuid-rescue-enter}

`POST /api/v1/client/vps/{uuid}/rescue/enter`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `iso_volid` | string | yes |

#### Responses

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

### Rescue exit {#op-post-api-v1-client-vps-uuid-rescue-exit}

`POST /api/v1/client/vps/{uuid}/rescue/exit`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Rescue media {#op-get-api-v1-client-vps-uuid-rescue-media}

`GET /api/v1/client/vps/{uuid}/rescue/media`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Reset the root/admin password {#op-post-api-v1-client-vps-uuid-reset-password}

`POST /api/v1/client/vps/{uuid}/reset-password`

Reset the root/admin password. Requires QEMU guest agent.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Capacity/mode preview for a plan change resize (billing via /services change-plan) {#op-post-api-v1-client-vps-uuid-resize-preview}

`POST /api/v1/client/vps/{uuid}/resize-preview`

Capacity/mode preview for a plan change resize (billing via /services change-plan).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `cpu_cores` | integer or null | no |
| `memory_mb` | integer or null | no |
| `disk_gb` | integer or null | no |

#### Responses

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

### List snapshots {#op-get-api-v1-client-vps-uuid-snapshots}

`GET /api/v1/client/vps/{uuid}/snapshots`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create snapshot {#op-post-api-v1-client-vps-uuid-snapshots}

`POST /api/v1/client/vps/{uuid}/snapshots`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `description` | string or null | no |
| `vmstate` | boolean | no |

#### Responses

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

### Delete snapshot {#op-delete-api-v1-client-vps-uuid-snapshots-snapshot-id}

`DELETE /api/v1/client/vps/{uuid}/snapshots/{snapshot_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_id` | path | integer | yes |

#### Responses

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

### Rollback snapshot {#op-post-api-v1-client-vps-uuid-snapshots-snapshot-id-rollback}

`POST /api/v1/client/vps/{uuid}/snapshots/{snapshot_id}/rollback`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_id` | path | integer | yes |

#### Responses

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

### Put SSH keys {#op-put-api-v1-client-vps-uuid-ssh-keys}

`PUT /api/v1/client/vps/{uuid}/ssh-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `ssh_keys` | string | no |

#### Responses

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

### Get real-time VM status from Proxmox (enriched) {#op-get-api-v1-client-vps-uuid-status}

`GET /api/v1/client/vps/{uuid}/status`

Get real-time VM status from Proxmox (enriched).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Get instance tasks {#op-get-api-v1-client-vps-uuid-tasks}

`GET /api/v1/client/vps/{uuid}/tasks`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

# Client API: Floating IPs

> Allocate and attach floating IPs to eligible services.

Source: https://www.coritan.com/docs/api/reference/client/floating-ips/

Allocate and attach floating IPs to eligible services.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/ips`](#op-get-api-v1-client-ips) | List account-owned floating IP / subnet services and attachment state |
| GET | [`/api/v1/client/ips/attach-targets`](#op-get-api-v1-client-ips-attach-targets) | Thin list of owned compute services eligible as floating-IP attach targets |
| GET | [`/api/v1/client/ips/orders`](#op-get-api-v1-client-ips-orders) | Open platform IP order intents for resume after login or a new tab |
| GET | [`/api/v1/client/ips/orders/{idempotency_key}`](#op-get-api-v1-client-ips-orders-idempotency-key) | Get my IP order |
| POST | [`/api/v1/client/ips/orders/{idempotency_key}/cancel`](#op-post-api-v1-client-ips-orders-idempotency-key-cancel) | Cancel my IP order |
| GET | [`/api/v1/client/ips/pools`](#op-get-api-v1-client-ips-pools) | Active geo pools with sellable stock for ordering |
| GET | [`/api/v1/client/ips/{service_id}`](#op-get-api-v1-client-ips-service-id) | Get my IP |
| POST | [`/api/v1/client/ips/{service_id}/attach`](#op-post-api-v1-client-ips-service-id-attach) | Attach IP |
| POST | [`/api/v1/client/ips/{service_id}/detach`](#op-post-api-v1-client-ips-service-id-detach) | Detach IP (or one subnet host) from its compute target; service remains on your account |
| GET | [`/api/v1/client/ips/{service_id}/hosts`](#op-get-api-v1-client-ips-service-id-hosts) | Host map for a rented subnet service |
| GET | [`/api/v1/client/ips/{service_id}/ptr`](#op-get-api-v1-client-ips-service-id-ptr) | Get PTR |
| PATCH | [`/api/v1/client/ips/{service_id}/ptr`](#op-patch-api-v1-client-ips-service-id-ptr) | Set PTR |

### List account-owned floating IP / subnet services and attachment state {#op-get-api-v1-client-ips}

`GET /api/v1/client/ips`

List account-owned floating IP / subnet services and attachment state.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Thin list of owned compute services eligible as floating-IP attach targets {#op-get-api-v1-client-ips-attach-targets}

`GET /api/v1/client/ips/attach-targets`

Thin list of owned compute services eligible as floating-IP attach targets.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Open platform IP order intents for resume after login or a new tab {#op-get-api-v1-client-ips-orders}

`GET /api/v1/client/ips/orders`

Open platform IP order intents for resume after login or a new tab.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get my IP order {#op-get-api-v1-client-ips-orders-idempotency-key}

`GET /api/v1/client/ips/orders/{idempotency_key}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Cancel my IP order {#op-post-api-v1-client-ips-orders-idempotency-key-cancel}

`POST /api/v1/client/ips/orders/{idempotency_key}/cancel`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Active geo pools with sellable stock for ordering {#op-get-api-v1-client-ips-pools}

`GET /api/v1/client/ips/pools`

Active geo pools with sellable stock for ordering.
Pass chosen pool `id` as config.pool_id when calling POST /services/order.
Prefer ``region`` matching the compute ``config.location`` airport code.
When subnet rental is disabled, block prefix queries return an empty list.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `version` | query | string | no | Default: `ipv4`. |
| `prefix_len` | query | integer or null | no | 32 (default) = floating /32 stock; 24–29 = block stock |
| `region` | query | string or null | no | Airport-code location filter (iad, fra, lhr, pdx, sin) |

#### Responses

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

### Get my IP {#op-get-api-v1-client-ips-service-id}

`GET /api/v1/client/ips/{service_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Attach IP {#op-post-api-v1-client-ips-service-id-attach}

`POST /api/v1/client/ips/{service_id}/attach`

Attach this IP (or a host from a rented subnet) to one of your compute
services (vps|container).

For subnet services, pass ``host_address`` / ``host_inventory_id``, or omit
both to attach the first free (lowest) host. For VPS targets, programs
Proxmox cloud-init ``ipconfig0`` (routed /32 + block gateway). For container
targets, places the /32 on the Wings host, remaps the server's published
ports onto it, re-points its gameproxy routes and restarts a running server;
the response carries a ``publish`` block describing what happened.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `target_type` | string | yes | vps \| container |
| `target_service_id` | integer | yes | Platform service id of the compute target |
| `host_address` | string or null | no | Host IP within a rented subnet; omit to attach first free host |
| `host_inventory_id` | integer or null | no | Alternative to host_address: inventory id of the host row |
| `is_primary` | boolean or null | no | For VPS multi-IP: set as primary (ipconfig0). Default: primary if none yet. |

#### Responses

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

### Detach IP (or one subnet host) from its compute target; service remains on your account {#op-post-api-v1-client-ips-service-id-detach}

`POST /api/v1/client/ips/{service_id}/detach`

Detach IP (or one subnet host) from its compute target; service remains
on your account. For subnets with multiple attached hosts, pass host_address.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `host_address` | string or null | no |
| `host_inventory_id` | integer or null | no |

#### Responses

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

### Host map for a rented subnet service {#op-get-api-v1-client-ips-service-id-hosts}

`GET /api/v1/client/ips/{service_id}/hosts`

Host map for a rented subnet service.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Get PTR {#op-get-api-v1-client-ips-service-id-ptr}

`GET /api/v1/client/ips/{service_id}/ptr`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `host_address` | query | string or null | no |
| `host_inventory_id` | query | integer or null | no |

#### Responses

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

### Set PTR {#op-patch-api-v1-client-ips-service-id-ptr}

`PATCH /api/v1/client/ips/{service_id}/ptr`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |
| `host_address` | string or null | no |
| `host_inventory_id` | integer or null | no |

#### Responses

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

# Client API: Shield

> Client-facing DDoS scrubber status and attack events for your IPs.

Source: https://www.coritan.com/docs/api/reference/client/shield/

Client-facing DDoS scrubber status and attack events for your IPs.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/shield/events`](#op-get-api-v1-client-shield-events) | Recent attack events for this account's IP services |
| GET | [`/api/v1/client/shield/status`](#op-get-api-v1-client-shield-status) | Protection view for every assigned floating IP on this account |
| GET | [`/api/v1/client/shield/subjects/{ip_service_id}/profile`](#op-get-api-v1-client-shield-subjects-ip-service-id-profile) | The profile scrubbing this IP: the platform default, or its custom one |
| PATCH | [`/api/v1/client/shield/subjects/{ip_service_id}/profile`](#op-patch-api-v1-client-shield-subjects-ip-service-id-profile) | Ensure custom profile |
| POST | [`/api/v1/client/shield/subjects/{ip_service_id}/rules`](#op-post-api-v1-client-shield-subjects-ip-service-id-rules) | Create subject rule |
| DELETE | [`/api/v1/client/shield/subjects/{ip_service_id}/rules/{rule_id}`](#op-delete-api-v1-client-shield-subjects-ip-service-id-rules-rule-id) | Delete subject rule |

### Recent attack events for this account's IP services {#op-get-api-v1-client-shield-events}

`GET /api/v1/client/shield/events`

Recent attack events for this account's IP services.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

### Protection view for every assigned floating IP on this account {#op-get-api-v1-client-shield-status}

`GET /api/v1/client/shield/status`

Protection view for every assigned floating IP on this account.

Unattached IPs remain scrubbed (platform default).

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### The profile scrubbing this IP: the platform default, or its custom one {#op-get-api-v1-client-shield-subjects-ip-service-id-profile}

`GET /api/v1/client/shield/subjects/{ip_service_id}/profile`

The profile scrubbing this IP: the platform default, or its custom one.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |

#### Responses

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

### Ensure custom profile {#op-patch-api-v1-client-shield-subjects-ip-service-id-profile}

`PATCH /api/v1/client/shield/subjects/{ip_service_id}/profile`

Promote the subject to a customer-editable custom profile (idempotent),
then apply any tuning in the body.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `protection_mode` | string or null | no |
| `default_action` | string or null | no |
| `established_passthrough` | boolean or null | no |
| `rate_limits` | RateLimitsPatch or null | no |
| `rate_limits.per_source_pps` | integer or null | no |
| `rate_limits.aggregate_pps` | integer or null | no |
| `rate_limits.syn_pps_per_source` | integer or null | no |
| `rate_limits.icmp_pps_per_source` | integer or null | no |

#### Responses

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

### Create subject rule {#op-post-api-v1-client-shield-subjects-ip-service-id-rules}

`POST /api/v1/client/shield/subjects/{ip_service_id}/rules`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | no |
| `enabled` | boolean | no |
| `action` | string | no |
| `protocol` | integer or null | no |
| `src_prefix` | string or null | no |
| `dst_prefix` | string or null | no |
| `src_port_min` | integer or null | no |
| `src_port_max` | integer or null | no |
| `dst_port_min` | integer or null | no |
| `dst_port_max` | integer or null | no |
| `tcp_flags_mask` | integer or null | no |
| `tcp_flags_value` | integer or null | no |
| `packet_len_min` | integer or null | no |
| `packet_len_max` | integer or null | no |
| `ttl_min` | integer or null | no |
| `ttl_max` | integer or null | no |
| `icmp_type` | integer or null | no |
| `icmp_code` | integer or null | no |
| `rate_limit_pps` | integer or null | no |
| `notes` | string or null | no |

#### Responses

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

### Delete subject rule {#op-delete-api-v1-client-shield-subjects-ip-service-id-rules-rule-id}

`DELETE /api/v1/client/shield/subjects/{ip_service_id}/rules/{rule_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |
| `rule_id` | path | integer | yes |

#### Responses

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

# Client API: Object Storage

> S3-compatible buckets, access keys, objects and usage for Object Storage services.

Source: https://www.coritan.com/docs/api/reference/client/object-storage/

S3-compatible buckets, access keys, objects and usage for Object Storage services.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/object-storage/regions`](#op-get-api-v1-client-object-storage-regions) | Regions with a gateway to put a bucket in, with each one's endpoint |
| GET | [`/api/v1/client/object-storage/services`](#op-get-api-v1-client-object-storage-services) | The account's object storage services with their headline numbers |
| GET | [`/api/v1/client/object-storage/{service_id}`](#op-get-api-v1-client-object-storage-service-id) | Get service |
| GET | [`/api/v1/client/object-storage/{service_id}/buckets`](#op-get-api-v1-client-object-storage-service-id-buckets) | List buckets |
| POST | [`/api/v1/client/object-storage/{service_id}/buckets`](#op-post-api-v1-client-object-storage-service-id-buckets) | Make a bucket in the chosen region, or the service's home region |
| GET | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}`](#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id) | Get bucket |
| DELETE | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}`](#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id) | Remove a bucket |
| GET | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects`](#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id-objects) | One page of the bucket under prefix, folders first |
| DELETE | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects`](#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id-objects) | Delete named objects |
| POST | [`/api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/presign`](#op-post-api-v1-client-object-storage-service-id-buckets-bucket-id-objects-presign) | A short-lived URL the browser uses directly for one GET, PUT or DELETE |
| GET | [`/api/v1/client/object-storage/{service_id}/keys`](#op-get-api-v1-client-object-storage-service-id-keys) | List keys |
| POST | [`/api/v1/client/object-storage/{service_id}/keys`](#op-post-api-v1-client-object-storage-service-id-keys) | Issue a key |
| DELETE | [`/api/v1/client/object-storage/{service_id}/keys/{key_id}`](#op-delete-api-v1-client-object-storage-service-id-keys-key-id) | Revoke key |
| GET | [`/api/v1/client/object-storage/{service_id}/usage`](#op-get-api-v1-client-object-storage-service-id-usage) | Stored bytes and objects over time, as the hourly meter recorded them |

### Regions with a gateway to put a bucket in, with each one's endpoint {#op-get-api-v1-client-object-storage-regions}

`GET /api/v1/client/object-storage/regions`

Regions with a gateway to put a bucket in, with each one's endpoint.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `regions` | array of RegionOut |
| `regions[].id` | integer |
| `regions[].code` | string |
| `regions[].name` | string |
| `regions[].country_code` | string or null |
| `regions[].endpoint` | string |

### The account's object storage services with their headline numbers {#op-get-api-v1-client-object-storage-services}

`GET /api/v1/client/object-storage/services`

The account's object storage services with their headline numbers.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `items` | array of ServiceItem |
| `items[].id` | integer |
| `items[].service_id` | integer |
| `items[].label` | string |
| `items[].hostname` | string or null |
| `items[].status` | string |
| `items[].product_name` | string or null |
| `items[].billing_cycle` | string or null |
| `items[].region` | string or null |
| `items[].location_id` | integer or null |
| `items[].namespace` | string |
| `items[].bucket_prefix` | string |
| `items[].quota_bytes` | integer or null |
| `items[].used_bytes` | integer |
| `items[].object_count` | integer |
| `items[].bucket_count` | integer |
| `items[].key_count` | integer |
| `items[].overage_per_gb_month` | number or null |
| `items[].created_at` | string or null |
| `items[].next_due_date` | string or null |
| `total` | integer |

### Get service {#op-get-api-v1-client-object-storage-service-id}

`GET /api/v1/client/object-storage/{service_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `service_id` | integer |
| `label` | string |
| `hostname` | string or null |
| `status` | string |
| `product_name` | string or null |
| `billing_cycle` | string or null |
| `region` | string or null |
| `location_id` | integer or null |
| `namespace` | string |
| `bucket_prefix` | string |
| `quota_bytes` | integer or null |
| `used_bytes` | integer |
| `object_count` | integer |
| `bucket_count` | integer |
| `key_count` | integer |
| `overage_per_gb_month` | number or null |
| `created_at` | string or null |
| `next_due_date` | string or null |
| `endpoints` | array of EndpointOut |
| `endpoints[].region` | string |
| `endpoints[].endpoint` | string |
| `overage_gb` | number |
| `grace_days` | integer |
| `max_buckets` | integer |
| `presign_max_seconds` | integer |

### List buckets {#op-get-api-v1-client-object-storage-service-id-buckets}

`GET /api/v1/client/object-storage/{service_id}/buckets`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `items` | array of BucketOut |
| `items[].id` | integer |
| `items[].name` | string |
| `items[].region` | string or null |
| `items[].location_id` | integer or null |
| `items[].location_name` | string or null |
| `items[].quota_bytes` | integer or null |
| `items[].used_bytes` | integer |
| `items[].object_count` | integer |
| `items[].usage_measured_at` | string or null |
| `items[].created_at` | string or null |
| `items[].deleted_at` | string or null |
| `items[].endpoint` | string or null |
| `items[].url` | string or null |
| `total` | integer |
| `bucket_prefix` | string |
| `max_buckets` | integer |

### Make a bucket in the chosen region, or the service's home region {#op-post-api-v1-client-object-storage-service-id-buckets}

`POST /api/v1/client/object-storage/{service_id}/buckets`

Make a bucket in the chosen region, or the service's home region.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `location_id` | integer or null | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `name` | string |
| `region` | string or null |
| `location_id` | integer or null |
| `location_name` | string or null |
| `quota_bytes` | integer or null |
| `used_bytes` | integer |
| `object_count` | integer |
| `usage_measured_at` | string or null |
| `created_at` | string or null |
| `deleted_at` | string or null |
| `endpoint` | string or null |
| `url` | string or null |

### Get bucket {#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id}

`GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `bucket_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `name` | string |
| `region` | string or null |
| `location_id` | integer or null |
| `location_name` | string or null |
| `quota_bytes` | integer or null |
| `used_bytes` | integer |
| `object_count` | integer |
| `usage_measured_at` | string or null |
| `created_at` | string or null |
| `deleted_at` | string or null |
| `endpoint` | string or null |
| `url` | string or null |

### Remove a bucket {#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id}

`DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}`

Remove a bucket. Refused while it holds objects unless ``force`` is set.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `bucket_id` | path | integer | yes |  |
| `force` | query | boolean | no | Destroy the objects in it as well Default: `False`. |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `ok` | boolean |
| `bucket` | string |
| `region` | string or null |
| `objects_destroyed` | integer |

### One page of the bucket under prefix, folders first {#op-get-api-v1-client-object-storage-service-id-buckets-bucket-id-objects}

`GET /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects`

One page of the bucket under ``prefix``, folders first.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `bucket_id` | path | integer | yes |  |
| `prefix` | query | string | no |  |
| `token` | query | string or null | no |  |
| `max_keys` | query | integer | no | Default: `200`. |
| `flat` | query | boolean | no | No folder collapsing: every key under the prefix Default: `False`. |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `items` | array of ObjectItem |
| `items[].key` | string |
| `items[].size` | integer or null |
| `items[].last_modified` | string or null |
| `items[].etag` | string or null |
| `items[].is_prefix` | boolean |
| `prefix` | string |
| `next_token` | string or null |

### Delete named objects {#op-delete-api-v1-client-object-storage-service-id-buckets-bucket-id-objects}

`DELETE /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects`

Delete named objects. Per-key failures are reported, not raised.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `bucket_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `keys` | array of string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `deleted` | integer |
| `errors` | array of object |

### A short-lived URL the browser uses directly for one GET, PUT or DELETE {#op-post-api-v1-client-object-storage-service-id-buckets-bucket-id-objects-presign}

`POST /api/v1/client/object-storage/{service_id}/buckets/{bucket_id}/objects/presign`

A short-lived URL the browser uses directly for one GET, PUT or DELETE.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `bucket_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `key` | string | yes |
| `op` | string, one of `get`, `put`, `delete` | yes |
| `content_type` | string or null | no |
| `expires` | integer or null | no |
| `download` | boolean | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `url` | string |
| `method` | string |
| `headers` | Headers |
| `expires_in` | integer |
| `expires_at` | string |

### List keys {#op-get-api-v1-client-object-storage-service-id-keys}

`GET /api/v1/client/object-storage/{service_id}/keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `items` | array of KeyOut |
| `items[].id` | integer |
| `items[].access_key_id` | string |
| `items[].label` | string |
| `items[].bucket_id` | integer or null |
| `items[].bucket_name` | string or null |
| `items[].scope` | string, one of `bucket`, `all` |
| `items[].mode` | string, one of `read`, `read_write` |
| `items[].actions` | array of string |
| `items[].is_active` | boolean |
| `items[].last_used_at` | string or null |
| `items[].created_at` | string or null |
| `total` | integer |

### Issue a key {#op-post-api-v1-client-object-storage-service-id-keys}

`POST /api/v1/client/object-storage/{service_id}/keys`

Issue a key. The secret is in this response and nowhere else after.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | yes |
| `bucket_id` | integer or null | no |
| `mode` | string, one of `read`, `read_write` | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `access_key_id` | string |
| `label` | string |
| `bucket_id` | integer or null |
| `bucket_name` | string or null |
| `scope` | string, one of `bucket`, `all` |
| `mode` | string, one of `read`, `read_write` |
| `actions` | array of string |
| `is_active` | boolean |
| `last_used_at` | string or null |
| `created_at` | string or null |
| `secret_key` | string |
| `endpoint` | string or null |
| `region` | string or null |
| `activation_note` | string |

### Revoke key {#op-delete-api-v1-client-object-storage-service-id-keys-key-id}

`DELETE /api/v1/client/object-storage/{service_id}/keys/{key_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `key_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `ok` | boolean |
| `access_key_id` | string |

### Stored bytes and objects over time, as the hourly meter recorded them {#op-get-api-v1-client-object-storage-service-id-usage}

`GET /api/v1/client/object-storage/{service_id}/usage`

Stored bytes and objects over time, as the hourly meter recorded them.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `quota_bytes` | integer or null |
| `used_bytes` | integer |
| `object_count` | integer |
| `bucket_count` | integer |
| `overage_gb` | number |
| `days` | integer |
| `series` | array of UsagePoint |
| `series[].measured_at` | string |
| `series[].bytes` | integer |
| `series[].objects` | integer |

# Client API: Mail

> Mail Hosting (domains, mailboxes, aliases), SMTP Relay (credentials, API keys, webhooks, suppressions, events) and the mail tenants an account owns.

Source: https://www.coritan.com/docs/api/reference/client/mail/

Mail Hosting (domains, mailboxes, aliases), SMTP Relay (credentials, API keys, webhooks, suppressions, events) and the mail tenants an account owns. Paths are under `/api/v1/client/mail`, `/api/v1/client/smtp-relay` and `/api/v1/client/platform-mail`.

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

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

## Pages in this area

| Page | Operations |
| --- | --- |
| [Mail](/docs/api/reference/client/mail/mail/) | 8 |
| [Aliases](/docs/api/reference/client/mail/mail-aliases/) | 3 |
| [Api keys](/docs/api/reference/client/mail/mail-api-keys/) | 3 |
| [Credentials](/docs/api/reference/client/mail/mail-credentials/) | 5 |
| [Domains](/docs/api/reference/client/mail/mail-domains/) | 6 |
| [Mailboxes](/docs/api/reference/client/mail/mail-mailboxes/) | 19 |
| [Suppressions](/docs/api/reference/client/mail/mail-suppressions/) | 3 |
| [Webhooks](/docs/api/reference/client/mail/mail-webhooks/) | 3 |
| [Platform mail](/docs/api/reference/client/mail/platform-mail/) | 7 |
| [Aliases](/docs/api/reference/client/mail/platform-mail-aliases/) | 3 |
| [Api keys](/docs/api/reference/client/mail/platform-mail-api-keys/) | 3 |
| [Credentials](/docs/api/reference/client/mail/platform-mail-credentials/) | 5 |
| [Domains](/docs/api/reference/client/mail/platform-mail-domains/) | 6 |
| [Mailboxes](/docs/api/reference/client/mail/platform-mail-mailboxes/) | 19 |
| [Suppressions](/docs/api/reference/client/mail/platform-mail-suppressions/) | 3 |
| [Webhooks](/docs/api/reference/client/mail/platform-mail-webhooks/) | 3 |
| [Smtp relay](/docs/api/reference/client/mail/smtp-relay/) | 8 |
| [Aliases](/docs/api/reference/client/mail/smtp-relay-aliases/) | 3 |
| [Api keys](/docs/api/reference/client/mail/smtp-relay-api-keys/) | 3 |
| [Credentials](/docs/api/reference/client/mail/smtp-relay-credentials/) | 5 |
| [Domains](/docs/api/reference/client/mail/smtp-relay-domains/) | 6 |
| [Mailboxes](/docs/api/reference/client/mail/smtp-relay-mailboxes/) | 19 |
| [Suppressions](/docs/api/reference/client/mail/smtp-relay-suppressions/) | 3 |
| [Webhooks](/docs/api/reference/client/mail/smtp-relay-webhooks/) | 3 |

# Client API: Mail: Mail

> The 8 Client API operations for mail.

Source: https://www.coritan.com/docs/api/reference/client/mail/mail/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/mail/services`](#op-get-api-v1-client-mail-services) | List services |
| GET | [`/api/v1/client/mail/{service_id}`](#op-get-api-v1-client-mail-service-id) | Get summary |
| PATCH | [`/api/v1/client/mail/{service_id}/category`](#op-patch-api-v1-client-mail-service-id-category) | Set category |
| GET | [`/api/v1/client/mail/{service_id}/events`](#op-get-api-v1-client-mail-service-id-events) | List events |
| POST | [`/api/v1/client/mail/{service_id}/limits/increase-request`](#op-post-api-v1-client-mail-service-id-limits-increase-request) | Request limit increase |
| POST | [`/api/v1/client/mail/{service_id}/messages`](#op-post-api-v1-client-mail-service-id-messages) | Send message |
| GET | [`/api/v1/client/mail/{service_id}/reputation`](#op-get-api-v1-client-mail-service-id-reputation) | Reputation report |
| GET | [`/api/v1/client/mail/{service_id}/usage`](#op-get-api-v1-client-mail-service-id-usage) | Usage report |

### List services {#op-get-api-v1-client-mail-services}

`GET /api/v1/client/mail/services`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get summary {#op-get-api-v1-client-mail-service-id}

`GET /api/v1/client/mail/{service_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Set category {#op-patch-api-v1-client-mail-service-id-category}

`PATCH /api/v1/client/mail/{service_id}/category`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `default_category` | string | yes |

#### Responses

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

### List events {#op-get-api-v1-client-mail-service-id-events}

`GET /api/v1/client/mail/{service_id}/events`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `category` | query | string or null | no |  |
| `recipient` | query | string or null | no |  |
| `hours` | query | integer | no | Default: `24`. |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

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

### Request limit increase {#op-post-api-v1-client-mail-service-id-limits-increase-request}

`POST /api/v1/client/mail/{service_id}/limits/increase-request`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requested_per_hour` | integer | yes |  |
| `reason` | string | no | What the relay sends and why the volume is going up |

#### Responses

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

### Send message {#op-post-api-v1-client-mail-service-id-messages}

`POST /api/v1/client/mail/{service_id}/messages`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from` | string | yes |
| `from_name` | string or null | no |
| `to` | array of string | yes |
| `cc` | array of string | no |
| `subject` | string | no |
| `text` | string or null | no |
| `html` | string or null | no |
| `reply_to` | string or null | no |
| `headers` | Headers | no |
| `category` | string or null | no |

#### Responses

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

### Reputation report {#op-get-api-v1-client-mail-service-id-reputation}

`GET /api/v1/client/mail/{service_id}/reputation`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

### Usage report {#op-get-api-v1-client-mail-service-id-usage}

`GET /api/v1/client/mail/{service_id}/usage`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

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

# Client API: Mail: Aliases

> The 3 Client API operations for aliases.

Source: https://www.coritan.com/docs/api/reference/client/mail/mail-aliases/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/mail/{service_id}/aliases`](#op-get-api-v1-client-mail-service-id-aliases) | List aliases |
| POST | [`/api/v1/client/mail/{service_id}/aliases`](#op-post-api-v1-client-mail-service-id-aliases) | Create alias |
| DELETE | [`/api/v1/client/mail/{service_id}/aliases/{account_id}`](#op-delete-api-v1-client-mail-service-id-aliases-account-id) | Delete alias |

### List aliases {#op-get-api-v1-client-mail-service-id-aliases}

`GET /api/v1/client/mail/{service_id}/aliases`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create alias {#op-post-api-v1-client-mail-service-id-aliases}

`POST /api/v1/client/mail/{service_id}/aliases`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `targets` | array of string | yes |

#### Responses

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

### Delete alias {#op-delete-api-v1-client-mail-service-id-aliases-account-id}

`DELETE /api/v1/client/mail/{service_id}/aliases/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Api keys

> The 3 Client API operations for api keys.

Source: https://www.coritan.com/docs/api/reference/client/mail/mail-api-keys/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/mail/{service_id}/api-keys`](#op-get-api-v1-client-mail-service-id-api-keys) | List API keys |
| POST | [`/api/v1/client/mail/{service_id}/api-keys`](#op-post-api-v1-client-mail-service-id-api-keys) | Create API key |
| DELETE | [`/api/v1/client/mail/{service_id}/api-keys/{key_id}`](#op-delete-api-v1-client-mail-service-id-api-keys-key-id) | Revoke API key |

### List API keys {#op-get-api-v1-client-mail-service-id-api-keys}

`GET /api/v1/client/mail/{service_id}/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create API key {#op-post-api-v1-client-mail-service-id-api-keys}

`POST /api/v1/client/mail/{service_id}/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

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

### Revoke API key {#op-delete-api-v1-client-mail-service-id-api-keys-key-id}

`DELETE /api/v1/client/mail/{service_id}/api-keys/{key_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `key_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Credentials

> The 5 Client API operations for credentials.

Source: https://www.coritan.com/docs/api/reference/client/mail/mail-credentials/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/mail/{service_id}/credentials`](#op-get-api-v1-client-mail-service-id-credentials) | List credentials |
| POST | [`/api/v1/client/mail/{service_id}/credentials`](#op-post-api-v1-client-mail-service-id-credentials) | Create credential |
| DELETE | [`/api/v1/client/mail/{service_id}/credentials/{account_id}`](#op-delete-api-v1-client-mail-service-id-credentials-account-id) | Delete credential |
| PATCH | [`/api/v1/client/mail/{service_id}/credentials/{account_id}/enabled`](#op-patch-api-v1-client-mail-service-id-credentials-account-id-enabled) | Credential enabled |
| POST | [`/api/v1/client/mail/{service_id}/credentials/{account_id}/rotate`](#op-post-api-v1-client-mail-service-id-credentials-account-id-rotate) | Rotate credential |

### List credentials {#op-get-api-v1-client-mail-service-id-credentials}

`GET /api/v1/client/mail/{service_id}/credentials`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create credential {#op-post-api-v1-client-mail-service-id-credentials}

`POST /api/v1/client/mail/{service_id}/credentials`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `label` | string | no |

#### Responses

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

### Delete credential {#op-delete-api-v1-client-mail-service-id-credentials-account-id}

`DELETE /api/v1/client/mail/{service_id}/credentials/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Credential enabled {#op-patch-api-v1-client-mail-service-id-credentials-account-id-enabled}

`PATCH /api/v1/client/mail/{service_id}/credentials/{account_id}/enabled`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Rotate credential {#op-post-api-v1-client-mail-service-id-credentials-account-id-rotate}

`POST /api/v1/client/mail/{service_id}/credentials/{account_id}/rotate`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Domains

> The 6 Client API operations for domains.

Source: https://www.coritan.com/docs/api/reference/client/mail/mail-domains/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/mail/{service_id}/domains`](#op-get-api-v1-client-mail-service-id-domains) | List domains |
| POST | [`/api/v1/client/mail/{service_id}/domains`](#op-post-api-v1-client-mail-service-id-domains) | Add domain |
| DELETE | [`/api/v1/client/mail/{service_id}/domains/{domain_id}`](#op-delete-api-v1-client-mail-service-id-domains-domain-id) | Remove domain |
| PATCH | [`/api/v1/client/mail/{service_id}/domains/{domain_id}/dmarc`](#op-patch-api-v1-client-mail-service-id-domains-domain-id-dmarc) | Set DMARC |
| GET | [`/api/v1/client/mail/{service_id}/domains/{domain_id}/records`](#op-get-api-v1-client-mail-service-id-domains-domain-id-records) | Domain records |
| POST | [`/api/v1/client/mail/{service_id}/domains/{domain_id}/verify`](#op-post-api-v1-client-mail-service-id-domains-domain-id-verify) | Verify domain |

### List domains {#op-get-api-v1-client-mail-service-id-domains}

`GET /api/v1/client/mail/{service_id}/domains`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Add domain {#op-post-api-v1-client-mail-service-id-domains}

`POST /api/v1/client/mail/{service_id}/domains`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `primary` | boolean | no |

#### Responses

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

### Remove domain {#op-delete-api-v1-client-mail-service-id-domains-domain-id}

`DELETE /api/v1/client/mail/{service_id}/domains/{domain_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Set DMARC {#op-patch-api-v1-client-mail-service-id-domains-domain-id-dmarc}

`PATCH /api/v1/client/mail/{service_id}/domains/{domain_id}/dmarc`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `stage` | string or null | no |
| `pinned` | boolean or null | no |

#### Responses

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

### Domain records {#op-get-api-v1-client-mail-service-id-domains-domain-id-records}

`GET /api/v1/client/mail/{service_id}/domains/{domain_id}/records`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Verify domain {#op-post-api-v1-client-mail-service-id-domains-domain-id-verify}

`POST /api/v1/client/mail/{service_id}/domains/{domain_id}/verify`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Mailboxes

> The 19 Client API operations for mailboxes.

Source: https://www.coritan.com/docs/api/reference/client/mail/mail-mailboxes/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/mail/{service_id}/mailboxes`](#op-get-api-v1-client-mail-service-id-mailboxes) | List mailboxes |
| POST | [`/api/v1/client/mail/{service_id}/mailboxes`](#op-post-api-v1-client-mail-service-id-mailboxes) | Create mailbox |
| DELETE | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}`](#op-delete-api-v1-client-mail-service-id-mailboxes-account-id) | Delete mailbox |
| GET | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords`](#op-get-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords) | Mailbox app passwords |
| POST | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords`](#op-post-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords) | Mailbox app password create |
| DELETE | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`](#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords-credenti) | Mailbox app password delete |
| PATCH | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/enabled`](#op-patch-api-v1-client-mail-service-id-mailboxes-account-id-enabled) | Mailbox enabled |
| GET | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports`](#op-get-api-v1-client-mail-service-id-mailboxes-account-id-imports) | Mailbox imports |
| POST | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports`](#op-post-api-v1-client-mail-service-id-mailboxes-account-id-imports) | Mailbox import start |
| POST | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports/oauth`](#op-post-api-v1-client-mail-service-id-mailboxes-account-id-imports-oauth) | Mailbox import sign in |
| POST | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports/upload`](#op-post-api-v1-client-mail-service-id-mailboxes-account-id-imports-upload) | Mailbox import upload |
| POST | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports/{import_id}/{action}`](#op-post-api-v1-client-mail-service-id-mailboxes-account-id-imports-import-id-action) | Mailbox import steer |
| POST | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/password`](#op-post-api-v1-client-mail-service-id-mailboxes-account-id-password) | Mailbox password |
| PATCH | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/quota`](#op-patch-api-v1-client-mail-service-id-mailboxes-account-id-quota) | Mailbox quota |
| GET | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions`](#op-get-api-v1-client-mail-service-id-mailboxes-account-id-sessions) | Mailbox sessions |
| DELETE | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions`](#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-sessions) | Mailbox sessions end |
| DELETE | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions/{session_id}`](#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-sessions-session-id) | Mailbox session end |
| POST | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/totp`](#op-post-api-v1-client-mail-service-id-mailboxes-account-id-totp) | Mailbox totp enable |
| DELETE | [`/api/v1/client/mail/{service_id}/mailboxes/{account_id}/totp`](#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-totp) | Mailbox totp disable |

### List mailboxes {#op-get-api-v1-client-mail-service-id-mailboxes}

`GET /api/v1/client/mail/{service_id}/mailboxes`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create mailbox {#op-post-api-v1-client-mail-service-id-mailboxes}

`POST /api/v1/client/mail/{service_id}/mailboxes`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `password` | string or null | no |
| `display_name` | string or null | no |
| `quota_bytes` | integer or null | no |

#### Responses

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

### Delete mailbox {#op-delete-api-v1-client-mail-service-id-mailboxes-account-id}

`DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox app passwords {#op-get-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords}

`GET /api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox app password create {#op-post-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords}

`POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

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

### Mailbox app password delete {#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-app-passwords-credenti}

`DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Mailbox enabled {#op-patch-api-v1-client-mail-service-id-mailboxes-account-id-enabled}

`PATCH /api/v1/client/mail/{service_id}/mailboxes/{account_id}/enabled`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Mailbox imports {#op-get-api-v1-client-mail-service-id-mailboxes-account-id-imports}

`GET /api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox import start {#op-post-api-v1-client-mail-service-id-mailboxes-account-id-imports}

`POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `preset` | string | no |
| `host` | string or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `folders` | array of string | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import sign in {#op-post-api-v1-client-mail-service-id-mailboxes-account-id-imports-oauth}

`POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports/oauth`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `provider` | string, one of `google`, `microsoft` | yes |
| `return_path` | string or null | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import upload {#op-post-api-v1-client-mail-service-id-mailboxes-account-id-imports-upload}

`POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports/upload`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |
| `kind` | string | no |
| `folder` | string | no |
| `cpanel_mailbox` | string | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import steer {#op-post-api-v1-client-mail-service-id-mailboxes-account-id-imports-import-id-action}

`POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/imports/{import_id}/{action}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `import_id` | path | integer | yes |
| `action` | path | string, one of `pause`, `resume`, `cancel` | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox password {#op-post-api-v1-client-mail-service-id-mailboxes-account-id-password}

`POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/password`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |

#### Responses

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

### Mailbox quota {#op-patch-api-v1-client-mail-service-id-mailboxes-account-id-quota}

`PATCH /api/v1/client/mail/{service_id}/mailboxes/{account_id}/quota`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

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

#### Responses

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

### Mailbox sessions {#op-get-api-v1-client-mail-service-id-mailboxes-account-id-sessions}

`GET /api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox sessions end {#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-sessions}

`DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox session end {#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-sessions-session-id}

`DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}/sessions/{session_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Mailbox totp enable {#op-post-api-v1-client-mail-service-id-mailboxes-account-id-totp}

`POST /api/v1/client/mail/{service_id}/mailboxes/{account_id}/totp`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox totp disable {#op-delete-api-v1-client-mail-service-id-mailboxes-account-id-totp}

`DELETE /api/v1/client/mail/{service_id}/mailboxes/{account_id}/totp`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Suppressions

> The 3 Client API operations for suppressions.

Source: https://www.coritan.com/docs/api/reference/client/mail/mail-suppressions/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/mail/{service_id}/suppressions`](#op-get-api-v1-client-mail-service-id-suppressions) | List suppressions |
| POST | [`/api/v1/client/mail/{service_id}/suppressions`](#op-post-api-v1-client-mail-service-id-suppressions) | Add suppression |
| DELETE | [`/api/v1/client/mail/{service_id}/suppressions/{suppression_id}`](#op-delete-api-v1-client-mail-service-id-suppressions-suppression-id) | Remove suppression |

### List suppressions {#op-get-api-v1-client-mail-service-id-suppressions}

`GET /api/v1/client/mail/{service_id}/suppressions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Add suppression {#op-post-api-v1-client-mail-service-id-suppressions}

`POST /api/v1/client/mail/{service_id}/suppressions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |

#### Responses

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

### Remove suppression {#op-delete-api-v1-client-mail-service-id-suppressions-suppression-id}

`DELETE /api/v1/client/mail/{service_id}/suppressions/{suppression_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `suppression_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Webhooks

> The 3 Client API operations for webhooks.

Source: https://www.coritan.com/docs/api/reference/client/mail/mail-webhooks/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/mail/{service_id}/webhooks`](#op-get-api-v1-client-mail-service-id-webhooks) | List webhooks |
| POST | [`/api/v1/client/mail/{service_id}/webhooks`](#op-post-api-v1-client-mail-service-id-webhooks) | Create webhook |
| DELETE | [`/api/v1/client/mail/{service_id}/webhooks/{webhook_id}`](#op-delete-api-v1-client-mail-service-id-webhooks-webhook-id) | Delete webhook |

### List webhooks {#op-get-api-v1-client-mail-service-id-webhooks}

`GET /api/v1/client/mail/{service_id}/webhooks`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create webhook {#op-post-api-v1-client-mail-service-id-webhooks}

`POST /api/v1/client/mail/{service_id}/webhooks`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `events` | array of string | no |

#### Responses

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

### Delete webhook {#op-delete-api-v1-client-mail-service-id-webhooks-webhook-id}

`DELETE /api/v1/client/mail/{service_id}/webhooks/{webhook_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `webhook_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Platform mail

> The 7 Client API operations for platform mail.

Source: https://www.coritan.com/docs/api/reference/client/mail/platform-mail/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-mail/{tenant_id}`](#op-get-api-v1-client-platform-mail-tenant-id) | Get summary |
| PATCH | [`/api/v1/client/platform-mail/{tenant_id}/category`](#op-patch-api-v1-client-platform-mail-tenant-id-category) | Set category |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/events`](#op-get-api-v1-client-platform-mail-tenant-id-events) | List events |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/limits/increase-request`](#op-post-api-v1-client-platform-mail-tenant-id-limits-increase-request) | Request limit increase |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/messages`](#op-post-api-v1-client-platform-mail-tenant-id-messages) | Send message |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/reputation`](#op-get-api-v1-client-platform-mail-tenant-id-reputation) | Reputation report |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/usage`](#op-get-api-v1-client-platform-mail-tenant-id-usage) | Usage report |

### Get summary {#op-get-api-v1-client-platform-mail-tenant-id}

`GET /api/v1/client/platform-mail/{tenant_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Set category {#op-patch-api-v1-client-platform-mail-tenant-id-category}

`PATCH /api/v1/client/platform-mail/{tenant_id}/category`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `default_category` | string | yes |

#### Responses

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

### List events {#op-get-api-v1-client-platform-mail-tenant-id-events}

`GET /api/v1/client/platform-mail/{tenant_id}/events`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |  |
| `category` | query | string or null | no |  |
| `recipient` | query | string or null | no |  |
| `hours` | query | integer | no | Default: `24`. |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

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

### Request limit increase {#op-post-api-v1-client-platform-mail-tenant-id-limits-increase-request}

`POST /api/v1/client/platform-mail/{tenant_id}/limits/increase-request`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requested_per_hour` | integer | yes |  |
| `reason` | string | no | What the relay sends and why the volume is going up |

#### Responses

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

### Send message {#op-post-api-v1-client-platform-mail-tenant-id-messages}

`POST /api/v1/client/platform-mail/{tenant_id}/messages`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from` | string | yes |
| `from_name` | string or null | no |
| `to` | array of string | yes |
| `cc` | array of string | no |
| `subject` | string | no |
| `text` | string or null | no |
| `html` | string or null | no |
| `reply_to` | string or null | no |
| `headers` | Headers | no |
| `category` | string or null | no |

#### Responses

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

### Reputation report {#op-get-api-v1-client-platform-mail-tenant-id-reputation}

`GET /api/v1/client/platform-mail/{tenant_id}/reputation`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

### Usage report {#op-get-api-v1-client-platform-mail-tenant-id-usage}

`GET /api/v1/client/platform-mail/{tenant_id}/usage`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

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

# Client API: Mail: Aliases

> The 3 Client API operations for aliases.

Source: https://www.coritan.com/docs/api/reference/client/mail/platform-mail-aliases/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/aliases`](#op-get-api-v1-client-platform-mail-tenant-id-aliases) | List aliases |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/aliases`](#op-post-api-v1-client-platform-mail-tenant-id-aliases) | Create alias |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/aliases/{account_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-aliases-account-id) | Delete alias |

### List aliases {#op-get-api-v1-client-platform-mail-tenant-id-aliases}

`GET /api/v1/client/platform-mail/{tenant_id}/aliases`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Create alias {#op-post-api-v1-client-platform-mail-tenant-id-aliases}

`POST /api/v1/client/platform-mail/{tenant_id}/aliases`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `targets` | array of string | yes |

#### Responses

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

### Delete alias {#op-delete-api-v1-client-platform-mail-tenant-id-aliases-account-id}

`DELETE /api/v1/client/platform-mail/{tenant_id}/aliases/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Api keys

> The 3 Client API operations for api keys.

Source: https://www.coritan.com/docs/api/reference/client/mail/platform-mail-api-keys/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/api-keys`](#op-get-api-v1-client-platform-mail-tenant-id-api-keys) | List API keys |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/api-keys`](#op-post-api-v1-client-platform-mail-tenant-id-api-keys) | Create API key |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/api-keys/{key_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-api-keys-key-id) | Revoke API key |

### List API keys {#op-get-api-v1-client-platform-mail-tenant-id-api-keys}

`GET /api/v1/client/platform-mail/{tenant_id}/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Create API key {#op-post-api-v1-client-platform-mail-tenant-id-api-keys}

`POST /api/v1/client/platform-mail/{tenant_id}/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

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

### Revoke API key {#op-delete-api-v1-client-platform-mail-tenant-id-api-keys-key-id}

`DELETE /api/v1/client/platform-mail/{tenant_id}/api-keys/{key_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `key_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Credentials

> The 5 Client API operations for credentials.

Source: https://www.coritan.com/docs/api/reference/client/mail/platform-mail-credentials/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/credentials`](#op-get-api-v1-client-platform-mail-tenant-id-credentials) | List credentials |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/credentials`](#op-post-api-v1-client-platform-mail-tenant-id-credentials) | Create credential |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-credentials-account-id) | Delete credential |
| PATCH | [`/api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}/enabled`](#op-patch-api-v1-client-platform-mail-tenant-id-credentials-account-id-enabled) | Credential enabled |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}/rotate`](#op-post-api-v1-client-platform-mail-tenant-id-credentials-account-id-rotate) | Rotate credential |

### List credentials {#op-get-api-v1-client-platform-mail-tenant-id-credentials}

`GET /api/v1/client/platform-mail/{tenant_id}/credentials`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Create credential {#op-post-api-v1-client-platform-mail-tenant-id-credentials}

`POST /api/v1/client/platform-mail/{tenant_id}/credentials`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `label` | string | no |

#### Responses

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

### Delete credential {#op-delete-api-v1-client-platform-mail-tenant-id-credentials-account-id}

`DELETE /api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Credential enabled {#op-patch-api-v1-client-platform-mail-tenant-id-credentials-account-id-enabled}

`PATCH /api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}/enabled`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Rotate credential {#op-post-api-v1-client-platform-mail-tenant-id-credentials-account-id-rotate}

`POST /api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}/rotate`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Domains

> The 6 Client API operations for domains.

Source: https://www.coritan.com/docs/api/reference/client/mail/platform-mail-domains/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/domains`](#op-get-api-v1-client-platform-mail-tenant-id-domains) | List domains |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/domains`](#op-post-api-v1-client-platform-mail-tenant-id-domains) | Add domain |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-domains-domain-id) | Remove domain |
| PATCH | [`/api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/dmarc`](#op-patch-api-v1-client-platform-mail-tenant-id-domains-domain-id-dmarc) | Set DMARC |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/records`](#op-get-api-v1-client-platform-mail-tenant-id-domains-domain-id-records) | Domain records |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/verify`](#op-post-api-v1-client-platform-mail-tenant-id-domains-domain-id-verify) | Verify domain |

### List domains {#op-get-api-v1-client-platform-mail-tenant-id-domains}

`GET /api/v1/client/platform-mail/{tenant_id}/domains`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Add domain {#op-post-api-v1-client-platform-mail-tenant-id-domains}

`POST /api/v1/client/platform-mail/{tenant_id}/domains`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `primary` | boolean | no |

#### Responses

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

### Remove domain {#op-delete-api-v1-client-platform-mail-tenant-id-domains-domain-id}

`DELETE /api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Set DMARC {#op-patch-api-v1-client-platform-mail-tenant-id-domains-domain-id-dmarc}

`PATCH /api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/dmarc`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `stage` | string or null | no |
| `pinned` | boolean or null | no |

#### Responses

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

### Domain records {#op-get-api-v1-client-platform-mail-tenant-id-domains-domain-id-records}

`GET /api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/records`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Verify domain {#op-post-api-v1-client-platform-mail-tenant-id-domains-domain-id-verify}

`POST /api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/verify`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Mailboxes

> The 19 Client API operations for mailboxes.

Source: https://www.coritan.com/docs/api/reference/client/mail/platform-mail-mailboxes/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes`](#op-get-api-v1-client-platform-mail-tenant-id-mailboxes) | List mailboxes |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes`](#op-post-api-v1-client-platform-mail-tenant-id-mailboxes) | Create mailbox |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id) | Delete mailbox |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords`](#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords) | Mailbox app passwords |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords`](#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords) | Mailbox app password create |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords/{credential_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords) | Mailbox app password delete |
| PATCH | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/enabled`](#op-patch-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-enabled) | Mailbox enabled |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports`](#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports) | Mailbox imports |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports`](#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports) | Mailbox import start |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/oauth`](#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-oauth) | Mailbox import sign in |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/upload`](#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-upload) | Mailbox import upload |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/{import_id}/{action}`](#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-import-i) | Mailbox import steer |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/password`](#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-password) | Mailbox password |
| PATCH | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/quota`](#op-patch-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-quota) | Mailbox quota |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions`](#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions) | Mailbox sessions |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions`](#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions) | Mailbox sessions end |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions/{session_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions-sessi) | Mailbox session end |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/totp`](#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-totp) | Mailbox totp enable |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/totp`](#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-totp) | Mailbox totp disable |

### List mailboxes {#op-get-api-v1-client-platform-mail-tenant-id-mailboxes}

`GET /api/v1/client/platform-mail/{tenant_id}/mailboxes`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Create mailbox {#op-post-api-v1-client-platform-mail-tenant-id-mailboxes}

`POST /api/v1/client/platform-mail/{tenant_id}/mailboxes`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `password` | string or null | no |
| `display_name` | string or null | no |
| `quota_bytes` | integer or null | no |

#### Responses

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

### Delete mailbox {#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id}

`DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox app passwords {#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords}

`GET /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox app password create {#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords}

`POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

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

### Mailbox app password delete {#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords}

`DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords/{credential_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `credential_id` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox enabled {#op-patch-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-enabled}

`PATCH /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/enabled`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Mailbox imports {#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports}

`GET /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox import start {#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports}

`POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `preset` | string | no |
| `host` | string or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `folders` | array of string | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import sign in {#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-oauth}

`POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/oauth`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `provider` | string, one of `google`, `microsoft` | yes |
| `return_path` | string or null | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import upload {#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-upload}

`POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/upload`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |
| `kind` | string | no |
| `folder` | string | no |
| `cpanel_mailbox` | string | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import steer {#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-import-i}

`POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/{import_id}/{action}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `import_id` | path | integer | yes |
| `action` | path | string, one of `pause`, `resume`, `cancel` | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox password {#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-password}

`POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/password`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |

#### Responses

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

### Mailbox quota {#op-patch-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-quota}

`PATCH /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/quota`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

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

#### Responses

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

### Mailbox sessions {#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions}

`GET /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox sessions end {#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions}

`DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox session end {#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions-sessi}

`DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions/{session_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `session_id` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox totp enable {#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-totp}

`POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/totp`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Mailbox totp disable {#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-totp}

`DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/totp`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Suppressions

> The 3 Client API operations for suppressions.

Source: https://www.coritan.com/docs/api/reference/client/mail/platform-mail-suppressions/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/suppressions`](#op-get-api-v1-client-platform-mail-tenant-id-suppressions) | List suppressions |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/suppressions`](#op-post-api-v1-client-platform-mail-tenant-id-suppressions) | Add suppression |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/suppressions/{suppression_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-suppressions-suppression-id) | Remove suppression |

### List suppressions {#op-get-api-v1-client-platform-mail-tenant-id-suppressions}

`GET /api/v1/client/platform-mail/{tenant_id}/suppressions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Add suppression {#op-post-api-v1-client-platform-mail-tenant-id-suppressions}

`POST /api/v1/client/platform-mail/{tenant_id}/suppressions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |

#### Responses

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

### Remove suppression {#op-delete-api-v1-client-platform-mail-tenant-id-suppressions-suppression-id}

`DELETE /api/v1/client/platform-mail/{tenant_id}/suppressions/{suppression_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `suppression_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Webhooks

> The 3 Client API operations for webhooks.

Source: https://www.coritan.com/docs/api/reference/client/mail/platform-mail-webhooks/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/platform-mail/{tenant_id}/webhooks`](#op-get-api-v1-client-platform-mail-tenant-id-webhooks) | List webhooks |
| POST | [`/api/v1/client/platform-mail/{tenant_id}/webhooks`](#op-post-api-v1-client-platform-mail-tenant-id-webhooks) | Create webhook |
| DELETE | [`/api/v1/client/platform-mail/{tenant_id}/webhooks/{webhook_id}`](#op-delete-api-v1-client-platform-mail-tenant-id-webhooks-webhook-id) | Delete webhook |

### List webhooks {#op-get-api-v1-client-platform-mail-tenant-id-webhooks}

`GET /api/v1/client/platform-mail/{tenant_id}/webhooks`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Responses

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

### Create webhook {#op-post-api-v1-client-platform-mail-tenant-id-webhooks}

`POST /api/v1/client/platform-mail/{tenant_id}/webhooks`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `events` | array of string | no |

#### Responses

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

### Delete webhook {#op-delete-api-v1-client-platform-mail-tenant-id-webhooks-webhook-id}

`DELETE /api/v1/client/platform-mail/{tenant_id}/webhooks/{webhook_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `webhook_id` | path | integer | yes |
| `tenant_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Smtp relay

> The 8 Client API operations for smtp relay.

Source: https://www.coritan.com/docs/api/reference/client/mail/smtp-relay/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/smtp-relay/services`](#op-get-api-v1-client-smtp-relay-services) | List services |
| GET | [`/api/v1/client/smtp-relay/{service_id}`](#op-get-api-v1-client-smtp-relay-service-id) | Get summary |
| PATCH | [`/api/v1/client/smtp-relay/{service_id}/category`](#op-patch-api-v1-client-smtp-relay-service-id-category) | Set category |
| GET | [`/api/v1/client/smtp-relay/{service_id}/events`](#op-get-api-v1-client-smtp-relay-service-id-events) | List events |
| POST | [`/api/v1/client/smtp-relay/{service_id}/limits/increase-request`](#op-post-api-v1-client-smtp-relay-service-id-limits-increase-request) | Request limit increase |
| POST | [`/api/v1/client/smtp-relay/{service_id}/messages`](#op-post-api-v1-client-smtp-relay-service-id-messages) | Send message |
| GET | [`/api/v1/client/smtp-relay/{service_id}/reputation`](#op-get-api-v1-client-smtp-relay-service-id-reputation) | Reputation report |
| GET | [`/api/v1/client/smtp-relay/{service_id}/usage`](#op-get-api-v1-client-smtp-relay-service-id-usage) | Usage report |

### List services {#op-get-api-v1-client-smtp-relay-services}

`GET /api/v1/client/smtp-relay/services`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get summary {#op-get-api-v1-client-smtp-relay-service-id}

`GET /api/v1/client/smtp-relay/{service_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Set category {#op-patch-api-v1-client-smtp-relay-service-id-category}

`PATCH /api/v1/client/smtp-relay/{service_id}/category`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `default_category` | string | yes |

#### Responses

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

### List events {#op-get-api-v1-client-smtp-relay-service-id-events}

`GET /api/v1/client/smtp-relay/{service_id}/events`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `category` | query | string or null | no |  |
| `recipient` | query | string or null | no |  |
| `hours` | query | integer | no | Default: `24`. |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

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

### Request limit increase {#op-post-api-v1-client-smtp-relay-service-id-limits-increase-request}

`POST /api/v1/client/smtp-relay/{service_id}/limits/increase-request`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requested_per_hour` | integer | yes |  |
| `reason` | string | no | What the relay sends and why the volume is going up |

#### Responses

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

### Send message {#op-post-api-v1-client-smtp-relay-service-id-messages}

`POST /api/v1/client/smtp-relay/{service_id}/messages`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from` | string | yes |
| `from_name` | string or null | no |
| `to` | array of string | yes |
| `cc` | array of string | no |
| `subject` | string | no |
| `text` | string or null | no |
| `html` | string or null | no |
| `reply_to` | string or null | no |
| `headers` | Headers | no |
| `category` | string or null | no |

#### Responses

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

### Reputation report {#op-get-api-v1-client-smtp-relay-service-id-reputation}

`GET /api/v1/client/smtp-relay/{service_id}/reputation`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

### Usage report {#op-get-api-v1-client-smtp-relay-service-id-usage}

`GET /api/v1/client/smtp-relay/{service_id}/usage`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

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

# Client API: Mail: Aliases

> The 3 Client API operations for aliases.

Source: https://www.coritan.com/docs/api/reference/client/mail/smtp-relay-aliases/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/smtp-relay/{service_id}/aliases`](#op-get-api-v1-client-smtp-relay-service-id-aliases) | List aliases |
| POST | [`/api/v1/client/smtp-relay/{service_id}/aliases`](#op-post-api-v1-client-smtp-relay-service-id-aliases) | Create alias |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/aliases/{account_id}`](#op-delete-api-v1-client-smtp-relay-service-id-aliases-account-id) | Delete alias |

### List aliases {#op-get-api-v1-client-smtp-relay-service-id-aliases}

`GET /api/v1/client/smtp-relay/{service_id}/aliases`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create alias {#op-post-api-v1-client-smtp-relay-service-id-aliases}

`POST /api/v1/client/smtp-relay/{service_id}/aliases`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `targets` | array of string | yes |

#### Responses

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

### Delete alias {#op-delete-api-v1-client-smtp-relay-service-id-aliases-account-id}

`DELETE /api/v1/client/smtp-relay/{service_id}/aliases/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Api keys

> The 3 Client API operations for api keys.

Source: https://www.coritan.com/docs/api/reference/client/mail/smtp-relay-api-keys/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/smtp-relay/{service_id}/api-keys`](#op-get-api-v1-client-smtp-relay-service-id-api-keys) | List API keys |
| POST | [`/api/v1/client/smtp-relay/{service_id}/api-keys`](#op-post-api-v1-client-smtp-relay-service-id-api-keys) | Create API key |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/api-keys/{key_id}`](#op-delete-api-v1-client-smtp-relay-service-id-api-keys-key-id) | Revoke API key |

### List API keys {#op-get-api-v1-client-smtp-relay-service-id-api-keys}

`GET /api/v1/client/smtp-relay/{service_id}/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create API key {#op-post-api-v1-client-smtp-relay-service-id-api-keys}

`POST /api/v1/client/smtp-relay/{service_id}/api-keys`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

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

### Revoke API key {#op-delete-api-v1-client-smtp-relay-service-id-api-keys-key-id}

`DELETE /api/v1/client/smtp-relay/{service_id}/api-keys/{key_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `key_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Credentials

> The 5 Client API operations for credentials.

Source: https://www.coritan.com/docs/api/reference/client/mail/smtp-relay-credentials/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/smtp-relay/{service_id}/credentials`](#op-get-api-v1-client-smtp-relay-service-id-credentials) | List credentials |
| POST | [`/api/v1/client/smtp-relay/{service_id}/credentials`](#op-post-api-v1-client-smtp-relay-service-id-credentials) | Create credential |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/credentials/{account_id}`](#op-delete-api-v1-client-smtp-relay-service-id-credentials-account-id) | Delete credential |
| PATCH | [`/api/v1/client/smtp-relay/{service_id}/credentials/{account_id}/enabled`](#op-patch-api-v1-client-smtp-relay-service-id-credentials-account-id-enabled) | Credential enabled |
| POST | [`/api/v1/client/smtp-relay/{service_id}/credentials/{account_id}/rotate`](#op-post-api-v1-client-smtp-relay-service-id-credentials-account-id-rotate) | Rotate credential |

### List credentials {#op-get-api-v1-client-smtp-relay-service-id-credentials}

`GET /api/v1/client/smtp-relay/{service_id}/credentials`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create credential {#op-post-api-v1-client-smtp-relay-service-id-credentials}

`POST /api/v1/client/smtp-relay/{service_id}/credentials`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `label` | string | no |

#### Responses

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

### Delete credential {#op-delete-api-v1-client-smtp-relay-service-id-credentials-account-id}

`DELETE /api/v1/client/smtp-relay/{service_id}/credentials/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Credential enabled {#op-patch-api-v1-client-smtp-relay-service-id-credentials-account-id-enabled}

`PATCH /api/v1/client/smtp-relay/{service_id}/credentials/{account_id}/enabled`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Rotate credential {#op-post-api-v1-client-smtp-relay-service-id-credentials-account-id-rotate}

`POST /api/v1/client/smtp-relay/{service_id}/credentials/{account_id}/rotate`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Domains

> The 6 Client API operations for domains.

Source: https://www.coritan.com/docs/api/reference/client/mail/smtp-relay-domains/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/smtp-relay/{service_id}/domains`](#op-get-api-v1-client-smtp-relay-service-id-domains) | List domains |
| POST | [`/api/v1/client/smtp-relay/{service_id}/domains`](#op-post-api-v1-client-smtp-relay-service-id-domains) | Add domain |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/domains/{domain_id}`](#op-delete-api-v1-client-smtp-relay-service-id-domains-domain-id) | Remove domain |
| PATCH | [`/api/v1/client/smtp-relay/{service_id}/domains/{domain_id}/dmarc`](#op-patch-api-v1-client-smtp-relay-service-id-domains-domain-id-dmarc) | Set DMARC |
| GET | [`/api/v1/client/smtp-relay/{service_id}/domains/{domain_id}/records`](#op-get-api-v1-client-smtp-relay-service-id-domains-domain-id-records) | Domain records |
| POST | [`/api/v1/client/smtp-relay/{service_id}/domains/{domain_id}/verify`](#op-post-api-v1-client-smtp-relay-service-id-domains-domain-id-verify) | Verify domain |

### List domains {#op-get-api-v1-client-smtp-relay-service-id-domains}

`GET /api/v1/client/smtp-relay/{service_id}/domains`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Add domain {#op-post-api-v1-client-smtp-relay-service-id-domains}

`POST /api/v1/client/smtp-relay/{service_id}/domains`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `primary` | boolean | no |

#### Responses

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

### Remove domain {#op-delete-api-v1-client-smtp-relay-service-id-domains-domain-id}

`DELETE /api/v1/client/smtp-relay/{service_id}/domains/{domain_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Set DMARC {#op-patch-api-v1-client-smtp-relay-service-id-domains-domain-id-dmarc}

`PATCH /api/v1/client/smtp-relay/{service_id}/domains/{domain_id}/dmarc`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `stage` | string or null | no |
| `pinned` | boolean or null | no |

#### Responses

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

### Domain records {#op-get-api-v1-client-smtp-relay-service-id-domains-domain-id-records}

`GET /api/v1/client/smtp-relay/{service_id}/domains/{domain_id}/records`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Verify domain {#op-post-api-v1-client-smtp-relay-service-id-domains-domain-id-verify}

`POST /api/v1/client/smtp-relay/{service_id}/domains/{domain_id}/verify`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Mailboxes

> The 19 Client API operations for mailboxes.

Source: https://www.coritan.com/docs/api/reference/client/mail/smtp-relay-mailboxes/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/smtp-relay/{service_id}/mailboxes`](#op-get-api-v1-client-smtp-relay-service-id-mailboxes) | List mailboxes |
| POST | [`/api/v1/client/smtp-relay/{service_id}/mailboxes`](#op-post-api-v1-client-smtp-relay-service-id-mailboxes) | Create mailbox |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}`](#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id) | Delete mailbox |
| GET | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords`](#op-get-api-v1-client-smtp-relay-service-id-mailboxes-account-id-app-passwords) | Mailbox app passwords |
| POST | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords`](#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-app-passwords) | Mailbox app password create |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`](#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id-app-passwords-cr) | Mailbox app password delete |
| PATCH | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/enabled`](#op-patch-api-v1-client-smtp-relay-service-id-mailboxes-account-id-enabled) | Mailbox enabled |
| GET | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports`](#op-get-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports) | Mailbox imports |
| POST | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports`](#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports) | Mailbox import start |
| POST | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports/oauth`](#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports-oauth) | Mailbox import sign in |
| POST | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports/upload`](#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports-upload) | Mailbox import upload |
| POST | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports/{import_id}/{action}`](#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports-import-id) | Mailbox import steer |
| POST | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/password`](#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-password) | Mailbox password |
| PATCH | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/quota`](#op-patch-api-v1-client-smtp-relay-service-id-mailboxes-account-id-quota) | Mailbox quota |
| GET | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/sessions`](#op-get-api-v1-client-smtp-relay-service-id-mailboxes-account-id-sessions) | Mailbox sessions |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/sessions`](#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id-sessions) | Mailbox sessions end |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/sessions/{session_id}`](#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id-sessions-session) | Mailbox session end |
| POST | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/totp`](#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-totp) | Mailbox totp enable |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/totp`](#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id-totp) | Mailbox totp disable |

### List mailboxes {#op-get-api-v1-client-smtp-relay-service-id-mailboxes}

`GET /api/v1/client/smtp-relay/{service_id}/mailboxes`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create mailbox {#op-post-api-v1-client-smtp-relay-service-id-mailboxes}

`POST /api/v1/client/smtp-relay/{service_id}/mailboxes`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `password` | string or null | no |
| `display_name` | string or null | no |
| `quota_bytes` | integer or null | no |

#### Responses

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

### Delete mailbox {#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id}

`DELETE /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox app passwords {#op-get-api-v1-client-smtp-relay-service-id-mailboxes-account-id-app-passwords}

`GET /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox app password create {#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-app-passwords}

`POST /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

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

### Mailbox app password delete {#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id-app-passwords-cr}

`DELETE /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Mailbox enabled {#op-patch-api-v1-client-smtp-relay-service-id-mailboxes-account-id-enabled}

`PATCH /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/enabled`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

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

### Mailbox imports {#op-get-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports}

`GET /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox import start {#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports}

`POST /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `preset` | string | no |
| `host` | string or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `folders` | array of string | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import sign in {#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports-oauth}

`POST /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports/oauth`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `provider` | string, one of `google`, `microsoft` | yes |
| `return_path` | string or null | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import upload {#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports-upload}

`POST /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports/upload`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |
| `kind` | string | no |
| `folder` | string | no |
| `cpanel_mailbox` | string | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

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

### Mailbox import steer {#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-imports-import-id}

`POST /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/imports/{import_id}/{action}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `import_id` | path | integer | yes |
| `action` | path | string, one of `pause`, `resume`, `cancel` | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox password {#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-password}

`POST /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/password`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |

#### Responses

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

### Mailbox quota {#op-patch-api-v1-client-smtp-relay-service-id-mailboxes-account-id-quota}

`PATCH /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/quota`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

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

#### Responses

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

### Mailbox sessions {#op-get-api-v1-client-smtp-relay-service-id-mailboxes-account-id-sessions}

`GET /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/sessions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox sessions end {#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id-sessions}

`DELETE /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/sessions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox session end {#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id-sessions-session}

`DELETE /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/sessions/{session_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Mailbox totp enable {#op-post-api-v1-client-smtp-relay-service-id-mailboxes-account-id-totp}

`POST /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/totp`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

### Mailbox totp disable {#op-delete-api-v1-client-smtp-relay-service-id-mailboxes-account-id-totp}

`DELETE /api/v1/client/smtp-relay/{service_id}/mailboxes/{account_id}/totp`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Suppressions

> The 3 Client API operations for suppressions.

Source: https://www.coritan.com/docs/api/reference/client/mail/smtp-relay-suppressions/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/smtp-relay/{service_id}/suppressions`](#op-get-api-v1-client-smtp-relay-service-id-suppressions) | List suppressions |
| POST | [`/api/v1/client/smtp-relay/{service_id}/suppressions`](#op-post-api-v1-client-smtp-relay-service-id-suppressions) | Add suppression |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/suppressions/{suppression_id}`](#op-delete-api-v1-client-smtp-relay-service-id-suppressions-suppression-id) | Remove suppression |

### List suppressions {#op-get-api-v1-client-smtp-relay-service-id-suppressions}

`GET /api/v1/client/smtp-relay/{service_id}/suppressions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Add suppression {#op-post-api-v1-client-smtp-relay-service-id-suppressions}

`POST /api/v1/client/smtp-relay/{service_id}/suppressions`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |

#### Responses

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

### Remove suppression {#op-delete-api-v1-client-smtp-relay-service-id-suppressions-suppression-id}

`DELETE /api/v1/client/smtp-relay/{service_id}/suppressions/{suppression_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `suppression_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail: Webhooks

> The 3 Client API operations for webhooks.

Source: https://www.coritan.com/docs/api/reference/client/mail/smtp-relay-webhooks/

Part of [Mail](/docs/api/reference/client/mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/smtp-relay/{service_id}/webhooks`](#op-get-api-v1-client-smtp-relay-service-id-webhooks) | List webhooks |
| POST | [`/api/v1/client/smtp-relay/{service_id}/webhooks`](#op-post-api-v1-client-smtp-relay-service-id-webhooks) | Create webhook |
| DELETE | [`/api/v1/client/smtp-relay/{service_id}/webhooks/{webhook_id}`](#op-delete-api-v1-client-smtp-relay-service-id-webhooks-webhook-id) | Delete webhook |

### List webhooks {#op-get-api-v1-client-smtp-relay-service-id-webhooks}

`GET /api/v1/client/smtp-relay/{service_id}/webhooks`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Responses

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

### Create webhook {#op-post-api-v1-client-smtp-relay-service-id-webhooks}

`POST /api/v1/client/smtp-relay/{service_id}/webhooks`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `events` | array of string | no |

#### Responses

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

### Delete webhook {#op-delete-api-v1-client-smtp-relay-service-id-webhooks-webhook-id}

`DELETE /api/v1/client/smtp-relay/{service_id}/webhooks/{webhook_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `webhook_id` | path | integer | yes |
| `service_id` | path | integer | yes |

#### Responses

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

# Client API: Mail Send API

> Send a message through an SMTP Relay service over HTTPS.

Source: https://www.coritan.com/docs/api/reference/client/mail-send-api/

Send a message through an SMTP Relay service over HTTPS. Authenticated with an SMTP Relay API key in `X-Api-Key`, not with an access token.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/mail/send`](#op-post-api-v1-mail-send) | Send |
| GET | [`/api/v1/mail/send/limits`](#op-get-api-v1-mail-send-limits) | Limits |
| GET | [`/api/v1/mail/unsubscribe/{token}`](#op-get-api-v1-mail-unsubscribe-token) | RFC 8058 target |
| POST | [`/api/v1/mail/unsubscribe/{token}`](#op-post-api-v1-mail-unsubscribe-token) | RFC 8058 target |

### Send {#op-post-api-v1-mail-send}

`POST /api/v1/mail/send`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `X-Api-Key` | header | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from` | string | yes |
| `from_name` | string or null | no |
| `to` | array of string | yes |
| `cc` | array of string | no |
| `subject` | string | no |
| `text` | string or null | no |
| `html` | string or null | no |
| `reply_to` | string or null | no |
| `headers` | Headers | no |
| `category` | string or null | no |

#### Responses

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

### Limits {#op-get-api-v1-mail-send-limits}

`GET /api/v1/mail/send/limits`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `X-Api-Key` | header | string or null | no |

#### Responses

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

### RFC 8058 target {#op-get-api-v1-mail-unsubscribe-token}

`GET /api/v1/mail/unsubscribe/{token}`

RFC 8058 target. Receivers POST here with ``List-Unsubscribe=One-Click``;
a person following the link gets the same result. Brand-neutral by
design: the token names the tenant and the addressee, nothing else.

#### Parameters

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

#### Responses

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

### RFC 8058 target {#op-post-api-v1-mail-unsubscribe-token}

`POST /api/v1/mail/unsubscribe/{token}`

RFC 8058 target. Receivers POST here with ``List-Unsubscribe=One-Click``;
a person following the link gets the same result. Brand-neutral by
design: the token names the tenant and the addressee, nothing else.

#### Parameters

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

#### Responses

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

# Client API: Support

> Conversational support chat (threads and messages).

Source: https://www.coritan.com/docs/api/reference/client/support/

Conversational support chat (threads and messages).

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/chat/conversations`](#op-get-api-v1-chat-conversations) | List user conversations |
| POST | [`/api/v1/chat/conversations`](#op-post-api-v1-chat-conversations) | Create user conversation |
| GET | [`/api/v1/chat/conversations/{conversation_id}`](#op-get-api-v1-chat-conversations-conversation-id) | Get user conversation |
| POST | [`/api/v1/chat/conversations/{conversation_id}/attachments`](#op-post-api-v1-chat-conversations-conversation-id-attachments) | Upload attachment |
| GET | [`/api/v1/chat/conversations/{conversation_id}/attachments/{attachment_id}`](#op-get-api-v1-chat-conversations-conversation-id-attachments-attachment-id) | Download attachment |
| GET | [`/api/v1/chat/conversations/{conversation_id}/attachments/{attachment_id}/thumbnail`](#op-get-api-v1-chat-conversations-conversation-id-attachments-attachment-id-thumbnai) | Download thumbnail |
| POST | [`/api/v1/chat/conversations/{conversation_id}/close`](#op-post-api-v1-chat-conversations-conversation-id-close) | Close user conversation |
| POST | [`/api/v1/chat/conversations/{conversation_id}/csat`](#op-post-api-v1-chat-conversations-conversation-id-csat) | Rate user conversation |
| GET | [`/api/v1/chat/conversations/{conversation_id}/messages`](#op-get-api-v1-chat-conversations-conversation-id-messages) | Get conversation messages |
| POST | [`/api/v1/chat/conversations/{conversation_id}/messages`](#op-post-api-v1-chat-conversations-conversation-id-messages) | Send user message |
| POST | [`/api/v1/chat/conversations/{conversation_id}/read`](#op-post-api-v1-chat-conversations-conversation-id-read) | Mark user conversation read |
| POST | [`/api/v1/chat/conversations/{conversation_id}/reopen`](#op-post-api-v1-chat-conversations-conversation-id-reopen) | Reopen user conversation |
| GET | [`/api/v1/chat/meta`](#op-get-api-v1-chat-meta) | Get support meta |

### List user conversations {#op-get-api-v1-chat-conversations}

`GET /api/v1/chat/conversations`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `status` | query | string | no |  |
| `priority` | query | string | no |  |
| `q` | query | string | no |  |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `20`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].conversation_number` | integer |
| `[].scope` | string |
| `[].subject` | string |
| `[].status` | string |
| `[].priority` | string |
| `[].department` | string or null |
| `[].assigned_agent_id` | integer or null |
| `[].assigned_agent_name` | string or null |
| `[].user_id` | integer or null |
| `[].user_email` | string or null |
| `[].user_name` | string or null |
| `[].customer_id` | integer or null |
| `[].channel` | string |
| `[].email_from` | string or null |
| `[].last_message_at` | string (date-time) or null |
| `[].last_message_preview` | string or null |
| `[].tags` | array of string or null |
| `[].unread_count` | integer |
| `[].waiting_seconds` | integer or null |
| `[].sla_first_response_due_at` | string (date-time) or null |
| `[].sla_resolution_due_at` | string (date-time) or null |
| `[].sla_breached_first_response` | boolean |
| `[].sla_breached_resolution` | boolean |
| `[].first_response_at` | string (date-time) or null |
| `[].csat_score` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |
| `[].is_free` | boolean or null |
| `[].viewers` | array of string |
| `[].escalated_tier` | integer or null |

### Create user conversation {#op-post-api-v1-chat-conversations}

`POST /api/v1/chat/conversations`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `subject` | string | yes |
| `department` | string or null | no |
| `priority` | string | no |
| `body` | string | yes |
| `service_id` | integer or null | no |
| `tags` | array of string or null | no |
| `client_request_id` | string or null | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Get user conversation {#op-get-api-v1-chat-conversations-conversation-id}

`GET /api/v1/chat/conversations/{conversation_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Upload attachment {#op-post-api-v1-chat-conversations-conversation-id-attachments}

`POST /api/v1/chat/conversations/{conversation_id}/attachments`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |

#### Responses

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

### Download attachment {#op-get-api-v1-chat-conversations-conversation-id-attachments-attachment-id}

`GET /api/v1/chat/conversations/{conversation_id}/attachments/{attachment_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `attachment_id` | path | integer | yes |

#### Responses

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

### Download thumbnail {#op-get-api-v1-chat-conversations-conversation-id-attachments-attachment-id-thumbnai}

`GET /api/v1/chat/conversations/{conversation_id}/attachments/{attachment_id}/thumbnail`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `attachment_id` | path | integer | yes |

#### Responses

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

### Close user conversation {#op-post-api-v1-chat-conversations-conversation-id-close}

`POST /api/v1/chat/conversations/{conversation_id}/close`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Rate user conversation {#op-post-api-v1-chat-conversations-conversation-id-csat}

`POST /api/v1/chat/conversations/{conversation_id}/csat`

Rating is only meaningful once the ticket is done, so it is refused
while the conversation is still open.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `score` | integer | yes |
| `comment` | string or null | no |

#### Responses

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

### Get conversation messages {#op-get-api-v1-chat-conversations-conversation-id-messages}

`GET /api/v1/chat/conversations/{conversation_id}/messages`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |  |
| `before_id` | query | integer | no |  |
| `after_id` | query | integer | no |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].conversation_id` | integer |
| `[].sender_type` | string |
| `[].sender_id` | integer or null |
| `[].sender_name` | string or null |
| `[].body` | string or null |
| `[].content_type` | string |
| `[].is_internal` | boolean |
| `[].attachments` | array of AttachmentResponse |
| `[].attachments[].id` | integer |
| `[].attachments[].file_name` | string |
| `[].attachments[].file_size` | integer |
| `[].attachments[].mime_type` | string |
| `[].attachments[].created_at` | string (date-time) |
| `[].read_at` | string (date-time) or null |
| `[].created_at` | string (date-time) |
| `[].client_request_id` | string or null |
| `[].request` | object or null |

### Send user message {#op-post-api-v1-chat-conversations-conversation-id-messages}

`POST /api/v1/chat/conversations/{conversation_id}/messages`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body` | string | yes |
| `client_request_id` | string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_id` | integer |
| `sender_type` | string |
| `sender_id` | integer or null |
| `sender_name` | string or null |
| `body` | string or null |
| `content_type` | string |
| `is_internal` | boolean |
| `attachments` | array of AttachmentResponse |
| `attachments[].id` | integer |
| `attachments[].file_name` | string |
| `attachments[].file_size` | integer |
| `attachments[].mime_type` | string |
| `attachments[].created_at` | string (date-time) |
| `read_at` | string (date-time) or null |
| `created_at` | string (date-time) |
| `client_request_id` | string or null |
| `request` | object or null |

### Mark user conversation read {#op-post-api-v1-chat-conversations-conversation-id-read}

`POST /api/v1/chat/conversations/{conversation_id}/read`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `up_to_message_id` | integer or null | no |

#### Responses

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

### Reopen user conversation {#op-post-api-v1-chat-conversations-conversation-id-reopen}

`POST /api/v1/chat/conversations/{conversation_id}/reopen`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Get support meta {#op-get-api-v1-chat-meta}

`GET /api/v1/chat/meta`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

# Client API: Authentication MFA

> Every Client API operation tagged Authentication MFA.

Source: https://www.coritan.com/docs/api/reference/client/authentication-mfa/

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/auth/mfa`](#op-get-api-v1-auth-mfa) | User MFA status |
| POST | [`/api/v1/auth/mfa/disable`](#op-post-api-v1-auth-mfa-disable) | User MFA disable |
| POST | [`/api/v1/auth/mfa/enable`](#op-post-api-v1-auth-mfa-enable) | User MFA enable |
| POST | [`/api/v1/auth/mfa/recovery-codes`](#op-post-api-v1-auth-mfa-recovery-codes) | User MFA regenerate recovery codes |
| POST | [`/api/v1/auth/mfa/setup`](#op-post-api-v1-auth-mfa-setup) | User MFA setup |
| POST | [`/api/v1/auth/mfa/verify`](#op-post-api-v1-auth-mfa-verify) | Second step of signing in |

### User MFA status {#op-get-api-v1-auth-mfa}

`GET /api/v1/auth/mfa`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### User MFA disable {#op-post-api-v1-auth-mfa-disable}

`POST /api/v1/auth/mfa/disable`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string | yes |
| `code` | string | yes |

#### Responses

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

### User MFA enable {#op-post-api-v1-auth-mfa-enable}

`POST /api/v1/auth/mfa/enable`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

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

### User MFA regenerate recovery codes {#op-post-api-v1-auth-mfa-recovery-codes}

`POST /api/v1/auth/mfa/recovery-codes`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

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

### User MFA setup {#op-post-api-v1-auth-mfa-setup}

`POST /api/v1/auth/mfa/setup`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Second step of signing in {#op-post-api-v1-auth-mfa-verify}

`POST /api/v1/auth/mfa/verify`

Second step of signing in. Bearer is the pending token from ``login``.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

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

# Client API: Resource Tags

> User-defined labels on services, Cloud Compute instances, Container Apps, and other resources.

Source: https://www.coritan.com/docs/api/reference/client/resource-tags/

User-defined labels on services, Cloud Compute instances, Container Apps, and other resources. Filter lists with `?tag=` or manage via `/api/v1/client/tags`.

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

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

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/tags/sources/{source_type}/{source_id}`](#op-get-api-v1-client-tags-sources-source-type-source-id) | Get resource tags |
| POST | [`/api/v1/client/tags/sources/{source_type}/{source_id}`](#op-post-api-v1-client-tags-sources-source-type-source-id) | Add resource tag |
| PUT | [`/api/v1/client/tags/sources/{source_type}/{source_id}`](#op-put-api-v1-client-tags-sources-source-type-source-id) | Replace resource tags |
| DELETE | [`/api/v1/client/tags/sources/{source_type}/{source_id}/{tag}`](#op-delete-api-v1-client-tags-sources-source-type-source-id-tag) | Remove resource tag |
| GET | [`/api/v1/client/tags/vocabulary`](#op-get-api-v1-client-tags-vocabulary) | Distinct tags on resources you own for a given sourcetype |

### Get resource tags {#op-get-api-v1-client-tags-sources-source-type-source-id}

`GET /api/v1/client/tags/sources/{source_type}/{source_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | path | string | yes |
| `source_id` | path | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `source_type` | string |
| `source_id` | string |
| `tags` | array of string |

### Add resource tag {#op-post-api-v1-client-tags-sources-source-type-source-id}

`POST /api/v1/client/tags/sources/{source_type}/{source_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | path | string | yes |
| `source_id` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `tag` | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `tags` | array of string |

### Replace resource tags {#op-put-api-v1-client-tags-sources-source-type-source-id}

`PUT /api/v1/client/tags/sources/{source_type}/{source_id}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | path | string | yes |
| `source_id` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `tags` | array of string | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `tags` | array of string |

### Remove resource tag {#op-delete-api-v1-client-tags-sources-source-type-source-id-tag}

`DELETE /api/v1/client/tags/sources/{source_type}/{source_id}/{tag}`

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | path | string | yes |
| `source_id` | path | string | yes |
| `tag` | path | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `tags` | array of string |

### Distinct tags on resources you own for a given sourcetype {#op-get-api-v1-client-tags-vocabulary}

`GET /api/v1/client/tags/vocabulary`

Distinct tags on resources you own for a given source_type.

Authentication: an access token, sent as `Authorization: Bearer <token>`.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `source_type` | query | string | yes | e.g. vps, container_server, service |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `items` | array of TagVocabularyItem |
| `items[].tag` | string |
| `items[].resource_count` | integer |
| `source_type` | string or null |

# Organization API reference

> Every operation of the Organization API, generated from the API: 1176 operations in 32 areas.

Source: https://www.coritan.com/docs/api/reference/organizations/

Every operation of the Organization API, by area. Base URL: `https://api.coritan.com/api/v1`.

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

| Area | Operations | What it covers |
| --- | --- | --- |
| [Organizations & Members](/docs/api/reference/organizations/organizations-members/) | 42 | Create and configure reseller organizations, members, roles, and audit log. |
| [API Keys](/docs/api/reference/organizations/api-keys/) | 9 | Create and revoke organization API keys. |
| [Customers](/docs/api/reference/organizations/customers/) | 48 | End-customers of the org: CRUD, custom fields, and OAuth clients. |
| [Catalog & Services](/docs/api/reference/organizations/catalog-services/) | 42 | Org-scoped products, pricing overrides, and customer services. |
| [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/) | 44 | Org invoices, credit grants, revenue, payout preferences, and billing webhooks. |
| [Staff Support](/docs/api/reference/organizations/staff-support/) | 46 | Reseller support inbox, where staff reply to customer chat under /{slug}/chat/staff. |
| [Analytics](/docs/api/reference/organizations/analytics/) | 6 | Live and historical tracking stats for the organization. |
| [Customer Authentication](/docs/api/reference/organizations/customer-authentication/) | 44 | End-customer login/refresh/me under /{slug}/auth. |
| [Customer Portal](/docs/api/reference/organizations/customer-portal/) | 396 | Authenticated end-customer self-service (requires OrgCustomerBearer). |
| [Storefront](/docs/api/reference/organizations/storefront/) | 49 | White-label catalog browse (public) and checkout (customer token). |
| [Commerce](/docs/api/reference/organizations/commerce/) | 123 |  |
| [Commerce Store API](/docs/api/reference/organizations/commerce-store-api/) | 28 |  |
| [DNS](/docs/api/reference/organizations/dns/) | 31 | Org-scoped authoritative DNS zones, records, DNSSEC, import/export, and geo load balancers. |
| [Discord](/docs/api/reference/organizations/discord/) | 15 | Your own Discord bot: application credentials, the staff channel that receives tickets, and which Discord accounts are staff. |
| [Org Cloud Compute](/docs/api/reference/organizations/org-cloud-compute/) | 27 |  |
| [Org Community Forum](/docs/api/reference/organizations/org-community-forum/) | 3 |  |
| [Org Community Guides](/docs/api/reference/organizations/org-community-guides/) | 5 |  |
| [Org Container Catalog](/docs/api/reference/organizations/org-container-catalog/) | 2 |  |
| [Org Mail](/docs/api/reference/organizations/org-mail/) | 45 |  |
| [Org Staff Auth](/docs/api/reference/organizations/org-staff-auth/) | 1 |  |
| [Org Staff Billing](/docs/api/reference/organizations/org-staff-billing/) | 6 |  |
| [Org Staff Community](/docs/api/reference/organizations/org-staff-community/) | 22 |  |
| [Org Staff Containers](/docs/api/reference/organizations/org-staff-containers/) | 77 |  |
| [Org Staff Coupons](/docs/api/reference/organizations/org-staff-coupons/) | 5 |  |
| [Org Staff Insight](/docs/api/reference/organizations/org-staff-insight/) | 4 |  |
| [Org Staff Notices](/docs/api/reference/organizations/org-staff-notices/) | 5 |  |
| [Org Staff Ops](/docs/api/reference/organizations/org-staff-ops/) | 9 |  |
| [Org Staff Team](/docs/api/reference/organizations/org-staff-team/) | 12 |  |
| [Org Ticket Requests](/docs/api/reference/organizations/org-ticket-requests/) | 2 |  |
| [Organization apps](/docs/api/reference/organizations/organization-apps/) | 22 | The organization's own Apps, as /api/v1/client/apps serves an account's: deployments, build logs, rollbacks, environment variables and domains. |
| [Partners](/docs/api/reference/organizations/partners/) | 1 | Server-to-server calls from the brand's partners, such as the Medal quest that grants a free server a RAM boost. |
| [Resource Tags](/docs/api/reference/organizations/resource-tags/) | 5 |  |

# Organization API: Organizations & Members

> Create and configure reseller organizations, members, roles, and audit log.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/

Create and configure reseller organizations, members, roles, and audit log.

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Audit log](/docs/api/reference/organizations/organizations-members/audit-log/) | 1 |
| [Deletion](/docs/api/reference/organizations/organizations-members/deletion/) | 1 |
| [Dns](/docs/api/reference/organizations/organizations-members/dns/) | 8 |
| [Gameproxy](/docs/api/reference/organizations/organizations-members/gameproxy/) | 2 |
| [Members](/docs/api/reference/organizations/organizations-members/members/) | 4 |
| [Customer link](/docs/api/reference/organizations/organizations-members/members-customer-link/) | 3 |
| [Orgs](/docs/api/reference/organizations/organizations-members/orgs/) | 2 |
| [Settings](/docs/api/reference/organizations/organizations-members/settings/) | 3 |
| [Staff](/docs/api/reference/organizations/organizations-members/staff/) | 15 |

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}`](#op-get-api-v1-orgs-org-slug) | Get organization |
| PATCH | [`/api/v1/orgs/{org_slug}`](#op-patch-api-v1-orgs-org-slug) | Update organization |
| DELETE | [`/api/v1/orgs/{org_slug}`](#op-delete-api-v1-orgs-org-slug) | Delete the organization, as its owner |

### Get organization {#op-get-api-v1-orgs-org-slug}

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

#### 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. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `slug` | string |
| `name` | string |
| `owner_user_id` | integer |
| `parent_org_id` | integer or null |
| `tier` | string |
| `status` | string |
| `billing_mode` | string |
| `platform_fee_percent` | string |
| `max_customers` | integer |
| `max_services` | integer |
| `max_sub_resellers` | integer |
| `max_api_calls_month` | integer |
| `max_custom_products` | integer |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `my_role` | string or null |

### Update organization {#op-patch-api-v1-orgs-org-slug}

`PATCH /api/v1/orgs/{org_slug}`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `billing_mode` | string or null | no |
| `tier` | string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `slug` | string |
| `name` | string |
| `owner_user_id` | integer |
| `parent_org_id` | integer or null |
| `tier` | string |
| `status` | string |
| `billing_mode` | string |
| `platform_fee_percent` | string |
| `max_customers` | integer |
| `max_services` | integer |
| `max_sub_resellers` | integer |
| `max_api_calls_month` | integer |
| `max_custom_products` | integer |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `my_role` | string or null |

### Delete the organization, as its owner {#op-delete-api-v1-orgs-org-slug}

`DELETE /api/v1/orgs/{org_slug}`

Delete the organization, as its owner.

It becomes ``deleted``: its storefront, staff console and API stop
answering, every staff and customer session into it ends, and it leaves
the dashboard of every member. Nothing is erased, and the owner cannot
undo it; platform staff can reactivate it, or delete it for good.

``confirm`` must be the organization's slug (case and surrounding spaces
do not count), or the answer is 422. While the organization still holds a
live product the answer is 409, naming them (``GET /deletion`` lists them
with where each ends). 403 for anyone but the owner's own coritan.com
session.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `confirm` | query | string | yes | The organization's slug, typed by the owner to confirm. |

#### Responses

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

# Organization API: Organizations & Members: Audit log

> The 1 Organization API operations for audit log.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/audit-log/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/audit-log`](#op-get-api-v1-orgs-org-slug-audit-log) | List audit log |

### List audit log {#op-get-api-v1-orgs-org-slug-audit-log}

`GET /api/v1/orgs/{org_slug}/audit-log`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

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

# Organization API: Organizations & Members: Deletion

> The 1 Organization API operations for deletion.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/deletion/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/deletion`](#op-get-api-v1-orgs-org-slug-deletion) | Whether the owner can delete this organization now, and what is in the way |

### Whether the owner can delete this organization now, and what is in the way {#op-get-api-v1-orgs-org-slug-deletion}

`GET /api/v1/orgs/{org_slug}/deletion`

Whether the owner can delete this organization now, and what is in the way.

Owner only. ``blockers`` names each live product the organization still
holds (``app.services.org_deletion.PRODUCT_CHECKS``: customer services,
DNS zones, mail tenants, ...), with ``count``, a ``hint`` saying how it
ends and the owner console ``tab`` where the owner can end it themselves,
when there is one. An empty list is ``deletable: true``: ``DELETE`` will
succeed.

#### 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. |

# Organization API: Organizations & Members: Dns

> The 8 Organization API operations for dns.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/dns/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}/members`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id-members) | Create LB member |
| PATCH | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}`](#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id-members-member-id) | Update LB member |
| DELETE | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}`](#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id-members-member-id) | Delete LB member |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}/health-check`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id-members-member-id-h) | Health check LB member |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}/members`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id-members) | Org create pool member |
| PATCH | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}`](#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id-members-member-id) | Org update pool member |
| DELETE | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}`](#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id-members-member-id) | Org delete pool member |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}/health-check`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id-members-member-id-heal) | Org pool member health |

### Create LB member {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id-members}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}/members`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |
| `address_type` | string | no |
| `weight` | integer | no |
| `priority` | integer | no |
| `enabled` | boolean | no |
| `health_mode` | string | no |
| `health_port` | integer or null | no |
| `health_path` | string | no |
| `health_interval_s` | integer | no |
| `health_timeout_s` | integer | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update LB member {#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id-members-member-id}

`PATCH /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string or null | no |
| `weight` | integer or null | no |
| `priority` | integer or null | no |
| `enabled` | boolean or null | no |
| `health_mode` | string or null | no |
| `health_port` | integer or null | no |
| `health_path` | string or null | no |
| `health_interval_s` | integer or null | no |
| `health_timeout_s` | integer or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete LB member {#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id-members-member-id}

`DELETE /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Health check LB member {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id-members-member-id-h}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}/members/{member_id}/health-check`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org create pool member {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id-members}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}/members`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |
| `address_type` | string | no |
| `weight` | integer | no |
| `priority` | integer | no |
| `enabled` | boolean | no |
| `health_mode` | string | no |
| `health_port` | integer or null | no |
| `health_path` | string | no |
| `health_interval_s` | integer | no |
| `health_timeout_s` | integer | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org update pool member {#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id-members-member-id}

`PATCH /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string or null | no |
| `weight` | integer or null | no |
| `priority` | integer or null | no |
| `enabled` | boolean or null | no |
| `health_mode` | string or null | no |
| `health_port` | integer or null | no |
| `health_path` | string or null | no |
| `health_interval_s` | integer or null | no |
| `health_timeout_s` | integer or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org delete pool member {#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id-members-member-id}

`DELETE /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

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

### Org pool member health {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id-members-member-id-heal}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}/members/{member_id}/health-check`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `pool_id` | integer |
| `address` | string |
| `address_type` | string |
| `weight` | integer |
| `priority` | integer |
| `enabled` | boolean |
| `health_mode` | string |
| `health_port` | integer or null |
| `health_path` | string |
| `health_interval_s` | integer |
| `health_timeout_s` | integer |
| `health_status` | string |
| `last_check_at` | string (date-time) or null |
| `last_error` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

# Organization API: Organizations & Members: Gameproxy

> The 2 Organization API operations for gameproxy.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/gameproxy/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/gameproxy/settings`](#op-get-api-v1-orgs-org-slug-gameproxy-settings) | Get org gameproxy settings |
| PUT | [`/api/v1/orgs/{org_slug}/gameproxy/settings`](#op-put-api-v1-orgs-org-slug-gameproxy-settings) | Update org gameproxy settings |

### Get org gameproxy settings {#op-get-api-v1-orgs-org-slug-gameproxy-settings}

`GET /api/v1/orgs/{org_slug}/gameproxy/settings`

#### 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. |

### Update org gameproxy settings {#op-put-api-v1-orgs-org-slug-gameproxy-settings}

`PUT /api/v1/orgs/{org_slug}/gameproxy/settings`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `auto_provision_minecraft` | boolean or null | no |
| `base_domain_id` | integer or null | no |
| `inherit_auto_provision` | boolean | no |
| `offline_motd` | string or null | no |
| `online_motd` | string or null | no |
| `generic_join_response` | string or null | no |
| `generic_ping_description` | string or null | no |
| `rejoin_message` | string or null | no |
| `blocked_message` | string or null | no |
| `favicon` | string or null | no |
| `version_name` | string or null | no |
| `status_cache_ttl_seconds` | integer or null | no |
| `clear_offline_motd` | boolean | no |
| `clear_online_motd` | boolean | no |
| `clear_generic_join_response` | boolean | no |
| `clear_generic_ping_description` | boolean | no |
| `clear_rejoin_message` | boolean | no |
| `clear_blocked_message` | boolean | no |
| `clear_favicon` | boolean | no |
| `clear_version_name` | boolean | no |
| `clear_status_cache_ttl_seconds` | boolean | no |

#### Responses

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

# Organization API: Organizations & Members: Members

> The 4 Organization API operations for members.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/members/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/members`](#op-get-api-v1-orgs-org-slug-members) | List members |
| POST | [`/api/v1/orgs/{org_slug}/members`](#op-post-api-v1-orgs-org-slug-members) | Invite member |
| PATCH | [`/api/v1/orgs/{org_slug}/members/{member_id}`](#op-patch-api-v1-orgs-org-slug-members-member-id) | Update member |
| DELETE | [`/api/v1/orgs/{org_slug}/members/{member_id}`](#op-delete-api-v1-orgs-org-slug-members-member-id) | Remove member |

### List members {#op-get-api-v1-orgs-org-slug-members}

`GET /api/v1/orgs/{org_slug}/members`

#### 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. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_id` | integer |
| `[].user_id` | integer |
| `[].role` | string |
| `[].permissions` | object or null |
| `[].joined_at` | string (date-time) or null |
| `[].customer_link_mode` | string or null |
| `[].linked_customer_id` | integer or null |
| `[].email` | string or null |
| `[].first_name` | string or null |
| `[].last_name` | string or null |

### Invite member {#op-post-api-v1-orgs-org-slug-members}

`POST /api/v1/orgs/{org_slug}/members`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string | yes |
| `role` | string | no |
| `name` | string or null | no |
| `password` | string or null | no |
| `send_invite_email` | boolean | no |
| `permissions` | object or null | no |
| `customer_link` | string | no |
| `customer_id` | integer or null | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `user_id` | integer |
| `role` | string |
| `permissions` | object or null |
| `joined_at` | string (date-time) or null |
| `customer_link_mode` | string or null |
| `linked_customer_id` | integer or null |
| `email` | string or null |
| `first_name` | string or null |
| `last_name` | string or null |

### Update member {#op-patch-api-v1-orgs-org-slug-members-member-id}

`PATCH /api/v1/orgs/{org_slug}/members/{member_id}`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `role` | string or null | no |
| `permissions` | object or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `user_id` | integer |
| `role` | string |
| `permissions` | object or null |
| `joined_at` | string (date-time) or null |
| `customer_link_mode` | string or null |
| `linked_customer_id` | integer or null |
| `email` | string or null |
| `first_name` | string or null |
| `last_name` | string or null |

### Remove member {#op-delete-api-v1-orgs-org-slug-members-member-id}

`DELETE /api/v1/orgs/{org_slug}/members/{member_id}`

#### Parameters

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

#### Responses

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

# Organization API: Organizations & Members: Customer link

> The 3 Organization API operations for customer link.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/members-customer-link/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/members/{member_id}/customer-link`](#op-get-api-v1-orgs-org-slug-members-member-id-customer-link) | The storefront customer account this member is on, if any |
| PUT | [`/api/v1/orgs/{org_slug}/members/{member_id}/customer-link`](#op-put-api-v1-orgs-org-slug-members-member-id-customer-link) | Set member customer link |
| DELETE | [`/api/v1/orgs/{org_slug}/members/{member_id}/customer-link`](#op-delete-api-v1-orgs-org-slug-members-member-id-customer-link) | Make the member console-only; the customer account itself is untouched |

### The storefront customer account this member is on, if any {#op-get-api-v1-orgs-org-slug-members-member-id-customer-link}

`GET /api/v1/orgs/{org_slug}/members/{member_id}/customer-link`

The storefront customer account this member is on, if any.

#### Parameters

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

#### Responses

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

### Set member customer link {#op-put-api-v1-orgs-org-slug-members-member-id-customer-link}

`PUT /api/v1/orgs/{org_slug}/members/{member_id}/customer-link`

Attach an existing customer account to the member (``existing`` +
``customer_id``) or make one with their email (``create``).

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `mode` | string | no |
| `customer_id` | integer or null | no |

#### Responses

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

### Make the member console-only; the customer account itself is untouched {#op-delete-api-v1-orgs-org-slug-members-member-id-customer-link}

`DELETE /api/v1/orgs/{org_slug}/members/{member_id}/customer-link`

Make the member console-only; the customer account itself is untouched.

#### Parameters

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

#### Responses

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

# Organization API: Organizations & Members: Orgs

> The 2 Organization API operations for orgs.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/orgs/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs`](#op-get-api-v1-orgs) | List organizations |
| POST | [`/api/v1/orgs`](#op-post-api-v1-orgs) | Create organization |

### List organizations {#op-get-api-v1-orgs}

`GET /api/v1/orgs`

The organizations this account belongs to, newest first, each with
the caller's role in ``my_role``: ``owner`` for the org's owner whatever
their member row says, as ``get_org_context`` decides it.

A ``deleted`` one is left out for every member: its owner deleted it, and
only platform staff can bring it back.

Authentication: an access token of a member of the organization, sent as `Authorization: Bearer <token>`.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].slug` | string |
| `[].name` | string |
| `[].tier` | string |
| `[].status` | string |
| `[].billing_mode` | string |
| `[].created_at` | string (date-time) or null |
| `[].my_role` | string or null |

### Create organization {#op-post-api-v1-orgs}

`POST /api/v1/orgs`

Authentication: an access token of a member of the organization, sent as `Authorization: Bearer <token>`.

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `slug` | string | yes |
| `billing_mode` | string | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `slug` | string |
| `name` | string |
| `owner_user_id` | integer |
| `parent_org_id` | integer or null |
| `tier` | string |
| `status` | string |
| `billing_mode` | string |
| `platform_fee_percent` | string |
| `max_customers` | integer |
| `max_services` | integer |
| `max_sub_resellers` | integer |
| `max_api_calls_month` | integer |
| `max_custom_products` | integer |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `my_role` | string or null |

# Organization API: Organizations & Members: Settings

> The 3 Organization API operations for settings.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/settings/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/settings`](#op-get-api-v1-orgs-org-slug-settings) | Get org settings |
| PATCH | [`/api/v1/orgs/{org_slug}/settings`](#op-patch-api-v1-orgs-org-slug-settings) | Update org settings |
| GET | [`/api/v1/orgs/{org_slug}/settings/mail-outbound`](#op-get-api-v1-orgs-org-slug-settings-mail-outbound) | The outbound transport block plus whether the in-house side can send now |

### Get org settings {#op-get-api-v1-orgs-org-slug-settings}

`GET /api/v1/orgs/{org_slug}/settings`

#### 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. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `custom_domain` | string or null |
| `custom_domain_verified` | boolean |
| `logo_url` | string or null |
| `favicon_url` | string or null |
| `primary_color` | string |
| `secondary_color` | string |
| `company_name` | string or null |
| `legal_name` | string or null |
| `registration_number` | string or null |
| `tax_id` | string or null |
| `registered_address` | string or null |
| `billing_email` | string or null |
| `country_code` | string or null |
| `support_email` | string or null |
| `terms_url` | string or null |
| `privacy_url` | string or null |
| `smtp_host` | string or null |
| `smtp_port` | integer |
| `smtp_user` | string or null |
| `smtp_from_email` | string or null |
| `smtp_from_name` | string or null |
| `invoice_prefix` | string |
| `invoice_footer` | string or null |
| `default_currency` | string |
| `tax_rate` | string |
| `payment_terms_days` | integer |
| `timezone` | string |
| `features` | object or null |
| `self_serve_downgrade_credit` | boolean or null |
| `self_serve_cancellation_credit` | boolean or null |

### Update org settings {#op-patch-api-v1-orgs-org-slug-settings}

`PATCH /api/v1/orgs/{org_slug}/settings`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `mail_outbound` | OrgMailOutbound or null | no |
| `mail_outbound.transport` | string, one of `auto`, `smtp`, `inhouse` | no |
| `mail_outbound.tenant` | string or null | no |
| `mail_outbound.envelope_domain` | string or null | no |
| `mail_outbound.envelope_local` | string or null | no |
| `mail_outbound.from_mode` | string, one of `apex`, `subdomain` | no |
| `custom_domain` | string or null | no |
| `logo_url` | string or null | no |
| `favicon_url` | string or null | no |
| `primary_color` | string or null | no |
| `secondary_color` | string or null | no |
| `company_name` | string or null | no |
| `legal_name` | string or null | no |
| `registration_number` | string or null | no |
| `tax_id` | string or null | no |
| `registered_address` | string or null | no |
| `billing_email` | string or null | no |
| `country_code` | string or null | no |
| `support_email` | string or null | no |
| `terms_url` | string or null | no |
| `privacy_url` | string or null | no |
| `smtp_host` | string or null | no |
| `smtp_port` | integer or null | no |
| `smtp_user` | string or null | no |
| `smtp_pass` | string or null | no |
| `smtp_from_email` | string or null | no |
| `smtp_from_name` | string or null | no |
| `invoice_prefix` | string or null | no |
| `invoice_footer` | string or null | no |
| `default_currency` | string or null | no |
| `tax_rate` | number or string or null | no |
| `payment_terms_days` | integer or null | no |
| `timezone` | string or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `custom_domain` | string or null |
| `custom_domain_verified` | boolean |
| `logo_url` | string or null |
| `favicon_url` | string or null |
| `primary_color` | string |
| `secondary_color` | string |
| `company_name` | string or null |
| `legal_name` | string or null |
| `registration_number` | string or null |
| `tax_id` | string or null |
| `registered_address` | string or null |
| `billing_email` | string or null |
| `country_code` | string or null |
| `support_email` | string or null |
| `terms_url` | string or null |
| `privacy_url` | string or null |
| `smtp_host` | string or null |
| `smtp_port` | integer |
| `smtp_user` | string or null |
| `smtp_from_email` | string or null |
| `smtp_from_name` | string or null |
| `invoice_prefix` | string |
| `invoice_footer` | string or null |
| `default_currency` | string |
| `tax_rate` | string |
| `payment_terms_days` | integer |
| `timezone` | string |
| `features` | object or null |
| `self_serve_downgrade_credit` | boolean or null |
| `self_serve_cancellation_credit` | boolean or null |

### The outbound transport block plus whether the in-house side can send now {#op-get-api-v1-orgs-org-slug-settings-mail-outbound}

`GET /api/v1/orgs/{org_slug}/settings/mail-outbound`

The outbound transport block plus whether the in-house side can send now.

#### 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. |

# Organization API: Organizations & Members: Staff

> The 15 Organization API operations for staff.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/staff/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/staff/community/forum/members`](#op-get-api-v1-orgs-org-slug-staff-community-forum-members) | Staff forum members |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/forum/members/{handle}/role`](#op-post-api-v1-orgs-org-slug-staff-community-forum-members-handle-role) | Staff set forum role |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/forum/members/{handle}/suspend`](#op-post-api-v1-orgs-org-slug-staff-community-forum-members-handle-suspend) | Staff suspend forum member |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/settings`](#op-patch-api-v1-orgs-org-slug-staff-servers-uuid-settings) | Staff patch settings |
| GET | [`/api/v1/orgs/{org_slug}/staff/settings`](#op-get-api-v1-orgs-org-slug-staff-settings) | Staff get settings |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/settings`](#op-patch-api-v1-orgs-org-slug-staff-settings) | Staff patch settings |
| GET | [`/api/v1/orgs/{org_slug}/staff/settings/email-design`](#op-get-api-v1-orgs-org-slug-staff-settings-email-design) | Staff get email design |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/settings/email-design`](#op-patch-api-v1-orgs-org-slug-staff-settings-email-design) | Change how the brand's email looks |
| POST | [`/api/v1/orgs/{org_slug}/staff/settings/email-design/preview`](#op-post-api-v1-orgs-org-slug-staff-settings-email-design-preview) | Staff preview email design |
| POST | [`/api/v1/orgs/{org_slug}/staff/settings/email-design/test`](#op-post-api-v1-orgs-org-slug-staff-settings-email-design-test) | Staff test email design |
| GET | [`/api/v1/orgs/{org_slug}/staff/settings/error-page`](#op-get-api-v1-orgs-org-slug-staff-settings-error-page) | Staff get error page |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/settings/error-page`](#op-patch-api-v1-orgs-org-slug-staff-settings-error-page) | Reword the page, pick its level of detail, switch it on or off |
| POST | [`/api/v1/orgs/{org_slug}/staff/settings/error-page/preview`](#op-post-api-v1-orgs-org-slug-staff-settings-error-page-preview) | The page as a visitor would get it, for a block that is not saved yet |
| GET | [`/api/v1/orgs/{org_slug}/staff/settings/support-desk`](#op-get-api-v1-orgs-org-slug-staff-settings-support-desk) | Staff get support desk |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/settings/support-desk`](#op-patch-api-v1-orgs-org-slug-staff-settings-support-desk) | Staff patch support desk |

### Staff forum members {#op-get-api-v1-orgs-org-slug-staff-community-forum-members}

`GET /api/v1/orgs/{org_slug}/staff/community/forum/members`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `only` | query | string | no | Default: `all`. |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `50`. |

#### Responses

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

### Staff set forum role {#op-post-api-v1-orgs-org-slug-staff-community-forum-members-handle-role}

`POST /api/v1/orgs/{org_slug}/staff/community/forum/members/{handle}/role`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `role` | string | yes |

#### Responses

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

### Staff suspend forum member {#op-post-api-v1-orgs-org-slug-staff-community-forum-members-handle-suspend}

`POST /api/v1/orgs/{org_slug}/staff/community/forum/members/{handle}/suspend`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `suspend` | boolean | no |
| `reason` | string or null | no |

#### Responses

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

### Staff patch settings {#op-patch-api-v1-orgs-org-slug-staff-servers-uuid-settings}

`PATCH /api/v1/orgs/{org_slug}/staff/servers/{uuid}/settings`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `world_optimization_enabled` | boolean or null | no |

#### Responses

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

### Staff get settings {#op-get-api-v1-orgs-org-slug-staff-settings}

`GET /api/v1/orgs/{org_slug}/staff/settings`

#### 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. |

### Staff patch settings {#op-patch-api-v1-orgs-org-slug-staff-settings}

`PATCH /api/v1/orgs/{org_slug}/staff/settings`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `company_name` | string or null | no |
| `legal_name` | string or null | no |
| `registration_number` | string or null | no |
| `tax_id` | string or null | no |
| `registered_address` | string or null | no |
| `country_code` | string or null | no |
| `support_email` | string or null | no |
| `billing_email` | string or null | no |
| `terms_url` | string or null | no |
| `privacy_url` | string or null | no |
| `logo_url` | string or null | no |
| `favicon_url` | string or null | no |
| `primary_color` | string or null | no |
| `secondary_color` | string or null | no |
| `invoice_prefix` | string or null | no |
| `invoice_footer` | string or null | no |
| `default_currency` | string or null | no |
| `tax_rate` | number or string or null | no |
| `payment_terms_days` | integer or null | no |
| `timezone` | string or null | no |
| `features` | object or null | no |

#### Responses

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

### Staff get email design {#op-get-api-v1-orgs-org-slug-staff-settings-email-design}

`GET /api/v1/orgs/{org_slug}/staff/settings/email-design`

#### 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. |

### Change how the brand's email looks {#op-patch-api-v1-orgs-org-slug-staff-settings-email-design}

`PATCH /api/v1/orgs/{org_slug}/staff/settings/email-design`

Change how the brand's email looks. A field sent as ``null`` goes back
to the theme's value (the accent and the logo: the brand's own).

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `theme` | string or null | no |
| `accent_color` | string or null | no |
| `background_color` | string or null | no |
| `surface_color` | string or null | no |
| `text_color` | string or null | no |
| `radius` | string or null | no |
| `font` | string or null | no |
| `header` | string or null | no |
| `logo_url` | string or null | no |
| `footer_text` | string or null | no |
| `links` | array of EmailLink or null | no |
| `links[].label` | string | yes |
| `links[].url` | string | yes |
| `show_address` | boolean or null | no |

#### Responses

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

### Staff preview email design {#op-post-api-v1-orgs-org-slug-staff-settings-email-design-preview}

`POST /api/v1/orgs/{org_slug}/staff/settings/email-design/preview`

A sample email as the brand's customers would get it, with the design
being edited: its own wording where it edited the template.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email_design` | object or null | no |
| `sample` | string | no |

#### Responses

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

### Staff test email design {#op-post-api-v1-orgs-org-slug-staff-settings-email-design-test}

`POST /api/v1/orgs/{org_slug}/staff/settings/email-design/test`

Send the sample to the staff member's own address, with the design
being edited, so it can be checked in a real mail client.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email_design` | object or null | no |
| `sample` | string | no |

#### Responses

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

### Staff get error page {#op-get-api-v1-orgs-org-slug-staff-settings-error-page}

`GET /api/v1/orgs/{org_slug}/staff/settings/error-page`

#### 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. |

### Reword the page, pick its level of detail, switch it on or off {#op-patch-api-v1-orgs-org-slug-staff-settings-error-page}

`PATCH /api/v1/orgs/{org_slug}/staff/settings/error-page`

Reword the page, pick its level of detail, switch it on or off.

Fields sent as ``null`` go back to the brand default. The Coritan label,
footer and headers are not fields, so they cannot be switched off here.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean or null | no |
| `heading` | string or null | no |
| `message` | string or null | no |
| `detail` | string or null | no |
| `logo_url` | string or null | no |
| `accent_color` | string or null | no |
| `support_url` | string or null | no |
| `support_label` | string or null | no |
| `updates_url` | string or null | no |
| `updates_label` | string or null | no |
| `theme` | string or null | no |
| `background_color` | string or null | no |
| `surface_color` | string or null | no |
| `text_color` | string or null | no |
| `radius` | string or null | no |
| `font` | string or null | no |
| `status_style` | string or null | no |

#### Responses

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

### The page as a visitor would get it, for a block that is not saved yet {#op-post-api-v1-orgs-org-slug-staff-settings-error-page-preview}

`POST /api/v1/orgs/{org_slug}/staff/settings/error-page/preview`

The page as a visitor would get it, for a block that is not saved yet.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `error_page` | object or null | no |
| `status` | integer | no |

#### Responses

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

### Staff get support desk {#op-get-api-v1-orgs-org-slug-staff-settings-support-desk}

`GET /api/v1/orgs/{org_slug}/staff/settings/support-desk`

#### 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. |

### Staff patch support desk {#op-patch-api-v1-orgs-org-slug-staff-settings-support-desk}

`PATCH /api/v1/orgs/{org_slug}/staff/settings/support-desk`

#### Parameters

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

#### Request body

`application/json` (required)

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

#### Responses

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

# Organization API: API Keys

> Create and revoke organization API keys.

Source: https://www.coritan.com/docs/api/reference/organizations/api-keys/

Create and revoke organization API keys. `X-API-Key` authenticates the commerce merchant API when the key carries commerce scopes; other org routes take a Bearer token.

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}/api-keys`](#op-get-api-v1-orgs-org-slug-api-keys) | List API keys |
| POST | [`/api/v1/orgs/{org_slug}/api-keys`](#op-post-api-v1-orgs-org-slug-api-keys) | Create API key |
| DELETE | [`/api/v1/orgs/{org_slug}/api-keys/{key_id}`](#op-delete-api-v1-orgs-org-slug-api-keys-key-id) | Revoke API key |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/api-keys`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-api-keys) | List API keys |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/api-keys`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-api-keys) | Create API key |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/api-keys/{key_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-api-keys-key-id) | Revoke API key |
| GET | [`/api/v1/orgs/{org_slug}/staff/settings/api-keys`](#op-get-api-v1-orgs-org-slug-staff-settings-api-keys) | Staff list API keys |
| POST | [`/api/v1/orgs/{org_slug}/staff/settings/api-keys`](#op-post-api-v1-orgs-org-slug-staff-settings-api-keys) | A key for the brand's own integrations |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/settings/api-keys/{key_id}`](#op-delete-api-v1-orgs-org-slug-staff-settings-api-keys-key-id) | Staff revoke API key |

### List API keys {#op-get-api-v1-orgs-org-slug-api-keys}

`GET /api/v1/orgs/{org_slug}/api-keys`

#### 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. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_id` | integer |
| `[].label` | string |
| `[].permissions` | object or null |
| `[].rate_limit_per_hour` | integer |
| `[].ip_whitelist` | array of any or null |
| `[].is_active` | boolean |
| `[].last_used_at` | string (date-time) or null |
| `[].created_at` | string (date-time) or null |

### Create API key {#op-post-api-v1-orgs-org-slug-api-keys}

`POST /api/v1/orgs/{org_slug}/api-keys`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | yes |
| `permissions` | object or null | no |
| `rate_limit_per_hour` | integer | no |
| `ip_whitelist` | array of string or null | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `label` | string |
| `permissions` | object or null |
| `rate_limit_per_hour` | integer |
| `ip_whitelist` | array of any or null |
| `is_active` | boolean |
| `last_used_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `raw_key` | string |

### Revoke API key {#op-delete-api-v1-orgs-org-slug-api-keys-key-id}

`DELETE /api/v1/orgs/{org_slug}/api-keys/{key_id}`

#### Parameters

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

#### Responses

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

### List API keys {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-api-keys}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/api-keys`

#### Parameters

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

#### Responses

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

### Create API key {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-api-keys}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/api-keys`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

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

### Revoke API key {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-api-keys-key-id}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/api-keys/{key_id}`

#### Parameters

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

#### Responses

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

### Staff list API keys {#op-get-api-v1-orgs-org-slug-staff-settings-api-keys}

`GET /api/v1/orgs/{org_slug}/staff/settings/api-keys`

#### 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. |

### A key for the brand's own integrations {#op-post-api-v1-orgs-org-slug-staff-settings-api-keys}

`POST /api/v1/orgs/{org_slug}/staff/settings/api-keys`

A key for the brand's own integrations. Shown once; only its hash is kept.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | yes |
| `rate_limit_per_hour` | integer | no |
| `ip_whitelist` | array of string or null | no |

#### Responses

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

### Staff revoke API key {#op-delete-api-v1-orgs-org-slug-staff-settings-api-keys-key-id}

`DELETE /api/v1/orgs/{org_slug}/staff/settings/api-keys/{key_id}`

#### Parameters

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

#### Responses

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

# Organization API: Customers

> End-customers of the org: CRUD, custom fields, and OAuth clients.

Source: https://www.coritan.com/docs/api/reference/organizations/customers/

End-customers of the org: CRUD, custom fields, and OAuth clients. Staff JWT required.

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Commerce](/docs/api/reference/organizations/customers/commerce/) | 4 |
| [Custom fields](/docs/api/reference/organizations/customers/custom-fields/) | 3 |
| [Customers](/docs/api/reference/organizations/customers/customers/) | 6 |
| [Oauth clients](/docs/api/reference/organizations/customers/oauth-clients/) | 2 |
| [Staff](/docs/api/reference/organizations/customers/staff/) | 26 |
| [Store](/docs/api/reference/organizations/customers/store/) | 7 |

# Organization API: Customers: Commerce

> The 4 Organization API operations for commerce.

Source: https://www.coritan.com/docs/api/reference/organizations/customers/commerce/

Part of [Customers](/docs/api/reference/organizations/customers/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/customer-groups/{group_id}/customers`](#op-put-api-v1-orgs-org-slug-commerce-customer-groups-group-id-customers) | Set group customers |
| GET | [`/api/v1/orgs/{org_slug}/commerce/customers`](#op-get-api-v1-orgs-org-slug-commerce-customers) | Newest first, with each customer's order count, spend and groups |
| GET | [`/api/v1/orgs/{org_slug}/commerce/customers/{customer_id}`](#op-get-api-v1-orgs-org-slug-commerce-customers-customer-id) | The customer, their saved addresses, note, tags, groups and spend |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/customers/{customer_id}`](#op-patch-api-v1-orgs-org-slug-commerce-customers-customer-id) | Note, tags, tax exemption, VAT id and its check; acceptsmarketing takes only false |

### Set group customers {#op-put-api-v1-orgs-org-slug-commerce-customer-groups-group-id-customers}

`PUT /api/v1/orgs/{org_slug}/commerce/customer-groups/{group_id}/customers`

Make ``customer_ids`` exactly the group's customers (at most 1000); an
id that is not one of the store's customers is not found.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `customer_ids` | array of integer | yes |

#### Responses

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

### Newest first, with each customer's order count, spend and groups {#op-get-api-v1-orgs-org-slug-commerce-customers}

`GET /api/v1/orgs/{org_slug}/commerce/customers`

Newest first, with each customer's order count, spend and groups.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no | Part of an email or a name. |
| `group_id` | query | integer or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

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

### The customer, their saved addresses, note, tags, groups and spend {#op-get-api-v1-orgs-org-slug-commerce-customers-customer-id}

`GET /api/v1/orgs/{org_slug}/commerce/customers/{customer_id}`

The customer, their saved addresses, note, tags, groups and spend.

#### Parameters

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

#### Responses

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

### Note, tags, tax exemption, VAT id and its check; acceptsmarketing takes only false {#op-patch-api-v1-orgs-org-slug-commerce-customers-customer-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/customers/{customer_id}`

Note, tags, tax exemption, VAT id and its check; ``accepts_marketing``
takes only false. Changing ``vat_id`` clears its check.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accepts_marketing` | boolean or null | no | Only false: a store can turn consent off. |
| `note` | string or null | no |  |
| `tags` | array of string or null | no |  |
| `tax_exempt` | boolean or null | no |  |
| `vat_id` | string or null | no |  |
| `vat_id_valid` | boolean or null | no | Whether the VAT id was checked and found valid. |

#### Responses

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

# Organization API: Customers: Custom fields

> The 3 Organization API operations for custom fields.

Source: https://www.coritan.com/docs/api/reference/organizations/customers/custom-fields/

Part of [Customers](/docs/api/reference/organizations/customers/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/custom-fields`](#op-get-api-v1-orgs-org-slug-custom-fields) | List custom fields |
| POST | [`/api/v1/orgs/{org_slug}/custom-fields`](#op-post-api-v1-orgs-org-slug-custom-fields) | Create custom field |
| DELETE | [`/api/v1/orgs/{org_slug}/custom-fields/{field_id}`](#op-delete-api-v1-orgs-org-slug-custom-fields-field-id) | Delete custom field |

### List custom fields {#op-get-api-v1-orgs-org-slug-custom-fields}

`GET /api/v1/orgs/{org_slug}/custom-fields`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `applies_to` | query | string | no |

#### Responses

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

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_id` | integer |
| `[].field_name` | string |
| `[].label` | string |
| `[].field_type` | string |
| `[].applies_to` | string |
| `[].validation_rules` | object or null |
| `[].options` | array of any or null |
| `[].default_value` | string or null |
| `[].required` | boolean |
| `[].is_indexed` | boolean |
| `[].sort_order` | integer |
| `[].created_at` | string (date-time) or null |

### Create custom field {#op-post-api-v1-orgs-org-slug-custom-fields}

`POST /api/v1/orgs/{org_slug}/custom-fields`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `field_name` | string | yes |
| `label` | string | yes |
| `field_type` | string | yes |
| `applies_to` | string | yes |
| `validation_rules` | object or null | no |
| `options` | array of any or null | no |
| `default_value` | string or null | no |
| `required` | boolean | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `field_name` | string |
| `label` | string |
| `field_type` | string |
| `applies_to` | string |
| `validation_rules` | object or null |
| `options` | array of any or null |
| `default_value` | string or null |
| `required` | boolean |
| `is_indexed` | boolean |
| `sort_order` | integer |
| `created_at` | string (date-time) or null |

### Delete custom field {#op-delete-api-v1-orgs-org-slug-custom-fields-field-id}

`DELETE /api/v1/orgs/{org_slug}/custom-fields/{field_id}`

#### Parameters

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

#### Responses

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

# Organization API: Customers: Customers

> The 6 Organization API operations for customers.

Source: https://www.coritan.com/docs/api/reference/organizations/customers/customers/

Part of [Customers](/docs/api/reference/organizations/customers/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/customers`](#op-get-api-v1-orgs-org-slug-customers) | The org's customers, newest first |
| POST | [`/api/v1/orgs/{org_slug}/customers`](#op-post-api-v1-orgs-org-slug-customers) | Create customer |
| GET | [`/api/v1/orgs/{org_slug}/customers/{customer_id}`](#op-get-api-v1-orgs-org-slug-customers-customer-id) | Get customer |
| PATCH | [`/api/v1/orgs/{org_slug}/customers/{customer_id}`](#op-patch-api-v1-orgs-org-slug-customers-customer-id) | Update customer |
| DELETE | [`/api/v1/orgs/{org_slug}/customers/{customer_id}`](#op-delete-api-v1-orgs-org-slug-customers-customer-id) | Deactivate customer |
| POST | [`/api/v1/orgs/{org_slug}/customers/{customer_id}/credit/add`](#op-post-api-v1-orgs-org-slug-customers-customer-id-credit-add) | Add credit |

### The org's customers, newest first {#op-get-api-v1-orgs-org-slug-customers}

`GET /api/v1/orgs/{org_slug}/customers`

The org's customers, newest first.

``q`` matches email, first, last or full name, public handle, company or
the customer number. ``with_total=true`` answers ``{items, total, limit,
offset, counts}``; ``counts`` per status are for the same search whatever
the status filter.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status_filter` | query | string | no |  |
| `q` | query | string | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |
| `with_total` | query | boolean | no | Default: `False`. |

#### Responses

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

### Create customer {#op-post-api-v1-orgs-org-slug-customers}

`POST /api/v1/orgs/{org_slug}/customers`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string | yes |
| `password` | string | yes |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `currency` | string or null | no |
| `custom_fields` | object or null | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `chat_handle` | string or null |
| `chat_handle_locked_for` | integer |
| `company` | string or null |
| `phone` | string or null |
| `status` | string |
| `credit_balance` | string |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `custom_fields` | object or null |
| `last_login_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `has_password` | boolean |
| `staff_member` | boolean |
| `email_verified` | boolean |
| `avatar_url` | string or null |

### Get customer {#op-get-api-v1-orgs-org-slug-customers-customer-id}

`GET /api/v1/orgs/{org_slug}/customers/{customer_id}`

#### Parameters

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

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `chat_handle` | string or null |
| `chat_handle_locked_for` | integer |
| `company` | string or null |
| `phone` | string or null |
| `status` | string |
| `credit_balance` | string |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `custom_fields` | object or null |
| `last_login_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `has_password` | boolean |
| `staff_member` | boolean |
| `email_verified` | boolean |
| `avatar_url` | string or null |

### Update customer {#op-patch-api-v1-orgs-org-slug-customers-customer-id}

`PATCH /api/v1/orgs/{org_slug}/customers/{customer_id}`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string or null | no |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `status` | string or null | no |
| `currency` | string or null | no |
| `custom_fields` | object or null | no |

#### Responses

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

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `chat_handle` | string or null |
| `chat_handle_locked_for` | integer |
| `company` | string or null |
| `phone` | string or null |
| `status` | string |
| `credit_balance` | string |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `custom_fields` | object or null |
| `last_login_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `has_password` | boolean |
| `staff_member` | boolean |
| `email_verified` | boolean |
| `avatar_url` | string or null |

### Deactivate customer {#op-delete-api-v1-orgs-org-slug-customers-customer-id}

`DELETE /api/v1/orgs/{org_slug}/customers/{customer_id}`

#### Parameters

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

#### Responses

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

### Add credit {#op-post-api-v1-orgs-org-slug-customers-customer-id-credit-add}

`POST /api/v1/orgs/{org_slug}/customers/{customer_id}/credit/add`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customer_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `amount` | query | number or string | yes |  |
| `description` | query | string | no | Default: `Manual credit`. |

#### Responses

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

# Organization API: Customers: Oauth clients

> The 2 Organization API operations for oauth clients.

Source: https://www.coritan.com/docs/api/reference/organizations/customers/oauth-clients/

Part of [Customers](/docs/api/reference/organizations/customers/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/oauth-clients`](#op-get-api-v1-orgs-org-slug-oauth-clients) | List OAuth clients |
| POST | [`/api/v1/orgs/{org_slug}/oauth-clients`](#op-post-api-v1-orgs-org-slug-oauth-clients) | Create OAuth client |

### List OAuth clients {#op-get-api-v1-orgs-org-slug-oauth-clients}

`GET /api/v1/orgs/{org_slug}/oauth-clients`

#### 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. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_id` | integer |
| `[].client_id` | string |
| `[].name` | string |
| `[].redirect_uris` | array of any |
| `[].allowed_scopes` | array of any or null |
| `[].grant_types` | array of any or null |
| `[].is_active` | boolean |
| `[].created_at` | string (date-time) or null |

### Create OAuth client {#op-post-api-v1-orgs-org-slug-oauth-clients}

`POST /api/v1/orgs/{org_slug}/oauth-clients`

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `redirect_uris` | array of string | yes |
| `allowed_scopes` | array of string or null | no |
| `grant_types` | array of string or null | no |

#### Responses

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

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `client_id` | string |
| `name` | string |
| `redirect_uris` | array of any |
| `allowed_scopes` | array of any or null |
| `grant_types` | array of any or null |
| `is_active` | boolean |
| `created_at` | string (date-time) or null |
| `client_secret` | string |

# Organization API: Customers: Staff

> The 26 Organization API operations for staff.

Source: https://www.coritan.com/docs/api/reference/organizations/customers/staff/

Part of [Customers](/docs/api/reference/organizations/customers/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers`](#op-get-api-v1-orgs-org-slug-staff-customers) | Directory for this brand, separate from the mixed desk search |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers`](#op-post-api-v1-orgs-org-slug-staff-customers) | An account for someone who ordered by phone or email |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/bulk`](#op-post-api-v1-orgs-org-slug-staff-customers-bulk) | Staff customers bulk |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/export.csv`](#op-get-api-v1-orgs-org-slug-staff-customers-export-csv) | The directory as it is filtered, as a CSV |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/tags`](#op-get-api-v1-orgs-org-slug-staff-customers-tags) | Every label in use on this brand, with how many customers carry it |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id) | Staff customer hub |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}`](#op-patch-api-v1-orgs-org-slug-staff-customers-customer-id) | Fix the profile (support), or change the account's standing (admin) |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/activity`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-activity) | Staff customer activity |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/chat-mute`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-chat-mute) | Silence a handle in community chat and the forum for a while, or lift it |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/close`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-close) | Staff close customer |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/credit`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-credit) | Staff add credit |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/credit-ledger`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-credit-ledger) | Staff credit ledger |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/data-export`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-data-export) | Everything held about the customer, as one JSON file, for a privacy request |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/emails`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-emails) | Staff customer emails |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/impersonate`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-impersonate) | Staff impersonate customer |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/mark-verified`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-mark-verified) | Vouch for an address the customer proved another way (a call, a ticket from that inbox) |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/notes`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-notes) | List customer notes |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/notes`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-notes) | Add customer note |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/payment-methods`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-payment-methods) | Staff customer payment methods |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/related`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-related) | Staff customer related |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/resend-verification`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-resend-verification) | Staff resend verification |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/reset-mfa`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-reset-mfa) | For a customer who lost their phone: remove their second factor and end their sessions |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/reset-password`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-reset-password) | Staff reset customer password |
| POST | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/revoke-sessions`](#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-revoke-sessions) | Staff revoke customer sessions |
| GET | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/sessions`](#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-sessions) | Staff customer sessions |
| PUT | [`/api/v1/orgs/{org_slug}/staff/customers/{customer_id}/tags`](#op-put-api-v1-orgs-org-slug-staff-customers-customer-id-tags) | Staff set customer tags |

### Directory for this brand, separate from the mixed desk search {#op-get-api-v1-orgs-org-slug-staff-customers}

`GET /api/v1/orgs/{org_slug}/staff/customers`

Directory for this brand, separate from the mixed desk search.

``status_filter`` is an account status or one of ``CUSTOMER_BUCKETS``
(``unverified``, ``new_7d``, ``paying``, ``free``). ``counts`` carries one
figure per status and per bucket. ``unverified`` is accounts whose email
was never verified, ``new_7d`` signups inside the last seven days,
``paying`` accounts with at least one non-free service and ``free`` the
rest. Every figure is counted under the audience the request carries, and
none is narrowed by ``q``, ``tag`` or the filter itself, so the tiles keep
reading as the whole directory while the list is narrowed.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `status_filter` | query | string or null | no |  |
| `tag` | query | string or null | no |  |
| `audience` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

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

### An account for someone who ordered by phone or email {#op-post-api-v1-orgs-org-slug-staff-customers}

`POST /api/v1/orgs/{org_slug}/staff/customers`

An account for someone who ordered by phone or email. No password is
set here; the customer gets a link to choose their own, so staff never
know it.

#### Parameters

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

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) | yes |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `currency` | string or null | no |
| `send_setup_email` | boolean | no |

#### Responses

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

### Staff customers bulk {#op-post-api-v1-orgs-org-slug-staff-customers-bulk}

`POST /api/v1/orgs/{org_slug}/staff/customers/bulk`

Suspend, unsuspend or terminate every order a selection of customers
has, or ban the accounts outright.

The fleet's bulk route acts on servers picked one by one; this one is for
the search that turned up a dozen accounts with the same email pattern.
Same gate: support may suspend and unsuspend; anything that ends an order
or an account is an org admin who has stepped up in the last ten minutes.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `customer_ids` | array of integer | yes |
| `action` | string | yes |
| `reason` | string | yes |
| `delete_after_days` | integer or null | no |
| `open_ticket` | boolean | no |
| `notify_customer` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The directory as it is filtered, as a CSV {#op-get-api-v1-orgs-org-slug-staff-customers-export-csv}

`GET /api/v1/orgs/{org_slug}/staff/customers/export.csv`

The directory as it is filtered, as a CSV. Billing roles only: an
export is every customer's contact details in one file. ``status_filter``
takes the same values as the directory, the tile buckets included.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `q` | query | string or null | no |
| `status_filter` | query | string or null | no |
| `tag` | query | string or null | no |
| `audience` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every label in use on this brand, with how many customers carry it {#op-get-api-v1-orgs-org-slug-staff-customers-tags}

`GET /api/v1/orgs/{org_slug}/staff/customers/tags`

Every label in use on this brand, with how many customers carry it.

#### 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. |

### Staff customer hub {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}`

One customer's record: the account (with ``display_name``), their
services, invoices, tickets and staff notes. Each ticket carries its
``department`` and ``assigned_agent_name`` (the team member's first and
last name, else their email; ``null`` when unassigned), as the inbox
shows them.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Fix the profile (support), or change the account's standing (admin) {#op-patch-api-v1-orgs-org-slug-staff-customers-customer-id}

`PATCH /api/v1/orgs/{org_slug}/staff/customers/{customer_id}`

Fix the profile (support), or change the account's standing (admin).

A new email address is unverified again and gets a fresh verification
mail: the old inbox proved nothing about the new one. Leaving ``active``
ends every session the customer has, so a ban is not decorative.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) or null | no |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `status` | string or null | no |
| `reason` | string or null | no |
| `currency` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff customer activity {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-activity}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/activity`

One timeline, newest first: what staff did to the account, what the
customer did, and what billing and support recorded.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customer_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Silence a handle in community chat and the forum for a while, or lift it {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-chat-mute}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/chat-mute`

Silence a handle in community chat and the forum for a while, or lift it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `minutes` | integer or null | no |
| `reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff close customer {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-close}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/close`

Close and anonymise, with the same guard the customer's own close has:
no active services, no unpaid invoices.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff add credit {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-credit}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/credit`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `amount` | number or string | yes |
| `description` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff credit ledger {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-credit-ledger}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/credit-ledger`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customer_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Everything held about the customer, as one JSON file, for a privacy request {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-data-export}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/data-export`

Everything held about the customer, as one JSON file, for a privacy request.

The privacy policy promises a copy of their data to anyone who asks; this
is the copy. Admin and stepped-up like closing the account, because it is
the whole person in one download; rate-limited with the other exports; and
audited *before* the document is built, so the document itself records
that it was produced, by whom, and when.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff customer emails {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-emails}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/emails`

Every transactional email the brand sent this customer and whether it
went, so "we emailed your server details on this date" can be shown
rather than asserted.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customer_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff impersonate customer {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-impersonate}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/impersonate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `mode` | string or null | no |
| `elevated` | boolean | no |
| `reason` | string or null | no |
| `next` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Vouch for an address the customer proved another way (a call, a ticket from that inbox) {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-mark-verified}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/mark-verified`

Vouch for an address the customer proved another way (a call, a
ticket from that inbox). Admin only, and on the record.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List customer notes {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-notes}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/notes`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `customer_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add customer note {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-notes}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/notes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff customer payment methods {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-payment-methods}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/payment-methods`

What the customer has on file, as the customer sees it: a label, a
brand, the last four digits, the expiry. The gateway token never leaves
the row.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff customer related {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-related}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/related`

Other customers on this brand that share a sign-up IP, a sign-up
fingerprint, a phone number or a recent session address with this one.

Signals, not verdicts: a household shares an IP. Each match says which
signal it came from so the person reading can weigh it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff resend verification {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-resend-verification}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/resend-verification`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### For a customer who lost their phone: remove their second factor and end their sessions {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-reset-mfa}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/reset-mfa`

For a customer who lost their phone: remove their second factor and end
their sessions. They sign in again and, if the brand requires it, enrol.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff reset customer password {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-reset-password}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/reset-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff revoke customer sessions {#op-post-api-v1-orgs-org-slug-staff-customers-customer-id-revoke-sessions}

`POST /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/revoke-sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `token_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff customer sessions {#op-get-api-v1-orgs-org-slug-staff-customers-customer-id-sessions}

`GET /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff set customer tags {#op-put-api-v1-orgs-org-slug-staff-customers-customer-id-tags}

`PUT /api/v1/orgs/{org_slug}/staff/customers/{customer_id}/tags`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `tags` | array of string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customers: Store

> The 7 Organization API operations for store.

Source: https://www.coritan.com/docs/api/reference/organizations/customers/store/

Part of [Customers](/docs/api/reference/organizations/customers/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/store/customers/me`](#op-get-api-v1-orgs-org-slug-store-customers-me) | Get me |
| PATCH | [`/api/v1/orgs/{org_slug}/store/customers/me`](#op-patch-api-v1-orgs-org-slug-store-customers-me) | Name, phone, marketing consent (the shopper alone turns it on) and VAT id |
| GET | [`/api/v1/orgs/{org_slug}/store/customers/me/addresses`](#op-get-api-v1-orgs-org-slug-store-customers-me-addresses) | List my addresses |
| POST | [`/api/v1/orgs/{org_slug}/store/customers/me/addresses`](#op-post-api-v1-orgs-org-slug-store-customers-me-addresses) | Add my address |
| PATCH | [`/api/v1/orgs/{org_slug}/store/customers/me/addresses/{address_id}`](#op-patch-api-v1-orgs-org-slug-store-customers-me-addresses-address-id) | Update my address |
| DELETE | [`/api/v1/orgs/{org_slug}/store/customers/me/addresses/{address_id}`](#op-delete-api-v1-orgs-org-slug-store-customers-me-addresses-address-id) | Delete my address |
| GET | [`/api/v1/orgs/{org_slug}/store/customers/me/orders`](#op-get-api-v1-orgs-org-slug-store-customers-me-orders) | The shopper's orders in the key's mode, newest first |

### Get me {#op-get-api-v1-orgs-org-slug-store-customers-me}

`GET /api/v1/orgs/{org_slug}/store/customers/me`

#### 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. |

### Name, phone, marketing consent (the shopper alone turns it on) and VAT id {#op-patch-api-v1-orgs-org-slug-store-customers-me}

`PATCH /api/v1/orgs/{org_slug}/store/customers/me`

Name, phone, marketing consent (the shopper alone turns it on) and VAT id.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `phone` | string or null | no |
| `accepts_marketing` | boolean or null | no |
| `vat_id` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List my addresses {#op-get-api-v1-orgs-org-slug-store-customers-me-addresses}

`GET /api/v1/orgs/{org_slug}/store/customers/me/addresses`

#### 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. |

### Add my address {#op-post-api-v1-orgs-org-slug-store-customers-me-addresses}

`POST /api/v1/orgs/{org_slug}/store/customers/me/addresses`

An address needs ``address_1``, ``city`` and ``country_code``; the first
one saved is the default for shipping and billing.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `address_1` | string or null | no |
| `address_2` | string or null | no |
| `city` | string or null | no |
| `province` | string or null | no |
| `postal_code` | string or null | no |
| `country_code` | string or null | no |
| `phone` | string or null | no |
| `is_default_shipping` | boolean or null | no |
| `is_default_billing` | boolean or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update my address {#op-patch-api-v1-orgs-org-slug-store-customers-me-addresses-address-id}

`PATCH /api/v1/orgs/{org_slug}/store/customers/me/addresses/{address_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `address_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `address_1` | string or null | no |
| `address_2` | string or null | no |
| `city` | string or null | no |
| `province` | string or null | no |
| `postal_code` | string or null | no |
| `country_code` | string or null | no |
| `phone` | string or null | no |
| `is_default_shipping` | boolean or null | no |
| `is_default_billing` | boolean or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete my address {#op-delete-api-v1-orgs-org-slug-store-customers-me-addresses-address-id}

`DELETE /api/v1/orgs/{org_slug}/store/customers/me/addresses/{address_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `address_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The shopper's orders in the key's mode, newest first {#op-get-api-v1-orgs-org-slug-store-customers-me-orders}

`GET /api/v1/orgs/{org_slug}/store/customers/me/orders`

The shopper's orders in the key's mode, newest first.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `20`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Catalog & Services

> Org-scoped products, pricing overrides, and customer services.

Source: https://www.coritan.com/docs/api/reference/organizations/catalog-services/

Org-scoped products, pricing overrides, and customer services.

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Commerce](/docs/api/reference/organizations/catalog-services/commerce/) | 16 |
| [Platform products](/docs/api/reference/organizations/catalog-services/platform-products/) | 1 |
| [Products](/docs/api/reference/organizations/catalog-services/products/) | 5 |
| [Services](/docs/api/reference/organizations/catalog-services/services/) | 5 |
| [Staff](/docs/api/reference/organizations/catalog-services/staff/) | 13 |
| [Store](/docs/api/reference/organizations/catalog-services/store/) | 2 |

# Organization API: Catalog & Services: Commerce

> The 16 Organization API operations for commerce.

Source: https://www.coritan.com/docs/api/reference/organizations/catalog-services/commerce/

Part of [Catalog & Services](/docs/api/reference/organizations/catalog-services/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/collections/{collection_id}/products`](#op-put-api-v1-orgs-org-slug-commerce-collections-collection-id-products) | A manual collection's products become exactly these, in this order |
| GET | [`/api/v1/orgs/{org_slug}/commerce/products`](#op-get-api-v1-orgs-org-slug-commerce-products) | Products, most recently changed first |
| POST | [`/api/v1/orgs/{org_slug}/commerce/products`](#op-post-api-v1-orgs-org-slug-commerce-products) | Create product |
| GET | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}`](#op-get-api-v1-orgs-org-slug-commerce-products-product-id) | Get product |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}`](#op-patch-api-v1-orgs-org-slug-commerce-products-product-id) | Fields change when named |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}`](#op-delete-api-v1-orgs-org-slug-commerce-products-product-id) | Archived and gone from every list and the Store API |
| POST | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/images`](#op-post-api-v1-orgs-org-slug-commerce-products-product-id-images) | An https image |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/images/{image_id}`](#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-images-image-id) | Update image |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/images/{image_id}`](#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-images-image-id) | If it was the thumbnail, the next image takes its place |
| POST | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/options`](#op-post-api-v1-orgs-org-slug-commerce-products-product-id-options) | An option such as Size |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/options/{option_id}`](#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-options-option-id) | Update option |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/options/{option_id}`](#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-options-option-id) | Delete option |
| POST | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants`](#op-post-api-v1-orgs-org-slug-commerce-products-product-id-variants) | Create variant |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}`](#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id) | Fields change when named; prices replaces the variant's base prices |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}`](#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id) | Gone from the catalog; orders keep naming it, and its SKU is free |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}/prices`](#op-put-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id-prices) | Replace variant prices |

### A manual collection's products become exactly these, in this order {#op-put-api-v1-orgs-org-slug-commerce-collections-collection-id-products}

`PUT /api/v1/orgs/{org_slug}/commerce/collections/{collection_id}/products`

A manual collection's products become exactly these, in this order.
A smart collection answers 409: its rules choose.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `collection_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `product_ids` | array of integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Products, most recently changed first {#op-get-api-v1-orgs-org-slug-commerce-products}

`GET /api/v1/orgs/{org_slug}/commerce/products`

Products, most recently changed first. ``q`` matches the title, the
handle or a variant's SKU; ``collection_id`` follows a smart collection's
rules; ``category_id`` is direct membership unless ``include_descendants``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `status` | query | string or null | no |  |
| `collection_id` | query | integer or null | no |  |
| `category_id` | query | integer or null | no |  |
| `include_descendants` | query | boolean | no | Default: `False`. |
| `tag` | query | string or null | no |  |
| `sales_channel_id` | query | integer or null | no |  |
| `external_id` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create product {#op-post-api-v1-orgs-org-slug-commerce-products}

`POST /api/v1/orgs/{org_slug}/commerce/products`

A product, with its options, variants, channels, collections, categories
and tags when given. A draft unless ``status`` says otherwise; sold in the
store's default channel unless ``sales_channel_ids`` says otherwise.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `weight_g` | integer or null | no |
| `length_mm` | integer or null | no |
| `width_mm` | integer or null | no |
| `height_mm` | integer or null | no |
| `hs_code` | string or null | no |
| `origin_country` | string or null | no |
| `mid_code` | string or null | no |
| `material` | string or null | no |
| `tax_code` | string or null | no |
| `external_id` | string or null | no |
| `metadata` | object or null | no |
| `title` | string or null | no |
| `handle` | string or null | no |
| `subtitle` | string or null | no |
| `description` | string or null | no |
| `status` | string or null | no |
| `thumbnail_url` | string or null | no |
| `is_giftcard` | boolean or null | no |
| `discountable` | boolean or null | no |
| `product_type` | string or null | no |
| `vendor` | string or null | no |
| `shipping_profile_id` | integer or null | no |
| `seo_title` | string or null | no |
| `seo_description` | string or null | no |
| `options` | array of object or null | no |
| `variants` | array of object or null | no |
| `sales_channel_ids` | array of integer or null | no |
| `collection_ids` | array of integer or null | no |
| `category_ids` | array of integer or null | no |
| `tags` | array of any or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get product {#op-get-api-v1-orgs-org-slug-commerce-products-product-id}

`GET /api/v1/orgs/{org_slug}/commerce/products/{product_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Fields change when named {#op-patch-api-v1-orgs-org-slug-commerce-products-product-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/products/{product_id}`

Fields change when named. ``options``, ``variants``, ``sales_channel_ids``,
``collection_ids``, ``category_ids`` and ``tags`` replace what the product
had when given: a variant not in ``variants`` is deleted.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `weight_g` | integer or null | no |
| `length_mm` | integer or null | no |
| `width_mm` | integer or null | no |
| `height_mm` | integer or null | no |
| `hs_code` | string or null | no |
| `origin_country` | string or null | no |
| `mid_code` | string or null | no |
| `material` | string or null | no |
| `tax_code` | string or null | no |
| `external_id` | string or null | no |
| `metadata` | object or null | no |
| `title` | string or null | no |
| `handle` | string or null | no |
| `subtitle` | string or null | no |
| `description` | string or null | no |
| `status` | string or null | no |
| `thumbnail_url` | string or null | no |
| `is_giftcard` | boolean or null | no |
| `discountable` | boolean or null | no |
| `product_type` | string or null | no |
| `vendor` | string or null | no |
| `shipping_profile_id` | integer or null | no |
| `seo_title` | string or null | no |
| `seo_description` | string or null | no |
| `options` | array of object or null | no |
| `variants` | array of object or null | no |
| `sales_channel_ids` | array of integer or null | no |
| `collection_ids` | array of integer or null | no |
| `category_ids` | array of integer or null | no |
| `tags` | array of any or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Archived and gone from every list and the Store API {#op-delete-api-v1-orgs-org-slug-commerce-products-product-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/products/{product_id}`

Archived and gone from every list and the Store API. Orders keep naming
its variants; its handle and SKUs are free for new products.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### An https image {#op-post-api-v1-orgs-org-slug-commerce-products-product-id-images}

`POST /api/v1/orgs/{org_slug}/commerce/products/{product_id}/images`

An https image. The first one becomes the thumbnail if there is none.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string or null | no |
| `alt` | string or null | no |
| `variant_id` | integer or null | no |
| `rank` | integer or null | no |
| `width` | integer or null | no |
| `height` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update image {#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-images-image-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/products/{product_id}/images/{image_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `image_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string or null | no |
| `alt` | string or null | no |
| `variant_id` | integer or null | no |
| `rank` | integer or null | no |
| `width` | integer or null | no |
| `height` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### If it was the thumbnail, the next image takes its place {#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-images-image-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/products/{product_id}/images/{image_id}`

If it was the thumbnail, the next image takes its place.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `image_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### An option such as Size {#op-post-api-v1-orgs-org-slug-commerce-products-product-id-options}

`POST /api/v1/orgs/{org_slug}/commerce/products/{product_id}/options`

An option such as Size. Every existing variant takes its first value.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `values` | array of any or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update option {#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-options-option-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/products/{product_id}/options/{option_id}`

Rename the option, or give its full list of ``values``: new ones are
added, and one a variant still uses cannot be left out (409).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `option_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `values` | array of any or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete option {#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-options-option-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/products/{product_id}/options/{option_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `option_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create variant {#op-post-api-v1-orgs-org-slug-commerce-products-product-id-variants}

`POST /api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants`

A variant naming one value for each of the product's options (a new
value is added to its option). Its inventory item is created with it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `weight_g` | integer or null | no |
| `length_mm` | integer or null | no |
| `width_mm` | integer or null | no |
| `height_mm` | integer or null | no |
| `hs_code` | string or null | no |
| `origin_country` | string or null | no |
| `mid_code` | string or null | no |
| `material` | string or null | no |
| `tax_code` | string or null | no |
| `external_id` | string or null | no |
| `metadata` | object or null | no |
| `title` | string or null | no |
| `sku` | string or null | no |
| `barcode` | string or null | no |
| `ean` | string or null | no |
| `upc` | string or null | no |
| `options` | object or null | no |
| `manage_inventory` | boolean or null | no |
| `allow_backorder` | boolean or null | no |
| `rank` | integer or null | no |
| `prices` | array of object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Fields change when named; prices replaces the variant's base prices {#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}`

Fields change when named; ``prices`` replaces the variant's base prices.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `variant_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `weight_g` | integer or null | no |
| `length_mm` | integer or null | no |
| `width_mm` | integer or null | no |
| `height_mm` | integer or null | no |
| `hs_code` | string or null | no |
| `origin_country` | string or null | no |
| `mid_code` | string or null | no |
| `material` | string or null | no |
| `tax_code` | string or null | no |
| `external_id` | string or null | no |
| `metadata` | object or null | no |
| `title` | string or null | no |
| `sku` | string or null | no |
| `barcode` | string or null | no |
| `ean` | string or null | no |
| `upc` | string or null | no |
| `options` | object or null | no |
| `manage_inventory` | boolean or null | no |
| `allow_backorder` | boolean or null | no |
| `rank` | integer or null | no |
| `prices` | array of object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Gone from the catalog; orders keep naming it, and its SKU is free {#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}`

Gone from the catalog; orders keep naming it, and its SKU is free.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `variant_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Replace variant prices {#op-put-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id-prices}

`PUT /api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}/prices`

The variant's base prices (outside any price list) become exactly these:
``{"prices": [...]}`` or a bare list of ``{currency_code, amount,
compare_at_amount?, region_id?, min_quantity?, max_quantity?}``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `variant_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

Type: Payload.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Catalog & Services: Platform products

> The 1 Organization API operations for platform products.

Source: https://www.coritan.com/docs/api/reference/organizations/catalog-services/platform-products/

Part of [Catalog & Services](/docs/api/reference/organizations/catalog-services/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/platform-products`](#op-get-api-v1-orgs-org-slug-platform-products) | The platform products this organization may link a product to |

### The platform products this organization may link a product to {#op-get-api-v1-orgs-org-slug-platform-products}

`GET /api/v1/orgs/{org_slug}/platform-products`

The platform products this organization may link a product to.

The platform catalogue (active products, with subnet rentals only while
they are on), plus the free plan when a platform admin has let the
organization sell it. It carries no availability: it is for choosing
what a product provisions, and the storefront reads availability itself.

#### 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. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].name` | string |
| `[].slug` | string |
| `[].description` | string or null |
| `[].group_name` | string or null |
| `[].module_name` | string |
| `[].hardware_tier_id` | integer or null |
| `[].hardware_tier` | HardwareTierSummary or null |
| `[].hardware_tier.id` | integer |
| `[].hardware_tier.slug` | string |
| `[].hardware_tier.name` | string |
| `[].hardware_tier.code` | string |
| `[].hardware_tier.description` | string or null |
| `[].status` | string |
| `[].config_schema` | object or null |
| `[].sort_order` | integer |
| `[].stock_limit` | integer or null |
| `[].metadata` | object or null |
| `[].pricing` | array of PricingResponse |
| `[].pricing[].id` | integer |
| `[].pricing[].product_id` | integer |
| `[].pricing[].name` | string |
| `[].pricing[].billing_cycle` | string |
| `[].pricing[].price` | number |
| `[].pricing[].setup_fee` | number |
| `[].pricing[].currency` | string |
| `[].pricing[].is_active` | boolean |
| `[].pricing[].sort_order` | integer |
| `[].pricing[].metadata` | object or null |
| `[].pricing[].created_at` | string (date-time) |
| `[].config_options` | array of ConfigOptionResponse |
| `[].config_options[].id` | integer |
| `[].config_options[].product_id` | integer |
| `[].config_options[].field_name` | string |
| `[].config_options[].label` | string |
| `[].config_options[].field_type` | string |
| `[].config_options[].options` | object or null |
| `[].config_options[].default_value` | string or null |
| `[].config_options[].required` | boolean |
| `[].config_options[].price_modifier` | number |
| `[].config_options[].sort_order` | integer |
| `[].is_orderable_now` | boolean or null |
| `[].stock_status` | string or null |
| `[].availability_reason` | string or null |
| `[].group_is_orderable_now` | boolean or null |
| `[].group_stock_status` | string or null |
| `[].locations` | array of ProductLocationAvailability |
| `[].locations[].id` | integer |
| `[].locations[].code` | string |
| `[].locations[].name` | string |
| `[].locations[].country_code` | string |
| `[].locations[].available` | boolean |
| `[].locations[].orderable` | boolean |
| `[].locations[].reason` | string or null |
| `[].created_at` | string (date-time) |

# Organization API: Catalog & Services: Products

> The 5 Organization API operations for products.

Source: https://www.coritan.com/docs/api/reference/organizations/catalog-services/products/

Part of [Catalog & Services](/docs/api/reference/organizations/catalog-services/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/products`](#op-get-api-v1-orgs-org-slug-products) | List products |
| POST | [`/api/v1/orgs/{org_slug}/products`](#op-post-api-v1-orgs-org-slug-products) | Create product |
| PATCH | [`/api/v1/orgs/{org_slug}/products/{product_id}`](#op-patch-api-v1-orgs-org-slug-products-product-id) | Update product |
| GET | [`/api/v1/orgs/{org_slug}/products/{product_id}/pricing`](#op-get-api-v1-orgs-org-slug-products-product-id-pricing) | List product pricing |
| POST | [`/api/v1/orgs/{org_slug}/products/{product_id}/pricing`](#op-post-api-v1-orgs-org-slug-products-product-id-pricing) | Create product pricing |

### List products {#op-get-api-v1-orgs-org-slug-products}

`GET /api/v1/orgs/{org_slug}/products`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `active_only` | query | boolean | no | Default: `True`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_id` | integer |
| `[].name` | string |
| `[].slug` | string |
| `[].description` | string or null |
| `[].product_type` | string |
| `[].linked_product_id` | integer or null |
| `[].is_active` | boolean |
| `[].sort_order` | integer |
| `[].created_at` | string (date-time) or null |
| `[].active_plan_count` | integer |

### Create product {#op-post-api-v1-orgs-org-slug-products}

`POST /api/v1/orgs/{org_slug}/products`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `slug` | string | yes |
| `description` | string or null | no |
| `product_type` | string | no |
| `linked_product_id` | integer or null | no |
| `config_schema` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `name` | string |
| `slug` | string |
| `description` | string or null |
| `product_type` | string |
| `linked_product_id` | integer or null |
| `is_active` | boolean |
| `sort_order` | integer |
| `created_at` | string (date-time) or null |
| `active_plan_count` | integer |

### Update product {#op-patch-api-v1-orgs-org-slug-products-product-id}

`PATCH /api/v1/orgs/{org_slug}/products/{product_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `description` | string or null | no |
| `is_active` | boolean or null | no |
| `config_schema` | object or null | no |
| `sort_order` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `name` | string |
| `slug` | string |
| `description` | string or null |
| `product_type` | string |
| `linked_product_id` | integer or null |
| `is_active` | boolean |
| `sort_order` | integer |
| `created_at` | string (date-time) or null |
| `active_plan_count` | integer |

### List product pricing {#op-get-api-v1-orgs-org-slug-products-product-id-pricing}

`GET /api/v1/orgs/{org_slug}/products/{product_id}/pricing`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_product_id` | integer |
| `[].name` | string |
| `[].billing_cycle` | string |
| `[].price` | string |
| `[].setup_fee` | string |
| `[].currency` | string |
| `[].is_active` | boolean |
| `[].sort_order` | integer |
| `[].created_at` | string (date-time) or null |

### Create product pricing {#op-post-api-v1-orgs-org-slug-products-product-id-pricing}

`POST /api/v1/orgs/{org_slug}/products/{product_id}/pricing`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `product_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `billing_cycle` | string | yes |
| `price` | number or string | yes |
| `setup_fee` | number or string | no |
| `currency` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_product_id` | integer |
| `name` | string |
| `billing_cycle` | string |
| `price` | string |
| `setup_fee` | string |
| `currency` | string |
| `is_active` | boolean |
| `sort_order` | integer |
| `created_at` | string (date-time) or null |

# Organization API: Catalog & Services: Services

> The 5 Organization API operations for services.

Source: https://www.coritan.com/docs/api/reference/organizations/catalog-services/services/

Part of [Catalog & Services](/docs/api/reference/organizations/catalog-services/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/services`](#op-get-api-v1-orgs-org-slug-services) | The org's services, newest first, each naming its product, plan and customer |
| POST | [`/api/v1/orgs/{org_slug}/services`](#op-post-api-v1-orgs-org-slug-services) | Order service |
| GET | [`/api/v1/orgs/{org_slug}/services/{service_id}`](#op-get-api-v1-orgs-org-slug-services-service-id) | Get service |
| POST | [`/api/v1/orgs/{org_slug}/services/{service_id}/suspend`](#op-post-api-v1-orgs-org-slug-services-service-id-suspend) | Suspend service |
| POST | [`/api/v1/orgs/{org_slug}/services/{service_id}/unsuspend`](#op-post-api-v1-orgs-org-slug-services-service-id-unsuspend) | Unsuspend service |

### The org's services, newest first, each naming its product, plan and customer {#op-get-api-v1-orgs-org-slug-services}

`GET /api/v1/orgs/{org_slug}/services`

The org's services, newest first, each naming its product, plan and
customer.

``q`` matches the hostname, the customer's email, name or company, the
product or plan name, a tag, or the service number. ``with_total=true``
answers ``{items, total, limit, offset, counts}``; ``counts`` per status
are for the same customer, tag and search whatever the status filter.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `customer_id` | query | integer | no |  |
| `status_filter` | query | string | no |  |
| `tag` | query | string | no |  |
| `q` | query | string | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |
| `with_total` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Order service {#op-post-api-v1-orgs-org-slug-services}

`POST /api/v1/orgs/{org_slug}/services`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `customer_id` | integer | yes |
| `org_product_id` | integer | yes |
| `org_pricing_id` | integer | yes |
| `hostname` | string or null | no |
| `config` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `customer_id` | integer |
| `org_product_id` | integer |
| `org_pricing_id` | integer |
| `platform_service_id` | integer or null |
| `hostname` | string or null |
| `status` | string |
| `billing_cycle` | string |
| `amount` | string |
| `next_due_date` | string (date-time) or null |
| `config` | object or null |
| `provisioned_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `tags` | array of string |
| `product_name` | string or null |
| `plan_name` | string or null |
| `currency` | string or null |
| `customer_email` | string or null |
| `customer_name` | string or null |
| `customer_status` | string or null |

### Get service {#op-get-api-v1-orgs-org-slug-services-service-id}

`GET /api/v1/orgs/{org_slug}/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. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `customer_id` | integer |
| `org_product_id` | integer |
| `org_pricing_id` | integer |
| `platform_service_id` | integer or null |
| `hostname` | string or null |
| `status` | string |
| `billing_cycle` | string |
| `amount` | string |
| `next_due_date` | string (date-time) or null |
| `config` | object or null |
| `provisioned_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `tags` | array of string |
| `product_name` | string or null |
| `plan_name` | string or null |
| `currency` | string or null |
| `customer_email` | string or null |
| `customer_name` | string or null |
| `customer_status` | string or null |

### Suspend service {#op-post-api-v1-orgs-org-slug-services-service-id-suspend}

`POST /api/v1/orgs/{org_slug}/services/{service_id}/suspend`

#### 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. |

### Unsuspend service {#op-post-api-v1-orgs-org-slug-services-service-id-unsuspend}

`POST /api/v1/orgs/{org_slug}/services/{service_id}/unsuspend`

#### 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. |

# Organization API: Catalog & Services: Staff

> The 13 Organization API operations for staff.

Source: https://www.coritan.com/docs/api/reference/organizations/catalog-services/staff/

Part of [Catalog & Services](/docs/api/reference/organizations/catalog-services/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/cancel`](#op-post-api-v1-orgs-org-slug-staff-services-service-id-cancel) | Staff cancel service |
| POST | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/cancel-plan-change`](#op-post-api-v1-orgs-org-slug-staff-services-service-id-cancel-plan-change) | Staff cancel plan change |
| GET | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/cancel-preview`](#op-get-api-v1-orgs-org-slug-staff-services-service-id-cancel-preview) | Staff cancel preview |
| POST | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/change-plan`](#op-post-api-v1-orgs-org-slug-staff-services-service-id-change-plan) | Move the service to another plan of the same cycle |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/due-date`](#op-patch-api-v1-orgs-org-slug-staff-services-service-id-due-date) | Move the next renewal |
| GET | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/notes`](#op-get-api-v1-orgs-org-slug-staff-services-service-id-notes) | Staff service notes |
| POST | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/notes`](#op-post-api-v1-orgs-org-slug-staff-services-service-id-notes) | Staff add service note |
| GET | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/plan-options`](#op-get-api-v1-orgs-org-slug-staff-services-service-id-plan-options) | Staff plan options |
| GET | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/plan-preview`](#op-get-api-v1-orgs-org-slug-staff-services-service-id-plan-preview) | Staff plan preview |
| POST | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/retry-provision`](#op-post-api-v1-orgs-org-slug-staff-services-service-id-retry-provision) | Re-queue provisioning for an order stuck before it had a server |
| POST | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/suspend`](#op-post-api-v1-orgs-org-slug-staff-services-service-id-suspend) | Staff suspend service |
| POST | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/terminate`](#op-post-api-v1-orgs-org-slug-staff-services-service-id-terminate) | End a service now with no cancellation credit |
| POST | [`/api/v1/orgs/{org_slug}/staff/services/{service_id}/unsuspend`](#op-post-api-v1-orgs-org-slug-staff-services-service-id-unsuspend) | Staff unsuspend service |

### Staff cancel service {#op-post-api-v1-orgs-org-slug-staff-services-service-id-cancel}

`POST /api/v1/orgs/{org_slug}/staff/services/{service_id}/cancel`

Cancel on the customer's behalf: the same sequence their own button runs,
credit for unused time included, with the staff member on the audit row.

#### 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_snapshot` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff cancel plan change {#op-post-api-v1-orgs-org-slug-staff-services-service-id-cancel-plan-change}

`POST /api/v1/orgs/{org_slug}/staff/services/{service_id}/cancel-plan-change`

#### 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. |

### Staff cancel preview {#op-get-api-v1-orgs-org-slug-staff-services-service-id-cancel-preview}

`GET /api/v1/orgs/{org_slug}/staff/services/{service_id}/cancel-preview`

#### 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. |

### Move the service to another plan of the same cycle {#op-post-api-v1-orgs-org-slug-staff-services-service-id-change-plan}

`POST /api/v1/orgs/{org_slug}/staff/services/{service_id}/change-plan`

Move the service to another plan of the same cycle. An upgrade raises
the prorated invoice the customer pays; a downgrade credits the wallet
under the credit policy. The customer's own flow, run by staff.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### 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. |

### Move the next renewal {#op-patch-api-v1-orgs-org-slug-staff-services-service-id-due-date}

`PATCH /api/v1/orgs/{org_slug}/staff/services/{service_id}/due-date`

Move the next renewal. Extending is goodwill; pulling it in is a
correction. Both are written to the platform service too, so the
invoice run and the suspension sweeper see the same date.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `next_due_date` | string (date) | yes |
| `reason` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff service notes {#op-get-api-v1-orgs-org-slug-staff-services-service-id-notes}

`GET /api/v1/orgs/{org_slug}/staff/services/{service_id}/notes`

#### 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. |

### Staff add service note {#op-post-api-v1-orgs-org-slug-staff-services-service-id-notes}

`POST /api/v1/orgs/{org_slug}/staff/services/{service_id}/notes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff plan options {#op-get-api-v1-orgs-org-slug-staff-services-service-id-plan-options}

`GET /api/v1/orgs/{org_slug}/staff/services/{service_id}/plan-options`

#### 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. |

### Staff plan preview {#op-get-api-v1-orgs-org-slug-staff-services-service-id-plan-preview}

`GET /api/v1/orgs/{org_slug}/staff/services/{service_id}/plan-preview`

#### 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. |

### Re-queue provisioning for an order stuck before it had a server {#op-post-api-v1-orgs-org-slug-staff-services-service-id-retry-provision}

`POST /api/v1/orgs/{org_slug}/staff/services/{service_id}/retry-provision`

Re-queue provisioning for an order stuck before it had a server.

The order must be this brand's, still pending, provisioning or failed,
have no live server yet, be paid for (or never invoiced), and have no
provision job already queued for it: paying is what starts provisioning,
and this must not be a way around that, whatever the order's status says.

#### 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. |

### Staff suspend service {#op-post-api-v1-orgs-org-slug-staff-services-service-id-suspend}

`POST /api/v1/orgs/{org_slug}/staff/services/{service_id}/suspend`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string or null | no |
| `notify` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### End a service now with no cancellation credit {#op-post-api-v1-orgs-org-slug-staff-services-service-id-terminate}

`POST /api/v1/orgs/{org_slug}/staff/services/{service_id}/terminate`

End a service now with no cancellation credit. This is for abuse, fraud,
or a refund already made. Admin only; the reason is kept.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |
| `notify_customer` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff unsuspend service {#op-post-api-v1-orgs-org-slug-staff-services-service-id-unsuspend}

`POST /api/v1/orgs/{org_slug}/staff/services/{service_id}/unsuspend`

#### 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. |

# Organization API: Catalog & Services: Store

> The 2 Organization API operations for store.

Source: https://www.coritan.com/docs/api/reference/organizations/catalog-services/store/

Part of [Catalog & Services](/docs/api/reference/organizations/catalog-services/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/store/products`](#op-get-api-v1-orgs-org-slug-store-products) | Published products in the key's sales channels |
| GET | [`/api/v1/orgs/{org_slug}/store/products/{id_or_handle}`](#op-get-api-v1-orgs-org-slug-store-products-id-or-handle) | One published product by handle (or by id), priced like the list |

### Published products in the key's sales channels {#op-get-api-v1-orgs-org-slug-store-products}

`GET /api/v1/orgs/{org_slug}/store/products`

Published products in the key's sales channels. ``category_*`` includes
the categories under it; ``collection_*`` follows a smart collection's rules.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `id` | query | array of integer or null | no | Only these product ids (at most 100) |
| `collection_id` | query | integer or null | no |  |
| `collection_handle` | query | string or null | no |  |
| `category_id` | query | integer or null | no |  |
| `category_handle` | query | string or null | no |  |
| `tag` | query | string or null | no |  |
| `sales_channel_id` | query | integer or null | no |  |
| `region_id` | query | integer or null | no |  |
| `country_code` | query | string or null | no |  |
| `currency_code` | query | string or null | no |  |
| `order` | query | string | no | Default: `-created_at`. |
| `limit` | query | integer | no | Default: `20`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### One published product by handle (or by id), priced like the list {#op-get-api-v1-orgs-org-slug-store-products-id-or-handle}

`GET /api/v1/orgs/{org_slug}/store/products/{id_or_handle}`

One published product by handle (or by id), priced like the list.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `id_or_handle` | path | string | yes |
| `org_slug` | path | string | yes |
| `sales_channel_id` | query | integer or null | no |
| `region_id` | query | integer or null | no |
| `country_code` | query | string or null | no |
| `currency_code` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Billing & Payouts

> Org invoices, credit grants, revenue, payout preferences, and billing webhooks.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/

Org invoices, credit grants, revenue, payout preferences, and billing webhooks.

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Billing](/docs/api/reference/organizations/billing-payouts/billing/) | 8 |
| [Commerce](/docs/api/reference/organizations/billing-payouts/commerce/) | 3 |
| [Disputes](/docs/api/reference/organizations/billing-payouts/disputes/) | 2 |
| [Invoices](/docs/api/reference/organizations/billing-payouts/invoices/) | 3 |
| [Mail](/docs/api/reference/organizations/billing-payouts/mail/) | 3 |
| [Payouts](/docs/api/reference/organizations/billing-payouts/payouts/) | 1 |
| [Staff](/docs/api/reference/organizations/billing-payouts/staff/) | 12 |
| [Statements](/docs/api/reference/organizations/billing-payouts/statements/) | 7 |
| [Stats](/docs/api/reference/organizations/billing-payouts/stats/) | 1 |
| [Webhooks](/docs/api/reference/organizations/billing-payouts/webhooks/) | 4 |

# Organization API: Billing & Payouts: Billing

> The 8 Organization API operations for billing.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/billing/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/billing/paynow`](#op-get-api-v1-orgs-org-slug-billing-paynow) | Get paynow status |
| PUT | [`/api/v1/orgs/{org_slug}/billing/paynow`](#op-put-api-v1-orgs-org-slug-billing-paynow) | Save org-owned PayNow store credentials (owngateway / hybrid) |
| GET | [`/api/v1/orgs/{org_slug}/billing/paynow/affiliates`](#op-get-api-v1-orgs-org-slug-billing-paynow-affiliates) | List paynow affiliates |
| POST | [`/api/v1/orgs/{org_slug}/billing/paynow/affiliates`](#op-post-api-v1-orgs-org-slug-billing-paynow-affiliates) | Create paynow affiliate |
| GET | [`/api/v1/orgs/{org_slug}/billing/paynow/giftcards`](#op-get-api-v1-orgs-org-slug-billing-paynow-giftcards) | List paynow giftcards |
| POST | [`/api/v1/orgs/{org_slug}/billing/paynow/giftcards`](#op-post-api-v1-orgs-org-slug-billing-paynow-giftcards) | Create paynow giftcard |
| GET | [`/api/v1/orgs/{org_slug}/billing/paynow/subscriptions`](#op-get-api-v1-orgs-org-slug-billing-paynow-subscriptions) | List paynow subscriptions |
| POST | [`/api/v1/orgs/{org_slug}/billing/paynow/subscriptions/{subscription_id}/cancel`](#op-post-api-v1-orgs-org-slug-billing-paynow-subscriptions-subscription-id-cancel) | Cancel paynow subscription |

### Get paynow status {#op-get-api-v1-orgs-org-slug-billing-paynow}

`GET /api/v1/orgs/{org_slug}/billing/paynow`

#### 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. |

### Save org-owned PayNow store credentials (owngateway / hybrid) {#op-put-api-v1-orgs-org-slug-billing-paynow}

`PUT /api/v1/orgs/{org_slug}/billing/paynow`

Save org-owned PayNow store credentials (own_gateway / hybrid).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `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. |

### List paynow affiliates {#op-get-api-v1-orgs-org-slug-billing-paynow-affiliates}

`GET /api/v1/orgs/{org_slug}/billing/paynow/affiliates`

#### 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. |

### Create paynow affiliate {#op-post-api-v1-orgs-org-slug-billing-paynow-affiliates}

`POST /api/v1/orgs/{org_slug}/billing/paynow/affiliates`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `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. |

### List paynow giftcards {#op-get-api-v1-orgs-org-slug-billing-paynow-giftcards}

`GET /api/v1/orgs/{org_slug}/billing/paynow/giftcards`

#### 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. |

### Create paynow giftcard {#op-post-api-v1-orgs-org-slug-billing-paynow-giftcards}

`POST /api/v1/orgs/{org_slug}/billing/paynow/giftcards`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `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. |

### List paynow subscriptions {#op-get-api-v1-orgs-org-slug-billing-paynow-subscriptions}

`GET /api/v1/orgs/{org_slug}/billing/paynow/subscriptions`

#### 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. |

### Cancel paynow subscription {#op-post-api-v1-orgs-org-slug-billing-paynow-subscriptions-subscription-id-cancel}

`POST /api/v1/orgs/{org_slug}/billing/paynow/subscriptions/{subscription_id}/cancel`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `subscription_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Billing & Payouts: Commerce

> The 3 Organization API operations for commerce.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/commerce/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/commerce/payouts`](#op-get-api-v1-orgs-org-slug-commerce-payouts) | List payouts |
| POST | [`/api/v1/orgs/{org_slug}/commerce/payouts`](#op-post-api-v1-orgs-org-slug-commerce-payouts) | Ask for the payable balance in a currency now |
| GET | [`/api/v1/orgs/{org_slug}/commerce/payouts/{payout_id}`](#op-get-api-v1-orgs-org-slug-commerce-payouts-payout-id) | The payout and the ledger rows it holds, oldest first |

### List payouts {#op-get-api-v1-orgs-org-slug-commerce-payouts}

`GET /api/v1/orgs/{org_slug}/commerce/payouts`

Newest first, with ``summary``: the schedule and, per currency, what is
payable now, the minimum and any payout still open.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no | A status, or open for both open ones. |
| `currency_code` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Ask for the payable balance in a currency now {#op-post-api-v1-orgs-org-slug-commerce-payouts}

`POST /api/v1/orgs/{org_slug}/commerce/payouts`

Ask for the payable balance in a currency now. 409 with ``error``
``nothing_payable``, ``below_minimum``, ``payout_open`` or ``held`` when
there is none to make; the balance carries.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `currency_code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The payout and the ledger rows it holds, oldest first {#op-get-api-v1-orgs-org-slug-commerce-payouts-payout-id}

`GET /api/v1/orgs/{org_slug}/commerce/payouts/{payout_id}`

The payout and the ledger rows it holds, oldest first.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `payout_id` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Ledger rows per page. Default: `100`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Billing & Payouts: Disputes

> The 2 Organization API operations for disputes.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/disputes/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/disputes`](#op-get-api-v1-orgs-org-slug-disputes) | Chargebacks raised against this org's customers |
| GET | [`/api/v1/orgs/{org_slug}/disputes/{dispute_id}`](#op-get-api-v1-orgs-org-slug-disputes-dispute-id) | Get org dispute |

### Chargebacks raised against this org's customers {#op-get-api-v1-orgs-org-slug-disputes}

`GET /api/v1/orgs/{org_slug}/disputes`

Chargebacks raised against this org's customers.

Resellers had no dispute surface at all. Under ``platform_mor`` that is
arguable, since Coritan is merchant of record and it is our fight. Under
``own_gateway`` it is not: the org's own store takes the chargeback, the
money comes off them, and they could not see it happen.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get org dispute {#op-get-api-v1-orgs-org-slug-disputes-dispute-id}

`GET /api/v1/orgs/{org_slug}/disputes/{dispute_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `dispute_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Billing & Payouts: Invoices

> The 3 Organization API operations for invoices.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/invoices/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/invoices`](#op-get-api-v1-orgs-org-slug-invoices) | The org's invoices, newest first, each naming its customer |
| GET | [`/api/v1/orgs/{org_slug}/invoices/{invoice_id}`](#op-get-api-v1-orgs-org-slug-invoices-invoice-id) | Get invoice |
| POST | [`/api/v1/orgs/{org_slug}/invoices/{invoice_id}/mark-paid`](#op-post-api-v1-orgs-org-slug-invoices-invoice-id-mark-paid) | Mark invoice paid |

### The org's invoices, newest first, each naming its customer {#op-get-api-v1-orgs-org-slug-invoices}

`GET /api/v1/orgs/{org_slug}/invoices`

The org's invoices, newest first, each naming its customer.

``status_filter=open`` is unpaid or overdue. ``with_total=true`` answers
``{items, total, limit, offset, counts, outstanding}`` instead of a bare
list: ``counts`` per status ignore the status filter (they are the tab's
pills) and ``outstanding`` is what every open invoice owes per currency,
both under the customer filter.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `customer_id` | query | integer | no |  |
| `status_filter` | query | string | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |
| `with_total` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get invoice {#op-get-api-v1-orgs-org-slug-invoices-invoice-id}

`GET /api/v1/orgs/{org_slug}/invoices/{invoice_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `customer_id` | integer |
| `invoice_number` | string |
| `subtotal` | string |
| `tax` | string |
| `total` | string |
| `amount_paid` | string |
| `currency` | string |
| `status` | string |
| `due_date` | string (date-time) or null |
| `paid_at` | string (date-time) or null |
| `notes` | string or null |
| `created_at` | string (date-time) or null |
| `customer_name` | string or null |
| `customer_email` | string or null |
| `items` | array of OrgInvoiceItemResponse |
| `items[].id` | integer |
| `items[].invoice_id` | integer |
| `items[].org_service_id` | integer or null |
| `items[].description` | string |
| `items[].item_type` | string |
| `items[].quantity` | string |
| `items[].unit_price` | string |
| `items[].total` | string |

### Mark invoice paid {#op-post-api-v1-orgs-org-slug-invoices-invoice-id-mark-paid}

`POST /api/v1/orgs/{org_slug}/invoices/{invoice_id}/mark-paid`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Billing & Payouts: Mail

> The 3 Organization API operations for mail.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/mail/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/webhooks`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-webhooks) | List webhooks |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/webhooks`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-webhooks) | Create webhook |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/webhooks/{webhook_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-webhooks-webhook-id) | Delete webhook |

### List webhooks {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-webhooks}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/webhooks`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create webhook {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-webhooks}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/webhooks`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `events` | array of string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete webhook {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-webhooks-webhook-id}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/webhooks/{webhook_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `webhook_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Billing & Payouts: Payouts

> The 1 Organization API operations for payouts.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/payouts/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/payouts`](#op-get-api-v1-orgs-org-slug-payouts) | The organization's hosting payouts, newest first |

### The organization's hosting payouts, newest first {#op-get-api-v1-orgs-org-slug-payouts}

`GET /api/v1/orgs/{org_slug}/payouts`

The organization's hosting payouts, newest first. Its store's payouts are
at ``/{org_slug}/commerce/payouts``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_id` | integer |
| `[].amount` | string |
| `[].currency` | string |
| `[].platform_fee` | string |
| `[].net_amount` | string |
| `[].status` | string |
| `[].payout_method` | string |
| `[].period_start` | string (date-time) or null |
| `[].period_end` | string (date-time) or null |
| `[].scheduled_at` | string (date-time) or null |
| `[].completed_at` | string (date-time) or null |
| `[].created_at` | string (date-time) or null |

# Organization API: Billing & Payouts: Staff

> The 12 Organization API operations for staff.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/staff/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/staff/invoices`](#op-get-api-v1-orgs-org-slug-staff-invoices) | Staff invoices |
| POST | [`/api/v1/orgs/{org_slug}/staff/invoices`](#op-post-api-v1-orgs-org-slug-staff-invoices) | Raise a one-line invoice by hand: a setup fee, an add-on, a correction |
| GET | [`/api/v1/orgs/{org_slug}/staff/invoices/export.csv`](#op-get-api-v1-orgs-org-slug-staff-invoices-export-csv) | Every invoice in the window, as a CSV |
| GET | [`/api/v1/orgs/{org_slug}/staff/invoices/stats`](#op-get-api-v1-orgs-org-slug-staff-invoices-stats) | Staff invoices stats |
| GET | [`/api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}`](#op-get-api-v1-orgs-org-slug-staff-invoices-invoice-id) | Staff invoice hub |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}`](#op-patch-api-v1-orgs-org-slug-staff-invoices-invoice-id) | Staff patch invoice |
| POST | [`/api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/cancel`](#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-cancel) | Close an invoice nobody should pay |
| POST | [`/api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/charge`](#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-charge) | Staff charge invoice |
| POST | [`/api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/mark-paid`](#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-mark-paid) | Staff mark invoice paid |
| GET | [`/api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/pdf`](#op-get-api-v1-orgs-org-slug-staff-invoices-invoice-id-pdf) | The same document the customer downloads from their portal |
| POST | [`/api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/refund`](#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-refund) | Staff refund invoice |
| POST | [`/api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/send`](#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-send) | Staff send invoice |

### Staff invoices {#op-get-api-v1-orgs-org-slug-staff-invoices}

`GET /api/v1/orgs/{org_slug}/staff/invoices`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `customer_id` | query | integer or null | no |  |
| `status_filter` | query | string or null | no |  |
| `audience` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Raise a one-line invoice by hand: a setup fee, an add-on, a correction {#op-post-api-v1-orgs-org-slug-staff-invoices}

`POST /api/v1/orgs/{org_slug}/staff/invoices`

Raise a one-line invoice by hand: a setup fee, an add-on, a correction.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `customer_id` | integer | yes |
| `description` | string | yes |
| `amount` | number or string | yes |
| `tax` | number or string | no |
| `currency` | string or null | no |
| `due_days` | integer | no |
| `notes` | string or null | no |
| `service_id` | integer or null | no |
| `send_email` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every invoice in the window, as a CSV {#op-get-api-v1-orgs-org-slug-staff-invoices-export-csv}

`GET /api/v1/orgs/{org_slug}/staff/invoices/export.csv`

Every invoice in the window, as a CSV.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `status` | query | string or null | no |
| `since` | query | string (date) or null | no |
| `until` | query | string (date) or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff invoices stats {#op-get-api-v1-orgs-org-slug-staff-invoices-stats}

`GET /api/v1/orgs/{org_slug}/staff/invoices/stats`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `audience` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff invoice hub {#op-get-api-v1-orgs-org-slug-staff-invoices-invoice-id}

`GET /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff patch invoice {#op-patch-api-v1-orgs-org-slug-staff-invoices-invoice-id}

`PATCH /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `notes` | string or null | no |
| `due_date` | string (date) or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Close an invoice nobody should pay {#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-cancel}

`POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/cancel`

Close an invoice nobody should pay. A paid one is refunded, not cancelled.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff charge invoice {#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-charge}

`POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/charge`

Charge the customer's saved method for an unpaid invoice now, the way
the dunning job would on its next attempt. Skipped, not forced, when the
customer has turned auto-pay off or a payment is still settling.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff mark invoice paid {#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-mark-paid}

`POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/mark-paid`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The same document the customer downloads from their portal {#op-get-api-v1-orgs-org-slug-staff-invoices-invoice-id-pdf}

`GET /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/pdf`

The same document the customer downloads from their portal.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff refund invoice {#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-refund}

`POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/refund`

Refund a paid invoice on staff's own decision (a goodwill gesture, a
duplicate charge, a mistake), in full or in part, to the payment method
or the wallet. Recorded as a refund request staff opened and approved, so
the ledger, the invoice, the service and the audit log move exactly as
they do for a request the customer made.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `amount` | number or string | yes |
| `reason` | string | yes |
| `to` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff send invoice {#op-post-api-v1-orgs-org-slug-staff-invoices-invoice-id-send}

`POST /api/v1/orgs/{org_slug}/staff/invoices/{invoice_id}/send`

Send the invoice email again: the issued one for an open invoice, the
overdue one once it is past due. Nothing about the invoice changes.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Billing & Payouts: Statements

> The 7 Organization API operations for statements.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/statements/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/statements`](#op-get-api-v1-orgs-org-slug-statements) | Org list statements |
| POST | [`/api/v1/orgs/{org_slug}/statements/generate`](#op-post-api-v1-orgs-org-slug-statements-generate) | Org generate statement |
| GET | [`/api/v1/orgs/{org_slug}/statements/options-catalog`](#op-get-api-v1-orgs-org-slug-statements-options-catalog) | Org statements options catalog |
| GET | [`/api/v1/orgs/{org_slug}/statements/{statement_id}`](#op-get-api-v1-orgs-org-slug-statements-statement-id) | Org get statement |
| DELETE | [`/api/v1/orgs/{org_slug}/statements/{statement_id}`](#op-delete-api-v1-orgs-org-slug-statements-statement-id) | Org delete statement |
| GET | [`/api/v1/orgs/{org_slug}/statements/{statement_id}/csv`](#op-get-api-v1-orgs-org-slug-statements-statement-id-csv) | Org statement CSV |
| GET | [`/api/v1/orgs/{org_slug}/statements/{statement_id}/pdf`](#op-get-api-v1-orgs-org-slug-statements-statement-id-pdf) | Org statement pdf |

### Org list statements {#op-get-api-v1-orgs-org-slug-statements}

`GET /api/v1/orgs/{org_slug}/statements`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org generate statement {#op-post-api-v1-orgs-org-slug-statements-generate}

`POST /api/v1/orgs/{org_slug}/statements/generate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `period_start` | string (date-time) | yes |
| `period_end` | string (date-time) | yes |
| `force` | boolean | no |
| `notes` | string or null | no |
| `options` | StatementGenerateOptions or null | no |
| `options.include` | StatementIncludeOptions or null | no |
| `options.presentation` | StatementPresentationOptions or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org statements options catalog {#op-get-api-v1-orgs-org-slug-statements-options-catalog}

`GET /api/v1/orgs/{org_slug}/statements/options-catalog`

#### 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. |

### Org get statement {#op-get-api-v1-orgs-org-slug-statements-statement-id}

`GET /api/v1/orgs/{org_slug}/statements/{statement_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `statement_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org delete statement {#op-delete-api-v1-orgs-org-slug-statements-statement-id}

`DELETE /api/v1/orgs/{org_slug}/statements/{statement_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `statement_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org statement CSV {#op-get-api-v1-orgs-org-slug-statements-statement-id-csv}

`GET /api/v1/orgs/{org_slug}/statements/{statement_id}/csv`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `statement_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org statement pdf {#op-get-api-v1-orgs-org-slug-statements-statement-id-pdf}

`GET /api/v1/orgs/{org_slug}/statements/{statement_id}/pdf`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `statement_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Billing & Payouts: Stats

> The 1 Organization API operations for stats.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/stats/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/stats/revenue`](#op-get-api-v1-orgs-org-slug-stats-revenue) | The same figures the admin console shows for this organization |

### The same figures the admin console shows for this organization {#op-get-api-v1-orgs-org-slug-stats-revenue}

`GET /api/v1/orgs/{org_slug}/stats/revenue`

The same figures the admin console shows for this organization.

``total_revenue`` is what the gateways took net of refunds, from the
ledger, not the sum of paid invoices: wallet credit and invoices marked
paid by staff settle an invoice without anyone being charged.
``outstanding_amount`` adds up open invoice totals across currencies and
stays for older clients; ``outstanding_by_currency`` is the balance still
owed, one row per currency.

#### 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. |

# Organization API: Billing & Payouts: Webhooks

> The 4 Organization API operations for webhooks.

Source: https://www.coritan.com/docs/api/reference/organizations/billing-payouts/webhooks/

Part of [Billing & Payouts](/docs/api/reference/organizations/billing-payouts/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/webhooks`](#op-get-api-v1-orgs-org-slug-webhooks) | List webhooks |
| POST | [`/api/v1/orgs/{org_slug}/webhooks`](#op-post-api-v1-orgs-org-slug-webhooks) | Create webhook |
| PATCH | [`/api/v1/orgs/{org_slug}/webhooks/{webhook_id}`](#op-patch-api-v1-orgs-org-slug-webhooks-webhook-id) | Update webhook |
| DELETE | [`/api/v1/orgs/{org_slug}/webhooks/{webhook_id}`](#op-delete-api-v1-orgs-org-slug-webhooks-webhook-id) | Delete webhook |

### List webhooks {#op-get-api-v1-orgs-org-slug-webhooks}

`GET /api/v1/orgs/{org_slug}/webhooks`

#### 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. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_id` | integer |
| `[].url` | string |
| `[].events` | array of any |
| `[].is_active` | boolean |
| `[].failure_count` | integer |
| `[].last_triggered_at` | string (date-time) or null |
| `[].created_at` | string (date-time) or null |

### Create webhook {#op-post-api-v1-orgs-org-slug-webhooks}

`POST /api/v1/orgs/{org_slug}/webhooks`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `events` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `url` | string |
| `events` | array of any |
| `is_active` | boolean |
| `failure_count` | integer |
| `last_triggered_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |

### Update webhook {#op-patch-api-v1-orgs-org-slug-webhooks-webhook-id}

`PATCH /api/v1/orgs/{org_slug}/webhooks/{webhook_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `webhook_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string or null | no |
| `events` | array of string or null | no |
| `is_active` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `url` | string |
| `events` | array of any |
| `is_active` | boolean |
| `failure_count` | integer |
| `last_triggered_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |

### Delete webhook {#op-delete-api-v1-orgs-org-slug-webhooks-webhook-id}

`DELETE /api/v1/orgs/{org_slug}/webhooks/{webhook_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `webhook_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Staff Support

> Reseller support inbox, where staff reply to customer chat under /{slug}/chat/staff.

Source: https://www.coritan.com/docs/api/reference/organizations/staff-support/

Reseller support inbox, where staff reply to customer chat under `/{slug}/chat/staff`.

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Chat](/docs/api/reference/organizations/staff-support/chat/) | 46 |

# Organization API: Staff Support: Chat

> The 46 Organization API operations for chat.

Source: https://www.coritan.com/docs/api/reference/organizations/staff-support/chat/

Part of [Staff Support](/docs/api/reference/organizations/staff-support/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/chat/conversations`](#op-get-api-v1-orgs-org-slug-chat-conversations) | List customer conversations |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations`](#op-post-api-v1-orgs-org-slug-chat-conversations) | Create customer conversation |
| GET | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}`](#op-get-api-v1-orgs-org-slug-chat-conversations-conversation-id) | Get customer conversation |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-attachments) | Upload customer attachment |
| GET | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments/{attachment_id}`](#op-get-api-v1-orgs-org-slug-chat-conversations-conversation-id-attachments-attachme) | Download customer attachment |
| GET | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments/{attachment_id}/thumbnail`](#op-get-api-v1-orgs-org-slug-chat-conversations-conversation-id-attachments-attachme) | Lets a thread show an image inline instead of a download link |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/close`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-close) | Close customer conversation |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/csat`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-csat) | Rate customer conversation |
| GET | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/messages`](#op-get-api-v1-orgs-org-slug-chat-conversations-conversation-id-messages) | Get customer messages |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/messages`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-messages) | Send customer message |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/read`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-read) | Mark customer conversation read |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/reopen`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-reopen) | Reopen customer conversation |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/approve`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-requests-request-id) | Approve ticket request |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/decline`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-requests-request-id) | Decline ticket request |
| POST | [`/api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/revoke`](#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-requests-request-id) | Take back access given from this ticket, before it closes |
| GET | [`/api/v1/orgs/{org_slug}/chat/meta`](#op-get-api-v1-orgs-org-slug-chat-meta) | Get customer support meta |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/canned-responses`](#op-get-api-v1-orgs-org-slug-chat-staff-canned-responses) | List org canned responses |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/canned-responses`](#op-post-api-v1-orgs-org-slug-chat-staff-canned-responses) | Create org canned response |
| PUT | [`/api/v1/orgs/{org_slug}/chat/staff/canned-responses/{response_id}`](#op-put-api-v1-orgs-org-slug-chat-staff-canned-responses-response-id) | Update org canned response |
| DELETE | [`/api/v1/orgs/{org_slug}/chat/staff/canned-responses/{response_id}`](#op-delete-api-v1-orgs-org-slug-chat-staff-canned-responses-response-id) | Delete org canned response |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/conversations`](#op-get-api-v1-orgs-org-slug-chat-staff-conversations) | Tickets, newest activity first |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations) | Open a ticket on a customer's behalf |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/bulk`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-bulk) | Bulk org staff conversations |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}`](#op-get-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id) | Get org staff conversation |
| PATCH | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}`](#op-patch-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id) | Priority, department, status, and (Tier 3 and above) which customer the ticket belongs to |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/assign`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-assign) | Claim a ticket, or with agentid (Tier 3 and above) give it to a teammate |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/attachments/{attachment_id}`](#op-get-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-attachments-at) | The file a customer attached, for the staff member reading the ticket |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/close`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-close) | Close org staff conversation |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/duplicate`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-duplicate) | Close this ticket as a duplicate of another of the same customer's |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/escalate`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-escalate) | Escalate org conversation |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/escalate-tier`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-escalate-tier) | Pass a ticket up to Tier 2 or Tier 3, back into the queue there |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/internal-note`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-internal-note) | A note for the desk, on any ticket the caller may read |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/messages`](#op-get-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-messages) | Get org staff messages |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/messages`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-messages) | A reply to a closed ticket reopens it first |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/release`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-release) | Give a claimed ticket back to the queue |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/reopen`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-reopen) | Reopen org staff conversation |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests`](#op-get-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-requests) | Every request on the ticket, newest first, as its card shows it |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-requests) | Create ticket request |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests/{request_id}/cancel`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-requests-requ) | Withdraw a request the customer has not answered yet |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests/{request_id}/release`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-requests-requ) | Give back server access before the ticket closes: done with it, or handing the work on |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/transfer`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-transfer) | Transfer org conversation |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/viewing`](#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-viewing) | Org ticket viewing |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/departments`](#op-get-api-v1-orgs-org-slug-chat-staff-departments) | Departments with their names and SLAs, for anything staff-side that shows a ticket |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/queue`](#op-get-api-v1-orgs-org-slug-chat-staff-queue) | Unclaimed tickets waiting for an answer, at the caller's tier or below |
| POST | [`/api/v1/orgs/{org_slug}/chat/staff/queue/take-next`](#op-post-api-v1-orgs-org-slug-chat-staff-queue-take-next) | Claim the ticket at the front of the queue and hand it back |
| GET | [`/api/v1/orgs/{org_slug}/chat/staff/stats`](#op-get-api-v1-orgs-org-slug-chat-staff-stats) | The figures above the inbox, under the audience the request carries |

### List customer conversations {#op-get-api-v1-orgs-org-slug-chat-conversations}

`GET /api/v1/orgs/{org_slug}/chat/conversations`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string | no |  |
| `priority` | query | string | no |  |
| `q` | query | string | no |  |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].conversation_number` | integer |
| `[].scope` | string |
| `[].subject` | string |
| `[].status` | string |
| `[].priority` | string |
| `[].department` | string or null |
| `[].assigned_agent_id` | integer or null |
| `[].assigned_agent_name` | string or null |
| `[].user_id` | integer or null |
| `[].user_email` | string or null |
| `[].user_name` | string or null |
| `[].customer_id` | integer or null |
| `[].channel` | string |
| `[].email_from` | string or null |
| `[].last_message_at` | string (date-time) or null |
| `[].last_message_preview` | string or null |
| `[].tags` | array of string or null |
| `[].unread_count` | integer |
| `[].waiting_seconds` | integer or null |
| `[].sla_first_response_due_at` | string (date-time) or null |
| `[].sla_resolution_due_at` | string (date-time) or null |
| `[].sla_breached_first_response` | boolean |
| `[].sla_breached_resolution` | boolean |
| `[].first_response_at` | string (date-time) or null |
| `[].csat_score` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |
| `[].is_free` | boolean or null |
| `[].viewers` | array of string |
| `[].escalated_tier` | integer or null |

### Create customer conversation {#op-post-api-v1-orgs-org-slug-chat-conversations}

`POST /api/v1/orgs/{org_slug}/chat/conversations`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `subject` | string | yes |
| `department` | string or null | no |
| `priority` | string | no |
| `body` | string | yes |
| `service_id` | integer or null | no |
| `tags` | array of string or null | no |
| `client_request_id` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Get customer conversation {#op-get-api-v1-orgs-org-slug-chat-conversations-conversation-id}

`GET /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Upload customer attachment {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-attachments}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Download customer attachment {#op-get-api-v1-orgs-org-slug-chat-conversations-conversation-id-attachments-attachme}

`GET /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments/{attachment_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `attachment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Lets a thread show an image inline instead of a download link {#op-get-api-v1-orgs-org-slug-chat-conversations-conversation-id-attachments-attachme}

`GET /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/attachments/{attachment_id}/thumbnail`

Lets a thread show an image inline instead of a download link.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `attachment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Close customer conversation {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-close}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/close`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Rate customer conversation {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-csat}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/csat`

Rating is only meaningful once the ticket is done, so it is refused
while the conversation is still open.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `score` | integer | yes |
| `comment` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get customer messages {#op-get-api-v1-orgs-org-slug-chat-conversations-conversation-id-messages}

`GET /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/messages`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `before_id` | query | integer | no |  |
| `after_id` | query | integer | no |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].conversation_id` | integer |
| `[].sender_type` | string |
| `[].sender_id` | integer or null |
| `[].sender_name` | string or null |
| `[].body` | string or null |
| `[].content_type` | string |
| `[].is_internal` | boolean |
| `[].attachments` | array of AttachmentResponse |
| `[].attachments[].id` | integer |
| `[].attachments[].file_name` | string |
| `[].attachments[].file_size` | integer |
| `[].attachments[].mime_type` | string |
| `[].attachments[].created_at` | string (date-time) |
| `[].read_at` | string (date-time) or null |
| `[].created_at` | string (date-time) |
| `[].client_request_id` | string or null |
| `[].request` | object or null |

### Send customer message {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-messages}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/messages`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body` | string | yes |
| `client_request_id` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_id` | integer |
| `sender_type` | string |
| `sender_id` | integer or null |
| `sender_name` | string or null |
| `body` | string or null |
| `content_type` | string |
| `is_internal` | boolean |
| `attachments` | array of AttachmentResponse |
| `attachments[].id` | integer |
| `attachments[].file_name` | string |
| `attachments[].file_size` | integer |
| `attachments[].mime_type` | string |
| `attachments[].created_at` | string (date-time) |
| `read_at` | string (date-time) or null |
| `created_at` | string (date-time) |
| `client_request_id` | string or null |
| `request` | object or null |

### Mark customer conversation read {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-read}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/read`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `up_to_message_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Reopen customer conversation {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-reopen}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/reopen`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Approve ticket request {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-requests-request-id}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/approve`

Share the logs asked for, or give the engineer who asked subuser access
until the ticket closes.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Decline ticket request {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-requests-request-id}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/decline`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Take back access given from this ticket, before it closes {#op-post-api-v1-orgs-org-slug-chat-conversations-conversation-id-requests-request-id}

`POST /api/v1/orgs/{org_slug}/chat/conversations/{conversation_id}/requests/{request_id}/revoke`

Take back access given from this ticket, before it closes.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get customer support meta {#op-get-api-v1-orgs-org-slug-chat-meta}

`GET /api/v1/orgs/{org_slug}/chat/meta`

#### 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. |

### List org canned responses {#op-get-api-v1-orgs-org-slug-chat-staff-canned-responses}

`GET /api/v1/orgs/{org_slug}/chat/staff/canned-responses`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `department` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].org_id` | integer or null |
| `[].title` | string |
| `[].shortcut` | string |
| `[].body` | string |
| `[].department` | string or null |
| `[].is_shared` | boolean |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create org canned response {#op-post-api-v1-orgs-org-slug-chat-staff-canned-responses}

`POST /api/v1/orgs/{org_slug}/chat/staff/canned-responses`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string | yes |
| `shortcut` | string | yes |
| `body` | string | yes |
| `department` | string or null | no |
| `is_shared` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer or null |
| `title` | string |
| `shortcut` | string |
| `body` | string |
| `department` | string or null |
| `is_shared` | boolean |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update org canned response {#op-put-api-v1-orgs-org-slug-chat-staff-canned-responses-response-id}

`PUT /api/v1/orgs/{org_slug}/chat/staff/canned-responses/{response_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `response_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `shortcut` | string or null | no |
| `body` | string or null | no |
| `department` | string or null | no |
| `is_shared` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer or null |
| `title` | string |
| `shortcut` | string |
| `body` | string |
| `department` | string or null |
| `is_shared` | boolean |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete org canned response {#op-delete-api-v1-orgs-org-slug-chat-staff-canned-responses-response-id}

`DELETE /api/v1/orgs/{org_slug}/chat/staff/canned-responses/{response_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `response_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Tickets, newest activity first {#op-get-api-v1-orgs-org-slug-chat-staff-conversations}

`GET /api/v1/orgs/{org_slug}/chat/staff/conversations`

Tickets, newest activity first. Tier 1 sees only the queue and its
own; ``assigned_to`` (one engineer's claims) is for Tier 3 and above,
``escalated`` narrows to tickets escalated to a higher tier.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string | no |  |
| `priority` | query | string | no |  |
| `q` | query | string | no |  |
| `assigned_to_me` | query | boolean | no | Default: `False`. |
| `assigned_to` | query | integer or null | no |  |
| `escalated` | query | boolean | no | Default: `False`. |
| `audience` | query | string | no |  |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].conversation_number` | integer |
| `[].scope` | string |
| `[].subject` | string |
| `[].status` | string |
| `[].priority` | string |
| `[].department` | string or null |
| `[].assigned_agent_id` | integer or null |
| `[].assigned_agent_name` | string or null |
| `[].user_id` | integer or null |
| `[].user_email` | string or null |
| `[].user_name` | string or null |
| `[].customer_id` | integer or null |
| `[].channel` | string |
| `[].email_from` | string or null |
| `[].last_message_at` | string (date-time) or null |
| `[].last_message_preview` | string or null |
| `[].tags` | array of string or null |
| `[].unread_count` | integer |
| `[].waiting_seconds` | integer or null |
| `[].sla_first_response_due_at` | string (date-time) or null |
| `[].sla_resolution_due_at` | string (date-time) or null |
| `[].sla_breached_first_response` | boolean |
| `[].sla_breached_resolution` | boolean |
| `[].first_response_at` | string (date-time) or null |
| `[].csat_score` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |
| `[].is_free` | boolean or null |
| `[].viewers` | array of string |
| `[].escalated_tier` | integer or null |

### Open a ticket on a customer's behalf {#op-post-api-v1-orgs-org-slug-chat-staff-conversations}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations`

Open a ticket on a customer's behalf. The customer sees a system line
saying staff opened it, then the staff member's message, and is emailed
like any reply; the paid-support gate does not apply because staff chose
to reach out.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `customer_id` | integer | yes |
| `subject` | string | yes |
| `body` | string | yes |
| `priority` | string | no |
| `department` | string or null | no |
| `service_id` | integer or null | no |
| `assign_to_me` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Bulk org staff conversations {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-bulk}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/bulk`

The same change to many tickets at once: take them, drop them, close
them, or set their priority or department. Tickets outside this org are
skipped, not refused, so one bad id cannot spoil a selection.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `ids` | array of integer | yes |
| `action` | string | yes |
| `value` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get org staff conversation {#op-get-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id}

`GET /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Priority, department, status, and (Tier 3 and above) which customer the ticket belongs to {#op-patch-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id}

`PATCH /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}`

Priority, department, status, and (Tier 3 and above) which customer
the ticket belongs to. A status of ``closed`` closes it the way the close
button does, and moving a closed ticket to any other status reopens it
first, so whatever a close or a reopen sets in motion runs either way.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `priority` | string or null | no |
| `department` | string or null | no |
| `status` | string or null | no |
| `tags` | array of string or null | no |
| `subject` | string or null | no |
| `customer_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Claim a ticket, or with agentid (Tier 3 and above) give it to a teammate {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-assign}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/assign`

Claim a ticket, or with ``agent_id`` (Tier 3 and above) give it to a
teammate. Either way the new holder must be able to take it and have
room under their claim limit.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `agent_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### The file a customer attached, for the staff member reading the ticket {#op-get-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-attachments-at}

`GET /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/attachments/{attachment_id}`

The file a customer attached, for the staff member reading the ticket.
The customer route is scoped to the owner; this one to the org.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `attachment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Close org staff conversation {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-close}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/close`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Close this ticket as a duplicate of another of the same customer's {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-duplicate}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/duplicate`

Close this ticket as a duplicate of another of the same customer's.

The customer is told which ticket the conversation continues in; the
other ticket gets an internal note pointing back, so whoever answers it
knows there was a second report. Only tickets of the same customer can be
folded together, because folding two customers' tickets is always a mistake.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `of` | integer | yes | The ticket this one duplicates |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Escalate org conversation {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-escalate}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/escalate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Pass a ticket up to Tier 2 or Tier 3, back into the queue there {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-escalate-tier}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/escalate-tier`

Pass a ticket up to Tier 2 or Tier 3, back into the queue there.

Tiers 1 and 2 may only send a ticket above themselves. Tier 3 and above
may also lower an escalation or clear it (``tier: null``). ``note`` tells
the next engineer what has been tried, as an internal note.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `tier` | integer or null | no |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### A note for the desk, on any ticket the caller may read {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-internal-note}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/internal-note`

A note for the desk, on any ticket the caller may read. Tier 2 can
leave one on a colleague's ticket it may not answer.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_id` | integer |
| `sender_type` | string |
| `sender_id` | integer or null |
| `sender_name` | string or null |
| `body` | string or null |
| `content_type` | string |
| `is_internal` | boolean |
| `attachments` | array of AttachmentResponse |
| `attachments[].id` | integer |
| `attachments[].file_name` | string |
| `attachments[].file_size` | integer |
| `attachments[].mime_type` | string |
| `attachments[].created_at` | string (date-time) |
| `read_at` | string (date-time) or null |
| `created_at` | string (date-time) |
| `client_request_id` | string or null |
| `request` | object or null |

### Get org staff messages {#op-get-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-messages}

`GET /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/messages`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `before_id` | query | integer | no |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].conversation_id` | integer |
| `[].sender_type` | string |
| `[].sender_id` | integer or null |
| `[].sender_name` | string or null |
| `[].body` | string or null |
| `[].content_type` | string |
| `[].is_internal` | boolean |
| `[].attachments` | array of AttachmentResponse |
| `[].attachments[].id` | integer |
| `[].attachments[].file_name` | string |
| `[].attachments[].file_size` | integer |
| `[].attachments[].mime_type` | string |
| `[].attachments[].created_at` | string (date-time) |
| `[].read_at` | string (date-time) or null |
| `[].created_at` | string (date-time) |
| `[].client_request_id` | string or null |
| `[].request` | object or null |

### A reply to a closed ticket reopens it first {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-messages}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/messages`

A reply to a closed ticket reopens it first. The composer says so,
and a staff member writing to a customer means to be heard, not refused.
An unassigned ticket becomes the replier's: whoever answers owns it,
unless somebody already does, and within the replier's claim limit.
With ``close`` the ticket is closed once the reply is in.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body` | string | yes |
| `client_request_id` | string or null | no |
| `close` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_id` | integer |
| `sender_type` | string |
| `sender_id` | integer or null |
| `sender_name` | string or null |
| `body` | string or null |
| `content_type` | string |
| `is_internal` | boolean |
| `attachments` | array of AttachmentResponse |
| `attachments[].id` | integer |
| `attachments[].file_name` | string |
| `attachments[].file_size` | integer |
| `attachments[].mime_type` | string |
| `attachments[].created_at` | string (date-time) |
| `read_at` | string (date-time) or null |
| `created_at` | string (date-time) |
| `client_request_id` | string or null |
| `request` | object or null |

### Give a claimed ticket back to the queue {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-release}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/release`

Give a claimed ticket back to the queue. The holder may release their
own; Tier 3 and above may release anyone's. ``note`` is left for
whoever takes it next, as an internal note.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Reopen org staff conversation {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-reopen}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/reopen`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Every request on the ticket, newest first, as its card shows it {#op-get-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-requests}

`GET /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests`

Every request on the ticket, newest first, as its card shows it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create ticket request {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-requests}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests`

Ask the ticket's customer for a server's logs (any tier) or for
subuser access to it (Tier 2 and above). The customer answers in their
thread; nothing is shared or granted until they do.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `kind` | string | yes |
| `server_uuid` | string | yes |
| `scope` | string | yes |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Withdraw a request the customer has not answered yet {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-requests-requ}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests/{request_id}/cancel`

Withdraw a request the customer has not answered yet.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Give back server access before the ticket closes: done with it, or handing the work on {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-requests-requ}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/requests/{request_id}/release`

Give back server access before the ticket closes: done with it, or
handing the work on.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Transfer org conversation {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-transfer}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/transfer`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `agent_id` | integer or null | no |
| `department` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `org_id` | integer or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `email_mailbox` | string or null |
| `subject` | string |
| `department` | string or null |
| `priority` | string |
| `status` | string |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `assigned_at` | string (date-time) or null |
| `service_id` | integer or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `closed_at` | string (date-time) or null |
| `reopened_count` | integer |
| `tags` | array of string or null |
| `first_response_at` | string (date-time) or null |
| `first_response_by_id` | integer or null |
| `resolved_at` | string (date-time) or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `csat_score` | integer or null |
| `csat_comment` | string or null |
| `csat_rated_at` | string (date-time) or null |
| `unread_count` | integer |
| `messages` | array of ChatMessageResponse |
| `messages[].id` | integer |
| `messages[].conversation_id` | integer |
| `messages[].sender_type` | string |
| `messages[].sender_id` | integer or null |
| `messages[].sender_name` | string or null |
| `messages[].body` | string or null |
| `messages[].content_type` | string |
| `messages[].is_internal` | boolean |
| `messages[].attachments` | array of AttachmentResponse |
| `messages[].read_at` | string (date-time) or null |
| `messages[].created_at` | string (date-time) |
| `messages[].client_request_id` | string or null |
| `messages[].request` | object or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `escalated_tier` | integer or null |

### Org ticket viewing {#op-post-api-v1-orgs-org-slug-chat-staff-conversations-conversation-id-viewing}

`POST /api/v1/orgs/{org_slug}/chat/staff/conversations/{conversation_id}/viewing`

The console's heartbeat on an open ticket: "I am looking at this one",
answered with who else is. One presence row per staff member follows
them from ticket to ticket; a row older than ``VIEWING_TTL`` is a closed
tab and is not reported.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `conversation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `viewers` | array of object |

### Departments with their names and SLAs, for anything staff-side that shows a ticket {#op-get-api-v1-orgs-org-slug-chat-staff-departments}

`GET /api/v1/orgs/{org_slug}/chat/staff/departments`

Departments with their names and SLAs, for anything staff-side that
shows a ticket. Tickets carry only the slug; without this the console
printed ``billing`` where a customer sees "Billing".

#### 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. |

### Unclaimed tickets waiting for an answer, at the caller's tier or below {#op-get-api-v1-orgs-org-slug-chat-staff-queue}

`GET /api/v1/orgs/{org_slug}/chat/staff/queue`

Unclaimed tickets waiting for an answer, at the caller's tier or below.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `department` | query | string | no |  |
| `audience` | query | string | no |  |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].conversation_number` | integer |
| `[].scope` | string |
| `[].subject` | string |
| `[].status` | string |
| `[].priority` | string |
| `[].department` | string or null |
| `[].assigned_agent_id` | integer or null |
| `[].assigned_agent_name` | string or null |
| `[].user_id` | integer or null |
| `[].user_email` | string or null |
| `[].user_name` | string or null |
| `[].customer_id` | integer or null |
| `[].channel` | string |
| `[].email_from` | string or null |
| `[].last_message_at` | string (date-time) or null |
| `[].last_message_preview` | string or null |
| `[].tags` | array of string or null |
| `[].unread_count` | integer |
| `[].waiting_seconds` | integer or null |
| `[].sla_first_response_due_at` | string (date-time) or null |
| `[].sla_resolution_due_at` | string (date-time) or null |
| `[].sla_breached_first_response` | boolean |
| `[].sla_breached_resolution` | boolean |
| `[].first_response_at` | string (date-time) or null |
| `[].csat_score` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |
| `[].is_free` | boolean or null |
| `[].viewers` | array of string |
| `[].escalated_tier` | integer or null |

### Claim the ticket at the front of the queue and hand it back {#op-post-api-v1-orgs-org-slug-chat-staff-queue-take-next}

`POST /api/v1/orgs/{org_slug}/chat/staff/queue/take-next`

Claim the ticket at the front of the queue and hand it back.

One click instead of open the inbox, pick the top row, press Take. The
lock means two people pressing at the same moment get two different
tickets, not the same one. ``null`` when nobody is waiting. Refused with
409 when the caller already holds as many tickets as their tier may.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `department` | query | string | no |
| `audience` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `conversation_number` | integer |
| `scope` | string |
| `subject` | string |
| `status` | string |
| `priority` | string |
| `department` | string or null |
| `assigned_agent_id` | integer or null |
| `assigned_agent_name` | string or null |
| `user_id` | integer or null |
| `user_email` | string or null |
| `user_name` | string or null |
| `customer_id` | integer or null |
| `channel` | string |
| `email_from` | string or null |
| `last_message_at` | string (date-time) or null |
| `last_message_preview` | string or null |
| `tags` | array of string or null |
| `unread_count` | integer |
| `waiting_seconds` | integer or null |
| `sla_first_response_due_at` | string (date-time) or null |
| `sla_resolution_due_at` | string (date-time) or null |
| `sla_breached_first_response` | boolean |
| `sla_breached_resolution` | boolean |
| `first_response_at` | string (date-time) or null |
| `csat_score` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |
| `is_free` | boolean or null |
| `viewers` | array of string |
| `escalated_tier` | integer or null |

### The figures above the inbox, under the audience the request carries {#op-get-api-v1-orgs-org-slug-chat-staff-stats}

`GET /api/v1/orgs/{org_slug}/chat/staff/stats`

The figures above the inbox, under the audience the request carries.
``closed_today`` is the tickets closed since midnight in the brand's own
timezone (``OrgSettings.timezone``; UTC when the brand has not set one),
so "what we finished today" is the day the team is working in. Waiting
counts what the caller's tier may take; ``claim_limit`` is how many the
caller may hold, and Tier 3 and above also get ``claims`` per engineer.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `audience` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `total_waiting` | integer |
| `agents_online` | integer |
| `my_open` | integer |
| `my_awaiting_agent` | integer |
| `total_active` | integer |
| `open` | integer |
| `total_on_hold` | integer |
| `sla_breached` | integer |
| `closed_today` | integer |
| `oldest_waiting_seconds` | integer or null |
| `avg_first_response_seconds` | number or null |
| `avg_resolution_seconds` | number or null |
| `by_department` | By Department |
| `by_priority` | By Priority |
| `by_status` | By Status |
| `claim_limit` | integer or null |
| `escalated_waiting` | integer |
| `claims` | array of object or null |

# Organization API: Analytics

> Live and historical tracking stats for the organization.

Source: https://www.coritan.com/docs/api/reference/organizations/analytics/

Live and historical tracking stats for the organization.

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}/tracking/conversions`](#op-get-api-v1-orgs-org-slug-tracking-conversions) | Org tracking conversions |
| GET | [`/api/v1/orgs/{org_slug}/tracking/live`](#op-get-api-v1-orgs-org-slug-tracking-live) | Org tracking live |
| GET | [`/api/v1/orgs/{org_slug}/tracking/pages`](#op-get-api-v1-orgs-org-slug-tracking-pages) | Org tracking pages |
| GET | [`/api/v1/orgs/{org_slug}/tracking/script`](#op-get-api-v1-orgs-org-slug-tracking-script) | Org tracking script |
| GET | [`/api/v1/orgs/{org_slug}/tracking/stats`](#op-get-api-v1-orgs-org-slug-tracking-stats) | Org tracking stats |
| GET | [`/api/v1/orgs/{org_slug}/tracking/today`](#op-get-api-v1-orgs-org-slug-tracking-today) | Org tracking today |

### Org tracking conversions {#op-get-api-v1-orgs-org-slug-tracking-conversions}

`GET /api/v1/orgs/{org_slug}/tracking/conversions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `start_date` | query | string (date) | yes |
| `end_date` | query | string (date) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org tracking live {#op-get-api-v1-orgs-org-slug-tracking-live}

`GET /api/v1/orgs/{org_slug}/tracking/live`

#### 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. |

### Org tracking pages {#op-get-api-v1-orgs-org-slug-tracking-pages}

`GET /api/v1/orgs/{org_slug}/tracking/pages`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `start_date` | query | string (date) | yes |  |
| `end_date` | query | string (date) | yes |  |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org tracking script {#op-get-api-v1-orgs-org-slug-tracking-script}

`GET /api/v1/orgs/{org_slug}/tracking/script`

#### 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. |

### Org tracking stats {#op-get-api-v1-orgs-org-slug-tracking-stats}

`GET /api/v1/orgs/{org_slug}/tracking/stats`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `start_date` | query | string (date) | yes |  |
| `end_date` | query | string (date) | yes |  |
| `granularity` | query | string | no | Default: `daily`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org tracking today {#op-get-api-v1-orgs-org-slug-tracking-today}

`GET /api/v1/orgs/{org_slug}/tracking/today`

#### 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. |

# Organization API: Customer Authentication

> End-customer login/refresh/me under /{slug}/auth.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-authentication/

End-customer login/refresh/me under `/{slug}/auth`. Returns OrgCustomerBearer tokens.

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Auth](/docs/api/reference/organizations/customer-authentication/auth/) | 25 |
| [Staff](/docs/api/reference/organizations/customer-authentication/staff/) | 19 |

# Organization API: Customer Authentication: Auth

> The 25 Organization API operations for auth.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-authentication/auth/

Part of [Customer Authentication](/docs/api/reference/organizations/customer-authentication/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/auth/forgot-password`](#op-post-api-v1-orgs-org-slug-auth-forgot-password) | Issue a password-reset token stored on the customer metadata |
| POST | [`/api/v1/orgs/{org_slug}/auth/login`](#op-post-api-v1-orgs-org-slug-auth-login) | Password sign-in with an email address or a username |
| POST | [`/api/v1/orgs/{org_slug}/auth/logout`](#op-post-api-v1-orgs-org-slug-auth-logout) | Revoke the current access token (and its refresh twin if present) |
| GET | [`/api/v1/orgs/{org_slug}/auth/me`](#op-get-api-v1-orgs-org-slug-auth-me) | Customer profile |
| PATCH | [`/api/v1/orgs/{org_slug}/auth/me`](#op-patch-api-v1-orgs-org-slug-auth-me) | Update customer profile |
| GET | [`/api/v1/orgs/{org_slug}/auth/mfa`](#op-get-api-v1-orgs-org-slug-auth-mfa) | Customer MFA status |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/disable`](#op-post-api-v1-orgs-org-slug-auth-mfa-disable) | Turn the factor off with a current code, and with the password when the account has one |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/enable`](#op-post-api-v1-orgs-org-slug-auth-mfa-enable) | Customer MFA enable |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/recovery-codes`](#op-post-api-v1-orgs-org-slug-auth-mfa-recovery-codes) | Customer MFA regenerate recovery codes |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/setup`](#op-post-api-v1-orgs-org-slug-auth-mfa-setup) | Customer MFA setup |
| POST | [`/api/v1/orgs/{org_slug}/auth/mfa/verify`](#op-post-api-v1-orgs-org-slug-auth-mfa-verify) | Customer MFA verify |
| GET | [`/api/v1/orgs/{org_slug}/auth/oauth/connections`](#op-get-api-v1-orgs-org-slug-auth-oauth-connections) | List OAuth connections |
| DELETE | [`/api/v1/orgs/{org_slug}/auth/oauth/connections/{provider}`](#op-delete-api-v1-orgs-org-slug-auth-oauth-connections-provider) | Disconnect OAuth provider |
| GET | [`/api/v1/orgs/{org_slug}/auth/oauth/providers`](#op-get-api-v1-orgs-org-slug-auth-oauth-providers) | Public: which social providers are configured for storefront login |
| POST | [`/api/v1/orgs/{org_slug}/auth/oauth/set-password`](#op-post-api-v1-orgs-org-slug-auth-oauth-set-password) | OAuth set password |
| GET | [`/api/v1/orgs/{org_slug}/auth/oauth/{provider}/authorize`](#op-get-api-v1-orgs-org-slug-auth-oauth-provider-authorize) | OAuth authorize |
| GET | [`/api/v1/orgs/{org_slug}/auth/oauth/{provider}/callback`](#op-get-api-v1-orgs-org-slug-auth-oauth-provider-callback) | OAuth callback |
| POST | [`/api/v1/orgs/{org_slug}/auth/refresh`](#op-post-api-v1-orgs-org-slug-auth-refresh) | Customer refresh token |
| POST | [`/api/v1/orgs/{org_slug}/auth/register`](#op-post-api-v1-orgs-org-slug-auth-register) | Self-service customer signup for the org storefront |
| POST | [`/api/v1/orgs/{org_slug}/auth/resend-verification`](#op-post-api-v1-orgs-org-slug-auth-resend-verification) | Send another confirmation link to the signed-in customer's own address |
| POST | [`/api/v1/orgs/{org_slug}/auth/reset-password`](#op-post-api-v1-orgs-org-slug-auth-reset-password) | Customer reset password |
| GET | [`/api/v1/orgs/{org_slug}/auth/sessions`](#op-get-api-v1-orgs-org-slug-auth-sessions) | Where this account is currently signed in |
| POST | [`/api/v1/orgs/{org_slug}/auth/sessions/revoke-others`](#op-post-api-v1-orgs-org-slug-auth-sessions-revoke-others) | Sign out everywhere except here |
| GET | [`/api/v1/orgs/{org_slug}/auth/username-available`](#op-get-api-v1-orgs-org-slug-auth-username-available) | Whether a username can be taken at signup, and why not when it cannot |
| POST | [`/api/v1/orgs/{org_slug}/auth/verify-email`](#op-post-api-v1-orgs-org-slug-auth-verify-email) | Confirm an address from an emailed link |

### Issue a password-reset token stored on the customer metadata {#op-post-api-v1-orgs-org-slug-auth-forgot-password}

`POST /api/v1/orgs/{org_slug}/auth/forgot-password`

Issue a password-reset token stored on the customer metadata.
Always returns success to avoid email enumeration.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Password sign-in with an email address or a username {#op-post-api-v1-orgs-org-slug-auth-login}

`POST /api/v1/orgs/{org_slug}/auth/login`

Password sign-in with an email address or a username.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `identifier` | string or null | no |
| `email` | string or null | no |
| `username` | string or null | no |
| `password` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Revoke the current access token (and its refresh twin if present) {#op-post-api-v1-orgs-org-slug-auth-logout}

`POST /api/v1/orgs/{org_slug}/auth/logout`

Revoke the current access token (and its refresh twin if present).

#### 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. |

### Customer profile {#op-get-api-v1-orgs-org-slug-auth-me}

`GET /api/v1/orgs/{org_slug}/auth/me`

#### 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. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `chat_handle` | string or null |
| `chat_handle_locked_for` | integer |
| `company` | string or null |
| `phone` | string or null |
| `status` | string |
| `credit_balance` | string |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `custom_fields` | object or null |
| `last_login_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `has_password` | boolean |
| `staff_member` | boolean |
| `email_verified` | boolean |
| `avatar_url` | string or null |

### Update customer profile {#op-patch-api-v1-orgs-org-slug-auth-me}

`PATCH /api/v1/orgs/{org_slug}/auth/me`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `chat_handle` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `password` | string or null | no |
| `current_password` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `org_id` | integer |
| `email` | string |
| `first_name` | string or null |
| `last_name` | string or null |
| `chat_handle` | string or null |
| `chat_handle_locked_for` | integer |
| `company` | string or null |
| `phone` | string or null |
| `status` | string |
| `credit_balance` | string |
| `currency` | string |
| `country_code` | string or null |
| `currency_source` | string |
| `custom_fields` | object or null |
| `last_login_at` | string (date-time) or null |
| `created_at` | string (date-time) or null |
| `updated_at` | string (date-time) or null |
| `has_password` | boolean |
| `staff_member` | boolean |
| `email_verified` | boolean |
| `avatar_url` | string or null |

### Customer MFA status {#op-get-api-v1-orgs-org-slug-auth-mfa}

`GET /api/v1/orgs/{org_slug}/auth/mfa`

#### 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. |

### Turn the factor off with a current code, and with the password when the account has one {#op-post-api-v1-orgs-org-slug-auth-mfa-disable}

`POST /api/v1/orgs/{org_slug}/auth/mfa/disable`

Turn the factor off with a current code, and with the password when the
account has one. Refused while the brand requires a factor of everyone.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Customer MFA enable {#op-post-api-v1-orgs-org-slug-auth-mfa-enable}

`POST /api/v1/orgs/{org_slug}/auth/mfa/enable`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Customer MFA regenerate recovery codes {#op-post-api-v1-orgs-org-slug-auth-mfa-recovery-codes}

`POST /api/v1/orgs/{org_slug}/auth/mfa/recovery-codes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Customer MFA setup {#op-post-api-v1-orgs-org-slug-auth-mfa-setup}

`POST /api/v1/orgs/{org_slug}/auth/mfa/setup`

#### 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. |

### Customer MFA verify {#op-post-api-v1-orgs-org-slug-auth-mfa-verify}

`POST /api/v1/orgs/{org_slug}/auth/mfa/verify`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List OAuth connections {#op-get-api-v1-orgs-org-slug-auth-oauth-connections}

`GET /api/v1/orgs/{org_slug}/auth/oauth/connections`

#### 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. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].provider` | string |
| `[].provider_username` | string or null |
| `[].provider_email` | string or null |
| `[].provider_avatar` | string or null |
| `[].created_at` | string (date-time) or null |

### Disconnect OAuth provider {#op-delete-api-v1-orgs-org-slug-auth-oauth-connections-provider}

`DELETE /api/v1/orgs/{org_slug}/auth/oauth/connections/{provider}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `provider` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Public: which social providers are configured for storefront login {#op-get-api-v1-orgs-org-slug-auth-oauth-providers}

`GET /api/v1/orgs/{org_slug}/auth/oauth/providers`

Public: which social providers are configured for storefront login.

#### 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. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `providers` | array of string |

### OAuth set password {#op-post-api-v1-orgs-org-slug-auth-oauth-set-password}

`POST /api/v1/orgs/{org_slug}/auth/oauth/set-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### OAuth authorize {#op-get-api-v1-orgs-org-slug-auth-oauth-provider-authorize}

`GET /api/v1/orgs/{org_slug}/auth/oauth/{provider}/authorize`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `provider` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### OAuth callback {#op-get-api-v1-orgs-org-slug-auth-oauth-provider-callback}

`GET /api/v1/orgs/{org_slug}/auth/oauth/{provider}/callback`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `provider` | path | string | yes |
| `code` | query | string or null | no |
| `state` | query | string or null | no |
| `error` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Customer refresh token {#op-post-api-v1-orgs-org-slug-auth-refresh}

`POST /api/v1/orgs/{org_slug}/auth/refresh`

#### 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. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `access_token` | string |
| `refresh_token` | string |
| `token_type` | string |
| `expires_in` | integer |
| `scopes` | array of string or null |

### Self-service customer signup for the org storefront {#op-post-api-v1-orgs-org-slug-auth-register}

`POST /api/v1/orgs/{org_slug}/auth/register`

Self-service customer signup for the org storefront.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string | yes |
| `password` | string | yes |
| `username` | string or null | no |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `turnstile_token` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send another confirmation link to the signed-in customer's own address {#op-post-api-v1-orgs-org-slug-auth-resend-verification}

`POST /api/v1/orgs/{org_slug}/auth/resend-verification`

Send another confirmation link to the signed-in customer's own address.

Authenticated rather than taking an email in the body: an anonymous version
would let anyone post mail to any address on this org's behalf, and there is
nothing to gain from it when the customer can already sign in.

#### 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. |

### Customer reset password {#op-post-api-v1-orgs-org-slug-auth-reset-password}

`POST /api/v1/orgs/{org_slug}/auth/reset-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `token` | string | yes |
| `password` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Where this account is currently signed in {#op-get-api-v1-orgs-org-slug-auth-sessions}

`GET /api/v1/orgs/{org_slug}/auth/sessions`

Where this account is currently signed in.

The token row already records the address and user agent it was issued to,
so a customer can see a session they do not recognise without us keeping a
second log of it. Tokens are never returned, only the hash we match the
caller's own session on. ``country_code`` is where the address places
(see ``_session_countries``), or null when nothing can place it, so the
page can say "Germany · 203.0.113.9" rather than an address alone.

Support sessions are labelled rather than hidden. An admin looking at an
account shows up here as a sign-in from an address the customer will not
recognise, and the honest answer to that is to say what it is.

#### 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. |

### Sign out everywhere except here {#op-post-api-v1-orgs-org-slug-auth-sessions-revoke-others}

`POST /api/v1/orgs/{org_slug}/auth/sessions/revoke-others`

Sign out everywhere except here.

The one action worth having after a shared or stolen laptop, and it must
not log the customer out of the browser asking for it, so the presented
token is the one row left alone.

#### 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. |

### Whether a username can be taken at signup, and why not when it cannot {#op-get-api-v1-orgs-org-slug-auth-username-available}

`GET /api/v1/orgs/{org_slug}/auth/username-available`

Whether a username can be taken at signup, and why not when it cannot.

Public, because the signup form asks while somebody is still typing and has
no session yet. It gives away nothing the community pages do not: a handle
is the name everyone already sees above every message its owner posts.
Answers rather than raising, so a 422 per keystroke is not the shape of it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `username` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Confirm an address from an emailed link {#op-post-api-v1-orgs-org-slug-auth-verify-email}

`POST /api/v1/orgs/{org_slug}/auth/verify-email`

Confirm an address from an emailed link.

Public, because the customer may follow the link in a browser that is not
signed in. The token is the credential, and it only ever sets a flag
nothing reads for access.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `customer_id` | integer | yes |
| `token` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Authentication: Staff

> The 19 Organization API operations for staff.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-authentication/staff/

Part of [Customer Authentication](/docs/api/reference/organizations/customer-authentication/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/change-password`](#op-post-api-v1-orgs-org-slug-staff-auth-change-password) | Change your own password |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/customer-session`](#op-post-api-v1-orgs-org-slug-staff-auth-customer-session) | A fresh storefront session for the member's own customer account |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/forgot-password`](#op-post-api-v1-orgs-org-slug-staff-auth-forgot-password) | Staff forgot password |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/login`](#op-post-api-v1-orgs-org-slug-staff-auth-login) | Staff login |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/logout`](#op-post-api-v1-orgs-org-slug-staff-auth-logout) | Staff logout |
| GET | [`/api/v1/orgs/{org_slug}/staff/auth/me`](#op-get-api-v1-orgs-org-slug-staff-auth-me) | Staff me |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/auth/me`](#op-patch-api-v1-orgs-org-slug-staff-auth-me) | Staff patch me |
| GET | [`/api/v1/orgs/{org_slug}/staff/auth/mfa`](#op-get-api-v1-orgs-org-slug-staff-auth-mfa) | Staff MFA status |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/mfa/disable`](#op-post-api-v1-orgs-org-slug-staff-auth-mfa-disable) | Turn the factor off: password and a current code, both |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/mfa/enable`](#op-post-api-v1-orgs-org-slug-staff-auth-mfa-enable) | Confirm the code from the freshly scanned secret |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/mfa/recovery-codes`](#op-post-api-v1-orgs-org-slug-staff-auth-mfa-recovery-codes) | A new set of recovery codes against a current code; the old set is void |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/mfa/setup`](#op-post-api-v1-orgs-org-slug-staff-auth-mfa-setup) | Start (or restart) enrolment: a fresh secret, the otpauth URI and the QR code for it |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/mfa/verify`](#op-post-api-v1-orgs-org-slug-staff-auth-mfa-verify) | The second step of signing in |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/reauth`](#op-post-api-v1-orgs-org-slug-staff-auth-reauth) | Prove it is still you |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/refresh`](#op-post-api-v1-orgs-org-slug-staff-auth-refresh) | Staff refresh |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/reset-password`](#op-post-api-v1-orgs-org-slug-staff-auth-reset-password) | Staff reset password |
| GET | [`/api/v1/orgs/{org_slug}/staff/auth/sessions`](#op-get-api-v1-orgs-org-slug-staff-auth-sessions) | Staff my sessions |
| POST | [`/api/v1/orgs/{org_slug}/staff/auth/sessions/revoke-others`](#op-post-api-v1-orgs-org-slug-staff-auth-sessions-revoke-others) | Staff end other sessions |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/auth/sessions/{token_id}`](#op-delete-api-v1-orgs-org-slug-staff-auth-sessions-token-id) | Staff end my session |

### Change your own password {#op-post-api-v1-orgs-org-slug-staff-auth-change-password}

`POST /api/v1/orgs/{org_slug}/staff/auth/change-password`

Change your own password. Every other session you have is ended; the
one making this request stays signed in.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `current_password` | string | yes |
| `new_password` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A fresh storefront session for the member's own customer account {#op-post-api-v1-orgs-org-slug-staff-auth-customer-session}

`POST /api/v1/orgs/{org_slug}/staff/auth/customer-session`

A fresh storefront session for the member's own customer account. The
console restores it after a support session ends, or mints one when the
member opens the storefront and has none.

#### 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. |

### Staff forgot password {#op-post-api-v1-orgs-org-slug-staff-auth-forgot-password}

`POST /api/v1/orgs/{org_slug}/staff/auth/forgot-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string | yes |
| `turnstile_token` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff login {#op-post-api-v1-orgs-org-slug-staff-auth-login}

`POST /api/v1/orgs/{org_slug}/staff/auth/login`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string | yes |
| `password` | string | yes |
| `turnstile_token` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff logout {#op-post-api-v1-orgs-org-slug-staff-auth-logout}

`POST /api/v1/orgs/{org_slug}/staff/auth/logout`

End this console session and every storefront session it minted for
the member, so signing out of the console signs them out of the site.

#### 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. |

### Staff me {#op-get-api-v1-orgs-org-slug-staff-auth-me}

`GET /api/v1/orgs/{org_slug}/staff/auth/me`

#### 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. |

### Staff patch me {#op-patch-api-v1-orgs-org-slug-staff-auth-me}

`PATCH /api/v1/orgs/{org_slug}/staff/auth/me`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff MFA status {#op-get-api-v1-orgs-org-slug-staff-auth-mfa}

`GET /api/v1/orgs/{org_slug}/staff/auth/mfa`

#### 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. |

### Turn the factor off: password and a current code, both {#op-post-api-v1-orgs-org-slug-staff-auth-mfa-disable}

`POST /api/v1/orgs/{org_slug}/staff/auth/mfa/disable`

Turn the factor off: password and a current code, both. Refused when
the brand requires a second factor of everyone; in that case an admin
resets it from the team page instead, and the member enrols again.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string | yes |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Confirm the code from the freshly scanned secret {#op-post-api-v1-orgs-org-slug-staff-auth-mfa-enable}

`POST /api/v1/orgs/{org_slug}/staff/auth/mfa/enable`

Confirm the code from the freshly scanned secret. Turns the factor on,
hands out the recovery codes once and, when the caller was a pending
enrolment session, issues the full session too.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A new set of recovery codes against a current code; the old set is void {#op-post-api-v1-orgs-org-slug-staff-auth-mfa-recovery-codes}

`POST /api/v1/orgs/{org_slug}/staff/auth/mfa/recovery-codes`

A new set of recovery codes against a current code; the old set is void.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Start (or restart) enrolment: a fresh secret, the otpauth URI and the QR code for it {#op-post-api-v1-orgs-org-slug-staff-auth-mfa-setup}

`POST /api/v1/orgs/{org_slug}/staff/auth/mfa/setup`

Start (or restart) enrolment: a fresh secret, the otpauth URI and the
QR code for it. Nothing is enforced until ``enable`` confirms a code.
Refused while a factor is already on; disable that one first.

#### 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. |

### The second step of signing in {#op-post-api-v1-orgs-org-slug-staff-auth-mfa-verify}

`POST /api/v1/orgs/{org_slug}/staff/auth/mfa/verify`

The second step of signing in. Bearer is the pending token from
``login``; a right code (or a recovery code) retires it and issues the
full session. A session that is already full gets its step-up stamp
refreshed instead, which is what ``reauth`` with a code does too.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Prove it is still you {#op-post-api-v1-orgs-org-slug-staff-auth-reauth}

`POST /api/v1/orgs/{org_slug}/staff/auth/reauth`

Prove it is still you. A password, or a code when two-factor is on
(the code is preferred and required once the factor exists, so a stolen
password alone never reaches the step-up routes).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |
| `code` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff refresh {#op-post-api-v1-orgs-org-slug-staff-auth-refresh}

`POST /api/v1/orgs/{org_slug}/staff/auth/refresh`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `refresh_token` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff reset password {#op-post-api-v1-orgs-org-slug-staff-auth-reset-password}

`POST /api/v1/orgs/{org_slug}/staff/auth/reset-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `token` | string | yes |
| `password` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff my sessions {#op-get-api-v1-orgs-org-slug-staff-auth-sessions}

`GET /api/v1/orgs/{org_slug}/staff/auth/sessions`

#### 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. |

### Staff end other sessions {#op-post-api-v1-orgs-org-slug-staff-auth-sessions-revoke-others}

`POST /api/v1/orgs/{org_slug}/staff/auth/sessions/revoke-others`

#### 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. |

### Staff end my session {#op-delete-api-v1-orgs-org-slug-staff-auth-sessions-token-id}

`DELETE /api/v1/orgs/{org_slug}/staff/auth/sessions/{token_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `token_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal

> Authenticated end-customer self-service (requires OrgCustomerBearer).

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/

Authenticated end-customer self-service (requires OrgCustomerBearer).

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Account](/docs/api/reference/organizations/customer-portal/account/) | 1 |
| [Community](/docs/api/reference/organizations/customer-portal/community/) | 44 |
| [Countries](/docs/api/reference/organizations/customer-portal/countries/) | 1 |
| [Credit](/docs/api/reference/organizations/customer-portal/credit/) | 6 |
| [Crypto](/docs/api/reference/organizations/customer-portal/crypto/) | 7 |
| [Currencies](/docs/api/reference/organizations/customer-portal/currencies/) | 1 |
| [External servers](/docs/api/reference/organizations/customer-portal/external-servers/) | 5 |
| [Custom domain](/docs/api/reference/organizations/customer-portal/external-servers-custom-domain/) | 5 |
| [Geo currency](/docs/api/reference/organizations/customer-portal/geo-currency/) | 1 |
| [Invoices](/docs/api/reference/organizations/customer-portal/invoices/) | 15 |
| [Ips](/docs/api/reference/organizations/customer-portal/ips/) | 13 |
| [Mail](/docs/api/reference/organizations/customer-portal/mail/) | 8 |
| [Aliases](/docs/api/reference/organizations/customer-portal/mail-aliases/) | 3 |
| [Api keys](/docs/api/reference/organizations/customer-portal/mail-api-keys/) | 3 |
| [Credentials](/docs/api/reference/organizations/customer-portal/mail-credentials/) | 5 |
| [Domains](/docs/api/reference/organizations/customer-portal/mail-domains/) | 6 |
| [Mailboxes](/docs/api/reference/organizations/customer-portal/mail-mailboxes/) | 19 |
| [Suppressions](/docs/api/reference/organizations/customer-portal/mail-suppressions/) | 3 |
| [Webhooks](/docs/api/reference/organizations/customer-portal/mail-webhooks/) | 3 |
| [Notices](/docs/api/reference/organizations/customer-portal/notices/) | 1 |
| [Payment config](/docs/api/reference/organizations/customer-portal/payment-config/) | 1 |
| [Payment methods](/docs/api/reference/organizations/customer-portal/payment-methods/) | 5 |
| [Payment preference](/docs/api/reference/organizations/customer-portal/payment-preference/) | 2 |
| [Platform domains](/docs/api/reference/organizations/customer-portal/platform-domains/) | 4 |
| [Profile](/docs/api/reference/organizations/customer-portal/profile/) | 1 |
| [Refund requests](/docs/api/reference/organizations/customer-portal/refund-requests/) | 2 |
| [Servers](/docs/api/reference/organizations/customer-portal/servers/) | 19 |
| [Allocations](/docs/api/reference/organizations/customer-portal/servers-allocations/) | 8 |
| [Backups](/docs/api/reference/organizations/customer-portal/servers-backups/) | 6 |
| [Custom domain](/docs/api/reference/organizations/customer-portal/servers-custom-domain/) | 5 |
| [Databases](/docs/api/reference/organizations/customer-portal/servers-databases/) | 16 |
| [Files](/docs/api/reference/organizations/customer-portal/servers-files/) | 15 |
| [Import](/docs/api/reference/organizations/customer-portal/servers-import/) | 5 |
| [Schedules](/docs/api/reference/organizations/customer-portal/servers-schedules/) | 11 |
| [Snapshots](/docs/api/reference/organizations/customer-portal/servers-snapshots/) | 9 |
| [Software](/docs/api/reference/organizations/customer-portal/servers-software/) | 35 |
| [Users](/docs/api/reference/organizations/customer-portal/servers-users/) | 5 |
| [Services](/docs/api/reference/organizations/customer-portal/services/) | 12 |
| [Shield](/docs/api/reference/organizations/customer-portal/shield/) | 6 |
| [Smtp relay](/docs/api/reference/organizations/customer-portal/smtp-relay/) | 8 |
| [Aliases](/docs/api/reference/organizations/customer-portal/smtp-relay-aliases/) | 3 |
| [Api keys](/docs/api/reference/organizations/customer-portal/smtp-relay-api-keys/) | 3 |
| [Credentials](/docs/api/reference/organizations/customer-portal/smtp-relay-credentials/) | 5 |
| [Domains](/docs/api/reference/organizations/customer-portal/smtp-relay-domains/) | 6 |
| [Mailboxes](/docs/api/reference/organizations/customer-portal/smtp-relay-mailboxes/) | 19 |
| [Suppressions](/docs/api/reference/organizations/customer-portal/smtp-relay-suppressions/) | 3 |
| [Webhooks](/docs/api/reference/organizations/customer-portal/smtp-relay-webhooks/) | 3 |
| [Snapshots](/docs/api/reference/organizations/customer-portal/snapshots/) | 7 |
| [Transactions](/docs/api/reference/organizations/customer-portal/transactions/) | 1 |
| [Vps](/docs/api/reference/organizations/customer-portal/vps/) | 10 |
| [Backups](/docs/api/reference/organizations/customer-portal/vps-backups/) | 4 |
| [Rescue](/docs/api/reference/organizations/customer-portal/vps-rescue/) | 3 |
| [Snapshots](/docs/api/reference/organizations/customer-portal/vps-snapshots/) | 4 |

# Organization API: Customer Portal: Account

> The 1 Organization API operations for account.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/account/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/portal/account/close`](#op-post-api-v1-orgs-org-slug-portal-account-close) | Close and anonymise the signed-in customer's own account |

### Close and anonymise the signed-in customer's own account {#op-post-api-v1-orgs-org-slug-portal-account-close}

`POST /api/v1/orgs/{org_slug}/portal/account/close`

Close and anonymise the signed-in customer's own account.

Irreversible, so identity is re-confirmed even though the request is
already authenticated: a session left open on a shared machine should not be
enough to erase somebody's account. Password accounts re-type their
password; social accounts complete an OAuth step-up and send the token.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |
| `reauth_token` | string or null | no |
| `reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Community

> The 44 Organization API operations for community.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/community/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/forum/me`](#op-get-api-v1-orgs-org-slug-portal-community-forum-me) | Forum viewer summary |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/moderation/members/{handle}/role`](#op-post-api-v1-orgs-org-slug-portal-community-forum-moderation-members-handle-role) | Set member role |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/moderation/members/{handle}/suspend`](#op-post-api-v1-orgs-org-slug-portal-community-forum-moderation-members-handle-suspe) | Suspend member |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/forum/moderation/reports`](#op-get-api-v1-orgs-org-slug-portal-community-forum-moderation-reports) | Moderation reports |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/moderation/reports/{report_id}/resolve`](#op-post-api-v1-orgs-org-slug-portal-community-forum-moderation-reports-report-id-re) | Close a report, optionally acting on what it pointed at |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/moderation/threads/{thread_id}/flags`](#op-post-api-v1-orgs-org-slug-portal-community-forum-moderation-threads-thread-id-fl) | Pin, lock, move or mark a thread as a duplicate |
| PUT | [`/api/v1/orgs/{org_slug}/portal/community/forum/posts/{post_id}`](#op-put-api-v1-orgs-org-slug-portal-community-forum-posts-post-id) | Update post |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/community/forum/posts/{post_id}`](#op-delete-api-v1-orgs-org-slug-portal-community-forum-posts-post-id) | Delete post |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/posts/{post_id}/react`](#op-post-api-v1-orgs-org-slug-portal-community-forum-posts-post-id-react) | React to post |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/posts/{post_id}/vote`](#op-post-api-v1-orgs-org-slug-portal-community-forum-posts-post-id-vote) | Vote post |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/reports`](#op-post-api-v1-orgs-org-slug-portal-community-forum-reports) | Report content |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/forum/subscriptions`](#op-get-api-v1-orgs-org-slug-portal-community-forum-subscriptions) | Threads the member follows, with how many posts they have not seen |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/subscriptions/read`](#op-post-api-v1-orgs-org-slug-portal-community-forum-subscriptions-read) | Mark subscriptions read |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads`](#op-post-api-v1-orgs-org-slug-portal-community-forum-threads) | Create thread |
| PUT | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}`](#op-put-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id) | Update thread |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}`](#op-delete-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id) | Delete thread |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/bump`](#op-post-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-bump) | Bump thread |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/posts`](#op-post-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-posts) | Create post |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/solution`](#op-post-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-solution) | Accept a reply as the answer |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/solution`](#op-delete-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-solution) | Clear solution |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/subscription`](#op-post-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-subscription) | Toggle subscription |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/subscription`](#op-delete-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-subscriptio) | Stop following, idempotently |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/guides/articles`](#op-get-api-v1-orgs-org-slug-portal-community-guides-articles) | My articles |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/articles`](#op-post-api-v1-orgs-org-slug-portal-community-guides-articles) | Create article |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}`](#op-get-api-v1-orgs-org-slug-portal-community-guides-articles-article-id) | Get my article |
| PUT | [`/api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}`](#op-put-api-v1-orgs-org-slug-portal-community-guides-articles-article-id) | Propose or update |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}`](#op-delete-api-v1-orgs-org-slug-portal-community-guides-articles-article-id) | The author removing their own guide, whatever state it is in |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}/diff`](#op-get-api-v1-orgs-org-slug-portal-community-guides-articles-article-id-diff) | Article diff |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}/proposal/withdraw`](#op-post-api-v1-orgs-org-slug-portal-community-guides-articles-article-id-proposal-w) | Withdraw proposal |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}/propose`](#op-post-api-v1-orgs-org-slug-portal-community-guides-articles-article-id-propose) | Propose or update |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/guides/moderation`](#op-get-api-v1-orgs-org-slug-portal-community-guides-moderation) | Moderation queue |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/moderation/articles/{article_id}/approve`](#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-articles-article-id) | Mod approve |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/moderation/articles/{article_id}/reject`](#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-articles-article-id) | Mod reject |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/moderation/comments/{comment_id}/approve`](#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-comments-comment-id) | Mod approve comment |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/moderation/comments/{comment_id}/reject`](#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-comments-comment-id) | Mod reject comment |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/moderation/reports/{report_id}/resolve`](#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-reports-report-id-r) | Close a report |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/guides/notifications`](#op-get-api-v1-orgs-org-slug-portal-community-guides-notifications) | List notifications |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/guides/notifications/{notification_id}/read`](#op-post-api-v1-orgs-org-slug-portal-community-guides-notifications-notification-id) | Mark notification read |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/members/{handle}/wall`](#op-post-api-v1-orgs-org-slug-portal-community-members-handle-wall) | Create wall post |
| GET | [`/api/v1/orgs/{org_slug}/portal/community/profile`](#op-get-api-v1-orgs-org-slug-portal-community-profile) | Get own profile |
| PUT | [`/api/v1/orgs/{org_slug}/portal/community/profile`](#op-put-api-v1-orgs-org-slug-portal-community-profile) | Update own profile |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/community/wall/comments/{comment_id}`](#op-delete-api-v1-orgs-org-slug-portal-community-wall-comments-comment-id) | Delete wall comment |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/community/wall/{wall_post_id}`](#op-delete-api-v1-orgs-org-slug-portal-community-wall-wall-post-id) | Delete wall post |
| POST | [`/api/v1/orgs/{org_slug}/portal/community/wall/{wall_post_id}/comments`](#op-post-api-v1-orgs-org-slug-portal-community-wall-wall-post-id-comments) | Create wall comment |

### Forum viewer summary {#op-get-api-v1-orgs-org-slug-portal-community-forum-me}

`GET /api/v1/orgs/{org_slug}/portal/community/forum/me`

The signed-in member as the forum chrome sees them: handle, role,
unread followed threads, and the open report count for staff.

Also the one request a member who only reads makes with their token, so
``ensure_profile`` stamping them present here is what keeps *Active … ago*
honest for somebody who never posts; the storefront asks again when its
copy is a few minutes old.

#### 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. |

### Set member role {#op-post-api-v1-orgs-org-slug-portal-community-forum-moderation-members-handle-role}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/moderation/members/{handle}/role`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `handle` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `role` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Suspend member {#op-post-api-v1-orgs-org-slug-portal-community-forum-moderation-members-handle-suspe}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/moderation/members/{handle}/suspend`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `handle` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `suspend` | boolean | no |
| `reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Moderation reports {#op-get-api-v1-orgs-org-slug-portal-community-forum-moderation-reports}

`GET /api/v1/orgs/{org_slug}/portal/community/forum/moderation/reports`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string | no | Default: `open`. |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `25`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Close a report, optionally acting on what it pointed at {#op-post-api-v1-orgs-org-slug-portal-community-forum-moderation-reports-report-id-re}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/moderation/reports/{report_id}/resolve`

Close a report, optionally acting on what it pointed at.

The action and the closing are one request, so the queue cannot end up
with a removed post and a report still open against it. Nor can it end up
the other way round, which is worse: a dismissed report and content nobody
looked at.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `report_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `resolution` | string or null | no |
| `action` | string | no |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Pin, lock, move or mark a thread as a duplicate {#op-post-api-v1-orgs-org-slug-portal-community-forum-moderation-threads-thread-id-fl}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/moderation/threads/{thread_id}/flags`

Pin, lock, move or mark a thread as a duplicate.

The duplicate marker is the one that matters for search: it takes the newer
thread out of the index and leaves the older one holding the ranking, which
is the opposite of what happens if you simply delete the repost.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `is_sticky` | boolean or null | no |
| `is_locked` | boolean or null | no |
| `category_slug` | string or null | no |
| `duplicate_of_thread_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update post {#op-put-api-v1-orgs-org-slug-portal-community-forum-posts-post-id}

`PUT /api/v1/orgs/{org_slug}/portal/community/forum/posts/{post_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `post_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body_markdown` | string | yes |
| `edit_reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete post {#op-delete-api-v1-orgs-org-slug-portal-community-forum-posts-post-id}

`DELETE /api/v1/orgs/{org_slug}/portal/community/forum/posts/{post_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `post_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### React to post {#op-post-api-v1-orgs-org-slug-portal-community-forum-posts-post-id-react}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/posts/{post_id}/react`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `post_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reaction_type` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Vote post {#op-post-api-v1-orgs-org-slug-portal-community-forum-posts-post-id-vote}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/posts/{post_id}/vote`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `post_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `value` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Report content {#op-post-api-v1-orgs-org-slug-portal-community-forum-reports}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/reports`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | query | integer or null | no |
| `post_id` | query | integer or null | no |
| `handle` | query | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `category` | string | no |
| `reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Threads the member follows, with how many posts they have not seen {#op-get-api-v1-orgs-org-slug-portal-community-forum-subscriptions}

`GET /api/v1/orgs/{org_slug}/portal/community/forum/subscriptions`

Threads the member follows, with how many posts they have not seen.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `unread` | query | boolean | no | Default: `False`. |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mark subscriptions read {#op-post-api-v1-orgs-org-slug-portal-community-forum-subscriptions-read}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/subscriptions/read`

#### 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. |

### Create thread {#op-post-api-v1-orgs-org-slug-portal-community-forum-threads}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/threads`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `category_slug` | string | yes |
| `title` | string | yes |
| `body_markdown` | string | yes |
| `kind` | string | no |
| `tags` | array of string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update thread {#op-put-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id}

`PUT /api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `body_markdown` | string or null | no |
| `tags` | array of string or null | no |
| `edit_reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete thread {#op-delete-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id}

`DELETE /api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Bump thread {#op-post-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-bump}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/bump`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create post {#op-post-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-posts}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/posts`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body_markdown` | string | yes |
| `parent_post_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Accept a reply as the answer {#op-post-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-solution}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/solution`

Accept a reply as the answer.

The reference forum has no such thing, which is why its question boards are
thousands of pages that end without one. An accepted answer is the single
strongest signal in the relevance score, and the only one that promotes a
thread into the assistant-facing export.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |
| `post_id` | query | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Clear solution {#op-delete-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-solution}

`DELETE /api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/solution`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Toggle subscription {#op-post-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-subscription}

`POST /api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/subscription`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Stop following, idempotently {#op-delete-api-v1-orgs-org-slug-portal-community-forum-threads-thread-id-subscriptio}

`DELETE /api/v1/orgs/{org_slug}/portal/community/forum/threads/{thread_id}/subscription`

Stop following, idempotently. The toggle is wrong for a list of
Unfollow buttons, where a double click would follow again.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### My articles {#op-get-api-v1-orgs-org-slug-portal-community-guides-articles}

`GET /api/v1/orgs/{org_slug}/portal/community/guides/articles`

#### 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. |

### Create article {#op-post-api-v1-orgs-org-slug-portal-community-guides-articles}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/articles`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `slug` | string or null | no |
| `summary` | string or null | no |
| `body_markdown` | string or null | no |
| `category` | string or null | no |
| `tags` | array of string or null | no |
| `difficulty` | string or null | no |
| `game_slug` | string or null | no |
| `cover_data_uri` | string or null | no |
| `seo_title` | string or null | no |
| `seo_description` | string or null | no |
| `change_note` | string or null | no |
| `submit` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get my article {#op-get-api-v1-orgs-org-slug-portal-community-guides-articles-article-id}

`GET /api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `article_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `view` | query | string | no | Default: `live`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Propose or update {#op-put-api-v1-orgs-org-slug-portal-community-guides-articles-article-id}

`PUT /api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `slug` | string or null | no |
| `summary` | string or null | no |
| `body_markdown` | string or null | no |
| `category` | string or null | no |
| `tags` | array of string or null | no |
| `difficulty` | string or null | no |
| `game_slug` | string or null | no |
| `cover_data_uri` | string or null | no |
| `seo_title` | string or null | no |
| `seo_description` | string or null | no |
| `change_note` | string or null | no |
| `submit` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The author removing their own guide, whatever state it is in {#op-delete-api-v1-orgs-org-slug-portal-community-guides-articles-article-id}

`DELETE /api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}`

The author removing their own guide, whatever state it is in.

A hard delete, on purpose: the author is withdrawing something they
wrote, and a row kept around "archived" would still be theirs to find in
the library and staff's to stumble over in the queue. Revisions, comments,
votes, reports and notifications go with it. The rows are removed in
dependency order rather than left to the cascades, because the two
article→revision keys were added best-effort and may not exist on an
older database.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Article diff {#op-get-api-v1-orgs-org-slug-portal-community-guides-articles-article-id-diff}

`GET /api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}/diff`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Withdraw proposal {#op-post-api-v1-orgs-org-slug-portal-community-guides-articles-article-id-proposal-w}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}/proposal/withdraw`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Propose or update {#op-post-api-v1-orgs-org-slug-portal-community-guides-articles-article-id-propose}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/articles/{article_id}/propose`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `slug` | string or null | no |
| `summary` | string or null | no |
| `body_markdown` | string or null | no |
| `category` | string or null | no |
| `tags` | array of string or null | no |
| `difficulty` | string or null | no |
| `game_slug` | string or null | no |
| `cover_data_uri` | string or null | no |
| `seo_title` | string or null | no |
| `seo_description` | string or null | no |
| `change_note` | string or null | no |
| `submit` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Moderation queue {#op-get-api-v1-orgs-org-slug-portal-community-guides-moderation}

`GET /api/v1/orgs/{org_slug}/portal/community/guides/moderation`

#### 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. |

### Mod approve {#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-articles-article-id}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/moderation/articles/{article_id}/approve`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mod reject {#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-articles-article-id}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/moderation/articles/{article_id}/reject`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mod approve comment {#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-comments-comment-id}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/moderation/comments/{comment_id}/approve`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `comment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mod reject comment {#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-comments-comment-id}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/moderation/comments/{comment_id}/reject`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `comment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Close a report {#op-post-api-v1-orgs-org-slug-portal-community-guides-moderation-reports-report-id-r}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/moderation/reports/{report_id}/resolve`

Close a report. Without this the queue only ever grew.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `report_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List notifications {#op-get-api-v1-orgs-org-slug-portal-community-guides-notifications}

`GET /api/v1/orgs/{org_slug}/portal/community/guides/notifications`

#### 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. |

### Mark notification read {#op-post-api-v1-orgs-org-slug-portal-community-guides-notifications-notification-id}

`POST /api/v1/orgs/{org_slug}/portal/community/guides/notifications/{notification_id}/read`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `notification_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create wall post {#op-post-api-v1-orgs-org-slug-portal-community-members-handle-wall}

`POST /api/v1/orgs/{org_slug}/portal/community/members/{handle}/wall`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `handle` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body_markdown` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get own profile {#op-get-api-v1-orgs-org-slug-portal-community-profile}

`GET /api/v1/orgs/{org_slug}/portal/community/profile`

#### 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. |

### Update own profile {#op-put-api-v1-orgs-org-slug-portal-community-profile}

`PUT /api/v1/orgs/{org_slug}/portal/community/profile`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `display_name` | string or null | no |
| `biography` | string or null | no |
| `location` | string or null | no |
| `website_url` | string or null | no |
| `signature` | string or null | no |
| `avatar_data_uri` | string or null | no |
| `banner_data_uri` | string or null | no |
| `wall_enabled` | boolean or null | no |
| `index_opt_out` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete wall comment {#op-delete-api-v1-orgs-org-slug-portal-community-wall-comments-comment-id}

`DELETE /api/v1/orgs/{org_slug}/portal/community/wall/comments/{comment_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `comment_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete wall post {#op-delete-api-v1-orgs-org-slug-portal-community-wall-wall-post-id}

`DELETE /api/v1/orgs/{org_slug}/portal/community/wall/{wall_post_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `wall_post_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create wall comment {#op-post-api-v1-orgs-org-slug-portal-community-wall-wall-post-id-comments}

`POST /api/v1/orgs/{org_slug}/portal/community/wall/{wall_post_id}/comments`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `wall_post_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body_markdown` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Countries

> The 1 Organization API operations for countries.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/countries/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/countries`](#op-get-api-v1-orgs-org-slug-portal-countries) | Countries a customer can bill from, and the one we think they are in |

### Countries a customer can bill from, and the one we think they are in {#op-get-api-v1-orgs-org-slug-portal-countries}

`GET /api/v1/orgs/{org_slug}/portal/countries`

Countries a customer can bill from, and the one we think they are in.

#### 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. |

# Organization API: Customer Portal: Credit

> The 6 Organization API operations for credit.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/credit/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/credit`](#op-get-api-v1-orgs-org-slug-portal-credit) | Get my credit balance |
| POST | [`/api/v1/orgs/{org_slug}/portal/credit/topup/charge`](#op-post-api-v1-orgs-org-slug-portal-credit-topup-charge) | Charge a saved payment method and credit the org customer balance (USD) |
| POST | [`/api/v1/orgs/{org_slug}/portal/credit/topup/checkout`](#op-post-api-v1-orgs-org-slug-portal-credit-topup-checkout) | Hosted checkout to buy USD credit for an org customer |
| POST | [`/api/v1/orgs/{org_slug}/portal/credit/topup/confirm-payment`](#op-post-api-v1-orgs-org-slug-portal-credit-topup-confirm-payment) | Finalize a credit top-up PaymentIntent after SCA and credit the balance |
| POST | [`/api/v1/orgs/{org_slug}/portal/credit/topup/pay-intent`](#op-post-api-v1-orgs-org-slug-portal-credit-topup-pay-intent) | Create an in-page Stripe Payment Element intent for a credit top-up |
| POST | [`/api/v1/orgs/{org_slug}/portal/credit/topup/paypal-capture`](#op-post-api-v1-orgs-org-slug-portal-credit-topup-paypal-capture) | Capture PayPal order and credit org customer balance |

### Get my credit balance {#op-get-api-v1-orgs-org-slug-portal-credit}

`GET /api/v1/orgs/{org_slug}/portal/credit`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `20`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Charge a saved payment method and credit the org customer balance (USD) {#op-post-api-v1-orgs-org-slug-portal-credit-topup-charge}

`POST /api/v1/orgs/{org_slug}/portal/credit/topup/charge`

Charge a saved payment method and credit the org customer balance (USD).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `amount` | query | number or string | yes |
| `payment_method_id` | query | integer | yes |
| `currency` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Hosted checkout to buy USD credit for an org customer {#op-post-api-v1-orgs-org-slug-portal-credit-topup-checkout}

`POST /api/v1/orgs/{org_slug}/portal/credit/topup/checkout`

Hosted checkout to buy USD credit for an org customer.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `amount` | query | number or string | yes |
| `currency` | query | string | no |
| `gateway_name` | query | string | no |
| `return_url` | query | string | no |
| `cancel_url` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Finalize a credit top-up PaymentIntent after SCA and credit the balance {#op-post-api-v1-orgs-org-slug-portal-credit-topup-confirm-payment}

`POST /api/v1/orgs/{org_slug}/portal/credit/topup/confirm-payment`

Finalize a credit top-up PaymentIntent after SCA and credit the balance.

USD credit comes from PaymentIntent metadata ``base_amount``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `gateway_name` | query | string | yes |
| `payment_intent_id` | query | string | yes |
| `amount` | query | number or string | no |
| `currency` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create an in-page Stripe Payment Element intent for a credit top-up {#op-post-api-v1-orgs-org-slug-portal-credit-topup-pay-intent}

`POST /api/v1/orgs/{org_slug}/portal/credit/topup/pay-intent`

Create an in-page Stripe Payment Element intent for a credit top-up.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `amount` | query | number or string | yes |  |
| `currency` | query | string | no |  |
| `gateway_name` | query | string | no |  |
| `save_method` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Capture PayPal order and credit org customer balance {#op-post-api-v1-orgs-org-slug-portal-credit-topup-paypal-capture}

`POST /api/v1/orgs/{org_slug}/portal/credit/topup/paypal-capture`

Capture PayPal order and credit org customer balance.

USD credit is derived from order ``custom_id=topup:<usd>``; optional
``amount`` may assert within $0.02.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `order_id` | query | string | yes |
| `gateway_name` | query | string | yes |
| `amount` | query | number or string | no |
| `currency` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Crypto

> The 7 Organization API operations for crypto.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/crypto/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/crypto/address`](#op-get-api-v1-orgs-org-slug-portal-crypto-address) | This customer's permanent deposit address for the network's family |
| GET | [`/api/v1/orgs/{org_slug}/portal/crypto/assets`](#op-get-api-v1-orgs-org-slug-portal-crypto-assets) | Assets this storefront can accept right now |
| POST | [`/api/v1/orgs/{org_slug}/portal/crypto/check`](#op-post-api-v1-orgs-org-slug-portal-crypto-check) | Look for this customer's payment now, and say where it stands |
| GET | [`/api/v1/orgs/{org_slug}/portal/crypto/deposits`](#op-get-api-v1-orgs-org-slug-portal-crypto-deposits) | Deposit history, including transfers still confirming |
| GET | [`/api/v1/orgs/{org_slug}/portal/crypto/deposits/{deposit_id}`](#op-get-api-v1-orgs-org-slug-portal-crypto-deposits-deposit-id) | One deposit, for polling while it confirms |
| GET | [`/api/v1/orgs/{org_slug}/portal/crypto/plan`](#op-get-api-v1-orgs-org-slug-portal-crypto-plan) | Every way to pay this amount in crypto, cheapest first |
| GET | [`/api/v1/orgs/{org_slug}/portal/crypto/quote`](#op-get-api-v1-orgs-org-slug-portal-crypto-quote) | How much to send for a target USD credit, itemised |

### This customer's permanent deposit address for the network's family {#op-get-api-v1-orgs-org-slug-portal-crypto-address}

`GET /api/v1/orgs/{org_slug}/portal/crypto/address`

This customer's permanent deposit address for the network's family.

Scoped to the org, so the same customer id under two different orgs gets two
different addresses and their deposits can never be confused.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `network` | query | string | yes | Network key, e.g. base or bitcoin |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Assets this storefront can accept right now {#op-get-api-v1-orgs-org-slug-portal-crypto-assets}

`GET /api/v1/orgs/{org_slug}/portal/crypto/assets`

Assets this storefront can accept right now.

#### 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. |

### Look for this customer's payment now, and say where it stands {#op-post-api-v1-orgs-org-slug-portal-crypto-check}

`POST /api/v1/orgs/{org_slug}/portal/crypto/check`

Look for this customer's payment now, and say where it stands.

The org portal counterpart of the platform check. An org customer waiting on
a crypto payment has exactly the same question as a platform one, and the
storefront SPA they are served has the same refresh button.

Rate limited per org customer, and the chain read inside is throttled per
address, so several open tabs cost one read rather than one each.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

Type: object or null.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Deposit history, including transfers still confirming {#op-get-api-v1-orgs-org-slug-portal-crypto-deposits}

`GET /api/v1/orgs/{org_slug}/portal/crypto/deposits`

Deposit history, including transfers still confirming.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### One deposit, for polling while it confirms {#op-get-api-v1-orgs-org-slug-portal-crypto-deposits-deposit-id}

`GET /api/v1/orgs/{org_slug}/portal/crypto/deposits/{deposit_id}`

One deposit, for polling while it confirms.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `deposit_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every way to pay this amount in crypto, cheapest first {#op-get-api-v1-orgs-org-slug-portal-crypto-plan}

`GET /api/v1/orgs/{org_slug}/portal/crypto/plan`

Every way to pay this amount in crypto, cheapest first.

The org counterpart of the platform plan endpoint. It answers the question
a customer has ("how much do I send to end up with $X?") instead of
showing a rate and leaving them the arithmetic, and says outright when a
chain's fee would eat the payment.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `amount` | query | number or string | yes |
| `invoice_id` | query | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### How much to send for a target USD credit, itemised {#op-get-api-v1-orgs-org-slug-portal-crypto-quote}

`GET /api/v1/orgs/{org_slug}/portal/crypto/quote`

How much to send for a target USD credit, itemised.

Quoting with ``invoice_id`` records a payment intent, which is what locks
the rate and lets the deposit settle that invoice when it lands instead of
arriving as a balance the customer then has to spend by hand.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `network` | query | string | yes |
| `asset` | query | string | yes |
| `amount` | query | number or string | yes |
| `invoice_id` | query | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Currencies

> The 1 Organization API operations for currencies.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/currencies/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/currencies`](#op-get-api-v1-orgs-org-slug-portal-currencies) | List portal currencies |

### List portal currencies {#op-get-api-v1-orgs-org-slug-portal-currencies}

`GET /api/v1/orgs/{org_slug}/portal/currencies`

#### 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. |

# Organization API: Customer Portal: External servers

> The 5 Organization API operations for external servers.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/external-servers/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/external-servers`](#op-get-api-v1-orgs-org-slug-portal-external-servers) | List external servers |
| GET | [`/api/v1/orgs/{org_slug}/portal/external-servers/regions`](#op-get-api-v1-orgs-org-slug-portal-external-servers-regions) | Regions an existing external server can be moved to |
| GET | [`/api/v1/orgs/{org_slug}/portal/external-servers/{service_id}`](#op-get-api-v1-orgs-org-slug-portal-external-servers-service-id) | Get external server |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/external-servers/{service_id}`](#op-patch-api-v1-orgs-org-slug-portal-external-servers-service-id) | Change where players are forwarded, how, and through which region |
| POST | [`/api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/test`](#op-post-api-v1-orgs-org-slug-portal-external-servers-service-id-test) | Status-ping the backend now and record the answer |

### List external servers {#op-get-api-v1-orgs-org-slug-portal-external-servers}

`GET /api/v1/orgs/{org_slug}/portal/external-servers`

#### 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. |

### Regions an existing external server can be moved to {#op-get-api-v1-orgs-org-slug-portal-external-servers-regions}

`GET /api/v1/orgs/{org_slug}/portal/external-servers/regions`

Regions an existing external server can be moved to.

#### 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. |

### Get external server {#op-get-api-v1-orgs-org-slug-portal-external-servers-service-id}

`GET /api/v1/orgs/{org_slug}/portal/external-servers/{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. |

### Change where players are forwarded, how, and through which region {#op-patch-api-v1-orgs-org-slug-portal-external-servers-service-id}

`PATCH /api/v1/orgs/{org_slug}/portal/external-servers/{service_id}`

Change where players are forwarded, how, and through which region.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `upstream_host` | string or null | no |
| `upstream_port` | integer or null | no |
| `proxy_protocol` | boolean or null | no |
| `real_ip` | boolean or null | no |
| `mode` | string or null | no |
| `bedrock_bridge` | boolean or null | no |
| `location_id` | integer or null | no |
| `display_name` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Status-ping the backend now and record the answer {#op-post-api-v1-orgs-org-slug-portal-external-servers-service-id-test}

`POST /api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/test`

Status-ping the backend now and record the answer.

#### 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. |

# Organization API: Customer Portal: Custom domain

> The 5 Organization API operations for custom domain.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/external-servers-custom-domain/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain`](#op-get-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain) | Get custom domain |
| POST | [`/api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain`](#op-post-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain) | Link custom domain |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain`](#op-patch-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain) | Show the vanity hostname, or the hosted one, in the public server list |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain`](#op-delete-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain) | Unlink custom domain |
| POST | [`/api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain/verify`](#op-post-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain-verif) | Check the CNAME now rather than waiting for the next maintenance pass |

### Get custom domain {#op-get-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain}

`GET /api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain`

#### 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. |

### Link custom domain {#op-post-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain}

`POST /api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `subdomain` | string | no |
| `include_in_list` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Show the vanity hostname, or the hosted one, in the public server list {#op-patch-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain}

`PATCH /api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain`

Show the vanity hostname, or the hosted one, in the public server list.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `include_in_list` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Unlink custom domain {#op-delete-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain}

`DELETE /api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain`

#### 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. |

### Check the CNAME now rather than waiting for the next maintenance pass {#op-post-api-v1-orgs-org-slug-portal-external-servers-service-id-custom-domain-verif}

`POST /api/v1/orgs/{org_slug}/portal/external-servers/{service_id}/custom-domain/verify`

Check the CNAME now rather than waiting for the next maintenance pass.

#### 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. |

# Organization API: Customer Portal: Geo currency

> The 1 Organization API operations for geo currency.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/geo-currency/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/geo-currency`](#op-get-api-v1-orgs-org-slug-portal-geo-currency) | Unauthenticated country → suggested pay currency for storefront preselect |

### Unauthenticated country → suggested pay currency for storefront preselect {#op-get-api-v1-orgs-org-slug-portal-geo-currency}

`GET /api/v1/orgs/{org_slug}/portal/geo-currency`

Unauthenticated country → suggested pay currency for storefront preselect.

#### 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. |

# Organization API: Customer Portal: Invoices

> The 15 Organization API operations for invoices.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/invoices/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/invoices`](#op-get-api-v1-orgs-org-slug-portal-invoices) | Newest first, ties by id |
| GET | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}`](#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id) | Get my invoice |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/apply-credit`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-apply-credit) | Apply the customer's credit balance toward an unpaid invoice |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/charge`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-charge) | Pay an invoice using a saved payment method (merchant-initiated charge) |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/checkout`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-checkout) | Canonical hosted checkout for an org-customer invoice (alias of /pay) |
| GET | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/checkout-session`](#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id-checkout-session) | Resume an in-flight checkout after a new tab, login, or API restart |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/confirm-payment`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-confirm-payment) | Finalize a charge after customer completes SCA (3-D Secure) |
| GET | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/gateways`](#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id-gateways) | Gateway accounts that can checkout this invoice's pay currency |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/pay`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-pay) | Hosted checkout for an invoice (legacy path; prefer /checkout) |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/pay-intent`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-pay-intent) | Create an in-page Stripe Payment Element intent for an org invoice |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/paypal-capture`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-paypal-capture) | Capture paypal order |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/paypal-stash`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-paypal-stash) | Persist a PayPal order id so a redirect or reboot can still capture it |
| GET | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/pdf`](#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id-pdf) | The invoice as a document to keep |
| GET | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/refund-eligibility`](#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id-refund-eligibility) | My invoice refund eligibility |
| POST | [`/api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/refund-request`](#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-refund-request) | Request my invoice refund |

### Newest first, ties by id {#op-get-api-v1-orgs-org-slug-portal-invoices}

`GET /api/v1/orgs/{org_slug}/portal/invoices`

Newest first, ties by id. ``with_total`` wraps the page as
``{items, total, limit, offset, counts}``; counts are per status for the
same search, whatever the status filter.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status_filter` | query | string | no |  |
| `q` | query | string | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |
| `with_total` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get my invoice {#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id}

`GET /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Apply the customer's credit balance toward an unpaid invoice {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-apply-credit}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/apply-credit`

Apply the customer's credit balance toward an unpaid invoice.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Pay an invoice using a saved payment method (merchant-initiated charge) {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-charge}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/charge`

Pay an invoice using a saved payment method (merchant-initiated charge).
If no payment_method_id specified, uses the default method.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `payment_method_id` | query | integer | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Canonical hosted checkout for an org-customer invoice (alias of /pay) {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-checkout}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/checkout`

Canonical hosted checkout for an org-customer invoice (alias of ``/pay``).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `return_url` | query | string | no |
| `cancel_url` | query | string | no |
| `currency` | query | string | no |
| `gateway_name` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Resume an in-flight checkout after a new tab, login, or API restart {#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id-checkout-session}

`GET /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/checkout-session`

Resume an in-flight checkout after a new tab, login, or API restart.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Finalize a charge after customer completes SCA (3-D Secure) {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-confirm-payment}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/confirm-payment`

Finalize a charge after customer completes SCA (3-D Secure).
Retrieves the PaymentIntent from Stripe and settles the org invoice on success.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `gateway_name` | query | string | yes |
| `payment_intent_id` | query | string | yes |
| `currency` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Gateway accounts that can checkout this invoice's pay currency {#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id-gateways}

`GET /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/gateways`

Gateway accounts that can checkout this invoice's pay currency.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `currency` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Hosted checkout for an invoice (legacy path; prefer /checkout) {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-pay}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/pay`

Hosted checkout for an invoice (legacy path; prefer ``/checkout``).
Creates a hosted checkout session and returns an approval URL.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `return_url` | query | string | no |
| `cancel_url` | query | string | no |
| `currency` | query | string | no |
| `gateway_name` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create an in-page Stripe Payment Element intent for an org invoice {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-pay-intent}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/pay-intent`

Create an in-page Stripe Payment Element intent for an org invoice.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `currency` | query | string | no |
| `country` | query | string | no |
| `gateway_name` | query | string | no |
| `save_method` | query | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Capture paypal order {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-paypal-capture}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/paypal-capture`

Finalize an embedded PayPal Buttons one-off payment: capture the
buyer-approved order server-side and apply it to the org invoice (USD ledger).
Idempotent via the gateway_reference uniqueness in settle_org_invoice_payment.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `order_id` | query | string | yes |
| `gateway_name` | query | string | yes |
| `currency` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Persist a PayPal order id so a redirect or reboot can still capture it {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-paypal-stash}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/paypal-stash`

Persist a PayPal order id so a redirect or reboot can still capture it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `order_id` | query | string | yes |
| `gateway_name` | query | string | yes |
| `currency` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The invoice as a document to keep {#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id-pdf}

`GET /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/pdf`

The invoice as a document to keep. Statements are staff-facing; this is
the copy a customer files with their own accounts.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### My invoice refund eligibility {#op-get-api-v1-orgs-org-slug-portal-invoices-invoice-id-refund-eligibility}

`GET /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/refund-eligibility`

What the Refund Policy says about this invoice, so the page can offer
the request, or say plainly why it cannot, before the customer types.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Request my invoice refund {#op-post-api-v1-orgs-org-slug-portal-invoices-invoice-id-refund-request}

`POST /api/v1/orgs/{org_slug}/portal/invoices/{invoice_id}/refund-request`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_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. |

# Organization API: Customer Portal: Ips

> The 13 Organization API operations for ips.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/ips/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/ips`](#op-get-api-v1-orgs-org-slug-portal-ips) | List my IPs |
| GET | [`/api/v1/orgs/{org_slug}/portal/ips/attach-targets`](#op-get-api-v1-orgs-org-slug-portal-ips-attach-targets) | List attach targets |
| POST | [`/api/v1/orgs/{org_slug}/portal/ips/order`](#op-post-api-v1-orgs-org-slug-portal-ips-order) | Order a floating IP / subnet via the org storefront path |
| GET | [`/api/v1/orgs/{org_slug}/portal/ips/orders`](#op-get-api-v1-orgs-org-slug-portal-ips-orders) | Open IP order intents, so unpaid or in-flight orders resume after login or in a new tab |
| GET | [`/api/v1/orgs/{org_slug}/portal/ips/orders/{idempotency_key}`](#op-get-api-v1-orgs-org-slug-portal-ips-orders-idempotency-key) | Get my IP order |
| POST | [`/api/v1/orgs/{org_slug}/portal/ips/orders/{idempotency_key}/cancel`](#op-post-api-v1-orgs-org-slug-portal-ips-orders-idempotency-key-cancel) | Cancel my IP order |
| GET | [`/api/v1/orgs/{org_slug}/portal/ips/pools`](#op-get-api-v1-orgs-org-slug-portal-ips-pools) | List sellable pools |
| GET | [`/api/v1/orgs/{org_slug}/portal/ips/{service_id}`](#op-get-api-v1-orgs-org-slug-portal-ips-service-id) | Get my IP |
| POST | [`/api/v1/orgs/{org_slug}/portal/ips/{service_id}/attach`](#op-post-api-v1-orgs-org-slug-portal-ips-service-id-attach) | Attach IP |
| POST | [`/api/v1/orgs/{org_slug}/portal/ips/{service_id}/detach`](#op-post-api-v1-orgs-org-slug-portal-ips-service-id-detach) | Detach IP |
| GET | [`/api/v1/orgs/{org_slug}/portal/ips/{service_id}/hosts`](#op-get-api-v1-orgs-org-slug-portal-ips-service-id-hosts) | List my IP hosts |
| GET | [`/api/v1/orgs/{org_slug}/portal/ips/{service_id}/ptr`](#op-get-api-v1-orgs-org-slug-portal-ips-service-id-ptr) | Get PTR |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/ips/{service_id}/ptr`](#op-patch-api-v1-orgs-org-slug-portal-ips-service-id-ptr) | Set PTR |

### List my IPs {#op-get-api-v1-orgs-org-slug-portal-ips}

`GET /api/v1/orgs/{org_slug}/portal/ips`

#### 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. |

### List attach targets {#op-get-api-v1-orgs-org-slug-portal-ips-attach-targets}

`GET /api/v1/orgs/{org_slug}/portal/ips/attach-targets`

#### 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. |

### Order a floating IP / subnet via the org storefront path {#op-post-api-v1-orgs-org-slug-portal-ips-order}

`POST /api/v1/orgs/{org_slug}/portal/ips/order`

Order a floating IP / subnet via the org storefront path.

Reserves inventory in the same transaction as the invoice. Replays of the
same ``idempotency_key`` return the original invoice instead of a second order.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `org_product_id` | integer | yes |  |
| `org_pricing_id` | integer | yes |  |
| `pool_id` | integer | yes |  |
| `prefix_len` | integer | no |  |
| `version` | string | no |  |
| `hostname` | string or null | no |  |
| `idempotency_key` | string | yes | Client-generated key so double-submit / multi-tab retries replay the same order |
| `attach_to_org_service_id` | integer or null | no | One of your Minecraft servers (org service id). The address is attached to it as soon as it is provisioned; single IPv4 only. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Open IP order intents, so unpaid or in-flight orders resume after login or in a new tab {#op-get-api-v1-orgs-org-slug-portal-ips-orders}

`GET /api/v1/orgs/{org_slug}/portal/ips/orders`

Open IP order intents, so unpaid or in-flight orders resume after login or in a new tab.

#### 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. |

### Get my IP order {#op-get-api-v1-orgs-org-slug-portal-ips-orders-idempotency-key}

`GET /api/v1/orgs/{org_slug}/portal/ips/orders/{idempotency_key}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `idempotency_key` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Cancel my IP order {#op-post-api-v1-orgs-org-slug-portal-ips-orders-idempotency-key-cancel}

`POST /api/v1/orgs/{org_slug}/portal/ips/orders/{idempotency_key}/cancel`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `idempotency_key` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List sellable pools {#op-get-api-v1-orgs-org-slug-portal-ips-pools}

`GET /api/v1/orgs/{org_slug}/portal/ips/pools`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `version` | query | string | no | Default: `ipv4`. |
| `prefix_len` | query | integer or null | no |  |
| `region` | query | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get my IP {#op-get-api-v1-orgs-org-slug-portal-ips-service-id}

`GET /api/v1/orgs/{org_slug}/portal/ips/{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. |

### Attach IP {#op-post-api-v1-orgs-org-slug-portal-ips-service-id-attach}

`POST /api/v1/orgs/{org_slug}/portal/ips/{service_id}/attach`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `target_type` | string | yes | vps \| container |
| `target_service_id` | integer | yes | Platform service id of the compute target |
| `host_address` | string or null | no | Host IP within a rented subnet; omit to attach first free host |
| `host_inventory_id` | integer or null | no | Alternative to host_address: inventory id of the host row |
| `is_primary` | boolean or null | no | For VPS multi-IP: set as primary (ipconfig0). Default: primary if none yet. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Detach IP {#op-post-api-v1-orgs-org-slug-portal-ips-service-id-detach}

`POST /api/v1/orgs/{org_slug}/portal/ips/{service_id}/detach`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `host_address` | string or null | no |
| `host_inventory_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List my IP hosts {#op-get-api-v1-orgs-org-slug-portal-ips-service-id-hosts}

`GET /api/v1/orgs/{org_slug}/portal/ips/{service_id}/hosts`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `service_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `include_reserved` | query | boolean | no | Default: `True`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get PTR {#op-get-api-v1-orgs-org-slug-portal-ips-service-id-ptr}

`GET /api/v1/orgs/{org_slug}/portal/ips/{service_id}/ptr`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `host_address` | query | string or null | no |
| `host_inventory_id` | query | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set PTR {#op-patch-api-v1-orgs-org-slug-portal-ips-service-id-ptr}

`PATCH /api/v1/orgs/{org_slug}/portal/ips/{service_id}/ptr`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |
| `host_address` | string or null | no |
| `host_inventory_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Mail

> The 8 Organization API operations for mail.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/services`](#op-get-api-v1-orgs-org-slug-portal-mail-services) | List services |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id) | Get summary |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/category`](#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-category) | Set category |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/events`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-events) | List events |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/limits/increase-request`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-limits-increase-request) | Request limit increase |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/messages`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-messages) | Send message |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/reputation`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-reputation) | Reputation report |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/usage`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-usage) | Usage report |

### List services {#op-get-api-v1-orgs-org-slug-portal-mail-services}

`GET /api/v1/orgs/{org_slug}/portal/mail/services`

#### 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. |

### Get summary {#op-get-api-v1-orgs-org-slug-portal-mail-service-id}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set category {#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-category}

`PATCH /api/v1/orgs/{org_slug}/portal/mail/{service_id}/category`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `default_category` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List events {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-events}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/events`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `service_id` | path | integer | yes |  |
| `category` | query | string or null | no |  |
| `recipient` | query | string or null | no |  |
| `hours` | query | integer | no | Default: `24`. |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Request limit increase {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-limits-increase-request}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/limits/increase-request`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requested_per_hour` | integer | yes |  |
| `reason` | string | no | What the relay sends and why the volume is going up |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send message {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-messages}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/messages`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from` | string | yes |
| `from_name` | string or null | no |
| `to` | array of string | yes |
| `cc` | array of string | no |
| `subject` | string | no |
| `text` | string or null | no |
| `html` | string or null | no |
| `reply_to` | string or null | no |
| `headers` | Headers | no |
| `category` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Reputation report {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-reputation}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/reputation`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `service_id` | path | integer | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Usage report {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-usage}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/usage`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `service_id` | path | integer | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Aliases

> The 3 Organization API operations for aliases.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail-aliases/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/aliases`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-aliases) | List aliases |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/aliases`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-aliases) | Create alias |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/aliases/{account_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-aliases-account-id) | Delete alias |

### List aliases {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-aliases}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/aliases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create alias {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-aliases}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/aliases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `targets` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete alias {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-aliases-account-id}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/aliases/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Api keys

> The 3 Organization API operations for api keys.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail-api-keys/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/api-keys`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-api-keys) | List API keys |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/api-keys`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-api-keys) | Create API key |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/api-keys/{key_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-api-keys-key-id) | Revoke API key |

### List API keys {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-api-keys}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/api-keys`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create API key {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-api-keys}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/api-keys`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Revoke API key {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-api-keys-key-id}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/api-keys/{key_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `key_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Credentials

> The 5 Organization API operations for credentials.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail-credentials/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-credentials) | List credentials |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-credentials) | Create credential |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials/{account_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-credentials-account-id) | Delete credential |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials/{account_id}/enabled`](#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-credentials-account-id-enabled) | Credential enabled |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials/{account_id}/rotate`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-credentials-account-id-rotate) | Rotate credential |

### List credentials {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-credentials}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create credential {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-credentials}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `label` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete credential {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-credentials-account-id}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Credential enabled {#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-credentials-account-id-enabled}

`PATCH /api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials/{account_id}/enabled`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rotate credential {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-credentials-account-id-rotate}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/credentials/{account_id}/rotate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Domains

> The 6 Organization API operations for domains.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail-domains/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-domains) | List domains |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-domains) | Add domain |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains/{domain_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-domains-domain-id) | Remove domain |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains/{domain_id}/dmarc`](#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-domains-domain-id-dmarc) | Set DMARC |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains/{domain_id}/records`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-domains-domain-id-records) | Domain records |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains/{domain_id}/verify`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-domains-domain-id-verify) | Verify domain |

### List domains {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-domains}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add domain {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-domains}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `primary` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove domain {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-domains-domain-id}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains/{domain_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set DMARC {#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-domains-domain-id-dmarc}

`PATCH /api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains/{domain_id}/dmarc`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `stage` | string or null | no |
| `pinned` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Domain records {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-domains-domain-id-records}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains/{domain_id}/records`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Verify domain {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-domains-domain-id-verify}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/domains/{domain_id}/verify`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Mailboxes

> The 19 Organization API operations for mailboxes.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail-mailboxes/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes) | List mailboxes |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes) | Create mailbox |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id) | Delete mailbox |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/app-passwords`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-app-passwor) | Mailbox app passwords |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/app-passwords`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-app-passwo) | Mailbox app password create |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-app-pass) | Mailbox app password delete |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/enabled`](#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-enabled) | Mailbox enabled |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports) | Mailbox imports |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports) | Mailbox import start |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports/oauth`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports-oa) | Mailbox import sign in |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports/upload`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports-up) | Mailbox import upload |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports/{import_id}/{action}`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports-im) | Mailbox import steer |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/password`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-password) | Mailbox password |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/quota`](#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-quota) | Mailbox quota |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/sessions`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-sessions) | Mailbox sessions |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/sessions`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-sessions) | Mailbox sessions end |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/sessions/{session_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-sessions) | Mailbox session end |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/totp`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-totp) | Mailbox totp enable |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/totp`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-totp) | Mailbox totp disable |

### List mailboxes {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create mailbox {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `password` | string or null | no |
| `display_name` | string or null | no |
| `quota_bytes` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete mailbox {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app passwords {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-app-passwor}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/app-passwords`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app password create {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-app-passwo}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/app-passwords`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app password delete {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-app-pass}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `credential_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox enabled {#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-enabled}

`PATCH /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/enabled`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox imports {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import start {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `preset` | string | no |
| `host` | string or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `folders` | array of string | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import sign in {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports-oa}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports/oauth`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `provider` | string, one of `google`, `microsoft` | yes |
| `return_path` | string or null | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import upload {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports-up}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports/upload`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |
| `kind` | string | no |
| `folder` | string | no |
| `cpanel_mailbox` | string | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import steer {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-imports-im}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/imports/{import_id}/{action}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `import_id` | path | integer | yes |
| `action` | path | string, one of `pause`, `resume`, `cancel` | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox password {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-password}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox quota {#op-patch-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-quota}

`PATCH /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/quota`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `quota_bytes` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox sessions {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-sessions}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox sessions end {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-sessions}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox session end {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-sessions}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/sessions/{session_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `session_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox totp enable {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-totp}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/totp`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox totp disable {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-mailboxes-account-id-totp}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/mailboxes/{account_id}/totp`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Suppressions

> The 3 Organization API operations for suppressions.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail-suppressions/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/suppressions`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-suppressions) | List suppressions |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/suppressions`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-suppressions) | Add suppression |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/suppressions/{suppression_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-suppressions-suppression-id) | Remove suppression |

### List suppressions {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-suppressions}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/suppressions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add suppression {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-suppressions}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/suppressions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove suppression {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-suppressions-suppression-id}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/suppressions/{suppression_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `suppression_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Webhooks

> The 3 Organization API operations for webhooks.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail-webhooks/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/webhooks`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-webhooks) | List webhooks |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/webhooks`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-webhooks) | Create webhook |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/webhooks/{webhook_id}`](#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-webhooks-webhook-id) | Delete webhook |

### List webhooks {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-webhooks}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/webhooks`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create webhook {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-webhooks}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/webhooks`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `events` | array of string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete webhook {#op-delete-api-v1-orgs-org-slug-portal-mail-service-id-webhooks-webhook-id}

`DELETE /api/v1/orgs/{org_slug}/portal/mail/{service_id}/webhooks/{webhook_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `webhook_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Notices

> The 1 Organization API operations for notices.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/notices/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/notices`](#op-get-api-v1-orgs-org-slug-portal-notices) | Live notices for the signed-in customer, by whether they pay |

### Live notices for the signed-in customer, by whether they pay {#op-get-api-v1-orgs-org-slug-portal-notices}

`GET /api/v1/orgs/{org_slug}/portal/notices`

Live notices for the signed-in customer, by whether they pay.

#### 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. |

# Organization API: Customer Portal: Payment config

> The 1 Organization API operations for payment config.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/payment-config/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/payment-config`](#op-get-api-v1-orgs-org-slug-portal-payment-config) | Get portal payment config |

### Get portal payment config {#op-get-api-v1-orgs-org-slug-portal-payment-config}

`GET /api/v1/orgs/{org_slug}/portal/payment-config`

Return the gateway accounts that can tokenize a payment method for the given
pay currency, each merged with the adapter's non-secret client config
(Stripe publishable key / PayPal client id) needed to render embedded UIs.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `currency` | query | string | no |
| `country` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Payment methods

> The 5 Organization API operations for payment methods.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/payment-methods/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/payment-methods`](#op-get-api-v1-orgs-org-slug-portal-payment-methods) | List customer's saved payment methods |
| POST | [`/api/v1/orgs/{org_slug}/portal/payment-methods/confirm`](#op-post-api-v1-orgs-org-slug-portal-payment-methods-confirm) | Confirm payment method setup after customer approves on gateway side |
| POST | [`/api/v1/orgs/{org_slug}/portal/payment-methods/setup`](#op-post-api-v1-orgs-org-slug-portal-payment-methods-setup) | Initiate payment method tokenization on a regional gateway account |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/payment-methods/{method_id}`](#op-delete-api-v1-orgs-org-slug-portal-payment-methods-method-id) | Remove (deactivate) a saved payment method |
| PUT | [`/api/v1/orgs/{org_slug}/portal/payment-methods/{method_id}/default`](#op-put-api-v1-orgs-org-slug-portal-payment-methods-method-id-default) | Set a payment method as the default for this customer |

### List customer's saved payment methods {#op-get-api-v1-orgs-org-slug-portal-payment-methods}

`GET /api/v1/orgs/{org_slug}/portal/payment-methods`

List customer's saved payment methods.

#### 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. |

### Confirm payment method setup after customer approves on gateway side {#op-post-api-v1-orgs-org-slug-portal-payment-methods-confirm}

`POST /api/v1/orgs/{org_slug}/portal/payment-methods/confirm`

Confirm payment method setup after customer approves on gateway side.
Stores the tokenized method for future charges.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `gateway_name` | query | string | yes |  |
| `session_id` | query | string | yes |  |
| `set_as_default` | query | boolean | no | Default: `True`. |
| `currency` | query | string | no |  |

#### Request body

`application/json`

Type: Callback Data.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Initiate payment method tokenization on a regional gateway account {#op-post-api-v1-orgs-org-slug-portal-payment-methods-setup}

`POST /api/v1/orgs/{org_slug}/portal/payment-methods/setup`

Initiate payment method tokenization on a regional gateway account.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `return_url` | query | string | yes |
| `cancel_url` | query | string | yes |
| `gateway_name` | query | string | no |
| `currency` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove (deactivate) a saved payment method {#op-delete-api-v1-orgs-org-slug-portal-payment-methods-method-id}

`DELETE /api/v1/orgs/{org_slug}/portal/payment-methods/{method_id}`

Remove (deactivate) a saved payment method.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `method_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set a payment method as the default for this customer {#op-put-api-v1-orgs-org-slug-portal-payment-methods-method-id-default}

`PUT /api/v1/orgs/{org_slug}/portal/payment-methods/{method_id}/default`

Set a payment method as the default for this customer.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `method_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Payment preference

> The 2 Organization API operations for payment preference.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/payment-preference/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/payment-preference`](#op-get-api-v1-orgs-org-slug-portal-payment-preference) | Get portal payment preference |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/payment-preference`](#op-patch-api-v1-orgs-org-slug-portal-payment-preference) | Update account-wide preferred payment currency |

### Get portal payment preference {#op-get-api-v1-orgs-org-slug-portal-payment-preference}

`GET /api/v1/orgs/{org_slug}/portal/payment-preference`

#### 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. |

### Update account-wide preferred payment currency {#op-patch-api-v1-orgs-org-slug-portal-payment-preference}

`PATCH /api/v1/orgs/{org_slug}/portal/payment-preference`

Update account-wide preferred payment currency.

Accepts JSON body ``{ currency, country_code, auto_pay_enabled }`` (same as
the client API) or legacy query params. Manual updates mark the source as
``user`` so a later geo lookup leaves the choice alone.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `currency` | query | string or null | no |
| `country_code` | query | string or null | no |
| `auto_pay_enabled` | query | boolean or null | no |

#### Request body

`application/json`

Type: object or null.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Platform domains

> The 4 Organization API operations for platform domains.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/platform-domains/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/platform-domains`](#op-get-api-v1-orgs-org-slug-portal-platform-domains) | Overview |
| GET | [`/api/v1/orgs/{org_slug}/portal/platform-domains/availability`](#op-get-api-v1-orgs-org-slug-portal-platform-domains-availability) | Check availability |
| POST | [`/api/v1/orgs/{org_slug}/portal/platform-domains/claims`](#op-post-api-v1-orgs-org-slug-portal-platform-domains-claims) | Create claim |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/platform-domains/claims/{claim_id}`](#op-delete-api-v1-orgs-org-slug-portal-platform-domains-claims-claim-id) | Delete claim |

### Overview {#op-get-api-v1-orgs-org-slug-portal-platform-domains}

`GET /api/v1/orgs/{org_slug}/portal/platform-domains`

#### 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. |

### Check availability {#op-get-api-v1-orgs-org-slug-portal-platform-domains-availability}

`GET /api/v1/orgs/{org_slug}/portal/platform-domains/availability`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `label` | query | string | yes |
| `suffix` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create claim {#op-post-api-v1-orgs-org-slug-portal-platform-domains-claims}

`POST /api/v1/orgs/{org_slug}/portal/platform-domains/claims`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | yes |
| `suffix` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete claim {#op-delete-api-v1-orgs-org-slug-portal-platform-domains-claims-claim-id}

`DELETE /api/v1/orgs/{org_slug}/portal/platform-domains/claims/{claim_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `claim_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Profile

> The 1 Organization API operations for profile.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/profile/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/profile`](#op-patch-api-v1-orgs-org-slug-portal-profile) | Alias for PATCH /auth/me (account page compatibility) |

### Alias for PATCH /auth/me (account page compatibility) {#op-patch-api-v1-orgs-org-slug-portal-profile}

`PATCH /api/v1/orgs/{org_slug}/portal/profile`

Alias for PATCH /auth/me (account page compatibility).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `first_name` | string or null | no |
| `last_name` | string or null | no |
| `chat_handle` | string or null | no |
| `company` | string or null | no |
| `phone` | string or null | no |
| `password` | string or null | no |
| `current_password` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Refund requests

> The 2 Organization API operations for refund requests.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/refund-requests/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/refund-requests`](#op-get-api-v1-orgs-org-slug-portal-refund-requests) | List my refund requests |
| POST | [`/api/v1/orgs/{org_slug}/portal/refund-requests/{request_id}/withdraw`](#op-post-api-v1-orgs-org-slug-portal-refund-requests-request-id-withdraw) | Withdraw my refund request |

### List my refund requests {#op-get-api-v1-orgs-org-slug-portal-refund-requests}

`GET /api/v1/orgs/{org_slug}/portal/refund-requests`

#### 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. |

### Withdraw my refund request {#op-post-api-v1-orgs-org-slug-portal-refund-requests-request-id-withdraw}

`POST /api/v1/orgs/{org_slug}/portal/refund-requests/{request_id}/withdraw`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Servers

> The 19 Organization API operations for servers.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid) | Get server |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/command`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-command) | Command |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/keep`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-keep) | Tell us this world is still wanted, and lift a hold if one is on |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-listing) | Public-list visibility and tags for the Server Settings tab |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-listing) | Toggle public-list visibility and replace the listing tags |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/permissions`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-permissions) | List grantable permissions |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/power`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-power) | Power |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/reinstall`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-reinstall) | Wipe server files and re-run the template install script + verify |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/resources`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-resources) | Get resources |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/settings`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-settings) | Patch settings |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/sftp`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-sftp) | Connection details for this server's SFTP login |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/sleep`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-sleep) | Sleep and start-queue state for a free server |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/startup-variables`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-startup-variables) | Update allowlisted startup env vars for the server's game |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/status-ping`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-status-ping) | Ask the game itself who is online |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/subdomain`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-subdomain) | Rename the gameproxy join-address subdomain for this server |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/wake`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-wake) | Ask for a sleeping free server to be started |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/websocket`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-websocket) | Return panel WS URL + the caller's bearer token for WS query auth |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-world-optimization) | What unused-chunk cleanup has done to this world, and when |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-world-optimization) | Queue an unused-chunk trim now, once per minintervalhours |

### Get server {#op-get-api-v1-orgs-org-slug-portal-servers-uuid}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Command {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-command}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/command`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `command` | query | string or null | no |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `command` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Tell us this world is still wanted, and lift a hold if one is on {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-keep}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/keep`

Tell us this world is still wanted, and lift a hold if one is on.

One endpoint for both halves of the inactivity ladder: the nudge's "keep it"
link and the suspension's "reactivate". They differ only in whether the
server is currently suspended, and asking the customer to understand that
distinction would be asking them to understand our sweep.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Public-list visibility and tags for the Server Settings tab {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-listing}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing`

Public-list visibility and tags for the Server Settings tab.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Toggle public-list visibility and replace the listing tags {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-listing}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/listing`

Toggle public-list visibility and replace the listing tags.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hidden` | boolean or null | no |
| `tags` | array of string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List grantable permissions {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-permissions}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/permissions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Power {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-power}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/power`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `signal` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Wipe server files and re-run the template install script + verify {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-reinstall}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/reinstall`

Wipe server files and re-run the template install script + verify.

On a server that installed, this deletes every file, so it is confirmed
the way every other wipe is: ``confirm_server_name`` must name the server.
The storefront asks for it before the request; a request without it is
refused here so no client can wipe a server on a bare click.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `confirm_server_name` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get resources {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-resources}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/resources`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Patch settings {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-settings}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/settings`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `world_optimization_enabled` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Connection details for this server's SFTP login {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-sftp}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/sftp`

Connection details for this server's SFTP login.

The portal login email is the SFTP identity, and it need not match any
platform user, so the storefront cannot derive this from ``auth/me``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `host` | string |
| `port` | integer |
| `username` | string |

### Sleep and start-queue state for a free server {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-sleep}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/sleep`

Sleep and start-queue state for a free server.

``sleeps_at`` is absolute so a client can run the countdown locally instead of
polling for a ticking number. Returns ``policy: none`` for a paid server, so a
frontend can render one component for both.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `sleep` | Sleep |
| `entitlements` | array of object |

### Update allowlisted startup env vars for the server's game {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-startup-variables}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/startup-variables`

Update allowlisted startup env vars for the server's game.

Values live in ``container_server_variables`` and apply on the next restart
after Wings sync. Arbitrary keys and startup_command are not accepted.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `variables` | Variables | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Ask the game itself who is online {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-status-ping}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/status-ping`

Ask the game itself who is online. Best-effort; never fails the request.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `reachable` | boolean |
| `players_online` | integer or null |
| `players_max` | integer or null |
| `sample` | array of string |
| `version` | string or null |
| `protocol` | integer or null |
| `motd` | string or null |
| `favicon` | string or null |
| `latency_ms` | integer or null |

### Rename the gameproxy join-address subdomain for this server {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-subdomain}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/subdomain`

Rename the gameproxy join-address subdomain for this server.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `subdomain` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Ask for a sleeping free server to be started {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-wake}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/wake`

Ask for a sleeping free server to be started.

First in line with headroom starts in this request so the customer is not
left waiting on a worker poll. Otherwise the row stays queued and a tick
job releases it when the node has room. The response always carries the
queue block (including ``ahead: 0``) so a frontend can show the process.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `turnstile_token` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Return panel WS URL + the caller's bearer token for WS query auth {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-websocket}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/websocket`

Return panel WS URL + the caller's bearer token for WS query auth.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `token` | string |
| `socket` | string |

### What unused-chunk cleanup has done to this world, and when {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-world-optimization}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization`

What unused-chunk cleanup has done to this world, and when.

A feature that quietly deletes parts of somebody's world owes them the
receipts: how much it reclaimed, when it last ran, and which worlds it left
alone. It is also what turns an abstract switch into "this saved you 1.8 GB".

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Queue an unused-chunk trim now, once per minintervalhours {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-world-optimization}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/world-optimization`

Queue an unused-chunk trim now, once per ``min_interval_hours``.

Free and paid alike. Safety checks (offline, lease, node concurrency) stay
with the job; this endpoint only gates the once-per-day customer button and
that the feature is on for this server. Platform dry-run mode still applies.

Cooldown is based on ``last_run_at``, not a pre-reserve of ``next_eligible_at``,
so a queued job that exits before recording a run cannot lock the button.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Allocations

> The 8 Organization API operations for allocations.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-allocations/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-allocations) | List allocations |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-allocations) | Create allocation |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/available-ports`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-allocations-available-ports) | Available ports |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/request`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-allocations-request) | Get port request |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/request`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-allocations-request) | Ask staff for an extra port on a free server whose brand requires it |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/{allocation_id}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-allocations-allocation-id) | Delete allocation |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/{allocation_id}/primary`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-allocations-allocation-id-primary) | Make one of the server's ports the one players type |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/{allocation_id}/publish-port`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-allocations-allocation-id-publish) | Publish a port on the game's default port of the attached floating IP |

### List allocations {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-allocations}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations`

The server's ports, where they publish, the node-range limit, the rules
for ports on its dedicated IP (``dedicated_ip``, when one is attached) and
which default port its players type (``game``).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create allocation {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-allocations}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `port` | integer or null | no |
| `notes` | string or null | no |
| `on_dedicated_ip` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Available ports {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-allocations-available-ports}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/available-ports`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get port request {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-allocations-request}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/request`

Whether this server's extra ports go through a ticket, and the open
request if there is one, so the panel can say "requested" rather than
offer the form twice.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Ask staff for an extra port on a free server whose brand requires it {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-allocations-request}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/request`

Ask staff for an extra port on a free server whose brand requires it.

Opens one ticket tagged ``port-request`` against the order; a second
request while one is open is answered with the first. Refused with 403
when the brand does not require requests, because then the customer can
add the port themselves and the panel should not have offered this.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `note` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete allocation {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-allocations-allocation-id}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/{allocation_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Make one of the server's ports the one players type {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-allocations-allocation-id-primary}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/{allocation_id}/primary`

Make one of the server's ports the one players type.

On a dedicated IP this is how the default port is chosen: the row on 25565
(or 19132) becomes primary, Wings hands it to the process as ``SERVER_PORT``,
the brand hostname's route follows, and a running server restarts onto it.
The ``publish`` block says what happened.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Publish a port on the game's default port of the attached floating IP {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-allocations-allocation-id-publish}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/allocations/{allocation_id}/publish-port`

Publish a port on the game's default port of the attached floating IP.

The whole point of a dedicated address is that players type it and nothing
else, so this is what makes ``25565`` (or ``19132`` for Bedrock) answer on
the float. Wings rebinds and a running server restarts, exactly as on attach.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `port` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Backups

> The 6 Organization API operations for backups.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-backups/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-backups) | List backups |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-backups) | Create backup |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups/{backup_uuid}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-backups-backup-uuid) | Delete backup |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups/{backup_uuid}/download`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-backups-backup-uuid-download) | A short-lived signed URL the browser fetches the archive from directly |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups/{backup_uuid}/lock`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-backups-backup-uuid-lock) | Keep a backup, or release it |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups/{backup_uuid}/restore`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-backups-backup-uuid-restore) | Restore backup |

### List backups {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-backups}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create backup {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-backups}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `ignored_files` | array of string or null | no |
| `is_locked` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete backup {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-backups-backup-uuid}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups/{backup_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A short-lived signed URL the browser fetches the archive from directly {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-backups-backup-uuid-download}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups/{backup_uuid}/download`

A short-lived signed URL the browser fetches the archive from directly.

The permission has existed since subusers shipped; this is the route it
was waiting for. The archive streams from the node, never through here.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Keep a backup, or release it {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-backups-backup-uuid-lock}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups/{backup_uuid}/lock`

Keep a backup, or release it. A locked backup cannot be deleted.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Restore backup {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-backups-backup-uuid-restore}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/backups/{backup_uuid}/restore`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Custom domain

> The 5 Organization API operations for custom domain.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-custom-domain/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain) | Vanity CNAME state for this server's join address |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain) | Link a customer hostname |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain) | Show the vanity hostname, or the hosted one, in the public server list |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain) | Unlink custom domain |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain/verify`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain-verify) | Check the CNAME now rather than waiting for the next maintenance pass |

### Vanity CNAME state for this server's join address {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain`

Vanity CNAME state for this server's join address.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Link a customer hostname {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain`

Link a customer hostname. Saved as ``pending`` when its CNAME is not
visible yet; the maintenance job promotes it when the record appears.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `subdomain` | string | no |
| `include_in_list` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Show the vanity hostname, or the hosted one, in the public server list {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain`

Show the vanity hostname, or the hosted one, in the public server list.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `include_in_list` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Unlink custom domain {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Check the CNAME now rather than waiting for the next maintenance pass {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-custom-domain-verify}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/custom-domain/verify`

Check the CNAME now rather than waiting for the next maintenance pass.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Databases

> The 16 Organization API operations for databases.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-databases/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases) | List databases |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases) | Create database |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id) | Delete database |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/credentials`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-credentials) | Get database credentials |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/query`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-query) | Query database |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/retry`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-retry) | Retry database |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/rotate-password`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-rotate-passw) | Rotate database password |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables) | List database tables |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-tab) | Drop database table |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/columns`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table) | Describe database table |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/export.csv`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table) | Export database table |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/rows`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table) | Read database rows |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/rows`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table) | Insert database row |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/rows`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-tabl) | Update database row |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/rows/delete`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table) | Delete database row |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/truncate`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table) | Truncate database table |

### List databases {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create database {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

Type: object or null.

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete database {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get database credentials {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-credentials}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Query database {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-query}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/query`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `sql` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Retry database {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-retry}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/retry`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rotate database password {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-rotate-passw}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/rotate-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List database tables {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Drop database table {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-tab}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `table` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Describe database table {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/columns`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `table` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Export database table {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/export.csv`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `table` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Read database rows {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/rows`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `database_id` | path | integer | yes |  |
| `table` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |
| `search` | query | string | no |  |
| `sort` | query | string or null | no |  |
| `direction` | query | string | no | Default: `asc`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Insert database row {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/rows`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `table` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `values` | Values | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update database row {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-tabl}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/rows`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `table` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `key` | Key | yes |
| `values` | Values | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete database row {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/rows/delete`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `table` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `key` | Key | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Truncate database table {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-databases-database-id-tables-table}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/databases/{database_id}/tables/{table}/truncate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `table` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Files

> The 15 Organization API operations for files.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-files/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/chmod`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-chmod) | Chmod files |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/compress`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-compress) | Compress files |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/contents`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-files-contents) | File contents |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/copy`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-copy) | Copy file |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/decompress`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-decompress) | Decompress file |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/delete`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-delete) | Delete files |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/download`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-files-download) | Download file |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/list`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-files-list) | List files |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/mkdir`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-mkdir) | Mkdir |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/pull`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-pull) | Pull file |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/pull/cancel`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-pull-cancel) | Cancel pull |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/pull/status`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-files-pull-status) | Pull status |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/rename`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-rename) | Rename files |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/upload`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-upload) | Upload files |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/write`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-write) | Write file |

### Chmod files {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-chmod}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/chmod`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of object | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Compress files {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-compress}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/compress`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### File contents {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-files-contents}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/contents`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `path` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Copy file {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-copy}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/copy`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `location` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Decompress file {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-decompress}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/decompress`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `file` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete files {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-delete}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/delete`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Download file {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-files-download}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/download`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `path` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List files {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-files-list}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/list`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `directory` | query | string | no | Default: `/`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mkdir {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-mkdir}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/mkdir`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `name` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Pull file {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-pull}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/pull`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `destination_path` | string | yes |
| `filename` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Cancel pull {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-pull-cancel}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/pull/cancel`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `download_id` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Pull status {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-files-pull-status}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/pull/status`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rename files {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-rename}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/rename`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of object | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Upload files {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-upload}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/upload`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `directory` | query | string | no | Default: `/`. |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `files` | array of string (binary) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Write file {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-files-write}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/files/write`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `path` | string | yes |
| `content` | string | no |
| `expected_hash` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Import

> The 5 Organization API operations for import.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-import/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/current`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-import-current) | Current server import |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/start`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-import-start) | Start server import |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/status/{import_id}`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-import-status-import-id) | Polled while an import runs |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/test-connection`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-import-test-connection) | Test import connection |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/{import_id}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-import-import-id) | Cancel server import |

### Current server import {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-import-current}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/current`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Start server import {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-import-start}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/start`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `type` | string | yes |
| `remote_host` | string | yes |
| `remote_port` | integer or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `base_path` | string | no |
| `truncate` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Polled while an import runs {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-import-status-import-id}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/status/{import_id}`

Polled while an import runs. Replica first; a miss re-asks the primary.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `import_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Test import connection {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-import-test-connection}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/test-connection`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `type` | string | yes |
| `remote_host` | string | yes |
| `remote_port` | integer or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `base_path` | string | no |
| `truncate` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Cancel server import {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-import-import-id}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/import/{import_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `import_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Schedules

> The 11 Organization API operations for schedules.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-schedules/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-schedules) | List schedules |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-schedules) | Create schedule |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid) | Get schedule |
| PUT | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}`](#op-put-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid) | Update schedule |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid) | Delete schedule |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/execute`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-execute) | Queue a run now |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/runs`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-runs) | Recent runs of a schedule, newest first, with the outcome of every step |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/tasks`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-tasks) | Add schedule task |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/tasks/reorder`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-tasks-reor) | Reorder schedule tasks |
| PUT | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/tasks/{task_id}`](#op-put-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-tasks-task) | Update schedule task |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/tasks/{task_id}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-tasks-ta) | Delete schedule task |

### List schedules {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-schedules}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string |
| `[].server_id` | integer |
| `[].name` | string |
| `[].cron_minute` | string |
| `[].cron_hour` | string |
| `[].cron_day_of_month` | string |
| `[].cron_month` | string |
| `[].cron_day_of_week` | string |
| `[].is_active` | boolean |
| `[].only_when_online` | boolean |
| `[].is_processing` | boolean |
| `[].timezone` | string |
| `[].catch_up` | boolean |
| `[].revision` | integer |
| `[].current_run_id` | string or null |
| `[].last_run_status` | string or null |
| `[].next_run_at` | string (date-time) or null |
| `[].last_run_at` | string (date-time) or null |
| `[].last_run_failed` | boolean |
| `[].last_failure_message` | string or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) or null |
| `[].tasks` | array of TaskResponse |
| `[].tasks[].id` | integer |
| `[].tasks[].sequence_id` | integer |
| `[].tasks[].action` | string |
| `[].tasks[].payload` | Payload |
| `[].tasks[].time_offset` | integer |
| `[].tasks[].continue_on_failure` | boolean |
| `[].tasks[].is_queued` | boolean |

### Create schedule {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-schedules}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `cron_minute` | string | yes |
| `cron_hour` | string | yes |
| `cron_day_of_month` | string | yes |
| `cron_month` | string | yes |
| `cron_day_of_week` | string | yes |
| `is_active` | boolean | no |
| `only_when_online` | boolean | no |
| `timezone` | string | no |
| `catch_up` | boolean | no |
| `tasks` | array of TaskCreate or null | no |
| `tasks[].action` | string | yes |
| `tasks[].payload` | object or null | no |
| `tasks[].time_offset` | integer | no |
| `tasks[].sequence_id` | integer or null | no |
| `tasks[].continue_on_failure` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `cron_minute` | string |
| `cron_hour` | string |
| `cron_day_of_month` | string |
| `cron_month` | string |
| `cron_day_of_week` | string |
| `is_active` | boolean |
| `only_when_online` | boolean |
| `is_processing` | boolean |
| `timezone` | string |
| `catch_up` | boolean |
| `revision` | integer |
| `current_run_id` | string or null |
| `last_run_status` | string or null |
| `next_run_at` | string (date-time) or null |
| `last_run_at` | string (date-time) or null |
| `last_run_failed` | boolean |
| `last_failure_message` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `tasks` | array of TaskResponse |
| `tasks[].id` | integer |
| `tasks[].sequence_id` | integer |
| `tasks[].action` | string |
| `tasks[].payload` | Payload |
| `tasks[].time_offset` | integer |
| `tasks[].continue_on_failure` | boolean |
| `tasks[].is_queued` | boolean |

### Get schedule {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `cron_minute` | string |
| `cron_hour` | string |
| `cron_day_of_month` | string |
| `cron_month` | string |
| `cron_day_of_week` | string |
| `is_active` | boolean |
| `only_when_online` | boolean |
| `is_processing` | boolean |
| `timezone` | string |
| `catch_up` | boolean |
| `revision` | integer |
| `current_run_id` | string or null |
| `last_run_status` | string or null |
| `next_run_at` | string (date-time) or null |
| `last_run_at` | string (date-time) or null |
| `last_run_failed` | boolean |
| `last_failure_message` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `tasks` | array of TaskResponse |
| `tasks[].id` | integer |
| `tasks[].sequence_id` | integer |
| `tasks[].action` | string |
| `tasks[].payload` | Payload |
| `tasks[].time_offset` | integer |
| `tasks[].continue_on_failure` | boolean |
| `tasks[].is_queued` | boolean |

### Update schedule {#op-put-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid}

`PUT /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `cron_minute` | string or null | no |
| `cron_hour` | string or null | no |
| `cron_day_of_month` | string or null | no |
| `cron_month` | string or null | no |
| `cron_day_of_week` | string or null | no |
| `is_active` | boolean or null | no |
| `only_when_online` | boolean or null | no |
| `timezone` | string or null | no |
| `catch_up` | boolean or null | no |
| `revision` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `cron_minute` | string |
| `cron_hour` | string |
| `cron_day_of_month` | string |
| `cron_month` | string |
| `cron_day_of_week` | string |
| `is_active` | boolean |
| `only_when_online` | boolean |
| `is_processing` | boolean |
| `timezone` | string |
| `catch_up` | boolean |
| `revision` | integer |
| `current_run_id` | string or null |
| `last_run_status` | string or null |
| `next_run_at` | string (date-time) or null |
| `last_run_at` | string (date-time) or null |
| `last_run_failed` | boolean |
| `last_failure_message` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `tasks` | array of TaskResponse |
| `tasks[].id` | integer |
| `tasks[].sequence_id` | integer |
| `tasks[].action` | string |
| `tasks[].payload` | Payload |
| `tasks[].time_offset` | integer |
| `tasks[].continue_on_failure` | boolean |
| `tasks[].is_queued` | boolean |

### Delete schedule {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Queue a run now {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-execute}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/execute`

Queue a run now. The next scheduled run is left where it was.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `revision` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Recent runs of a schedule, newest first, with the outcome of every step {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-runs}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/runs`

Recent runs of a schedule, newest first, with the outcome of every step.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `schedule_uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].uuid` | string |
| `[].trigger` | string |
| `[].status` | string |
| `[].started_at` | string (date-time) or null |
| `[].finished_at` | string (date-time) or null |
| `[].failure_message` | string or null |
| `[].created_at` | string (date-time) or null |
| `[].steps` | array of ScheduleRunStepResponse |
| `[].steps[].task_id` | integer |
| `[].steps[].sequence_id` | integer |
| `[].steps[].action` | string |
| `[].steps[].payload` | Payload |
| `[].steps[].time_offset` | integer |
| `[].steps[].continue_on_failure` | boolean |
| `[].steps[].status` | string |
| `[].steps[].started_at` | string (date-time) or null |
| `[].steps[].finished_at` | string (date-time) or null |
| `[].steps[].error` | string or null |

### Add schedule task {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-tasks}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/tasks`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `action` | string | yes |
| `payload` | object or null | no |
| `time_offset` | integer | no |
| `sequence_id` | integer or null | no |
| `continue_on_failure` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `sequence_id` | integer |
| `action` | string |
| `payload` | Payload |
| `time_offset` | integer |
| `continue_on_failure` | boolean |
| `is_queued` | boolean |

### Reorder schedule tasks {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-tasks-reor}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/tasks/reorder`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `task_ids` | array of integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].sequence_id` | integer |
| `[].action` | string |
| `[].payload` | Payload |
| `[].time_offset` | integer |
| `[].continue_on_failure` | boolean |
| `[].is_queued` | boolean |

### Update schedule task {#op-put-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-tasks-task}

`PUT /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/tasks/{task_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `task_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `action` | string or null | no |
| `payload` | object or null | no |
| `time_offset` | integer or null | no |
| `sequence_id` | integer or null | no |
| `continue_on_failure` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `sequence_id` | integer |
| `action` | string |
| `payload` | Payload |
| `time_offset` | integer |
| `continue_on_failure` | boolean |
| `is_queued` | boolean |

### Delete schedule task {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-schedules-schedule-uuid-tasks-ta}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/schedules/{schedule_uuid}/tasks/{task_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `task_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Snapshots

> The 9 Organization API operations for snapshots.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-snapshots/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-snapshots) | List snapshots |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-snapshots) | Create snapshot |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/estimate`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-estimate) | How much of the allowance a snapshot of this server would use |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/seed`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-seed) | The restore a server ordered from a snapshot is waiting on, or got |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/seed/retry`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-seed-retry) | Run a failed seed again |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/{snapshot_uuid}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-snapshot-uuid) | Delete snapshot |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/{snapshot_uuid}/download`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-snapshot-uuid-download) | Download snapshot |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/{snapshot_uuid}/lock`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-snapshot-uuid-lock) | Keep a snapshot, or release it |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/{snapshot_uuid}/restore`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-snapshot-uuid-restore) | Restore onto this server, from any snapshot this customer owns |

### List snapshots {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-snapshots}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots`

Snapshots taken from this server or, with ``scope=account``, every
snapshot the account holds, each judged for restoring onto *this* server.

The account list is the owner's, since those are the only snapshots a
restore here would accept; a shared-server viewer asking for it gets this
server's own list, the same as the platform client surface.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `scope` | query | string | no | Default: `this`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create snapshot {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-snapshots}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `ignored_files` | array of string or null | no |
| `is_locked` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### How much of the allowance a snapshot of this server would use {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-estimate}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/estimate`

How much of the allowance a snapshot of this server would use.

Its own endpoint rather than a field on the listing, because the figure is
read live from Wings: folding it into the list would make the snapshots tab
as slow as the slowest node on the fleet, on every load, to answer a
question only the create dialog asks.

Deliberately an over-estimate. It is the server's current *uncompressed*
disk usage, and an archive is never larger than what it archives, so a
creation that fits on this number cannot push the account over. The
retention policy depends on that. What the customer sees is therefore a
ceiling, and the dialog says so.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The restore a server ordered from a snapshot is waiting on, or got {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-seed}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/seed`

The restore a server ordered from a snapshot is waiting on, or got.

Null for a server ordered the ordinary way, which is nearly all of them.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Run a failed seed again {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-seed-retry}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/seed/retry`

Run a failed seed again. A failed restore leaves the snapshot unharmed.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete snapshot {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-snapshot-uuid}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/{snapshot_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Download snapshot {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-snapshot-uuid-download}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/{snapshot_uuid}/download`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Keep a snapshot, or release it {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-snapshot-uuid-lock}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/{snapshot_uuid}/lock`

Keep a snapshot, or release it. A locked snapshot is not rotated away.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Restore onto this server, from any snapshot this customer owns {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-snapshots-snapshot-uuid-restore}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/snapshots/{snapshot_uuid}/restore`

Restore onto this server, from any snapshot this customer owns.

Addressed by the target server because that is what is being overwritten,
and what the permission is checked against.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `target_server_uuid` | string or null | no |
| `truncate` | boolean | no |
| `allow_mismatch` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Software

> The 35 Organization API operations for software.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-software/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software) | List installed software |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/addons`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-addons) | Every addon in the folders the server loads from, tracked or hand-uploaded |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/addons/records/{record_uuid}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-software-addons-records-record-u) | Drop a tracking record whose files are gone, without touching the disk |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/addons/remove`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-addons-remove) | Delete one addon from disk, through the tracked uninstall when it has a record |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/addons/toggle`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-addons-toggle) | Switch one addon file on or off (Foo.jar <- Foo.jar.disabled) |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock) | Turn Bedrock crossplay on or off for a Java server |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs) | Behavior and resource packs on disk, which are active in the world, and importable uploads |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs/disable-all`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs-disable-all) | Empty the world's activation lists so it boots on vanilla content; folders stay |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs/import`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs-import) | Queue an import of an uploaded .mcaddon / .mcpack / .zip already on the server |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs/{pack_uuid}/active`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs-pack-uuid-a) | Add a pack to, or drop it from, the world's activation list |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs/{pack_uuid}/remove`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs-pack-uuid-r) | Deactivate a pack, delete its folder, and drop its tracking row |
| PUT | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/texturepack-required`](#op-put-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-texturepack-requir) | Texturepack-required: players must accept the resource packs to join |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/catalog`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-catalog) | Software catalog |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/catalog/{key}/versions`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-catalog-key-versions) | Software catalog versions |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/catalog/{key}/versions/{version}/builds`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-catalog-key-versions-versi) | Publisher builds of one game version: the loader versions for Fabric/Forge |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/change`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-change) | Change server software |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/context`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-context) | Software context |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/dependencies/{source_uuid}/{identifier}`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-dependencies-source-uuid-i) | What a version requires, named, with what is already installed marked |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/install`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-install) | Install software |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/installs`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-installs) | List software installs |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/installs/{install_uuid}`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-installs-install-uuid) | Get software install |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/installs/{install_uuid}/cancel`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-installs-install-uuid-can) | Cancel software install |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/installs/{install_uuid}/retry`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-installs-install-uuid-ret) | Retry software install |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/jvm`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-jvm) | The heap slider and the allowlisted startup flags, as the panel shows them |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/jvm`](#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-software-jvm) | Move the heap, pick startup flags from the catalog, or reset both |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/resource-pack`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-resource-pack) | The server resource pack as server.properties declares it |
| PUT | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/resource-pack`](#op-put-api-v1-orgs-org-slug-portal-servers-uuid-software-resource-pack) | Point players at a pack, from a URL or a marketplace resource pack version |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/resource-pack`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-software-resource-pack) | Stop offering a server resource pack |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/safe-mode`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-safe-mode) | Arm a one-shot --safeMode start (vanilla datapack only), optionally starting now |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/search`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-search) | Search software |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/sources`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-sources) | Software sources |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/updates`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-updates) | Newer compatible builds for the addons the marketplace installed |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/versions/{source_uuid}/{identifier}`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-versions-source-uuid-ident) | Software versions |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/{record_uuid}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-software-record-uuid) | Uninstall software |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/{record_uuid}/update`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-record-uuid-update) | Queue an in-place update: the old file is removed, the new build installed |

### List installed software {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every addon in the folders the server loads from, tracked or hand-uploaded {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-addons}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/addons`

Every addon in the folders the server loads from, tracked or hand-uploaded.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `kind` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Drop a tracking record whose files are gone, without touching the disk {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-software-addons-records-record-u}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/addons/records/{record_uuid}`

Drop a tracking record whose files are gone, without touching the disk.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `record_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete one addon from disk, through the tracked uninstall when it has a record {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-addons-remove}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/addons/remove`

Delete one addon from disk, through the tracked uninstall when it has a record.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Switch one addon file on or off (Foo.jar <- Foo.jar.disabled) {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-addons-toggle}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/addons/toggle`

Switch one addon file on or off (``Foo.jar`` <-> ``Foo.jar.disabled``).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Turn Bedrock crossplay on or off for a Java server {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock`

Turn Bedrock crossplay on or off for a Java server.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Behavior and resource packs on disk, which are active in the world, and importable uploads {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs`

Behavior and resource packs on disk, which are active in the world, and importable uploads.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Empty the world's activation lists so it boots on vanilla content; folders stay {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs-disable-all}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs/disable-all`

Empty the world's activation lists so it boots on vanilla content; folders stay.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Queue an import of an uploaded .mcaddon / .mcpack / .zip already on the server {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs-import}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs/import`

Queue an import of an uploaded ``.mcaddon`` / ``.mcpack`` / ``.zip`` already on the server.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Add a pack to, or drop it from, the world's activation list {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs-pack-uuid-a}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs/{pack_uuid}/active`

Add a pack to, or drop it from, the world's activation list.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `pack_uuid` | path | string | 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. |

### Deactivate a pack, delete its folder, and drop its tracking row {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-packs-pack-uuid-r}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/packs/{pack_uuid}/remove`

Deactivate a pack, delete its folder, and drop its tracking row.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `pack_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Texturepack-required: players must accept the resource packs to join {#op-put-api-v1-orgs-org-slug-portal-servers-uuid-software-bedrock-texturepack-requir}

`PUT /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/bedrock/texturepack-required`

``texturepack-required``: players must accept the resource packs to join.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Software catalog {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-catalog}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/catalog`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Software catalog versions {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-catalog-key-versions}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/catalog/{key}/versions`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `key` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `200`. |
| `include_unsupported` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Publisher builds of one game version: the loader versions for Fabric/Forge {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-catalog-key-versions-versi}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/catalog/{key}/versions/{version}/builds`

Publisher builds of one game version: the loader versions for Fabric/Forge.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `key` | path | string | yes |
| `version` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Change server software {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-change}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/change`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Software context {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-context}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/context`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### What a version requires, named, with what is already installed marked {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-dependencies-source-uuid-i}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/dependencies/{source_uuid}/{identifier}`

What a version requires, named, with what is already installed marked.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `source_uuid` | path | string | yes |  |
| `identifier` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `version` | query | string | no | Default: `latest`. |
| `kind` | query | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Install software {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-install}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/install`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

Type: SoftwareInstallBody or object.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List software installs {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-installs}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/installs`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `status` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get software install {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-installs-install-uuid}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/installs/{install_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `install_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Cancel software install {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-installs-install-uuid-can}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/installs/{install_uuid}/cancel`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `install_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Retry software install {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-installs-install-uuid-ret}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/installs/{install_uuid}/retry`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `install_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The heap slider and the allowlisted startup flags, as the panel shows them {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-jvm}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/jvm`

The heap slider and the allowlisted startup flags, as the panel shows them.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Move the heap, pick startup flags from the catalog, or reset both {#op-patch-api-v1-orgs-org-slug-portal-servers-uuid-software-jvm}

`PATCH /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/jvm`

Move the heap, pick startup flags from the catalog, or reset both. Applies on restart.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### The server resource pack as server.properties declares it {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-resource-pack}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/resource-pack`

The server resource pack as ``server.properties`` declares it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Point players at a pack, from a URL or a marketplace resource pack version {#op-put-api-v1-orgs-org-slug-portal-servers-uuid-software-resource-pack}

`PUT /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/resource-pack`

Point players at a pack, from a URL or a marketplace resource pack version.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Stop offering a server resource pack {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-software-resource-pack}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/resource-pack`

Stop offering a server resource pack.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Arm a one-shot --safeMode start (vanilla datapack only), optionally starting now {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-safe-mode}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/safe-mode`

Arm a one-shot ``--safeMode`` start (vanilla datapack only), optionally starting now.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Search software {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-search}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/search`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `query` | string | no |
| `source` | string or null | no |
| `source_uuid` | string or null | no |
| `page` | integer | no |
| `limit` | integer | no |
| `kind` | string or null | no |
| `sort` | string or null | no |
| `loaders` | array of string or null | no |
| `game_versions` | array of string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Software sources {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-sources}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/sources`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `kind` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Newer compatible builds for the addons the marketplace installed {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-updates}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/updates`

Newer compatible builds for the addons the marketplace installed.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `kind` | query | string or null | no |  |
| `include_current` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Software versions {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-software-versions-source-uuid-ident}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/versions/{source_uuid}/{identifier}`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `source_uuid` | path | string | yes |  |
| `identifier` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `page` | query | integer | no | Default: `1`. |
| `limit` | query | integer | no | Default: `50`. |
| `loaders` | query | string or null | no |  |
| `game_versions` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `include_incompatible` | query | boolean | no | List builds for other loaders / game versions too, flagged Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Uninstall software {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-software-record-uuid}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/{record_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `record_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Queue an in-place update: the old file is removed, the new build installed {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-software-record-uuid-update}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/software/{record_uuid}/update`

Queue an in-place update: the old file is removed, the new build installed.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `record_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

Type: object or null.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Users

> The 5 Organization API operations for users.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/servers-users/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/users`](#op-get-api-v1-orgs-org-slug-portal-servers-uuid-users) | List org subusers |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/users`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-users) | Add org subuser |
| POST | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/users/leave`](#op-post-api-v1-orgs-org-slug-portal-servers-uuid-users-leave) | A subuser drops their own grant |
| PUT | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/users/{subuser_id}`](#op-put-api-v1-orgs-org-slug-portal-servers-uuid-users-subuser-id) | Update org subuser |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/servers/{uuid}/users/{subuser_id}`](#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-users-subuser-id) | Delete org subuser |

### List org subusers {#op-get-api-v1-orgs-org-slug-portal-servers-uuid-users}

`GET /api/v1/orgs/{org_slug}/portal/servers/{uuid}/users`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add org subuser {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-users}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/users`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `permissions` | array of string | yes |
| `username_or_email` | string or null | no |
| `username` | string or null | no |
| `email` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A subuser drops their own grant {#op-post-api-v1-orgs-org-slug-portal-servers-uuid-users-leave}

`POST /api/v1/orgs/{org_slug}/portal/servers/{uuid}/users/leave`

A subuser drops their own grant. Owners cannot leave their own server.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update org subuser {#op-put-api-v1-orgs-org-slug-portal-servers-uuid-users-subuser-id}

`PUT /api/v1/orgs/{org_slug}/portal/servers/{uuid}/users/{subuser_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `subuser_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `permissions` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete org subuser {#op-delete-api-v1-orgs-org-slug-portal-servers-uuid-users-subuser-id}

`DELETE /api/v1/orgs/{org_slug}/portal/servers/{uuid}/users/{subuser_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `subuser_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Services

> The 12 Organization API operations for services.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/services/

Part of [Customer Portal](/docs/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. |

# Organization API: Customer Portal: Shield

> The 6 Organization API operations for shield.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/shield/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/shield/events`](#op-get-api-v1-orgs-org-slug-portal-shield-events) | Shield events list |
| GET | [`/api/v1/orgs/{org_slug}/portal/shield/status`](#op-get-api-v1-orgs-org-slug-portal-shield-status) | Shield status |
| GET | [`/api/v1/orgs/{org_slug}/portal/shield/subjects/{ip_service_id}/profile`](#op-get-api-v1-orgs-org-slug-portal-shield-subjects-ip-service-id-profile) | Get subject profile |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/shield/subjects/{ip_service_id}/profile`](#op-patch-api-v1-orgs-org-slug-portal-shield-subjects-ip-service-id-profile) | Promote subject to a customer-editable custom profile (idempotent) |
| POST | [`/api/v1/orgs/{org_slug}/portal/shield/subjects/{ip_service_id}/rules`](#op-post-api-v1-orgs-org-slug-portal-shield-subjects-ip-service-id-rules) | Create subject rule |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/shield/subjects/{ip_service_id}/rules/{rule_id}`](#op-delete-api-v1-orgs-org-slug-portal-shield-subjects-ip-service-id-rules-rule-id) | Delete subject rule |

### Shield events list {#op-get-api-v1-orgs-org-slug-portal-shield-events}

`GET /api/v1/orgs/{org_slug}/portal/shield/events`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `ip_service_id` | query | integer or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Shield status {#op-get-api-v1-orgs-org-slug-portal-shield-status}

`GET /api/v1/orgs/{org_slug}/portal/shield/status`

#### 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. |

### Get subject profile {#op-get-api-v1-orgs-org-slug-portal-shield-subjects-ip-service-id-profile}

`GET /api/v1/orgs/{org_slug}/portal/shield/subjects/{ip_service_id}/profile`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_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. |

### Promote subject to a customer-editable custom profile (idempotent) {#op-patch-api-v1-orgs-org-slug-portal-shield-subjects-ip-service-id-profile}

`PATCH /api/v1/orgs/{org_slug}/portal/shield/subjects/{ip_service_id}/profile`

Promote subject to a customer-editable custom profile (idempotent).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_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. |

### Create subject rule {#op-post-api-v1-orgs-org-slug-portal-shield-subjects-ip-service-id-rules}

`POST /api/v1/orgs/{org_slug}/portal/shield/subjects/{ip_service_id}/rules`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | no |
| `enabled` | boolean | no |
| `action` | string | no |
| `protocol` | integer or null | no |
| `src_prefix` | string or null | no |
| `dst_prefix` | string or null | no |
| `src_port_min` | integer or null | no |
| `src_port_max` | integer or null | no |
| `dst_port_min` | integer or null | no |
| `dst_port_max` | integer or null | no |
| `tcp_flags_mask` | integer or null | no |
| `tcp_flags_value` | integer or null | no |
| `packet_len_min` | integer or null | no |
| `packet_len_max` | integer or null | no |
| `ttl_min` | integer or null | no |
| `ttl_max` | integer or null | no |
| `icmp_type` | integer or null | no |
| `icmp_code` | integer or null | no |
| `rate_limit_pps` | integer or null | no |
| `notes` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete subject rule {#op-delete-api-v1-orgs-org-slug-portal-shield-subjects-ip-service-id-rules-rule-id}

`DELETE /api/v1/orgs/{org_slug}/portal/shield/subjects/{ip_service_id}/rules/{rule_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `ip_service_id` | path | integer | yes |
| `rule_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Smtp relay

> The 8 Organization API operations for smtp relay.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/smtp-relay/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/services`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-services) | List services |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id) | Get summary |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/category`](#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-category) | Set category |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/events`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-events) | List events |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/limits/increase-request`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-limits-increase-request) | Request limit increase |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/messages`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-messages) | Send message |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/reputation`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-reputation) | Reputation report |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/usage`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-usage) | Usage report |

### List services {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-services}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/services`

#### 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. |

### Get summary {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set category {#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-category}

`PATCH /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/category`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `default_category` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List events {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-events}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/events`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `service_id` | path | integer | yes |  |
| `category` | query | string or null | no |  |
| `recipient` | query | string or null | no |  |
| `hours` | query | integer | no | Default: `24`. |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Request limit increase {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-limits-increase-request}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/limits/increase-request`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requested_per_hour` | integer | yes |  |
| `reason` | string | no | What the relay sends and why the volume is going up |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send message {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-messages}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/messages`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from` | string | yes |
| `from_name` | string or null | no |
| `to` | array of string | yes |
| `cc` | array of string | no |
| `subject` | string | no |
| `text` | string or null | no |
| `html` | string or null | no |
| `reply_to` | string or null | no |
| `headers` | Headers | no |
| `category` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Reputation report {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-reputation}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/reputation`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `service_id` | path | integer | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Usage report {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-usage}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/usage`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `service_id` | path | integer | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Aliases

> The 3 Organization API operations for aliases.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/smtp-relay-aliases/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/aliases`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-aliases) | List aliases |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/aliases`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-aliases) | Create alias |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/aliases/{account_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-aliases-account-id) | Delete alias |

### List aliases {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-aliases}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/aliases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create alias {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-aliases}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/aliases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `targets` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete alias {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-aliases-account-id}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/aliases/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Api keys

> The 3 Organization API operations for api keys.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/smtp-relay-api-keys/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/api-keys`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-api-keys) | List API keys |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/api-keys`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-api-keys) | Create API key |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/api-keys/{key_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-api-keys-key-id) | Revoke API key |

### List API keys {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-api-keys}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/api-keys`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create API key {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-api-keys}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/api-keys`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Revoke API key {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-api-keys-key-id}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/api-keys/{key_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `key_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Credentials

> The 5 Organization API operations for credentials.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/smtp-relay-credentials/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials) | List credentials |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials) | Create credential |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials/{account_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials-account-id) | Delete credential |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials/{account_id}/enabled`](#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials-account-id-e) | Credential enabled |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials/{account_id}/rotate`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials-account-id-ro) | Rotate credential |

### List credentials {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create credential {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `label` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete credential {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials-account-id}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Credential enabled {#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials-account-id-e}

`PATCH /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials/{account_id}/enabled`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rotate credential {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-credentials-account-id-ro}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/credentials/{account_id}/rotate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Domains

> The 6 Organization API operations for domains.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/smtp-relay-domains/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains) | List domains |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains) | Add domain |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains/{domain_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains-domain-id) | Remove domain |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains/{domain_id}/dmarc`](#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains-domain-id-dmarc) | Set DMARC |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains/{domain_id}/records`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains-domain-id-records) | Domain records |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains/{domain_id}/verify`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains-domain-id-verify) | Verify domain |

### List domains {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add domain {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `primary` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove domain {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains-domain-id}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains/{domain_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set DMARC {#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains-domain-id-dmarc}

`PATCH /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains/{domain_id}/dmarc`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `stage` | string or null | no |
| `pinned` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Domain records {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains-domain-id-records}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains/{domain_id}/records`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Verify domain {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-domains-domain-id-verify}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/domains/{domain_id}/verify`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Mailboxes

> The 19 Organization API operations for mailboxes.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/smtp-relay-mailboxes/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes) | List mailboxes |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes) | Create mailbox |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id) | Delete mailbox |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-app-p) | Mailbox app passwords |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-app) | Mailbox app password create |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-ap) | Mailbox app password delete |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/enabled`](#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-ena) | Mailbox enabled |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impor) | Mailbox imports |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impo) | Mailbox import start |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports/oauth`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impo) | Mailbox import sign in |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports/upload`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impo) | Mailbox import upload |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports/{import_id}/{action}`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impo) | Mailbox import steer |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/password`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-pass) | Mailbox password |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/quota`](#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-quo) | Mailbox quota |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/sessions`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-sessi) | Mailbox sessions |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/sessions`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-se) | Mailbox sessions end |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/sessions/{session_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-se) | Mailbox session end |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/totp`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-totp) | Mailbox totp enable |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/totp`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-to) | Mailbox totp disable |

### List mailboxes {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create mailbox {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `password` | string or null | no |
| `display_name` | string or null | no |
| `quota_bytes` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete mailbox {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app passwords {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-app-p}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app password create {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-app}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app password delete {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-ap}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/app-passwords/{credential_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `credential_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox enabled {#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-ena}

`PATCH /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/enabled`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox imports {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impor}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import start {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impo}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `preset` | string | no |
| `host` | string or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `folders` | array of string | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import sign in {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impo}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports/oauth`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `provider` | string, one of `google`, `microsoft` | yes |
| `return_path` | string or null | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import upload {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impo}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports/upload`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |
| `kind` | string | no |
| `folder` | string | no |
| `cpanel_mailbox` | string | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import steer {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-impo}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/imports/{import_id}/{action}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `import_id` | path | integer | yes |
| `action` | path | string, one of `pause`, `resume`, `cancel` | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox password {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-pass}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox quota {#op-patch-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-quo}

`PATCH /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/quota`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `quota_bytes` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox sessions {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-sessi}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox sessions end {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-se}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox session end {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-se}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/sessions/{session_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `session_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox totp enable {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-totp}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/totp`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox totp disable {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-mailboxes-account-id-to}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/mailboxes/{account_id}/totp`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Suppressions

> The 3 Organization API operations for suppressions.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/smtp-relay-suppressions/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/suppressions`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-suppressions) | List suppressions |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/suppressions`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-suppressions) | Add suppression |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/suppressions/{suppression_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-suppressions-suppressio) | Remove suppression |

### List suppressions {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-suppressions}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/suppressions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add suppression {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-suppressions}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/suppressions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove suppression {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-suppressions-suppressio}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/suppressions/{suppression_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `suppression_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Webhooks

> The 3 Organization API operations for webhooks.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/smtp-relay-webhooks/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/webhooks`](#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-webhooks) | List webhooks |
| POST | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/webhooks`](#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-webhooks) | Create webhook |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/webhooks/{webhook_id}`](#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-webhooks-webhook-id) | Delete webhook |

### List webhooks {#op-get-api-v1-orgs-org-slug-portal-smtp-relay-service-id-webhooks}

`GET /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/webhooks`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create webhook {#op-post-api-v1-orgs-org-slug-portal-smtp-relay-service-id-webhooks}

`POST /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/webhooks`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `events` | array of string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete webhook {#op-delete-api-v1-orgs-org-slug-portal-smtp-relay-service-id-webhooks-webhook-id}

`DELETE /api/v1/orgs/{org_slug}/portal/smtp-relay/{service_id}/webhooks/{webhook_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `webhook_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Snapshots

> The 7 Organization API operations for snapshots.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/snapshots/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/snapshots`](#op-get-api-v1-orgs-org-slug-portal-snapshots) | Every snapshot this customer holds, across every server they have had |
| GET | [`/api/v1/orgs/{org_slug}/portal/snapshots/allowance`](#op-get-api-v1-orgs-org-slug-portal-snapshots-allowance) | Snapshot allowance |
| GET | [`/api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}`](#op-get-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid) | One snapshot, for the order form that was handed its uuid in a link |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}`](#op-delete-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid) | Delete a snapshot the account owns, with or without its source server |
| GET | [`/api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}/download`](#op-get-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid-download) | A signed URL for an archive whose server may no longer exist |
| POST | [`/api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}/lock`](#op-post-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid-lock) | Keep or release a snapshot the account owns, with or without its server |
| POST | [`/api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}/restore`](#op-post-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid-restore) | Restore an account snapshot onto one of the customer's servers |

### Every snapshot this customer holds, across every server they have had {#op-get-api-v1-orgs-org-slug-portal-snapshots}

`GET /api/v1/orgs/{org_slug}/portal/snapshots`

Every snapshot this customer holds, across every server they have had.

Scoped by the customer rather than by a server, so a customer whose service
was terminated can still see what they can restore. This uses the
customer's own tuple instead of deriving one from a server, because there
may be no server left to derive it from, and that is the case that matters.

#### 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. |

### Snapshot allowance {#op-get-api-v1-orgs-org-slug-portal-snapshots-allowance}

`GET /api/v1/orgs/{org_slug}/portal/snapshots/allowance`

#### 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. |

### One snapshot, for the order form that was handed its uuid in a link {#op-get-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid}

`GET /api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}`

One snapshot, for the order form that was handed its uuid in a link.

Registered after ``/snapshots/allowance`` on purpose: FastAPI matches in
declaration order, and a path parameter here would otherwise swallow it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete a snapshot the account owns, with or without its source server {#op-delete-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid}

`DELETE /api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}`

Delete a snapshot the account owns, with or without its source server.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A signed URL for an archive whose server may no longer exist {#op-get-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid-download}

`GET /api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}/download`

A signed URL for an archive whose server may no longer exist.

The free-tier download gate reads the *source server's* plan, and a
snapshot whose server is gone has none to read, so it is treated as
paid. Refusing instead would strand the archives that matter most, and a
customer with no server is not using a free tier.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Keep or release a snapshot the account owns, with or without its server {#op-post-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid-lock}

`POST /api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}/lock`

Keep or release a snapshot the account owns, with or without its server.

The platform client had this and the portal did not, so a customer whose
server was deleted could see the snapshot the sweep was about to rotate
away and had no way to keep it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Restore an account snapshot onto one of the customer's servers {#op-post-api-v1-orgs-org-slug-portal-snapshots-snapshot-uuid-restore}

`POST /api/v1/orgs/{org_slug}/portal/snapshots/{snapshot_uuid}/restore`

Restore an account snapshot onto one of the customer's servers.

The target is required rather than defaulted. On this path there is no
server in the URL to fall back to, and guessing which server to overwrite
is the one mistake here that destroys data.

The permission is still checked against the target server, because that is
the one being overwritten and the one a subuser was or was not trusted with.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `target_server_uuid` | string or null | no |
| `truncate` | boolean | no |
| `allow_mismatch` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Transactions

> The 1 Organization API operations for transactions.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/transactions/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/transactions`](#op-get-api-v1-orgs-org-slug-portal-transactions) | List my transactions |

### List my transactions {#op-get-api-v1-orgs-org-slug-portal-transactions}

`GET /api/v1/orgs/{org_slug}/portal/transactions`

As ``list_my_invoices``: newest first, ties by id, ``with_total`` for
the page with its total and per-type counts.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `type_filter` | query | string | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |
| `with_total` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Vps

> The 10 Organization API operations for vps.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/vps/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid) | Get instance |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/bandwidth`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-bandwidth) | Get bandwidth |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/console`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-console) | Console info |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/credentials`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-credentials) | Credentials |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/graphs`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-graphs) | Get graphs |
| PATCH | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/hostname`](#op-patch-api-v1-orgs-org-slug-portal-vps-uuid-hostname) | Patch hostname |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/ips`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-ips) | List IPs |
| POST | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/power`](#op-post-api-v1-orgs-org-slug-portal-vps-uuid-power) | Power |
| POST | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/reset-password`](#op-post-api-v1-orgs-org-slug-portal-vps-uuid-reset-password) | Reset password |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/status`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-status) | Get status |

### Get instance {#op-get-api-v1-orgs-org-slug-portal-vps-uuid}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get bandwidth {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-bandwidth}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/bandwidth`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Console info {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-console}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/console`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Credentials {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-credentials}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get graphs {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-graphs}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/graphs`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `timeframe` | query | string | no | Default: `hour`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Patch hostname {#op-patch-api-v1-orgs-org-slug-portal-vps-uuid-hostname}

`PATCH /api/v1/orgs/{org_slug}/portal/vps/{uuid}/hostname`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |
| `reboot` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List IPs {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-ips}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/ips`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Power {#op-post-api-v1-orgs-org-slug-portal-vps-uuid-power}

`POST /api/v1/orgs/{org_slug}/portal/vps/{uuid}/power`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `action` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Reset password {#op-post-api-v1-orgs-org-slug-portal-vps-uuid-reset-password}

`POST /api/v1/orgs/{org_slug}/portal/vps/{uuid}/reset-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get status {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-status}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/status`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Backups

> The 4 Organization API operations for backups.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/vps-backups/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/backups`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-backups) | List backups |
| POST | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/backups`](#op-post-api-v1-orgs-org-slug-portal-vps-uuid-backups) | Create backup |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/backups/{backup_id}`](#op-delete-api-v1-orgs-org-slug-portal-vps-uuid-backups-backup-id) | Delete backup |
| POST | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/backups/{backup_id}/restore`](#op-post-api-v1-orgs-org-slug-portal-vps-uuid-backups-backup-id-restore) | Restore backup |

### List backups {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-backups}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/backups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create backup {#op-post-api-v1-orgs-org-slug-portal-vps-uuid-backups}

`POST /api/v1/orgs/{org_slug}/portal/vps/{uuid}/backups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete backup {#op-delete-api-v1-orgs-org-slug-portal-vps-uuid-backups-backup-id}

`DELETE /api/v1/orgs/{org_slug}/portal/vps/{uuid}/backups/{backup_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Restore backup {#op-post-api-v1-orgs-org-slug-portal-vps-uuid-backups-backup-id-restore}

`POST /api/v1/orgs/{org_slug}/portal/vps/{uuid}/backups/{backup_id}/restore`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Rescue

> The 3 Organization API operations for rescue.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/vps-rescue/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/rescue/enter`](#op-post-api-v1-orgs-org-slug-portal-vps-uuid-rescue-enter) | Rescue enter |
| POST | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/rescue/exit`](#op-post-api-v1-orgs-org-slug-portal-vps-uuid-rescue-exit) | Rescue exit |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/rescue/media`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-rescue-media) | Rescue media |

### Rescue enter {#op-post-api-v1-orgs-org-slug-portal-vps-uuid-rescue-enter}

`POST /api/v1/orgs/{org_slug}/portal/vps/{uuid}/rescue/enter`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `iso_volid` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rescue exit {#op-post-api-v1-orgs-org-slug-portal-vps-uuid-rescue-exit}

`POST /api/v1/orgs/{org_slug}/portal/vps/{uuid}/rescue/exit`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rescue media {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-rescue-media}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/rescue/media`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Customer Portal: Snapshots

> The 4 Organization API operations for snapshots.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/vps-snapshots/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/snapshots`](#op-get-api-v1-orgs-org-slug-portal-vps-uuid-snapshots) | List snapshots |
| POST | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/snapshots`](#op-post-api-v1-orgs-org-slug-portal-vps-uuid-snapshots) | Create snapshot |
| DELETE | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/snapshots/{snapshot_id}`](#op-delete-api-v1-orgs-org-slug-portal-vps-uuid-snapshots-snapshot-id) | Delete snapshot |
| POST | [`/api/v1/orgs/{org_slug}/portal/vps/{uuid}/snapshots/{snapshot_id}/rollback`](#op-post-api-v1-orgs-org-slug-portal-vps-uuid-snapshots-snapshot-id-rollback) | Rollback snapshot |

### List snapshots {#op-get-api-v1-orgs-org-slug-portal-vps-uuid-snapshots}

`GET /api/v1/orgs/{org_slug}/portal/vps/{uuid}/snapshots`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create snapshot {#op-post-api-v1-orgs-org-slug-portal-vps-uuid-snapshots}

`POST /api/v1/orgs/{org_slug}/portal/vps/{uuid}/snapshots`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | no |
| `description` | string or null | no |
| `vmstate` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete snapshot {#op-delete-api-v1-orgs-org-slug-portal-vps-uuid-snapshots-snapshot-id}

`DELETE /api/v1/orgs/{org_slug}/portal/vps/{uuid}/snapshots/{snapshot_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rollback snapshot {#op-post-api-v1-orgs-org-slug-portal-vps-uuid-snapshots-snapshot-id-rollback}

`POST /api/v1/orgs/{org_slug}/portal/vps/{uuid}/snapshots/{snapshot_id}/rollback`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Storefront

> White-label catalog browse (public) and checkout (customer token).

Source: https://www.coritan.com/docs/api/reference/organizations/storefront/

White-label catalog browse (public) and checkout (customer token).

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Storefront](/docs/api/reference/organizations/storefront/storefront/) | 49 |

# Organization API: Storefront: Storefront

> The 49 Organization API operations for storefront.

Source: https://www.coritan.com/docs/api/reference/organizations/storefront/storefront/

Part of [Storefront](/docs/api/reference/organizations/storefront/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/storefront/branding`](#op-get-api-v1-orgs-org-slug-storefront-branding) | Public branding + legal links for the org storefront |
| POST | [`/api/v1/orgs/{org_slug}/storefront/checkout/{invoice_id}`](#op-post-api-v1-orgs-org-slug-storefront-checkout-invoice-id) | Create a payment checkout session for a specific invoice |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/chat/channels`](#op-get-api-v1-orgs-org-slug-storefront-community-chat-channels) | The public channels, and how to join the Discord properly |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/chat/messages`](#op-get-api-v1-orgs-org-slug-storefront-community-chat-messages) | A window of the mirror |
| POST | [`/api/v1/orgs/{org_slug}/storefront/community/chat/send`](#op-post-api-v1-orgs-org-slug-storefront-community-chat-send) | Relay one message into Discord under the sender's display name |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/chat/status`](#op-get-api-v1-orgs-org-slug-storefront-community-chat-status) | The remaining wait, mute, and handle after a refresh or a new tab |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/forum`](#op-get-api-v1-orgs-org-slug-storefront-community-forum) | The board list, plus the counters a forum landing page shows |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/forum/boards/{category_slug}`](#op-get-api-v1-orgs-org-slug-storefront-community-forum-boards-category-slug) | Board threads |
| POST | [`/api/v1/orgs/{org_slug}/storefront/community/forum/preview`](#op-post-api-v1-orgs-org-slug-storefront-community-forum-preview) | Preview post |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/forum/search`](#op-get-api-v1-orgs-org-slug-storefront-community-forum-search) | Title and body search |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/forum/tags`](#op-get-api-v1-orgs-org-slug-storefront-community-forum-tags) | The tags in use, busiest first, each with the page that lists it |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/forum/tags/{tag}`](#op-get-api-v1-orgs-org-slug-storefront-community-forum-tags-tag) | Every public thread carrying one tag, across boards |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/forum/threads`](#op-get-api-v1-orgs-org-slug-storefront-community-forum-threads) | Threads across every public board |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/forum/threads/{category_slug}/{thread_slug}`](#op-get-api-v1-orgs-org-slug-storefront-community-forum-threads-category-slug-thread) | Thread detail |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/guides`](#op-get-api-v1-orgs-org-slug-storefront-community-guides) | List guides |
| POST | [`/api/v1/orgs/{org_slug}/storefront/community/guides/preview`](#op-post-api-v1-orgs-org-slug-storefront-community-guides-preview) | Preview markdown |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/guides/{slug}`](#op-get-api-v1-orgs-org-slug-storefront-community-guides-slug) | Get guide |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/guides/{slug}/comments`](#op-get-api-v1-orgs-org-slug-storefront-community-guides-slug-comments) | List comments |
| POST | [`/api/v1/orgs/{org_slug}/storefront/community/guides/{slug}/comments`](#op-post-api-v1-orgs-org-slug-storefront-community-guides-slug-comments) | Post comment |
| POST | [`/api/v1/orgs/{org_slug}/storefront/community/guides/{slug}/helpful`](#op-post-api-v1-orgs-org-slug-storefront-community-guides-slug-helpful) | Vote helpful |
| POST | [`/api/v1/orgs/{org_slug}/storefront/community/guides/{slug}/report`](#op-post-api-v1-orgs-org-slug-storefront-community-guides-slug-report) | Report guide |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/handle-available`](#op-get-api-v1-orgs-org-slug-storefront-community-handle-available) | Whether a display name can be taken, and why not when it cannot |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/members`](#op-get-api-v1-orgs-org-slug-storefront-community-members) | The member list |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/members/{handle}`](#op-get-api-v1-orgs-org-slug-storefront-community-members-handle) | Member profile |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/members/{handle}/activity`](#op-get-api-v1-orgs-org-slug-storefront-community-members-handle-activity) | A page of one member's threads, replies or accepted answers |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/members/{handle}/wall`](#op-get-api-v1-orgs-org-slug-storefront-community-members-handle-wall) | Member wall |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/overview`](#op-get-api-v1-orgs-org-slug-storefront-community-overview) | The community index; with include=pages, each tab's first page as well |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/servers`](#op-get-api-v1-orgs-org-slug-storefront-community-servers) | List community servers |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/servers/{listing_slug}`](#op-get-api-v1-orgs-org-slug-storefront-community-servers-listing-slug) | Get community server |
| POST | [`/api/v1/orgs/{org_slug}/storefront/community/servers/{listing_slug}/rate`](#op-post-api-v1-orgs-org-slug-storefront-community-servers-listing-slug-rate) | Rate community server |
| GET | [`/api/v1/orgs/{org_slug}/storefront/community/stats`](#op-get-api-v1-orgs-org-slug-storefront-community-stats) | Homepage tiles: live totals plus this org's Coritan counts |
| POST | [`/api/v1/orgs/{org_slug}/storefront/contact`](#op-post-api-v1-orgs-org-slug-storefront-contact) | Public contact / bare-metal quote intake |
| GET | [`/api/v1/orgs/{org_slug}/storefront/coupons/preview`](#op-get-api-v1-orgs-org-slug-storefront-coupons-preview) | What a code would take off this plan's first invoice, before ordering |
| GET | [`/api/v1/orgs/{org_slug}/storefront/currencies`](#op-get-api-v1-orgs-org-slug-storefront-currencies) | Public enabled pay currencies with FX rates (quote per 1 USD) |
| POST | [`/api/v1/orgs/{org_slug}/storefront/external-servers/probe`](#op-post-api-v1-orgs-org-slug-storefront-external-servers-probe) | Customer: check a backend before ordering ("Test connection") |
| GET | [`/api/v1/orgs/{org_slug}/storefront/external-servers/regions`](#op-get-api-v1-orgs-org-slug-storefront-external-servers-regions) | Public: edge regions an external server can be served from, and the default |
| POST | [`/api/v1/orgs/{org_slug}/storefront/gameproxy/availability`](#op-post-api-v1-orgs-org-slug-storefront-gameproxy-availability) | Storefront availability |
| POST | [`/api/v1/orgs/{org_slug}/storefront/gameproxy/name-suggestions`](#op-post-api-v1-orgs-org-slug-storefront-gameproxy-name-suggestions) | Storefront name suggestions |
| GET | [`/api/v1/orgs/{org_slug}/storefront/gameproxy/policy`](#op-get-api-v1-orgs-org-slug-storefront-gameproxy-policy) | Public: whether Minecraft orders auto-attach gameproxy + base domain |
| GET | [`/api/v1/orgs/{org_slug}/storefront/locations`](#op-get-api-v1-orgs-org-slug-storefront-locations) | Public DC list, optionally with capacity for a module |
| GET | [`/api/v1/orgs/{org_slug}/storefront/notices`](#op-get-api-v1-orgs-org-slug-storefront-notices) | Live notices for everyone, for the dashboard bar when nobody is signed in |
| POST | [`/api/v1/orgs/{org_slug}/storefront/order`](#op-post-api-v1-orgs-org-slug-storefront-order) | Authenticated customer places an order for a product |
| GET | [`/api/v1/orgs/{org_slug}/storefront/products`](#op-get-api-v1-orgs-org-slug-storefront-products) | Public endpoint: browse the organization's product catalog |
| GET | [`/api/v1/orgs/{org_slug}/storefront/products/{product_slug}`](#op-get-api-v1-orgs-org-slug-storefront-products-product-slug) | Public endpoint: view a single product with all pricing tiers |
| GET | [`/api/v1/orgs/{org_slug}/storefront/specializations`](#op-get-api-v1-orgs-org-slug-storefront-specializations) | Public game/app specialization catalog for order UX |
| GET | [`/api/v1/orgs/{org_slug}/storefront/specializations/{slug}/compose`](#op-get-api-v1-orgs-org-slug-storefront-specializations-slug-compose) | Storefront compose specialization |
| GET | [`/api/v1/orgs/{org_slug}/storefront/status`](#op-get-api-v1-orgs-org-slug-storefront-status) | Per-location and per-node platform health, for the public status page |
| GET | [`/api/v1/orgs/{org_slug}/storefront/timezones`](#op-get-api-v1-orgs-org-slug-storefront-timezones) | Zones a schedule may be set to, and the old names for them |
| GET | [`/api/v1/orgs/{org_slug}/storefront/vps-templates`](#op-get-api-v1-orgs-org-slug-storefront-vps-templates) | Ready OS templates for Cloud / VPS storefront orders |

### Public branding + legal links for the org storefront {#op-get-api-v1-orgs-org-slug-storefront-branding}

`GET /api/v1/orgs/{org_slug}/storefront/branding`

Public branding + legal links for the org storefront.

Every storefront page load asks for this, and building it is eight
sequential reads (settings, server list, analytics, ads, knowledgebase,
forum, chat, free-tier) for a payload that changes when an operator edits
a colour. Kept warm per organisation for a few seconds, with concurrent
misses collapsed onto one build; a page load fan-in of a dozen tabs then
costs one build per process rather than a dozen.

#### 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. |

### Create a payment checkout session for a specific invoice {#op-post-api-v1-orgs-org-slug-storefront-checkout-invoice-id}

`POST /api/v1/orgs/{org_slug}/storefront/checkout/{invoice_id}`

Create a payment checkout session for a specific invoice.
Invoice totals are USD; charge currency uses customer preference / override.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `invoice_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `currency` | query | string | no |
| `gateway_name` | query | string | no |
| `return_url` | query | string | no |
| `cancel_url` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The public channels, and how to join the Discord properly {#op-get-api-v1-orgs-org-slug-storefront-community-chat-channels}

`GET /api/v1/orgs/{org_slug}/storefront/community/chat/channels`

The public channels, and how to join the Discord properly.

#### 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. |

### A window of the mirror {#op-get-api-v1-orgs-org-slug-storefront-community-chat-messages}

`GET /api/v1/orgs/{org_slug}/storefront/community/chat/messages`

A window of the mirror.

``after_id`` is what the page polls with once it has the conversation: it asks
for what it has not seen rather than re-downloading the fifty messages already
on screen, so the common answer is an empty list. ``has_more`` says the window
was filled, which is how a reader coming back from a long disconnect knows to
ask again instead of assuming it has caught up.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `channel_id` | query | string or null | no |  |
| `before_id` | query | integer or null | no |  |
| `after_id` | query | integer or null | no |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Relay one message into Discord under the sender's display name {#op-post-api-v1-orgs-org-slug-storefront-community-chat-send}

`POST /api/v1/orgs/{org_slug}/storefront/community/chat/send`

Relay one message into Discord under the sender's display name.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `channel_id` | string or null | no |
| `body` | string | yes |
| `client_nonce` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The remaining wait, mute, and handle after a refresh or a new tab {#op-get-api-v1-orgs-org-slug-storefront-community-chat-status}

`GET /api/v1/orgs/{org_slug}/storefront/community/chat/status`

The remaining wait, mute, and handle after a refresh or a new tab.

The composer used to invent a fresh countdown in memory, so a reload
(or a second tab) looked ready to send while the shared limiter still
refused. This is the server's own remaining time.

#### 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. |

### The board list, plus the counters a forum landing page shows {#op-get-api-v1-orgs-org-slug-storefront-community-forum}

`GET /api/v1/orgs/{org_slug}/storefront/community/forum`

The board list, plus the counters a forum landing page shows.

Public and read from a replica. The boards are materialised from the org's
settings the first time anybody looks, which is a write, but only on that
first look. The page reads what exists and takes the write path only when
the rows do not yet match the configuration. Every visitor used to open a
primary connection to find that they did.

#### 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. |

### Board threads {#op-get-api-v1-orgs-org-slug-storefront-community-forum-boards-category-slug}

`GET /api/v1/orgs/{org_slug}/storefront/community/forum/boards/{category_slug}`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `category_slug` | path | string | yes |  |
| `sort` | query | string | no | Default: `hot`. |
| `q` | query | string or null | no |  |
| `tag` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Preview post {#op-post-api-v1-orgs-org-slug-storefront-community-forum-preview}

`POST /api/v1/orgs/{org_slug}/storefront/community/forum/preview`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body_markdown` | string | yes |
| `edit_reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Title and body search {#op-get-api-v1-orgs-org-slug-storefront-community-forum-search}

`GET /api/v1/orgs/{org_slug}/storefront/community/forum/search`

Title and body search. Unlike the reference forum, bodies count.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string | yes |  |
| `scope` | query | string | no | Default: `all`. |
| `board` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The tags in use, busiest first, each with the page that lists it {#op-get-api-v1-orgs-org-slug-storefront-community-forum-tags}

`GET /api/v1/orgs/{org_slug}/storefront/community/forum/tags`

The tags in use, busiest first, each with the page that lists it.

#### 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. |

### Every public thread carrying one tag, across boards {#op-get-api-v1-orgs-org-slug-storefront-community-forum-tags-tag}

`GET /api/v1/orgs/{org_slug}/storefront/community/forum/tags/{tag}`

Every public thread carrying one tag, across boards.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `tag` | path | string | yes |  |
| `sort` | query | string | no | Default: `active`. |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Threads across every public board {#op-get-api-v1-orgs-org-slug-storefront-community-forum-threads}

`GET /api/v1/orgs/{org_slug}/storefront/community/forum/threads`

Threads across every public board.

``latest`` is the index page's activity list with pages; ``unanswered`` is
the questions nobody has replied to yet, which is the list a member who
wants to help should be handed rather than made to assemble board by board.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `filter` | query | string | no | Default: `latest`. |
| `sort` | query | string | no | Default: `active`. |
| `kind` | query | string or null | no |  |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Thread detail {#op-get-api-v1-orgs-org-slug-storefront-community-forum-threads-category-slug-thread}

`GET /api/v1/orgs/{org_slug}/storefront/community/forum/threads/{category_slug}/{thread_slug}`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `category_slug` | path | string | yes |  |
| `thread_slug` | path | string | yes |  |
| `sort` | query | string | no | Default: `best`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List guides {#op-get-api-v1-orgs-org-slug-storefront-community-guides}

`GET /api/v1/orgs/{org_slug}/storefront/community/guides`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `category` | query | string or null | no |  |
| `tag` | query | string or null | no |  |
| `difficulty` | query | string or null | no |  |
| `sort` | query | string | no | Default: `views`. |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `24`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Preview markdown {#op-post-api-v1-orgs-org-slug-storefront-community-guides-preview}

`POST /api/v1/orgs/{org_slug}/storefront/community/guides/preview`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body_markdown` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get guide {#op-get-api-v1-orgs-org-slug-storefront-community-guides-slug}

`GET /api/v1/orgs/{org_slug}/storefront/community/guides/{slug}`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `slug` | path | string | yes |  |
| `view` | query | string | no | Default: `live`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List comments {#op-get-api-v1-orgs-org-slug-storefront-community-guides-slug-comments}

`GET /api/v1/orgs/{org_slug}/storefront/community/guides/{slug}/comments`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Post comment {#op-post-api-v1-orgs-org-slug-storefront-community-guides-slug-comments}

`POST /api/v1/orgs/{org_slug}/storefront/community/guides/{slug}/comments`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `body_markdown` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Vote helpful {#op-post-api-v1-orgs-org-slug-storefront-community-guides-slug-helpful}

`POST /api/v1/orgs/{org_slug}/storefront/community/guides/{slug}/helpful`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `helpful` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Report guide {#op-post-api-v1-orgs-org-slug-storefront-community-guides-slug-report}

`POST /api/v1/orgs/{org_slug}/storefront/community/guides/{slug}/report`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |
| `comment_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Whether a display name can be taken, and why not when it cannot {#op-get-api-v1-orgs-org-slug-storefront-community-handle-available}

`GET /api/v1/orgs/{org_slug}/storefront/community/handle-available`

Whether a display name can be taken, and why not when it cannot.

Called while somebody types, so it answers rather than raising: a 422 per
keystroke is the wrong shape for a form.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `handle` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The member list {#op-get-api-v1-orgs-org-slug-storefront-community-members}

`GET /api/v1/orgs/{org_slug}/storefront/community/members`

The member list. Public, unlike the reference forum's, which 404s to guests.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `sort` | query | string | no | Default: `posts`. |
| `staff_only` | query | boolean | no | Default: `False`. |
| `q` | query | string or null | no |  |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `24`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Member profile {#op-get-api-v1-orgs-org-slug-storefront-community-members-handle}

`GET /api/v1/orgs/{org_slug}/storefront/community/members/{handle}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `handle` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A page of one member's threads, replies or accepted answers {#op-get-api-v1-orgs-org-slug-storefront-community-members-handle-activity}

`GET /api/v1/orgs/{org_slug}/storefront/community/members/{handle}/activity`

A page of one member's threads, replies or accepted answers.

Nothing in it depends on who is asking, so it is cached like the directory.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `handle` | path | string | yes |  |
| `kind` | query | string | no | Default: `replies`. |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `10`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Member wall {#op-get-api-v1-orgs-org-slug-storefront-community-members-handle-wall}

`GET /api/v1/orgs/{org_slug}/storefront/community/members/{handle}/wall`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `handle` | path | string | yes |  |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The community index; with include=pages, each tab's first page as well {#op-get-api-v1-orgs-org-slug-storefront-community-overview}

`GET /api/v1/orgs/{org_slug}/storefront/community/overview`

The community index; with ``include=pages``, each tab's first page as well.

Both come from the same cached build, so asking for the pages afterwards costs
the server nothing it had not already done.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `include` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List community servers {#op-get-api-v1-orgs-org-slug-storefront-community-servers}

`GET /api/v1/orgs/{org_slug}/storefront/community/servers`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `category` | query | string or null | no |  |
| `tag` | query | string or null | no |  |
| `sort` | query | string | no | Default: `players`. |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `24`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get community server {#op-get-api-v1-orgs-org-slug-storefront-community-servers-listing-slug}

`GET /api/v1/orgs/{org_slug}/storefront/community/servers/{listing_slug}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `listing_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rate community server {#op-post-api-v1-orgs-org-slug-storefront-community-servers-listing-slug-rate}

`POST /api/v1/orgs/{org_slug}/storefront/community/servers/{listing_slug}/rate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `listing_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `rating` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Homepage tiles: live totals plus this org's Coritan counts {#op-get-api-v1-orgs-org-slug-storefront-community-stats}

`GET /api/v1/orgs/{org_slug}/storefront/community/stats`

Homepage tiles: live totals plus this org's Coritan counts.

Separate from the directory list so the hero does not download every card.

Served from a per-org value that is recomputed every second for as long as
anyone is polling it (``STATS_REFRESH_SECONDS``). The first visitor on a
cold worker waits for one computation; everyone after them gets the latest
reading at once, and the database sees one reading per second per process
rather than one per tab.

#### 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. |

### Public contact / bare-metal quote intake {#op-post-api-v1-orgs-org-slug-storefront-contact}

`POST /api/v1/orgs/{org_slug}/storefront/contact`

Public contact / bare-metal quote intake.

Persists an inquiry, emails org support_email, and optionally opens a sales
chat conversation when the visitor is an authenticated org customer.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `kind` | string, one of `bare_metal_quote`, `general` | no |
| `name` | string | yes |
| `email` | string (email) | yes |
| `company` | string or null | no |
| `location` | string or null | no |
| `cpu` | string or null | no |
| `ram` | string or null | no |
| `storage` | string or null | no |
| `quantity` | string or null | no |
| `timeline` | string or null | no |
| `message` | string or null | no |
| `source_path` | string or null | no |
| `website` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### What a code would take off this plan's first invoice, before ordering {#op-get-api-v1-orgs-org-slug-storefront-coupons-preview}

`GET /api/v1/orgs/{org_slug}/storefront/coupons/preview`

What a code would take off this plan's first invoice, before ordering.
The order applies exactly this answer or refuses the same way.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `code` | query | string | yes |
| `org_product_id` | query | integer | yes |
| `org_pricing_id` | query | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Public enabled pay currencies with FX rates (quote per 1 USD) {#op-get-api-v1-orgs-org-slug-storefront-currencies}

`GET /api/v1/orgs/{org_slug}/storefront/currencies`

Public enabled pay currencies with FX rates (quote per 1 USD).

#### 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. |

### Customer: check a backend before ordering ("Test connection") {#op-post-api-v1-orgs-org-slug-storefront-external-servers-probe}

`POST /api/v1/orgs/{org_slug}/storefront/external-servers/probe`

Customer: check a backend before ordering ("Test connection").

Validates the address the same way the order will, then status-pings it.
Signed in and rate limited: it dials an address the customer typed, from
our network, so it must not be usable as an anonymous port scanner.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `upstream_host` | string | yes |
| `upstream_port` | integer | yes |
| `mode` | string | no |
| `proxy_protocol` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Public: edge regions an external server can be served from, and the default {#op-get-api-v1-orgs-org-slug-storefront-external-servers-regions}

`GET /api/v1/orgs/{org_slug}/storefront/external-servers/regions`

Public: edge regions an external server can be served from, and the default.

A join name only resolves to edges in its route's region, so the checkout
offers exactly the regions that have healthy gameproxy edges right now.

#### 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. |

### Storefront availability {#op-post-api-v1-orgs-org-slug-storefront-gameproxy-availability}

`POST /api/v1/orgs/{org_slug}/storefront/gameproxy/availability`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `subdomain` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Storefront name suggestions {#op-post-api-v1-orgs-org-slug-storefront-gameproxy-name-suggestions}

`POST /api/v1/orgs/{org_slug}/storefront/gameproxy/name-suggestions`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `count` | query | integer | no | Default: `5`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Public: whether Minecraft orders auto-attach gameproxy + base domain {#op-get-api-v1-orgs-org-slug-storefront-gameproxy-policy}

`GET /api/v1/orgs/{org_slug}/storefront/gameproxy/policy`

Public: whether Minecraft orders auto-attach gameproxy + base domain.

#### 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. |

### Public DC list, optionally with capacity for a module {#op-get-api-v1-orgs-org-slug-storefront-locations}

`GET /api/v1/orgs/{org_slug}/storefront/locations`

Public DC list, optionally with capacity for a module.

Capacity and usage are read for every location at once: two queries for
the module, not two per region. Each is the per-location predicate over the
whole set (``vps_location_usage_percent`` and friends, grouped), so a region
answers exactly as it did when it was asked on its own.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `module` | query | string | no | Optional: vps or container for availability |
| `hardware_tier_id` | query | integer | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Live notices for everyone, for the dashboard bar when nobody is signed in {#op-get-api-v1-orgs-org-slug-storefront-notices}

`GET /api/v1/orgs/{org_slug}/storefront/notices`

Live notices for everyone, for the dashboard bar when nobody is signed in.

#### 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. |

### Authenticated customer places an order for a product {#op-post-api-v1-orgs-org-slug-storefront-order}

`POST /api/v1/orgs/{org_slug}/storefront/order`

Authenticated customer places an order for a product.
Creates an OrgService + initial invoice + returns checkout URL.

Accepts ids/hostname as query params and/or JSON body; ``config`` from JSON body.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `org_product_id` | query | integer | no |
| `org_pricing_id` | query | integer | no |
| `hostname` | query | string | no |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `org_product_id` | integer or null | no |  |
| `org_pricing_id` | integer or null | no |  |
| `hostname` | string or null | no |  |
| `config` | object or null | no |  |
| `accepted_terms` | boolean | no |  |
| `terms_url` | string or null | no |  |
| `turnstile_token` | string or null | no |  |
| `idempotency_key` | string or null | no | Replay key for IP orders (double-submit / multi-tab) |
| `coupon_code` | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Public endpoint: browse the organization's product catalog {#op-get-api-v1-orgs-org-slug-storefront-products}

`GET /api/v1/orgs/{org_slug}/storefront/products`

Public endpoint: browse the organization's product catalog.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `game` | query | string or null | no | Filter by metadata.game (e.g. minecraft, terraria) |
| `category` | query | string or null | no | Filter by metadata.storefront_category (minecraft\|games\|cloud\|addons) |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Public endpoint: view a single product with all pricing tiers {#op-get-api-v1-orgs-org-slug-storefront-products-product-slug}

`GET /api/v1/orgs/{org_slug}/storefront/products/{product_slug}`

Public endpoint: view a single product with all pricing tiers.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `product_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Public game/app specialization catalog for order UX {#op-get-api-v1-orgs-org-slug-storefront-specializations}

`GET /api/v1/orgs/{org_slug}/storefront/specializations`

Public game/app specialization catalog for order UX.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `category` | query | string | no |
| `product_slug` | query | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Storefront compose specialization {#op-get-api-v1-orgs-org-slug-storefront-specializations-slug-compose}

`GET /api/v1/orgs/{org_slug}/storefront/specializations/{slug}/compose`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `slug` | path | string | yes |  |
| `supported_only` | query | boolean | no | Default: `True`. |
| `limit` | query | integer | no | Default: `200`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Per-location and per-node platform health, for the public status page {#op-get-api-v1-orgs-org-slug-storefront-status}

`GET /api/v1/orgs/{org_slug}/storefront/status`

Per-location and per-node platform health, for the public status page.

Publishes public host names and utilization percentages so both storefronts
can show every node. FQDNs, addresses and internal ids stay off this
payload, and they still live in the admin console.

#### 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. |

### Zones a schedule may be set to, and the old names for them {#op-get-api-v1-orgs-org-slug-storefront-timezones}

`GET /api/v1/orgs/{org_slug}/storefront/timezones`

Zones a schedule may be set to, and the old names for them.

On the storefront rather than only the platform API because the host guard
admits nothing but ``/api/v1/orgs/`` here, and it is the panel's schedule
form that needs the list. It needs it from us and not from the browser:
Chrome reports CLDR's ids, which for a dozen zones are the pre-rename IANA
names, and those resolve only where the backward-compatibility links are
installed. So a customer in Kyiv was offered ``Europe/Kiev`` by their own
browser and told it was unknown on every save.

#### 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. |

### Ready OS templates for Cloud / VPS storefront orders {#op-get-api-v1-orgs-org-slug-storefront-vps-templates}

`GET /api/v1/orgs/{org_slug}/storefront/vps-templates`

Ready OS templates for Cloud / VPS storefront orders.

#### 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. |

# Organization API: Commerce

> Every Organization API operation tagged Commerce.

Source: https://www.coritan.com/docs/api/reference/organizations/commerce/

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Commerce](/docs/api/reference/organizations/commerce/commerce/) | 123 |

# Organization API: Commerce: Commerce

> The 123 Organization API operations for commerce.

Source: https://www.coritan.com/docs/api/reference/organizations/commerce/commerce/

Part of [Commerce](/docs/api/reference/organizations/commerce/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/commerce/balance`](#op-get-api-v1-orgs-org-slug-commerce-balance) | Get balance |
| GET | [`/api/v1/orgs/{org_slug}/commerce/categories`](#op-get-api-v1-orgs-org-slug-commerce-categories) | List categories |
| POST | [`/api/v1/orgs/{org_slug}/commerce/categories`](#op-post-api-v1-orgs-org-slug-commerce-categories) | A category; isinternal keeps it out of the Store API |
| GET | [`/api/v1/orgs/{org_slug}/commerce/categories/{category_id}`](#op-get-api-v1-orgs-org-slug-commerce-categories-category-id) | Get category |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/categories/{category_id}`](#op-patch-api-v1-orgs-org-slug-commerce-categories-category-id) | Moving a category under itself or one of its children is a 409 |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/categories/{category_id}`](#op-delete-api-v1-orgs-org-slug-commerce-categories-category-id) | A category with children answers 409; move or delete them first |
| GET | [`/api/v1/orgs/{org_slug}/commerce/collections`](#op-get-api-v1-orgs-org-slug-commerce-collections) | List collections |
| POST | [`/api/v1/orgs/{org_slug}/commerce/collections`](#op-post-api-v1-orgs-org-slug-commerce-collections) | Create collection |
| GET | [`/api/v1/orgs/{org_slug}/commerce/collections/{collection_id}`](#op-get-api-v1-orgs-org-slug-commerce-collections-collection-id) | The collection and its product ids, in the collection's order |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/collections/{collection_id}`](#op-patch-api-v1-orgs-org-slug-commerce-collections-collection-id) | Turning a manual collection smart drops the products added by hand |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/collections/{collection_id}`](#op-delete-api-v1-orgs-org-slug-commerce-collections-collection-id) | The collection goes; its products stay |
| GET | [`/api/v1/orgs/{org_slug}/commerce/customer-groups`](#op-get-api-v1-orgs-org-slug-commerce-customer-groups) | Every group, by name, with its customer count |
| POST | [`/api/v1/orgs/{org_slug}/commerce/customer-groups`](#op-post-api-v1-orgs-org-slug-commerce-customer-groups) | Create group |
| GET | [`/api/v1/orgs/{org_slug}/commerce/customer-groups/{group_id}`](#op-get-api-v1-orgs-org-slug-commerce-customer-groups-group-id) | The group; its customers are GET /commerce/customers?groupid= |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/customer-groups/{group_id}`](#op-patch-api-v1-orgs-org-slug-commerce-customer-groups-group-id) | Update group |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/customer-groups/{group_id}`](#op-delete-api-v1-orgs-org-slug-commerce-customer-groups-group-id) | Delete group |
| GET | [`/api/v1/orgs/{org_slug}/commerce/disputes`](#op-get-api-v1-orgs-org-slug-commerce-disputes) | Newest first; count is every dispute the filters match |
| GET | [`/api/v1/orgs/{org_slug}/commerce/disputes/{dispute_id}`](#op-get-api-v1-orgs-org-slug-commerce-disputes-dispute-id) | The dispute, its evidence and what the provider has said about it |
| POST | [`/api/v1/orgs/{org_slug}/commerce/disputes/{dispute_id}/accept`](#op-post-api-v1-orgs-org-slug-commerce-disputes-dispute-id-accept) | Concede the dispute: the shopper keeps the money and the debit stays |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/disputes/{dispute_id}/evidence`](#op-put-api-v1-orgs-org-slug-commerce-disputes-dispute-id-evidence) | Set evidence text fields and links while the dispute waits for them |
| POST | [`/api/v1/orgs/{org_slug}/commerce/disputes/{dispute_id}/submit`](#op-post-api-v1-orgs-org-slug-commerce-disputes-dispute-id-submit) | Send the evidence to the bank |
| GET | [`/api/v1/orgs/{org_slug}/commerce/events`](#op-get-api-v1-orgs-org-slug-commerce-events) | What the store announced, newest first: the log behind its webhooks |
| GET | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers`](#op-get-api-v1-orgs-org-slug-commerce-fulfillment-providers) | List providers |
| POST | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers`](#op-post-api-v1-orgs-org-slug-commerce-fulfillment-providers) | A provider |
| GET | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}`](#op-get-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id) | Get provider |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}`](#op-patch-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id) | Rename, enable or disable, move the endpoint, change settings |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}`](#op-delete-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id) | Refused while a fulfillment that has not shipped uses it; disable it instead |
| GET | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/deliveries`](#op-get-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-deliveries) | Requests sent (or waiting to be sent) to the provider, newest first |
| GET | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/events`](#op-get-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-events) | Events the provider sent, newest first, with what became of each |
| POST | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/events`](#op-post-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-events) | One event from a fulfillment provider |
| POST | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/rotate-secrets`](#op-post-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-rotate-secr) | New outbound and inbound secrets, returned this once |
| POST | [`/api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/test`](#op-post-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-test) | Send a signed ping and report what the endpoint answered |
| GET | [`/api/v1/orgs/{org_slug}/commerce/gift-cards`](#op-get-api-v1-orgs-org-slug-commerce-gift-cards) | Newest first |
| POST | [`/api/v1/orgs/{org_slug}/commerce/gift-cards`](#op-post-api-v1-orgs-org-slug-commerce-gift-cards) | Issue a card |
| GET | [`/api/v1/orgs/{org_slug}/commerce/gift-cards/{gift_card_id}`](#op-get-api-v1-orgs-org-slug-commerce-gift-cards-gift-card-id) | The card and its latest transactions, newest first |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/gift-cards/{gift_card_id}`](#op-patch-api-v1-orgs-org-slug-commerce-gift-cards-gift-card-id) | Disable or re-enable a card, move its expiry, correct its recipient |
| POST | [`/api/v1/orgs/{org_slug}/commerce/gift-cards/{gift_card_id}/adjust`](#op-post-api-v1-orgs-org-slug-commerce-gift-cards-gift-card-id-adjust) | Move the balance by a signed amount; 409 giftcardbalancenegative below zero |
| GET | [`/api/v1/orgs/{org_slug}/commerce/imports`](#op-get-api-v1-orgs-org-slug-commerce-imports) | The store's imports, newest first, without their error lists; count counts every match |
| POST | [`/api/v1/orgs/{org_slug}/commerce/imports`](#op-post-api-v1-orgs-org-slug-commerce-imports) | Queue a Shopify product export for import and answer 202 with it |
| POST | [`/api/v1/orgs/{org_slug}/commerce/imports/shopify-products`](#op-post-api-v1-orgs-org-slug-commerce-imports-shopify-products) | Queue a Shopify product export for import and answer 202 with it |
| GET | [`/api/v1/orgs/{org_slug}/commerce/imports/{import_id}`](#op-get-api-v1-orgs-org-slug-commerce-imports-import-id) | One import: its status, progress, counts and every row it could not use |
| GET | [`/api/v1/orgs/{org_slug}/commerce/inventory-items`](#op-get-api-v1-orgs-org-slug-commerce-inventory-items) | Inventory items by SKU, with their levels |
| GET | [`/api/v1/orgs/{org_slug}/commerce/inventory-items/{item_id}`](#op-get-api-v1-orgs-org-slug-commerce-inventory-items-item-id) | Get item |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/inventory-items/{item_id}`](#op-patch-api-v1-orgs-org-slug-commerce-inventory-items-item-id) | What customs and shipping need to know about the item |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/inventory-items/{item_id}/levels/{location_id}`](#op-put-api-v1-orgs-org-slug-commerce-inventory-items-item-id-levels-location-id) | Set level |
| POST | [`/api/v1/orgs/{org_slug}/commerce/inventory/levels/batch`](#op-post-api-v1-orgs-org-slug-commerce-inventory-levels-batch) | Set levels by sku |
| GET | [`/api/v1/orgs/{org_slug}/commerce/ledger`](#op-get-api-v1-orgs-org-slug-commerce-ledger) | Every movement of the store's money, newest first |
| GET | [`/api/v1/orgs/{org_slug}/commerce/merchant-profile`](#op-get-api-v1-orgs-org-slug-commerce-merchant-profile) | Get profile |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/merchant-profile`](#op-put-api-v1-orgs-org-slug-commerce-merchant-profile) | Update profile |
| POST | [`/api/v1/orgs/{org_slug}/commerce/merchant-profile/submit`](#op-post-api-v1-orgs-org-slug-commerce-merchant-profile-submit) | Send the profile to platform review |
| GET | [`/api/v1/orgs/{org_slug}/commerce/orders`](#op-get-api-v1-orgs-org-slug-commerce-orders) | Newest first; count is every order the filters match |
| GET | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}`](#op-get-api-v1-orgs-org-slug-commerce-orders-order-id) | The order with its items, payments, refunds, fulfillments, documents and timeline |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}`](#op-patch-api-v1-orgs-org-slug-commerce-orders-order-id) | Update order |
| POST | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/cancel`](#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-cancel) | Refund what is left, give the stock back and end the order |
| GET | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/documents`](#op-get-api-v1-orgs-org-slug-commerce-orders-order-id-documents) | The invoice and credit notes, with the issuing entity's details as issued |
| GET | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments`](#op-get-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments) | The order's fulfillments with their 3PL requests, and each item's progress |
| POST | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments`](#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments) | Fulfill chosen units |
| POST | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments/{fulfillment_id}/cancel`](#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments-fulfillment-id-c) | Cancel before it ships (409 alreadyshipped after) |
| POST | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments/{fulfillment_id}/deliver`](#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments-fulfillment-id-d) | Delivered |
| POST | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments/{fulfillment_id}/dispatch`](#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments-fulfillment-id-d) | Dispatch fulfillment |
| POST | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments/{fulfillment_id}/ship`](#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments-fulfillment-id-s) | Shipped, with tracking |
| POST | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/notes`](#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-notes) | A note on the timeline; customervisible shows it on the shopper's order page |
| POST | [`/api/v1/orgs/{org_slug}/commerce/orders/{order_id}/refunds`](#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-refunds) | Refund an amount, or items and shipping, never more than is left |
| GET | [`/api/v1/orgs/{org_slug}/commerce/price-lists`](#op-get-api-v1-orgs-org-slug-commerce-price-lists) | List price lists |
| POST | [`/api/v1/orgs/{org_slug}/commerce/price-lists`](#op-post-api-v1-orgs-org-slug-commerce-price-lists) | Create price list |
| GET | [`/api/v1/orgs/{org_slug}/commerce/price-lists/{price_list_id}`](#op-get-api-v1-orgs-org-slug-commerce-price-lists-price-list-id) | Get price list |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/price-lists/{price_list_id}`](#op-patch-api-v1-orgs-org-slug-commerce-price-lists-price-list-id) | Fields change when named; prices replaces the list's prices |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/price-lists/{price_list_id}`](#op-delete-api-v1-orgs-org-slug-commerce-price-lists-price-list-id) | The list and its prices go; base prices are untouched |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/price-lists/{price_list_id}/prices`](#op-put-api-v1-orgs-org-slug-commerce-price-lists-price-list-id-prices) | Replace price list prices |
| GET | [`/api/v1/orgs/{org_slug}/commerce/product-tags`](#op-get-api-v1-orgs-org-slug-commerce-product-tags) | The tags on live products, most used first: what a tag picker suggests |
| GET | [`/api/v1/orgs/{org_slug}/commerce/promotions`](#op-get-api-v1-orgs-org-slug-commerce-promotions) | Newest first |
| POST | [`/api/v1/orgs/{org_slug}/commerce/promotions`](#op-post-api-v1-orgs-org-slug-commerce-promotions) | A code (or an automatic promotion) |
| GET | [`/api/v1/orgs/{org_slug}/commerce/promotions/{promotion_id}`](#op-get-api-v1-orgs-org-slug-commerce-promotions-promotion-id) | The promotion and what it has given, per currency |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/promotions/{promotion_id}`](#op-patch-api-v1-orgs-org-slug-commerce-promotions-promotion-id) | Update promotion |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/promotions/{promotion_id}`](#op-delete-api-v1-orgs-org-slug-commerce-promotions-promotion-id) | A promotion no order used |
| GET | [`/api/v1/orgs/{org_slug}/commerce/publishable-keys`](#op-get-api-v1-orgs-org-slug-commerce-publishable-keys) | List keys |
| POST | [`/api/v1/orgs/{org_slug}/commerce/publishable-keys`](#op-post-api-v1-orgs-org-slug-commerce-publishable-keys) | A key for a storefront |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/publishable-keys/{key_id}`](#op-delete-api-v1-orgs-org-slug-commerce-publishable-keys-key-id) | Revoke key |
| GET | [`/api/v1/orgs/{org_slug}/commerce/regions`](#op-get-api-v1-orgs-org-slug-commerce-regions) | Every region of the store, disabled ones included |
| POST | [`/api/v1/orgs/{org_slug}/commerce/regions`](#op-post-api-v1-orgs-org-slug-commerce-regions) | A region |
| GET | [`/api/v1/orgs/{org_slug}/commerce/regions/{region_id}`](#op-get-api-v1-orgs-org-slug-commerce-regions-region-id) | Get region |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/regions/{region_id}`](#op-patch-api-v1-orgs-org-slug-commerce-regions-region-id) | Fields change when named; countries replaces the region's |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/regions/{region_id}`](#op-delete-api-v1-orgs-org-slug-commerce-regions-region-id) | The region, its countries and the prices set for it go |
| GET | [`/api/v1/orgs/{org_slug}/commerce/return-reasons`](#op-get-api-v1-orgs-org-slug-commerce-return-reasons) | Every reason, disabled ones included, in the order shoppers see them |
| POST | [`/api/v1/orgs/{org_slug}/commerce/return-reasons`](#op-post-api-v1-orgs-org-slug-commerce-return-reasons) | A reason shoppers may pick for a return |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/return-reasons/{reason_id}`](#op-patch-api-v1-orgs-org-slug-commerce-return-reasons-reason-id) | Label, description, rank or whether shoppers may pick it; the code never changes |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/return-reasons/{reason_id}`](#op-delete-api-v1-orgs-org-slug-commerce-return-reasons-reason-id) | Delete return reason |
| GET | [`/api/v1/orgs/{org_slug}/commerce/returns`](#op-get-api-v1-orgs-org-slug-commerce-returns) | Newest first; count is every return the filters match |
| POST | [`/api/v1/orgs/{org_slug}/commerce/returns`](#op-post-api-v1-orgs-org-slug-commerce-returns) | Create return |
| GET | [`/api/v1/orgs/{org_slug}/commerce/returns/{return_id}`](#op-get-api-v1-orgs-org-slug-commerce-returns-return-id) | Get return |
| POST | [`/api/v1/orgs/{org_slug}/commerce/returns/{return_id}/approve`](#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-approve) | Approve return |
| POST | [`/api/v1/orgs/{org_slug}/commerce/returns/{return_id}/cancel`](#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-cancel) | End a return before its goods are in, or a claim before it is settled |
| POST | [`/api/v1/orgs/{org_slug}/commerce/returns/{return_id}/receive`](#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-receive) | Receive return |
| POST | [`/api/v1/orgs/{org_slug}/commerce/returns/{return_id}/refund`](#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-refund) | Refund return |
| POST | [`/api/v1/orgs/{org_slug}/commerce/returns/{return_id}/reject`](#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-reject) | Decline a requested return; the shopper reads the reason |
| GET | [`/api/v1/orgs/{org_slug}/commerce/sales-channels`](#op-get-api-v1-orgs-org-slug-commerce-sales-channels) | List channels |
| POST | [`/api/v1/orgs/{org_slug}/commerce/sales-channels`](#op-post-api-v1-orgs-org-slug-commerce-sales-channels) | Create channel |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/sales-channels/{channel_id}`](#op-patch-api-v1-orgs-org-slug-commerce-sales-channels-channel-id) | Update channel |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/sales-channels/{channel_id}`](#op-delete-api-v1-orgs-org-slug-commerce-sales-channels-channel-id) | Delete channel |
| GET | [`/api/v1/orgs/{org_slug}/commerce/sales-channels/{channel_id}/stock-locations`](#op-get-api-v1-orgs-org-slug-commerce-sales-channels-channel-id-stock-locations) | The locations a channel sells from |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/sales-channels/{channel_id}/stock-locations`](#op-put-api-v1-orgs-org-slug-commerce-sales-channels-channel-id-stock-locations) | The channel sells from exactly these locations; an empty list means every enabled location |
| GET | [`/api/v1/orgs/{org_slug}/commerce/shipping-options`](#op-get-api-v1-orgs-org-slug-commerce-shipping-options) | List options |
| POST | [`/api/v1/orgs/{org_slug}/commerce/shipping-options`](#op-post-api-v1-orgs-org-slug-commerce-shipping-options) | An option in a zone for a profile (the default one when profileid is left out) |
| GET | [`/api/v1/orgs/{org_slug}/commerce/shipping-options/{option_id}`](#op-get-api-v1-orgs-org-slug-commerce-shipping-options-option-id) | Get option |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/shipping-options/{option_id}`](#op-patch-api-v1-orgs-org-slug-commerce-shipping-options-option-id) | Update option |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/shipping-options/{option_id}`](#op-delete-api-v1-orgs-org-slug-commerce-shipping-options-option-id) | Carts that chose it choose again; orders keep the name and amount they were charged |
| GET | [`/api/v1/orgs/{org_slug}/commerce/shipping-profiles`](#op-get-api-v1-orgs-org-slug-commerce-shipping-profiles) | Every profile, the default first |
| POST | [`/api/v1/orgs/{org_slug}/commerce/shipping-profiles`](#op-post-api-v1-orgs-org-slug-commerce-shipping-profiles) | Create profile |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/shipping-profiles/{profile_id}`](#op-patch-api-v1-orgs-org-slug-commerce-shipping-profiles-profile-id) | Update profile |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/shipping-profiles/{profile_id}`](#op-delete-api-v1-orgs-org-slug-commerce-shipping-profiles-profile-id) | A profile no product and no option uses |
| GET | [`/api/v1/orgs/{org_slug}/commerce/shipping-zones`](#op-get-api-v1-orgs-org-slug-commerce-shipping-zones) | Every zone, with how many options each holds |
| POST | [`/api/v1/orgs/{org_slug}/commerce/shipping-zones`](#op-post-api-v1-orgs-org-slug-commerce-shipping-zones) | Create zone |
| GET | [`/api/v1/orgs/{org_slug}/commerce/shipping-zones/{zone_id}`](#op-get-api-v1-orgs-org-slug-commerce-shipping-zones-zone-id) | Get zone |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/shipping-zones/{zone_id}`](#op-patch-api-v1-orgs-org-slug-commerce-shipping-zones-zone-id) | Update zone |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/shipping-zones/{zone_id}`](#op-delete-api-v1-orgs-org-slug-commerce-shipping-zones-zone-id) | The zone and its options |
| GET | [`/api/v1/orgs/{org_slug}/commerce/stock-locations`](#op-get-api-v1-orgs-org-slug-commerce-stock-locations) | Every location, the default first, with the channels that sell from it |
| POST | [`/api/v1/orgs/{org_slug}/commerce/stock-locations`](#op-post-api-v1-orgs-org-slug-commerce-stock-locations) | A warehouse, shop or 3PL site |
| GET | [`/api/v1/orgs/{org_slug}/commerce/stock-locations/{location_id}`](#op-get-api-v1-orgs-org-slug-commerce-stock-locations-location-id) | Get location |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/stock-locations/{location_id}`](#op-patch-api-v1-orgs-org-slug-commerce-stock-locations-location-id) | Isdefault: true moves the default here |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/stock-locations/{location_id}`](#op-delete-api-v1-orgs-org-slug-commerce-stock-locations-location-id) | Delete location |
| GET | [`/api/v1/orgs/{org_slug}/commerce/store`](#op-get-api-v1-orgs-org-slug-commerce-store) | The store, its sales channels, and where its merchant review stands |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/store`](#op-patch-api-v1-orgs-org-slug-commerce-store) | Update store |
| GET | [`/api/v1/orgs/{org_slug}/commerce/tax-reports`](#op-get-api-v1-orgs-org-slug-commerce-tax-reports) | Tax report |

### Get balance {#op-get-api-v1-orgs-org-slug-commerce-balance}

`GET /api/v1/orgs/{org_slug}/commerce/balance`

What the store is owed from live sales, per currency: ``pending`` until
the order's hold ends, then ``available``; ``reserved`` is held back until
its release date, and ``payable`` is what a payout could take now.

#### 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. |

### List categories {#op-get-api-v1-orgs-org-slug-commerce-categories}

`GET /api/v1/orgs/{org_slug}/commerce/categories`

Every category, flat, with ``parent_id`` to build the tree from, and the
number of live products placed directly in each.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `parent_id` | query | integer or null | no | 0 for the top level |
| `limit` | query | integer | no | Default: `500`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A category; isinternal keeps it out of the Store API {#op-post-api-v1-orgs-org-slug-commerce-categories}

`POST /api/v1/orgs/{org_slug}/commerce/categories`

A category; ``is_internal`` keeps it out of the Store API.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `handle` | string or null | no |
| `description` | string or null | no |
| `parent_id` | integer or null | no |
| `rank` | integer or null | no |
| `is_active` | boolean or null | no |
| `is_internal` | boolean or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get category {#op-get-api-v1-orgs-org-slug-commerce-categories-category-id}

`GET /api/v1/orgs/{org_slug}/commerce/categories/{category_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `category_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Moving a category under itself or one of its children is a 409 {#op-patch-api-v1-orgs-org-slug-commerce-categories-category-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/categories/{category_id}`

Moving a category under itself or one of its children is a 409.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `category_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `handle` | string or null | no |
| `description` | string or null | no |
| `parent_id` | integer or null | no |
| `rank` | integer or null | no |
| `is_active` | boolean or null | no |
| `is_internal` | boolean or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A category with children answers 409; move or delete them first {#op-delete-api-v1-orgs-org-slug-commerce-categories-category-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/categories/{category_id}`

A category with children answers 409; move or delete them first. Its
products stay, out of the category.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `category_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List collections {#op-get-api-v1-orgs-org-slug-commerce-collections}

`GET /api/v1/orgs/{org_slug}/commerce/collections`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `is_published` | query | boolean or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create collection {#op-post-api-v1-orgs-org-slug-commerce-collections}

`POST /api/v1/orgs/{org_slug}/commerce/collections`

A manual collection (products added by hand), or a smart one whose
``rules`` choose its products: ``{"match": "all"|"any", "conditions":
[{"field": "tag"|"product_type"|"vendor"|"title", "op": "equals"|"contains", "value"}]}``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `handle` | string or null | no |
| `description` | string or null | no |
| `kind` | string or null | no |
| `rules` | object or null | no |
| `is_published` | boolean or null | no |
| `rank` | integer or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The collection and its product ids, in the collection's order {#op-get-api-v1-orgs-org-slug-commerce-collections-collection-id}

`GET /api/v1/orgs/{org_slug}/commerce/collections/{collection_id}`

The collection and its product ids, in the collection's order.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `collection_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Turning a manual collection smart drops the products added by hand {#op-patch-api-v1-orgs-org-slug-commerce-collections-collection-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/collections/{collection_id}`

Turning a manual collection smart drops the products added by hand.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `collection_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `handle` | string or null | no |
| `description` | string or null | no |
| `kind` | string or null | no |
| `rules` | object or null | no |
| `is_published` | boolean or null | no |
| `rank` | integer or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The collection goes; its products stay {#op-delete-api-v1-orgs-org-slug-commerce-collections-collection-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/collections/{collection_id}`

The collection goes; its products stay.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `collection_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every group, by name, with its customer count {#op-get-api-v1-orgs-org-slug-commerce-customer-groups}

`GET /api/v1/orgs/{org_slug}/commerce/customer-groups`

Every group, by name, with its customer count.

#### 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. |

### Create group {#op-post-api-v1-orgs-org-slug-commerce-customer-groups}

`POST /api/v1/orgs/{org_slug}/commerce/customer-groups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The group; its customers are GET /commerce/customers?groupid= {#op-get-api-v1-orgs-org-slug-commerce-customer-groups-group-id}

`GET /api/v1/orgs/{org_slug}/commerce/customer-groups/{group_id}`

The group; its customers are ``GET /commerce/customers?group_id=``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `group_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update group {#op-patch-api-v1-orgs-org-slug-commerce-customer-groups-group-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/customer-groups/{group_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `group_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete group {#op-delete-api-v1-orgs-org-slug-commerce-customer-groups-group-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/customer-groups/{group_id}`

Delete the group; its customers stay, and lose any price list or
promotion that was for the group.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `group_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Newest first; count is every dispute the filters match {#op-get-api-v1-orgs-org-slug-commerce-disputes}

`GET /api/v1/orgs/{org_slug}/commerce/disputes`

Newest first; ``count`` is every dispute the filters match.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no | A status, or open for both open ones. |
| `order_id` | query | integer or null | no |  |
| `livemode` | query | boolean or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The dispute, its evidence and what the provider has said about it {#op-get-api-v1-orgs-org-slug-commerce-disputes-dispute-id}

`GET /api/v1/orgs/{org_slug}/commerce/disputes/{dispute_id}`

The dispute, its evidence and what the provider has said about it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `dispute_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Concede the dispute: the shopper keeps the money and the debit stays {#op-post-api-v1-orgs-org-slug-commerce-disputes-dispute-id-accept}

`POST /api/v1/orgs/{org_slug}/commerce/disputes/{dispute_id}/accept`

Concede the dispute: the shopper keeps the money and the debit stays.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `dispute_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set evidence text fields and links while the dispute waits for them {#op-put-api-v1-orgs-org-slug-commerce-disputes-dispute-id-evidence}

`PUT /api/v1/orgs/{org_slug}/commerce/disputes/{dispute_id}/evidence`

Set evidence text fields and links while the dispute waits for them.
Fields not named keep their value.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `dispute_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fields` | Fields | no | Text fields to set; null hands a field back to the text assembled from the order. |
| `urls` | array of string or null | no | Replaces the links; omit to keep them. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send the evidence to the bank {#op-post-api-v1-orgs-org-slug-commerce-disputes-dispute-id-submit}

`POST /api/v1/orgs/{org_slug}/commerce/disputes/{dispute_id}/submit`

Send the evidence to the bank. Final: a bank takes one submission.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `dispute_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### What the store announced, newest first: the log behind its webhooks {#op-get-api-v1-orgs-org-slug-commerce-events}

`GET /api/v1/orgs/{org_slug}/commerce/events`

What the store announced, newest first: the log behind its webhooks.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `event_type` | query | string or null | no |  |
| `status` | query | string or null | no |  |
| `before_id` | query | integer or null | no |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List providers {#op-get-api-v1-orgs-org-slug-commerce-fulfillment-providers}

`GET /api/v1/orgs/{org_slug}/commerce/fulfillment-providers`

#### 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. |

### A provider {#op-post-api-v1-orgs-org-slug-commerce-fulfillment-providers}

`POST /api/v1/orgs/{org_slug}/commerce/fulfillment-providers`

A provider. A webhook provider's two secrets are in ``secrets``, this once.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `kind` | string | yes |
| `name` | string | yes |
| `is_enabled` | boolean | no |
| `endpoint_url` | string or null | no |
| `config` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get provider {#op-get-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id}

`GET /api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `provider_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rename, enable or disable, move the endpoint, change settings {#op-patch-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}`

Rename, enable or disable, move the endpoint, change settings. A disabled
provider is sent nothing; what waited for it goes out once it is enabled.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `provider_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `kind` | string or null | no |
| `name` | string or null | no |
| `is_enabled` | boolean or null | no |
| `endpoint_url` | string or null | no |
| `config` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Refused while a fulfillment that has not shipped uses it; disable it instead {#op-delete-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}`

Refused while a fulfillment that has not shipped uses it; disable it instead.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `provider_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Requests sent (or waiting to be sent) to the provider, newest first {#op-get-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-deliveries}

`GET /api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/deliveries`

Requests sent (or waiting to be sent) to the provider, newest first.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `before_id` | query | integer or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `include_payload` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Events the provider sent, newest first, with what became of each {#op-get-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-events}

`GET /api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/events`

Events the provider sent, newest first, with what became of each.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `provider_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no |  |
| `type` | query | string or null | no |  |
| `before_id` | query | integer or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `include_payload` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### One event from a fulfillment provider {#op-post-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-events}

`POST /api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/events`

One event from a fulfillment provider.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `provider_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### New outbound and inbound secrets, returned this once {#op-post-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-rotate-secr}

`POST /api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/rotate-secrets`

New outbound and inbound secrets, returned this once. The old ones stop
working at once.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `provider_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send a signed ping and report what the endpoint answered {#op-post-api-v1-orgs-org-slug-commerce-fulfillment-providers-provider-id-test}

`POST /api/v1/orgs/{org_slug}/commerce/fulfillment-providers/{provider_id}/test`

Send a signed ``ping`` and report what the endpoint answered.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `provider_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Newest first {#op-get-api-v1-orgs-org-slug-commerce-gift-cards}

`GET /api/v1/orgs/{org_slug}/commerce/gift-cards`

Newest first. ``expired`` includes active cards past their expiry.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no | The last four characters, the full code, or an email. |
| `status` | query | string or null | no |  |
| `livemode` | query | boolean or null | no |  |
| `before_id` | query | integer or null | no |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Issue a card {#op-post-api-v1-orgs-org-slug-commerce-gift-cards}

`POST /api/v1/orgs/{org_slug}/commerce/gift-cards`

Issue a card. ``code`` is in this answer only; it cannot be shown again.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `currency_code` | string | yes |
| `amount` | integer | yes |
| `livemode` | boolean or null | no |
| `recipient_email` | string or null | no |
| `recipient_name` | string or null | no |
| `sender_name` | string or null | no |
| `message` | string or null | no |
| `expires_at` | string (date-time) or null | no |
| `customer_id` | integer or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The card and its latest transactions, newest first {#op-get-api-v1-orgs-org-slug-commerce-gift-cards-gift-card-id}

`GET /api/v1/orgs/{org_slug}/commerce/gift-cards/{gift_card_id}`

The card and its latest transactions, newest first.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `gift_card_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Disable or re-enable a card, move its expiry, correct its recipient {#op-patch-api-v1-orgs-org-slug-commerce-gift-cards-gift-card-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/gift-cards/{gift_card_id}`

Disable or re-enable a card, move its expiry, correct its recipient.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `gift_card_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `status` | string or null | no |
| `expires_at` | string (date-time) or null | no |
| `recipient_email` | string or null | no |
| `recipient_name` | string or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Move the balance by a signed amount; 409 giftcardbalancenegative below zero {#op-post-api-v1-orgs-org-slug-commerce-gift-cards-gift-card-id-adjust}

`POST /api/v1/orgs/{org_slug}/commerce/gift-cards/{gift_card_id}/adjust`

Move the balance by a signed amount; 409 ``gift_card_balance_negative`` below zero.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `gift_card_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `amount` | integer | yes |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The store's imports, newest first, without their error lists; count counts every match {#op-get-api-v1-orgs-org-slug-commerce-imports}

`GET /api/v1/orgs/{org_slug}/commerce/imports`

The store's imports, newest first, without their error lists; ``count``
counts every match. ``status`` is queued, running, completed or failed
(422 naming them otherwise).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `20`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Queue a Shopify product export for import and answer 202 with it {#op-post-api-v1-orgs-org-slug-commerce-imports}

`POST /api/v1/orgs/{org_slug}/commerce/imports`

Queue a Shopify product export for import and answer 202 with it.

The file is the multipart field ``file``, a ``text/csv`` body or JSON
``{"csv": "...", "filename": "..."}``. ``mode=upsert`` (the default)
updates the products whose Handle the store already has; ``create_only``
skips them. Prices are read in ``currency_code`` (the store's default
currency unless given; the store must sell in it) and ``Variant Inventory
Qty`` is the count at ``location_id``. ``dry_run=true`` runs the same way
and writes nothing but the report. A file that cannot be imported at all
is refused here (422); a row the import cannot use is listed in the
finished import's ``report.errors`` with its spreadsheet row number, and
the rest of the file still imports. While another import is queued or
running this answers 409 ``import_in_progress`` with its ``import_id``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `mode` | query | string | no | Default: `upsert`. |
| `dry_run` | query | boolean | no | Default: `False`. |
| `currency_code` | query | string or null | no |  |
| `location_id` | query | integer or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Queue a Shopify product export for import and answer 202 with it {#op-post-api-v1-orgs-org-slug-commerce-imports-shopify-products}

`POST /api/v1/orgs/{org_slug}/commerce/imports/shopify-products`

> [!WARNING]
> Deprecated. It still answers, but new code should not use it.

Queue a Shopify product export for import and answer 202 with it.

The file is the multipart field ``file``, a ``text/csv`` body or JSON
``{"csv": "...", "filename": "..."}``. ``mode=upsert`` (the default)
updates the products whose Handle the store already has; ``create_only``
skips them. Prices are read in ``currency_code`` (the store's default
currency unless given; the store must sell in it) and ``Variant Inventory
Qty`` is the count at ``location_id``. ``dry_run=true`` runs the same way
and writes nothing but the report. A file that cannot be imported at all
is refused here (422); a row the import cannot use is listed in the
finished import's ``report.errors`` with its spreadsheet row number, and
the rest of the file still imports. While another import is queued or
running this answers 409 ``import_in_progress`` with its ``import_id``.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `mode` | query | string | no | Default: `upsert`. |
| `dry_run` | query | boolean | no | Default: `False`. |
| `currency_code` | query | string or null | no |  |
| `location_id` | query | integer or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### One import: its status, progress, counts and every row it could not use {#op-get-api-v1-orgs-org-slug-commerce-imports-import-id}

`GET /api/v1/orgs/{org_slug}/commerce/imports/{import_id}`

One import: its status, progress, counts and every row it could not use.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `import_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Inventory items by SKU, with their levels {#op-get-api-v1-orgs-org-slug-commerce-inventory-items}

`GET /api/v1/orgs/{org_slug}/commerce/inventory-items`

Inventory items by SKU, with their levels. ``location_id`` keeps items
stocked there; ``low_stock=n`` keeps items of variants that track stock with
at most ``n`` available (at ``location_id`` when given).

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `location_id` | query | integer or null | no |  |
| `low_stock` | query | integer or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get item {#op-get-api-v1-orgs-org-slug-commerce-inventory-items-item-id}

`GET /api/v1/orgs/{org_slug}/commerce/inventory-items/{item_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `item_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 customs and shipping need to know about the item {#op-patch-api-v1-orgs-org-slug-commerce-inventory-items-item-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/inventory-items/{item_id}`

What customs and shipping need to know about the item. Its SKU follows
its variant's.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `item_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `requires_shipping` | boolean or null | no |
| `hs_code` | string or null | no |
| `origin_country` | string or null | no |
| `weight_g` | integer or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set level {#op-put-api-v1-orgs-org-slug-commerce-inventory-items-item-id-levels-location-id}

`PUT /api/v1/orgs/{org_slug}/commerce/inventory-items/{item_id}/levels/{location_id}`

Set the count on the shelf (``stocked_quantity``) or move it
(``delta``, negative to take stock out), and optionally what is on its way
(``incoming_quantity``). Stock never goes below zero; reserved stock is
untouched.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `item_id` | path | integer | yes |
| `location_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `stocked_quantity` | integer or null | no |
| `delta` | integer or null | no |
| `incoming_quantity` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set levels by sku {#op-post-api-v1-orgs-org-slug-commerce-inventory-levels-batch}

`POST /api/v1/orgs/{org_slug}/commerce/inventory/levels/batch`

A stock count from a warehouse: ``{location_id, levels: [{sku,
stocked_quantity}]}``, at most 1000 rows. A SKU the store does not have is
listed in ``unknown_skus`` and the rest are still set; a SKU given twice
takes its last count.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `location_id` | integer | yes |
| `levels` | array of object | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every movement of the store's money, newest first {#op-get-api-v1-orgs-org-slug-commerce-ledger}

`GET /api/v1/orgs/{org_slug}/commerce/ledger`

Every movement of the store's money, newest first. Test orders book to
the test ledger (``livemode=false``), which never pays out.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `currency_code` | query | string or null | no |  |
| `status` | query | string or null | no |  |
| `entry_type` | query | string or null | no |  |
| `order_id` | query | integer or null | no |  |
| `livemode` | query | boolean | no | Default: `True`. |
| `created_from` | query | string (date-time) or null | no |  |
| `created_to` | query | string (date-time) or null | no | Exclusive. |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get profile {#op-get-api-v1-orgs-org-slug-commerce-merchant-profile}

`GET /api/v1/orgs/{org_slug}/commerce/merchant-profile`

#### 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. |

### Update profile {#op-put-api-v1-orgs-org-slug-commerce-merchant-profile}

`PUT /api/v1/orgs/{org_slug}/commerce/merchant-profile`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `legal_name` | string or null | no |
| `trading_name` | string or null | no |
| `legal_form` | string or null | no |
| `registration_number` | string or null | no |
| `tax_id` | string or null | no |
| `country_code` | string or null | no |
| `address` | object or null | no |
| `website` | string or null | no |
| `support_email` | string or null | no |
| `support_phone` | string or null | no |
| `product_categories` | array of string or null | no |
| `product_description` | string or null | no |
| `ship_from` | object or null | no |
| `return_address` | object or null | no |
| `beneficial_owners` | array of object or null | no |
| `expected_monthly_volume` | integer or null | no |
| `volume_currency` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send the profile to platform review {#op-post-api-v1-orgs-org-slug-commerce-merchant-profile-submit}

`POST /api/v1/orgs/{org_slug}/commerce/merchant-profile/submit`

Send the profile to platform review. 422 lists what is still missing.

#### 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. |

### Newest first; count is every order the filters match {#op-get-api-v1-orgs-org-slug-commerce-orders}

`GET /api/v1/orgs/{org_slug}/commerce/orders`

Newest first; ``count`` is every order the filters match.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no |  |
| `payment_status` | query | string or null | no |  |
| `fulfillment_status` | query | string or null | no |  |
| `customer_id` | query | integer or null | no |  |
| `email` | query | string or null | no |  |
| `q` | query | string or null | no | #1001, an order_... id, or part of an email. |
| `livemode` | query | boolean or null | no |  |
| `risk_hold` | query | boolean or null | no |  |
| `placed_from` | query | string (date-time) or null | no |  |
| `placed_to` | query | string (date-time) or null | no | Exclusive. |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The order with its items, payments, refunds, fulfillments, documents and timeline {#op-get-api-v1-orgs-org-slug-commerce-orders-order-id}

`GET /api/v1/orgs/{org_slug}/commerce/orders/{order_id}`

The order with its items, payments, refunds, fulfillments, documents and timeline.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update order {#op-patch-api-v1-orgs-org-slug-commerce-orders-order-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/orders/{order_id}`

Correct the email or the shipping address (not its country, nor a US or
Canadian state, which the order was taxed for), change the note or the
metadata, or release a risk hold with ``risk_hold: false``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string or null | no |  |
| `shipping_address` | object or null | no | Until a fulfillment has gone to its provider. |
| `note` | string or null | no |  |
| `metadata` | object or null | no |  |
| `risk_hold` | boolean or null | no | Only false, which releases a risk hold. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Refund what is left, give the stock back and end the order {#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-cancel}

`POST /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/cancel`

Refund what is left, give the stock back and end the order. 409
``already_shipped`` once any of it has shipped: refund it instead.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string or null | no |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The invoice and credit notes, with the issuing entity's details as issued {#op-get-api-v1-orgs-org-slug-commerce-orders-order-id-documents}

`GET /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/documents`

The invoice and credit notes, with the issuing entity's details as issued.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The order's fulfillments with their 3PL requests, and each item's progress {#op-get-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments}

`GET /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments`

The order's fulfillments with their 3PL requests, and each item's progress.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Fulfill chosen units {#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments}

`POST /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments`

Fulfill chosen units. They go to ``provider_id`` if named, else where the
order routes them; a webhook provider with ``auto_dispatch`` is sent the
fulfillment at once.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `items` | array of UnitIn | yes |
| `items[].order_item_id` | integer | yes |
| `items[].quantity` | integer | yes |
| `location_id` | integer or null | no |
| `provider_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Cancel before it ships (409 alreadyshipped after) {#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments-fulfillment-id-c}

`POST /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments/{fulfillment_id}/cancel`

Cancel before it ships (409 ``already_shipped`` after). A 3PL that may
hold it is sent ``fulfillment.cancel``. Payments are not touched.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `fulfillment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delivered {#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments-fulfillment-id-d}

`POST /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments/{fulfillment_id}/deliver`

Delivered. One not yet marked shipped is shipped (without tracking) first.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `fulfillment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Dispatch fulfillment {#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments-fulfillment-id-d}

`POST /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments/{fulfillment_id}/dispatch`

Send the fulfillment to its 3PL now: a waiting request goes at once, and
one that failed is sent again as a new request.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `fulfillment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Shipped, with tracking {#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-fulfillments-fulfillment-id-s}

`POST /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/fulfillments/{fulfillment_id}/ship`

Shipped, with tracking. ``items`` ships part of it: those units become a
fulfillment of their own and the rest stays under this id.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `fulfillment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `tracking` | array of object | no |
| `items` | array of UnitIn or null | no |
| `items[].order_item_id` | integer | yes |
| `items[].quantity` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A note on the timeline; customervisible shows it on the shopper's order page {#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-notes}

`POST /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/notes`

A note on the timeline; ``customer_visible`` shows it on the shopper's order page.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `note` | string | yes |
| `customer_visible` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Refund an amount, or items and shipping, never more than is left {#op-post-api-v1-orgs-org-slug-commerce-orders-order-id-refunds}

`POST /api/v1/orgs/{org_slug}/commerce/orders/{order_id}/refunds`

Refund an ``amount``, or ``items`` and ``shipping``, never more than is
left. A card payment is refunded first and gift cards the shopper paid with
are credited with the rest; a credit note is issued for it. Refunded units
not yet shipped release their stock; with ``restock: true`` shipped units
named go back in stock at ``location_id`` (or where they shipped from).

With an ``Idempotency-Key``, a retry of the same body answers what the
first request did instead of refunding again.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `order_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | integer or null | no | Minor units, spread over what is left to refund. |
| `items` | array of RefundItem or null | no |  |
| `items[].order_item_id` | integer | yes |  |
| `items[].quantity` | integer | yes |  |
| `shipping` | boolean | no |  |
| `reason` | string or null | no |  |
| `note` | string or null | no |  |
| `payment_id` | integer or null | no | A second payment the order received. |
| `restock` | boolean | no | The shipped units named came back: they go back in stock first. |
| `location_id` | integer or null | no | Where restocked units go, else where they shipped. |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List price lists {#op-get-api-v1-orgs-org-slug-commerce-price-lists}

`GET /api/v1/orgs/{org_slug}/commerce/price-lists`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create price list {#op-post-api-v1-orgs-org-slug-commerce-price-lists}

`POST /api/v1/orgs/{org_slug}/commerce/price-lists`

A sale (shown against the base price as a discount) or an override (a
different price, such as a wholesale one), for everyone or for
``customer_group_ids``; a draft until ``status`` is ``active``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `description` | string or null | no |
| `kind` | string or null | no |
| `status` | string or null | no |
| `starts_at` | string (date-time) or null | no |
| `ends_at` | string (date-time) or null | no |
| `customer_group_ids` | array of integer or null | no |
| `prices` | array of object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get price list {#op-get-api-v1-orgs-org-slug-commerce-price-lists-price-list-id}

`GET /api/v1/orgs/{org_slug}/commerce/price-lists/{price_list_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `price_list_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Fields change when named; prices replaces the list's prices {#op-patch-api-v1-orgs-org-slug-commerce-price-lists-price-list-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/price-lists/{price_list_id}`

Fields change when named; ``prices`` replaces the list's prices.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `price_list_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `title` | string or null | no |
| `description` | string or null | no |
| `kind` | string or null | no |
| `status` | string or null | no |
| `starts_at` | string (date-time) or null | no |
| `ends_at` | string (date-time) or null | no |
| `customer_group_ids` | array of integer or null | no |
| `prices` | array of object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The list and its prices go; base prices are untouched {#op-delete-api-v1-orgs-org-slug-commerce-price-lists-price-list-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/price-lists/{price_list_id}`

The list and its prices go; base prices are untouched.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `price_list_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Replace price list prices {#op-put-api-v1-orgs-org-slug-commerce-price-lists-price-list-id-prices}

`PUT /api/v1/orgs/{org_slug}/commerce/price-lists/{price_list_id}/prices`

The list's prices become exactly these: ``{"prices": [...]}`` or a bare
list of ``{variant_id, currency_code, amount, region_id?, min_quantity?,
max_quantity?}``, at most 5000.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `price_list_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

Type: Payload.

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The tags on live products, most used first: what a tag picker suggests {#op-get-api-v1-orgs-org-slug-commerce-product-tags}

`GET /api/v1/orgs/{org_slug}/commerce/product-tags`

The tags on live products, most used first: what a tag picker suggests.
Tags that differ only in case are one tag, as the tag filter treats them.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Newest first {#op-get-api-v1-orgs-org-slug-commerce-promotions}

`GET /api/v1/orgs/{org_slug}/commerce/promotions`

Newest first.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no | The start of a code, or words in the description. |
| `status` | query | string or null | no |  |
| `is_automatic` | query | boolean or null | no |  |
| `before_id` | query | integer or null | no |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A code (or an automatic promotion) {#op-post-api-v1-orgs-org-slug-commerce-promotions}

`POST /api/v1/orgs/{org_slug}/commerce/promotions`

A code (or an automatic promotion). It starts as ``draft`` unless ``status`` says otherwise.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string or null | no |
| `description` | string or null | no |
| `status` | string or null | no |
| `value_type` | string | yes |
| `percentage` | number or string or null | no |
| `amount` | integer or null | no |
| `currency_code` | string or null | no |
| `target` | string or null | no |
| `conditions` | object or null | no |
| `usage_limit` | integer or null | no |
| `per_customer_limit` | integer or null | no |
| `starts_at` | string (date-time) or null | no |
| `ends_at` | string (date-time) or null | no |
| `combinable` | boolean or null | no |
| `metadata` | object or null | no |
| `is_automatic` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The promotion and what it has given, per currency {#op-get-api-v1-orgs-org-slug-commerce-promotions-promotion-id}

`GET /api/v1/orgs/{org_slug}/commerce/promotions/{promotion_id}`

The promotion and what it has given, per currency.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `promotion_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update promotion {#op-patch-api-v1-orgs-org-slug-commerce-promotions-promotion-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/promotions/{promotion_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `promotion_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string or null | no |
| `description` | string or null | no |
| `status` | string or null | no |
| `value_type` | string or null | no |
| `percentage` | number or string or null | no |
| `amount` | integer or null | no |
| `currency_code` | string or null | no |
| `target` | string or null | no |
| `conditions` | object or null | no |
| `usage_limit` | integer or null | no |
| `per_customer_limit` | integer or null | no |
| `starts_at` | string (date-time) or null | no |
| `ends_at` | string (date-time) or null | no |
| `combinable` | boolean or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A promotion no order used {#op-delete-api-v1-orgs-org-slug-commerce-promotions-promotion-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/promotions/{promotion_id}`

A promotion no order used. One that was used is disabled instead, so its history stays.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `promotion_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List keys {#op-get-api-v1-orgs-org-slug-commerce-publishable-keys}

`GET /api/v1/orgs/{org_slug}/commerce/publishable-keys`

#### 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. |

### A key for a storefront {#op-post-api-v1-orgs-org-slug-commerce-publishable-keys}

`POST /api/v1/orgs/{org_slug}/commerce/publishable-keys`

A key for a storefront. A live key works once the store is live.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | yes |
| `livemode` | boolean | no |
| `sales_channel_ids` | array of integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Revoke key {#op-delete-api-v1-orgs-org-slug-commerce-publishable-keys-key-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/publishable-keys/{key_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `key_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every region of the store, disabled ones included {#op-get-api-v1-orgs-org-slug-commerce-regions}

`GET /api/v1/orgs/{org_slug}/commerce/regions`

Every region of the store, disabled ones included.

#### 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. |

### A region {#op-post-api-v1-orgs-org-slug-commerce-regions}

`POST /api/v1/orgs/{org_slug}/commerce/regions`

A region. The store's first enabled region becomes its default unless
``is_default`` is false.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `currency_code` | string or null | no |
| `countries` | array of string or null | no |
| `automatic_taxes` | boolean or null | no |
| `tax_inclusive` | boolean or null | no |
| `payment_providers` | array of string or null | no |
| `is_disabled` | boolean or null | no |
| `is_default` | boolean or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get region {#op-get-api-v1-orgs-org-slug-commerce-regions-region-id}

`GET /api/v1/orgs/{org_slug}/commerce/regions/{region_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `region_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Fields change when named; countries replaces the region's {#op-patch-api-v1-orgs-org-slug-commerce-regions-region-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/regions/{region_id}`

Fields change when named; ``countries`` replaces the region's.
``is_default: true`` makes it the store's default region; the default
region cannot be disabled (make another the default first).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `region_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `currency_code` | string or null | no |
| `countries` | array of string or null | no |
| `automatic_taxes` | boolean or null | no |
| `tax_inclusive` | boolean or null | no |
| `payment_providers` | array of string or null | no |
| `is_disabled` | boolean or null | no |
| `is_default` | boolean or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The region, its countries and the prices set for it go {#op-delete-api-v1-orgs-org-slug-commerce-regions-region-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/regions/{region_id}`

The region, its countries and the prices set for it go. The store's
default region cannot be deleted (make another the default first).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `region_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every reason, disabled ones included, in the order shoppers see them {#op-get-api-v1-orgs-org-slug-commerce-return-reasons}

`GET /api/v1/orgs/{org_slug}/commerce/return-reasons`

Every reason, disabled ones included, in the order shoppers see them.

#### 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. |

### A reason shoppers may pick for a return {#op-post-api-v1-orgs-org-slug-commerce-return-reasons}

`POST /api/v1/orgs/{org_slug}/commerce/return-reasons`

A reason shoppers may pick for a return. Its ``code`` never changes,
since returns name it; a code the store already has answers 409
``reason_code_taken``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | Lowercase letters, digits, - and _. |
| `label` | string | yes |  |
| `description` | string or null | no |  |
| `rank` | integer | no |  |
| `is_disabled` | boolean | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Label, description, rank or whether shoppers may pick it; the code never changes {#op-patch-api-v1-orgs-org-slug-commerce-return-reasons-reason-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/return-reasons/{reason_id}`

Label, description, rank or whether shoppers may pick it; the code never changes.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reason_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string or null | no | Never changes; sent only to be refused. |
| `label` | string or null | no |  |
| `description` | string or null | no |  |
| `rank` | integer or null | no |  |
| `is_disabled` | boolean or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete return reason {#op-delete-api-v1-orgs-org-slug-commerce-return-reasons-reason-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/return-reasons/{reason_id}`

Deletes a reason no return names; one a return names is disabled
instead (``deleted: false``), so those returns still read it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `reason_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Newest first; count is every return the filters match {#op-get-api-v1-orgs-org-slug-commerce-returns}

`GET /api/v1/orgs/{org_slug}/commerce/returns`

Newest first; ``count`` is every return the filters match.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no | One of requested, approved, rejected, received, refunded, completed, canceled. |
| `kind` | query | string or null | no | One of return, exchange, claim. |
| `order` | query | string or null | no | An order's id or order_... public id. |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create return {#op-post-api-v1-orgs-org-slug-commerce-returns}

`POST /api/v1/orgs/{org_slug}/commerce/returns`

A return, exchange or claim the store opens for shipped units: approved
at once, outside the shoppers' returns window. A claim (units damaged or
lost after they shipped) brings nothing back and is settled by the refund
route: refunded, or replaced on an exchange order.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `order_id` | integer or string | yes | The order's id or its order_... public id. |
| `kind` | string or null | no | return, exchange or claim; exchange when exchange_items are named. |
| `claim_type` | string or null | no | A claim is settled by a refund or by replacing the units. |
| `items` | array of ReturnItemIn | yes |  |
| `items[].order_item_id` | integer | yes |  |
| `items[].quantity` | integer | yes |  |
| `items[].reason_code` | string or null | no | The code of a return reason. |
| `items[].note` | string or null | no |  |
| `exchange_items` | array of ExchangeItemIn or null | no |  |
| `exchange_items[].variant_id` | integer | yes |  |
| `exchange_items[].quantity` | integer | yes |  |
| `restocking_fee` | integer or null | no | Minor units kept back from the refund. |
| `shipping_deduction` | integer or null | no | Minor units kept back from the refund. |
| `waive_difference` | boolean | no | Send an exchange's dearer new items without collecting the difference. |
| `location_id` | integer or null | no | Where sellable units go back in stock. |
| `instructions` | string or null | no |  |
| `label_url` | string or null | no | An https:// return label. |
| `note` | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get return {#op-get-api-v1-orgs-org-slug-commerce-returns-return-id}

`GET /api/v1/orgs/{org_slug}/commerce/returns/{return_id}`

The return with each unit it names, how many came back and in what
condition, an exchange's new items and order, and what it refunds.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `return_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Approve return {#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-approve}

`POST /api/v1/orgs/{org_slug}/commerce/returns/{return_id}/approve`

Accept a requested return, with any restocking fee and shipping
deduction (kept back from its refund) and how to send the goods back. A
3PL that shipped them and takes returns is sent ``return.requested``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `return_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `restocking_fee` | integer or null | no |
| `shipping_deduction` | integer or null | no |
| `waive_difference` | boolean | no |
| `location_id` | integer or null | no |
| `instructions` | string or null | no |
| `label_url` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### End a return before its goods are in, or a claim before it is settled {#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-cancel}

`POST /api/v1/orgs/{org_slug}/commerce/returns/{return_id}/cancel`

End a return before its goods are in, or a claim before it is settled.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `return_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Receive return {#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-receive}

`POST /api/v1/orgs/{org_slug}/commerce/returns/{return_id}/receive`

The goods are back: sellable units go back in stock, damaged ones are
counted as returned only. An exchange's new items go out on an exchange
order; its difference is refunded now when the caller may refund, and
``refund_error`` says why when that refund could not be made.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `return_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of ReceivedItemIn or null | no | Omit to receive every unit as sellable. An item may appear once per condition. |
| `items[].order_item_id` | integer | yes |  |
| `items[].quantity` | integer | yes |  |
| `items[].condition` | string | no | sellable goes back in stock; damaged does not. |
| `location_id` | integer or null | no | Where sellable units go, else the return's location, else where they shipped from. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Refund return {#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-refund}

`POST /api/v1/orgs/{org_slug}/commerce/returns/{return_id}/refund`

Settle the return: refund what the received units are worth less the
fee and deduction (an exchange: less its new items), refund or replace a
claim, or complete it when nothing is left to refund. The refund goes
through the order's refunds, with its credit note and ledger entries.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `return_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string or null | no |  |
| `note` | string or null | no |  |
| `waive_difference` | boolean | no | Send an exchange's dearer new items anyway. |
| `as_return` | boolean | no | Refund an exchange's received units instead of sending its new items; only before its exchange order exists. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Decline a requested return; the shopper reads the reason {#op-post-api-v1-orgs-org-slug-commerce-returns-return-id-reject}

`POST /api/v1/orgs/{org_slug}/commerce/returns/{return_id}/reject`

Decline a requested return; the shopper reads the reason.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `return_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | yes | The shopper reads it. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List channels {#op-get-api-v1-orgs-org-slug-commerce-sales-channels}

`GET /api/v1/orgs/{org_slug}/commerce/sales-channels`

#### 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. |

### Create channel {#op-post-api-v1-orgs-org-slug-commerce-sales-channels}

`POST /api/v1/orgs/{org_slug}/commerce/sales-channels`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `description` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update channel {#op-patch-api-v1-orgs-org-slug-commerce-sales-channels-channel-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/sales-channels/{channel_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `channel_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `description` | string or null | no |
| `is_disabled` | boolean or null | no |
| `is_default` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete channel {#op-delete-api-v1-orgs-org-slug-commerce-sales-channels-channel-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/sales-channels/{channel_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `channel_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The locations a channel sells from {#op-get-api-v1-orgs-org-slug-commerce-sales-channels-channel-id-stock-locations}

`GET /api/v1/orgs/{org_slug}/commerce/sales-channels/{channel_id}/stock-locations`

The locations a channel sells from. None named means every enabled location.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `channel_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The channel sells from exactly these locations; an empty list means every enabled location {#op-put-api-v1-orgs-org-slug-commerce-sales-channels-channel-id-stock-locations}

`PUT /api/v1/orgs/{org_slug}/commerce/sales-channels/{channel_id}/stock-locations`

The channel sells from exactly these locations; an empty list means
every enabled location.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `channel_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `location_ids` | array of integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List options {#op-get-api-v1-orgs-org-slug-commerce-shipping-options}

`GET /api/v1/orgs/{org_slug}/commerce/shipping-options`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `zone_id` | query | integer or null | no |
| `profile_id` | query | integer or null | no |
| `is_return` | query | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### An option in a zone for a profile (the default one when profileid is left out) {#op-post-api-v1-orgs-org-slug-commerce-shipping-options}

`POST /api/v1/orgs/{org_slug}/commerce/shipping-options`

An option in a zone for a profile (the default one when ``profile_id`` is left out).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `profile_id` | integer or null | no |
| `price_type` | string or null | no |
| `currency_code` | string | yes |
| `amount` | integer or null | no |
| `free_over_amount` | integer or null | no |
| `tiers` | array of object or null | no |
| `min_subtotal` | integer or null | no |
| `max_subtotal` | integer or null | no |
| `is_return` | boolean or null | no |
| `is_pickup` | boolean or null | no |
| `delivery_min_days` | integer or null | no |
| `delivery_max_days` | integer or null | no |
| `tax_code` | string or null | no |
| `is_disabled` | boolean or null | no |
| `rank` | integer or null | no |
| `provider_id` | integer or null | no |
| `provider_code` | string or null | no |
| `metadata` | object or null | no |
| `zone_id` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get option {#op-get-api-v1-orgs-org-slug-commerce-shipping-options-option-id}

`GET /api/v1/orgs/{org_slug}/commerce/shipping-options/{option_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `option_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update option {#op-patch-api-v1-orgs-org-slug-commerce-shipping-options-option-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/shipping-options/{option_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `option_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `profile_id` | integer or null | no |
| `price_type` | string or null | no |
| `currency_code` | string or null | no |
| `amount` | integer or null | no |
| `free_over_amount` | integer or null | no |
| `tiers` | array of object or null | no |
| `min_subtotal` | integer or null | no |
| `max_subtotal` | integer or null | no |
| `is_return` | boolean or null | no |
| `is_pickup` | boolean or null | no |
| `delivery_min_days` | integer or null | no |
| `delivery_max_days` | integer or null | no |
| `tax_code` | string or null | no |
| `is_disabled` | boolean or null | no |
| `rank` | integer or null | no |
| `provider_id` | integer or null | no |
| `provider_code` | string or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Carts that chose it choose again; orders keep the name and amount they were charged {#op-delete-api-v1-orgs-org-slug-commerce-shipping-options-option-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/shipping-options/{option_id}`

Carts that chose it choose again; orders keep the name and amount they were charged.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `option_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every profile, the default first {#op-get-api-v1-orgs-org-slug-commerce-shipping-profiles}

`GET /api/v1/orgs/{org_slug}/commerce/shipping-profiles`

Every profile, the default first. Products that name none ship under the default.

#### 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. |

### Create profile {#op-post-api-v1-orgs-org-slug-commerce-shipping-profiles}

`POST /api/v1/orgs/{org_slug}/commerce/shipping-profiles`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `kind` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update profile {#op-patch-api-v1-orgs-org-slug-commerce-shipping-profiles-profile-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/shipping-profiles/{profile_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `profile_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A profile no product and no option uses {#op-delete-api-v1-orgs-org-slug-commerce-shipping-profiles-profile-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/shipping-profiles/{profile_id}`

A profile no product and no option uses. The default profile stays.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `profile_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every zone, with how many options each holds {#op-get-api-v1-orgs-org-slug-commerce-shipping-zones}

`GET /api/v1/orgs/{org_slug}/commerce/shipping-zones`

Every zone, with how many options each holds.

#### 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. |

### Create zone {#op-post-api-v1-orgs-org-slug-commerce-shipping-zones}

`POST /api/v1/orgs/{org_slug}/commerce/shipping-zones`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `geo` | array of object | yes |
| `location_id` | integer or null | no |
| `is_disabled` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get zone {#op-get-api-v1-orgs-org-slug-commerce-shipping-zones-zone-id}

`GET /api/v1/orgs/{org_slug}/commerce/shipping-zones/{zone_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Update zone {#op-patch-api-v1-orgs-org-slug-commerce-shipping-zones-zone-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/shipping-zones/{zone_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `geo` | array of object or null | no |
| `location_id` | integer or null | no |
| `is_disabled` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The zone and its options {#op-delete-api-v1-orgs-org-slug-commerce-shipping-zones-zone-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/shipping-zones/{zone_id}`

The zone and its options. Carts that chose one of them choose again.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Every location, the default first, with the channels that sell from it {#op-get-api-v1-orgs-org-slug-commerce-stock-locations}

`GET /api/v1/orgs/{org_slug}/commerce/stock-locations`

Every location, the default first, with the channels that sell from it.

#### 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. |

### A warehouse, shop or 3PL site {#op-post-api-v1-orgs-org-slug-commerce-stock-locations}

`POST /api/v1/orgs/{org_slug}/commerce/stock-locations`

A warehouse, shop or 3PL site. The store's first enabled location
becomes its default unless the body says ``is_default: false``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `address` | object or null | no |
| `is_default` | boolean or null | no |
| `is_disabled` | boolean or null | no |
| `fulfillment_provider_id` | integer or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get location {#op-get-api-v1-orgs-org-slug-commerce-stock-locations-location-id}

`GET /api/v1/orgs/{org_slug}/commerce/stock-locations/{location_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `location_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Isdefault: true moves the default here {#op-patch-api-v1-orgs-org-slug-commerce-stock-locations-location-id}

`PATCH /api/v1/orgs/{org_slug}/commerce/stock-locations/{location_id}`

``is_default: true`` moves the default here. The default location cannot
be disabled or stop being the default on its own: make another the default.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `location_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `address` | object or null | no |
| `is_default` | boolean or null | no |
| `is_disabled` | boolean or null | no |
| `fulfillment_provider_id` | integer or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete location {#op-delete-api-v1-orgs-org-slug-commerce-stock-locations-location-id}

`DELETE /api/v1/orgs/{org_slug}/commerce/stock-locations/{location_id}`

Only an empty location nothing refers to can go: no stock or reservations
held there, no shipping zone shipping from it, no fulfillment or return
naming it. Disable it instead to stop selling from it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `location_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The store, its sales channels, and where its merchant review stands {#op-get-api-v1-orgs-org-slug-commerce-store}

`GET /api/v1/orgs/{org_slug}/commerce/store`

The store, its sales channels, and where its merchant review stands.

#### 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. |

### Update store {#op-patch-api-v1-orgs-org-slug-commerce-store}

`PATCH /api/v1/orgs/{org_slug}/commerce/store`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `default_currency` | string or null | no |
| `supported_currencies` | array of string or null | no |
| `default_locale` | string or null | no |
| `supported_locales` | array of string or null | no |
| `allowed_origins` | array of string or null | no |
| `storefront_url` | string or null | no |
| `support_email` | string or null | no |
| `settings` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Tax report {#op-get-api-v1-orgs-org-slug-commerce-tax-reports}

`GET /api/v1/orgs/{org_slug}/commerce/tax-reports`

The tax charged on the store's sales, from its issued invoices and
credit notes, per seller entity, period, jurisdiction and rate.
``format=csv`` is the same rows as a file.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `from` | query | string | yes | Included: 2026-07-01, UTC. |
| `to` | query | string | yes | Excluded: 2026-10-01, UTC. |
| `bucket` | query | string | no | Default: `month`. |
| `seller_entity_key` | query | string or null | no |  |
| `country_code` | query | string or null | no |  |
| `subdivision_code` | query | string or null | no |  |
| `format` | query | string | no | Default: `json`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Commerce Store API

> Every Organization API operation tagged Commerce Store API.

Source: https://www.coritan.com/docs/api/reference/organizations/commerce-store-api/

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}/store`](#op-get-api-v1-orgs-org-slug-store) | Store info |
| POST | [`/api/v1/orgs/{org_slug}/store/carts`](#op-post-api-v1-orgs-org-slug-store-carts) | A cart in the key's mode and sales channel, in a region and its currency |
| GET | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}`](#op-get-api-v1-orgs-org-slug-store-carts-cart-id) | Get cart |
| PATCH | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}`](#op-patch-api-v1-orgs-org-slug-store-carts-cart-id) | Email, addresses, region or country (re-prices every line), note, locale, metadata |
| POST | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/complete`](#op-post-api-v1-orgs-org-slug-store-carts-cart-id-complete) | Place the cart's order: {"order", "accesstoken"} |
| POST | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/gift-cards`](#op-post-api-v1-orgs-org-slug-store-carts-cart-id-gift-cards) | Apply a gift card by its code: 10 attempts per 10 minutes per cart and per client IP |
| DELETE | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/gift-cards/{gift_card_id}`](#op-delete-api-v1-orgs-org-slug-store-carts-cart-id-gift-cards-gift-card-id) | Remove gift card |
| POST | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/line-items`](#op-post-api-v1-orgs-org-slug-store-carts-cart-id-line-items) | Add a variant; the same variant with the same metadata merges into its line |
| PATCH | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/line-items/{line_id}`](#op-patch-api-v1-orgs-org-slug-store-carts-cart-id-line-items-line-id) | Set a line's quantity; 0 removes it |
| DELETE | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/line-items/{line_id}`](#op-delete-api-v1-orgs-org-slug-store-carts-cart-id-line-items-line-id) | Delete line item |
| GET | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/payment-providers`](#op-get-api-v1-orgs-org-slug-store-carts-cart-id-payment-providers) | The providers that can take this cart's payment, and whether it needs one |
| POST | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/payment-sessions`](#op-post-api-v1-orgs-org-slug-store-carts-cart-id-payment-sessions) | Start the payment with provider, or refresh the one already started for the same amount |
| POST | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/promotions`](#op-post-api-v1-orgs-org-slug-store-carts-cart-id-promotions) | Apply a code |
| DELETE | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/promotions`](#op-delete-api-v1-orgs-org-slug-store-carts-cart-id-promotions) | Remove a code, named in the body {"code"} or as ?code= |
| POST | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/shipping-methods`](#op-post-api-v1-orgs-org-slug-store-carts-cart-id-shipping-methods) | Choose an option; it replaces the method its shipping profile had |
| GET | [`/api/v1/orgs/{org_slug}/store/carts/{cart_id}/shipping-options`](#op-get-api-v1-orgs-org-slug-store-carts-cart-id-shipping-options) | The options the cart's address and items allow, priced for them, per shipping profile |
| GET | [`/api/v1/orgs/{org_slug}/store/categories`](#op-get-api-v1-orgs-org-slug-store-categories) | The active, public categories as a tree |
| GET | [`/api/v1/orgs/{org_slug}/store/categories/{handle}`](#op-get-api-v1-orgs-org-slug-store-categories-handle) | Get category |
| GET | [`/api/v1/orgs/{org_slug}/store/collections`](#op-get-api-v1-orgs-org-slug-store-collections) | List collections |
| GET | [`/api/v1/orgs/{org_slug}/store/collections/{handle}`](#op-get-api-v1-orgs-org-slug-store-collections-handle) | A published collection; its products are /store/products?collectionhandle= |
| POST | [`/api/v1/orgs/{org_slug}/store/orders/lookup`](#op-post-api-v1-orgs-org-slug-store-orders-lookup) | Look up orders |
| GET | [`/api/v1/orgs/{org_slug}/store/orders/{order_id}`](#op-get-api-v1-orgs-org-slug-store-orders-order-id) | Get order |
| GET | [`/api/v1/orgs/{org_slug}/store/orders/{order_id}/documents`](#op-get-api-v1-orgs-org-slug-store-orders-order-id-documents) | The invoice and credit notes, as issued by the seller of record |
| GET | [`/api/v1/orgs/{org_slug}/store/orders/{order_id}/returns`](#op-get-api-v1-orgs-org-slug-store-orders-order-id-returns) | The order's returns, oldest first |
| POST | [`/api/v1/orgs/{org_slug}/store/orders/{order_id}/returns`](#op-post-api-v1-orgs-org-slug-store-orders-order-id-returns) | Request return |
| GET | [`/api/v1/orgs/{org_slug}/store/regions`](#op-get-api-v1-orgs-org-slug-store-regions) | The regions the store sells in, to pick a country and currency from |
| GET | [`/api/v1/orgs/{org_slug}/store/regions/{region_id}`](#op-get-api-v1-orgs-org-slug-store-regions-region-id) | Get region |
| GET | [`/api/v1/orgs/{org_slug}/store/return-reasons`](#op-get-api-v1-orgs-org-slug-store-return-reasons) | List return reasons |

### Store info {#op-get-api-v1-orgs-org-slug-store}

`GET /api/v1/orgs/{org_slug}/store`

#### 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. |

### A cart in the key's mode and sales channel, in a region and its currency {#op-post-api-v1-orgs-org-slug-store-carts}

`POST /api/v1/orgs/{org_slug}/store/carts`

A cart in the key's mode and sales channel, in a region and its currency.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `region_id` | integer or null | no |
| `country_code` | string or null | no |
| `currency_code` | string or null | no |
| `email` | string or null | no |
| `sales_channel_id` | integer or null | no |
| `locale` | string or null | no |
| `metadata` | object or null | no |
| `items` | array of LineItemIn or null | no |
| `items[].variant_id` | integer | yes |
| `items[].quantity` | integer | no |
| `items[].metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get cart {#op-get-api-v1-orgs-org-slug-store-carts-cart-id}

`GET /api/v1/orgs/{org_slug}/store/carts/{cart_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Email, addresses, region or country (re-prices every line), note, locale, metadata {#op-patch-api-v1-orgs-org-slug-store-carts-cart-id}

`PATCH /api/v1/orgs/{org_slug}/store/carts/{cart_id}`

Email, addresses, region or country (re-prices every line), note, locale, metadata.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string or null | no |
| `shipping_address` | object or null | no |
| `billing_address` | object or null | no |
| `region_id` | integer or null | no |
| `country_code` | string or null | no |
| `note` | string or null | no |
| `locale` | string or null | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Place the cart's order: {"order", "accesstoken"} {#op-post-api-v1-orgs-org-slug-store-carts-cart-id-complete}

`POST /api/v1/orgs/{org_slug}/store/carts/{cart_id}/complete`

Place the cart's order: ``{"order", "access_token"}``. The token is what
the shopper's order link carries (``GET /store/orders/{id}?token=``).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `accept_terms` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Apply a gift card by its code: 10 attempts per 10 minutes per cart and per client IP {#op-post-api-v1-orgs-org-slug-store-carts-cart-id-gift-cards}

`POST /api/v1/orgs/{org_slug}/store/carts/{cart_id}/gift-cards`

Apply a gift card by its code: 10 attempts per 10 minutes per cart and per client IP.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove gift card {#op-delete-api-v1-orgs-org-slug-store-carts-cart-id-gift-cards-gift-card-id}

`DELETE /api/v1/orgs/{org_slug}/store/carts/{cart_id}/gift-cards/{gift_card_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `gift_card_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add a variant; the same variant with the same metadata merges into its line {#op-post-api-v1-orgs-org-slug-store-carts-cart-id-line-items}

`POST /api/v1/orgs/{org_slug}/store/carts/{cart_id}/line-items`

Add a variant; the same variant with the same metadata merges into its line.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `variant_id` | integer | yes |
| `quantity` | integer | no |
| `metadata` | object or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set a line's quantity; 0 removes it {#op-patch-api-v1-orgs-org-slug-store-carts-cart-id-line-items-line-id}

`PATCH /api/v1/orgs/{org_slug}/store/carts/{cart_id}/line-items/{line_id}`

Set a line's quantity; 0 removes it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `line_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `quantity` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete line item {#op-delete-api-v1-orgs-org-slug-store-carts-cart-id-line-items-line-id}

`DELETE /api/v1/orgs/{org_slug}/store/carts/{cart_id}/line-items/{line_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `line_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The providers that can take this cart's payment, and whether it needs one {#op-get-api-v1-orgs-org-slug-store-carts-cart-id-payment-providers}

`GET /api/v1/orgs/{org_slug}/store/carts/{cart_id}/payment-providers`

The providers that can take this cart's payment, and whether it needs one.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Start the payment with provider, or refresh the one already started for the same amount {#op-post-api-v1-orgs-org-slug-store-carts-cart-id-payment-sessions}

`POST /api/v1/orgs/{org_slug}/store/carts/{cart_id}/payment-sessions`

Start the payment with ``provider``, or refresh the one already started
for the same amount. ``accept_terms`` records the shopper's acceptance of
the store's terms with the session.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `provider` | string | yes | stripe, paypal or manual. |
| `accept_terms` | boolean | no |  |
| `return_url` | string or null | no |  |
| `cancel_url` | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Apply a code {#op-post-api-v1-orgs-org-slug-store-carts-cart-id-promotions}

`POST /api/v1/orgs/{org_slug}/store/carts/{cart_id}/promotions`

Apply a code. 422 ``promotion_not_applicable`` says why in ``reason``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove a code, named in the body {"code"} or as ?code= {#op-delete-api-v1-orgs-org-slug-store-carts-cart-id-promotions}

`DELETE /api/v1/orgs/{org_slug}/store/carts/{cart_id}/promotions`

Remove a code, named in the body ``{"code"}`` or as ``?code=``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `code` | query | string or null | no |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Choose an option; it replaces the method its shipping profile had {#op-post-api-v1-orgs-org-slug-store-carts-cart-id-shipping-methods}

`POST /api/v1/orgs/{org_slug}/store/carts/{cart_id}/shipping-methods`

Choose an option; it replaces the method its shipping profile had.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `option_id` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The options the cart's address and items allow, priced for them, per shipping profile {#op-get-api-v1-orgs-org-slug-store-carts-cart-id-shipping-options}

`GET /api/v1/orgs/{org_slug}/store/carts/{cart_id}/shipping-options`

The options the cart's address and items allow, priced for them, per shipping profile.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `cart_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The active, public categories as a tree {#op-get-api-v1-orgs-org-slug-store-categories}

`GET /api/v1/orgs/{org_slug}/store/categories`

The active, public categories as a tree. A category that is inactive or
internal hides the categories under it too.

#### 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. |

### Get category {#op-get-api-v1-orgs-org-slug-store-categories-handle}

`GET /api/v1/orgs/{org_slug}/store/categories/{handle}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `handle` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List collections {#op-get-api-v1-orgs-org-slug-store-collections}

`GET /api/v1/orgs/{org_slug}/store/collections`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A published collection; its products are /store/products?collectionhandle= {#op-get-api-v1-orgs-org-slug-store-collections-handle}

`GET /api/v1/orgs/{org_slug}/store/collections/{handle}`

A published collection; its products are ``/store/products?collection_handle=``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `handle` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Look up orders {#op-post-api-v1-orgs-org-slug-store-orders-lookup}

`POST /api/v1/orgs/{org_slug}/store/orders/lookup`

Email the links to the orders placed with ``email`` (in the key's mode,
within the store's order link lifetime). Always ``{"sent": true}``; the
email goes out after the answer, and only when there are orders.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | yes |  |
| `order_number` | string or null | no | #1001 or 1001: only that order. |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get order {#op-get-api-v1-orgs-org-slug-store-orders-order-id}

`GET /api/v1/orgs/{org_slug}/store/orders/{order_id}`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `order_id` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `token` | query | string or null | no | The order link's token. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The invoice and credit notes, as issued by the seller of record {#op-get-api-v1-orgs-org-slug-store-orders-order-id-documents}

`GET /api/v1/orgs/{org_slug}/store/orders/{order_id}/documents`

The invoice and credit notes, as issued by the seller of record.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `order_id` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `token` | query | string or null | no | The order link's token. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The order's returns, oldest first {#op-get-api-v1-orgs-org-slug-store-orders-order-id-returns}

`GET /api/v1/orgs/{org_slug}/store/orders/{order_id}/returns`

The order's returns, oldest first.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `order_id` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `token` | query | string or null | no | The order link's token. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Request return {#op-post-api-v1-orgs-org-slug-store-orders-order-id-returns}

`POST /api/v1/orgs/{org_slug}/store/orders/{order_id}/returns`

Ask to return shipped units, or to exchange them: ``requested`` until
the store approves or declines it.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `order_id` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `token` | query | string or null | no | The order link's token. |
| `Idempotency-Key` | header | string or null | no |  |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of ReturnItemIn | yes |  |
| `items[].order_item_id` | integer | yes |  |
| `items[].quantity` | integer | yes |  |
| `items[].reason_code` | string or null | no | The code of a return reason. |
| `items[].note` | string or null | no |  |
| `exchange_items` | array of ExchangeItemIn or null | no |  |
| `exchange_items[].variant_id` | integer | yes |  |
| `exchange_items[].quantity` | integer | yes |  |
| `note` | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The regions the store sells in, to pick a country and currency from {#op-get-api-v1-orgs-org-slug-store-regions}

`GET /api/v1/orgs/{org_slug}/store/regions`

The regions the store sells in, to pick a country and currency from.

#### 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. |

### Get region {#op-get-api-v1-orgs-org-slug-store-regions-region-id}

`GET /api/v1/orgs/{org_slug}/store/regions/{region_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `region_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List return reasons {#op-get-api-v1-orgs-org-slug-store-return-reasons}

`GET /api/v1/orgs/{org_slug}/store/return-reasons`

The reasons a shopper may pick for a return, in the store's order,
leaving out those it disabled. An item's ``reason_code`` takes a ``code``.

#### 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. |

# Organization API: DNS

> Org-scoped authoritative DNS zones, records, DNSSEC, import/export, and geo load balancers.

Source: https://www.coritan.com/docs/api/reference/organizations/dns/

Org-scoped authoritative DNS zones, records, DNSSEC, import/export, and geo load balancers.

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}/dns/lb-regions`](#op-get-api-v1-orgs-org-slug-dns-lb-regions) | Org list LB regions |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones`](#op-get-api-v1-orgs-org-slug-dns-zones) | List zones |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones`](#op-post-api-v1-orgs-org-slug-dns-zones) | Create zone |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id) | Get zone |
| PATCH | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}`](#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id) | Update zone |
| DELETE | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}`](#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id) | Delete zone |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/dnssec`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-dnssec) | Get DNSSEC info |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/export`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-export) | Export zone |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/import`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-import) | Import zone |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools) | List LB pools |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools) | Create LB pool |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id) | Get LB pool |
| PATCH | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}`](#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id) | Update LB pool |
| DELETE | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}`](#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id) | Delete LB pool |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers) | Org list lbs |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers) | Org create LB |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers/{lb_id}`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers-lb-id) | Org get LB |
| PATCH | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers/{lb_id}`](#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers-lb-id) | Org update LB |
| DELETE | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers/{lb_id}`](#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers-lb-id) | Org delete LB |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers/{lb_id}/preview`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers-lb-id-preview) | Org preview LB |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-pools) | Org list pools |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-pools) | Org create pool |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id) | Org get pool |
| PATCH | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}`](#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id) | Org update pool |
| DELETE | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}`](#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id) | Org delete pool |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-records) | List records |
| POST | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records`](#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-records) | Create record |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records/{record_id}`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-records-record-id) | Get record |
| PUT | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records/{record_id}`](#op-put-api-v1-orgs-org-slug-dns-zones-zone-id-records-record-id) | Update record |
| DELETE | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records/{record_id}`](#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-records-record-id) | Delete record |
| GET | [`/api/v1/orgs/{org_slug}/dns/zones/{zone_id}/stats`](#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-stats) | Get zone stats |

### Org list LB regions {#op-get-api-v1-orgs-org-slug-dns-lb-regions}

`GET /api/v1/orgs/{org_slug}/dns/lb-regions`

#### 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. |

### List zones {#op-get-api-v1-orgs-org-slug-dns-zones}

`GET /api/v1/orgs/{org_slug}/dns/zones`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `25`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].service_id` | integer or null |
| `[].user_id` | integer |
| `[].org_id` | integer or null |
| `[].domain` | string |
| `[].status` | string |
| `[].dnssec_enabled` | boolean |
| `[].serial` | integer |
| `[].soa_email` | string |
| `[].record_count` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create zone {#op-post-api-v1-orgs-org-slug-dns-zones}

`POST /api/v1/orgs/{org_slug}/dns/zones`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `service_id` | integer or null |
| `user_id` | integer |
| `org_id` | integer or null |
| `domain` | string |
| `status` | string |
| `dnssec_enabled` | boolean |
| `serial` | integer |
| `soa_email` | string |
| `record_count` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Get zone {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `service_id` | integer or null |
| `user_id` | integer |
| `org_id` | integer or null |
| `domain` | string |
| `status` | string |
| `dnssec_enabled` | boolean |
| `serial` | integer |
| `soa_email` | string |
| `record_count` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update zone {#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id}

`PATCH /api/v1/orgs/{org_slug}/dns/zones/{zone_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `soa_email` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `service_id` | integer or null |
| `user_id` | integer |
| `org_id` | integer or null |
| `domain` | string |
| `status` | string |
| `dnssec_enabled` | boolean |
| `serial` | integer |
| `soa_email` | string |
| `record_count` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete zone {#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id}

`DELETE /api/v1/orgs/{org_slug}/dns/zones/{zone_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get DNSSEC info {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-dnssec}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/dnssec`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `enabled` | boolean |
| `algorithm` | string |
| `ksk_key_tag` | integer or null |
| `zsk_key_tag` | integer or null |
| `ds_records` | array of string |
| `zsk_rotated_at` | string (date-time) or null |

### Export zone {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-export}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/export`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Import zone {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-import}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/import`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `zone_file` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List LB pools {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].zone_id` | integer |
| `[].name` | string |
| `[].description` | string or null |
| `[].hostname` | string or null |
| `[].algorithm` | string |
| `[].ttl` | integer |
| `[].session_affinity` | string |
| `[].primary_location_code` | string or null |
| `[].enabled` | boolean |
| `[].members` | array of LbMemberResponse |
| `[].members[].id` | integer |
| `[].members[].pool_id` | integer |
| `[].members[].address` | string |
| `[].members[].address_type` | string |
| `[].members[].weight` | integer |
| `[].members[].priority` | integer |
| `[].members[].enabled` | boolean |
| `[].members[].health_mode` | string |
| `[].members[].health_port` | integer or null |
| `[].members[].health_path` | string |
| `[].members[].health_interval_s` | integer |
| `[].members[].health_timeout_s` | integer |
| `[].members[].health_status` | string |
| `[].members[].last_check_at` | string (date-time) or null |
| `[].members[].last_error` | string or null |
| `[].members[].created_at` | string (date-time) |
| `[].members[].updated_at` | string (date-time) |
| `[].healthy_members` | integer or null |
| `[].total_members` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create LB pool {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `description` | string or null | no |
| `hostname` | string or null | no |
| `algorithm` | string | no |
| `ttl` | integer | no |
| `session_affinity` | string | no |
| `primary_location_code` | string or null | no |
| `enabled` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Get LB pool {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update LB pool {#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id}

`PATCH /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `description` | string or null | no |
| `algorithm` | string or null | no |
| `ttl` | integer or null | no |
| `session_affinity` | string or null | no |
| `primary_location_code` | string or null | no |
| `enabled` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete LB pool {#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-lb-pools-pool-id}

`DELETE /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/lb-pools/{pool_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org list lbs {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].zone_id` | integer |
| `[].name` | string |
| `[].hostname` | string |
| `[].enabled` | boolean |
| `[].ttl` | integer |
| `[].session_affinity` | string |
| `[].steering_policy` | string |
| `[].location_strategy` | string |
| `[].fallback_pool_id` | integer or null |
| `[].default_pools` | array of integer |
| `[].location_pools` | Location Pools |
| `[].country_pools` | Country Pools |
| `[].region_pools` | Region Pools |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Org create LB {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `hostname` | string | yes |
| `ttl` | integer | no |
| `session_affinity` | string | no |
| `steering_policy` | string | no |
| `location_strategy` | string | no |
| `default_pools` | array of integer | no |
| `fallback_pool_id` | integer or null | no |
| `location_pools` | Location Pools | no |
| `country_pools` | Country Pools | no |
| `region_pools` | Region Pools | no |
| `enabled` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `hostname` | string |
| `enabled` | boolean |
| `ttl` | integer |
| `session_affinity` | string |
| `steering_policy` | string |
| `location_strategy` | string |
| `fallback_pool_id` | integer or null |
| `default_pools` | array of integer |
| `location_pools` | Location Pools |
| `country_pools` | Country Pools |
| `region_pools` | Region Pools |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org get LB {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers-lb-id}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers/{lb_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `lb_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `hostname` | string |
| `enabled` | boolean |
| `ttl` | integer |
| `session_affinity` | string |
| `steering_policy` | string |
| `location_strategy` | string |
| `fallback_pool_id` | integer or null |
| `default_pools` | array of integer |
| `location_pools` | Location Pools |
| `country_pools` | Country Pools |
| `region_pools` | Region Pools |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org update LB {#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers-lb-id}

`PATCH /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers/{lb_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `lb_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `hostname` | string or null | no |
| `ttl` | integer or null | no |
| `session_affinity` | string or null | no |
| `steering_policy` | string or null | no |
| `location_strategy` | string or null | no |
| `default_pools` | array of integer or null | no |
| `fallback_pool_id` | integer or null | no |
| `location_pools` | object or null | no |
| `country_pools` | object or null | no |
| `region_pools` | object or null | no |
| `enabled` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `hostname` | string |
| `enabled` | boolean |
| `ttl` | integer |
| `session_affinity` | string |
| `steering_policy` | string |
| `location_strategy` | string |
| `fallback_pool_id` | integer or null |
| `default_pools` | array of integer |
| `location_pools` | Location Pools |
| `country_pools` | Country Pools |
| `region_pools` | Region Pools |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org delete LB {#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers-lb-id}

`DELETE /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers/{lb_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `lb_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org preview LB {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-load-balancers-lb-id-preview}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/load-balancers/{lb_id}/preview`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `lb_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from_location` | string or null | no |
| `from_ip` | string or null | no |
| `qtype` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org list pools {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-pools}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].zone_id` | integer |
| `[].name` | string |
| `[].description` | string or null |
| `[].hostname` | string or null |
| `[].algorithm` | string |
| `[].ttl` | integer |
| `[].session_affinity` | string |
| `[].primary_location_code` | string or null |
| `[].enabled` | boolean |
| `[].members` | array of LbMemberResponse |
| `[].members[].id` | integer |
| `[].members[].pool_id` | integer |
| `[].members[].address` | string |
| `[].members[].address_type` | string |
| `[].members[].weight` | integer |
| `[].members[].priority` | integer |
| `[].members[].enabled` | boolean |
| `[].members[].health_mode` | string |
| `[].members[].health_port` | integer or null |
| `[].members[].health_path` | string |
| `[].members[].health_interval_s` | integer |
| `[].members[].health_timeout_s` | integer |
| `[].members[].health_status` | string |
| `[].members[].last_check_at` | string (date-time) or null |
| `[].members[].last_error` | string or null |
| `[].members[].created_at` | string (date-time) |
| `[].members[].updated_at` | string (date-time) |
| `[].healthy_members` | integer or null |
| `[].total_members` | integer or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Org create pool {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-pools}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `description` | string or null | no |
| `hostname` | string or null | no |
| `algorithm` | string | no |
| `ttl` | integer | no |
| `session_affinity` | string | no |
| `primary_location_code` | string or null | no |
| `enabled` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org get pool {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org update pool {#op-patch-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id}

`PATCH /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string or null | no |
| `description` | string or null | no |
| `algorithm` | string or null | no |
| `ttl` | integer or null | no |
| `session_affinity` | string or null | no |
| `primary_location_code` | string or null | no |
| `enabled` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `description` | string or null |
| `hostname` | string or null |
| `algorithm` | string |
| `ttl` | integer |
| `session_affinity` | string |
| `primary_location_code` | string or null |
| `enabled` | boolean |
| `members` | array of LbMemberResponse |
| `members[].id` | integer |
| `members[].pool_id` | integer |
| `members[].address` | string |
| `members[].address_type` | string |
| `members[].weight` | integer |
| `members[].priority` | integer |
| `members[].enabled` | boolean |
| `members[].health_mode` | string |
| `members[].health_port` | integer or null |
| `members[].health_path` | string |
| `members[].health_interval_s` | integer |
| `members[].health_timeout_s` | integer |
| `members[].health_status` | string |
| `members[].last_check_at` | string (date-time) or null |
| `members[].last_error` | string or null |
| `members[].created_at` | string (date-time) |
| `members[].updated_at` | string (date-time) |
| `healthy_members` | integer or null |
| `total_members` | integer or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Org delete pool {#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-pools-pool-id}

`DELETE /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/pools/{pool_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `pool_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List records {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-records}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `zone_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `record_type` | query | string | no |  |
| `name` | query | string | no |  |
| `page` | query | integer | no | Default: `1`. |
| `per_page` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].zone_id` | integer |
| `[].name` | string |
| `[].record_type` | string |
| `[].content` | string |
| `[].ttl` | integer |
| `[].priority` | integer or null |
| `[].weight` | integer or null |
| `[].port` | integer or null |
| `[].proxied` | boolean |
| `[].comment` | string or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) |

### Create record {#op-post-api-v1-orgs-org-slug-dns-zones-zone-id-records}

`POST /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `record_type` | string | yes |
| `content` | string | yes |
| `ttl` | integer | no |
| `priority` | integer or null | no |
| `weight` | integer or null | no |
| `port` | integer or null | no |
| `proxied` | boolean | no |
| `comment` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `201` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `record_type` | string |
| `content` | string |
| `ttl` | integer |
| `priority` | integer or null |
| `weight` | integer or null |
| `port` | integer or null |
| `proxied` | boolean |
| `comment` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Get record {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-records-record-id}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records/{record_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `record_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `record_type` | string |
| `content` | string |
| `ttl` | integer |
| `priority` | integer or null |
| `weight` | integer or null |
| `port` | integer or null |
| `proxied` | boolean |
| `comment` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Update record {#op-put-api-v1-orgs-org-slug-dns-zones-zone-id-records-record-id}

`PUT /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records/{record_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `record_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `content` | string or null | no |
| `ttl` | integer or null | no |
| `priority` | integer or null | no |
| `weight` | integer or null | no |
| `port` | integer or null | no |
| `proxied` | boolean or null | no |
| `comment` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `zone_id` | integer |
| `name` | string |
| `record_type` | string |
| `content` | string |
| `ttl` | integer |
| `priority` | integer or null |
| `weight` | integer or null |
| `port` | integer or null |
| `proxied` | boolean |
| `comment` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) |

### Delete record {#op-delete-api-v1-orgs-org-slug-dns-zones-zone-id-records-record-id}

`DELETE /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/records/{record_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `zone_id` | path | integer | yes |
| `record_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get zone stats {#op-get-api-v1-orgs-org-slug-dns-zones-zone-id-stats}

`GET /api/v1/orgs/{org_slug}/dns/zones/{zone_id}/stats`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `zone_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `hours` | query | integer | no | Default: `24`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `zone_id` | integer |
| `period_hours` | integer |
| `total_queries` | integer |
| `noerror` | integer |
| `nxdomain` | integer |
| `servfail` | integer |
| `by_type` | By Type |
| `hourly` | array of object |

# Organization API: Discord

> Your own Discord bot: application credentials, the staff channel that receives tickets, and which Discord accounts are staff.

Source: https://www.coritan.com/docs/api/reference/organizations/discord/

Your own Discord bot: application credentials, the staff channel that receives tickets, and which Discord accounts are staff. The bot token is write-only: we store it encrypted and never return it.

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}/discord`](#op-get-api-v1-orgs-org-slug-discord) | Get discord config |
| PUT | [`/api/v1/orgs/{org_slug}/discord`](#op-put-api-v1-orgs-org-slug-discord) | Put discord config |
| DELETE | [`/api/v1/orgs/{org_slug}/discord`](#op-delete-api-v1-orgs-org-slug-discord) | Switch the bot off and forget the token |
| POST | [`/api/v1/orgs/{org_slug}/discord/community/sync-channels`](#op-post-api-v1-orgs-org-slug-discord-community-sync-channels) | Rebuild the public-channel allowlist from Discord's own permissions |
| GET | [`/api/v1/orgs/{org_slug}/discord/diagnostics`](#op-get-api-v1-orgs-org-slug-discord-diagnostics) | Probe the bot, the guild, the staff channel and the job queue |
| POST | [`/api/v1/orgs/{org_slug}/discord/register-commands`](#op-post-api-v1-orgs-org-slug-discord-register-commands) | Register commands |
| GET | [`/api/v1/orgs/{org_slug}/discord/role-menus`](#op-get-api-v1-orgs-org-slug-discord-role-menus) | List role menus |
| POST | [`/api/v1/orgs/{org_slug}/discord/role-menus`](#op-post-api-v1-orgs-org-slug-discord-role-menus) | Create role menu |
| PUT | [`/api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}`](#op-put-api-v1-orgs-org-slug-discord-role-menus-menu-id) | Update role menu |
| DELETE | [`/api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}`](#op-delete-api-v1-orgs-org-slug-discord-role-menus-menu-id) | Delete role menu |
| POST | [`/api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}/publish`](#op-post-api-v1-orgs-org-slug-discord-role-menus-menu-id-publish) | Post the menu to its channel, or edit the message already posted for it |
| GET | [`/api/v1/orgs/{org_slug}/discord/roles`](#op-get-api-v1-orgs-org-slug-discord-roles) | The roles in the org's guild, so a menu can be built by picking not typing |
| GET | [`/api/v1/orgs/{org_slug}/discord/staff`](#op-get-api-v1-orgs-org-slug-discord-staff) | List staff links |
| PUT | [`/api/v1/orgs/{org_slug}/discord/staff`](#op-put-api-v1-orgs-org-slug-discord-staff) | Put staff link |
| DELETE | [`/api/v1/orgs/{org_slug}/discord/staff/{discord_user_id}`](#op-delete-api-v1-orgs-org-slug-discord-staff-discord-user-id) | Delete staff link |

### Get discord config {#op-get-api-v1-orgs-org-slug-discord}

`GET /api/v1/orgs/{org_slug}/discord`

#### 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. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `configured` | boolean |
| `application_id` | string or null |
| `public_key` | string or null |
| `guild_id` | string or null |
| `staff_channel_id` | string or null |
| `staff_channel_kind` | string |
| `is_enabled` | boolean |
| `has_bot_token` | boolean |
| `commands_registered_at` | string (date-time) or null |
| `interactions_url` | string or null |
| `last_error` | string or null |
| `gateway_status` | string |
| `bot_user_id` | string or null |
| `ticket_channels_enabled` | boolean |
| `ticket_category_prefix` | string |
| `staff_role_id` | string or null |
| `max_ticket_channels` | integer |
| `community_chat_enabled` | boolean |
| `community_invite_url` | string or null |
| `community_hidden_channels` | array of string |

### Put discord config {#op-put-api-v1-orgs-org-slug-discord}

`PUT /api/v1/orgs/{org_slug}/discord`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `application_id` | string | yes |
| `public_key` | string | yes |
| `bot_token` | string or null | no |
| `guild_id` | string or null | no |
| `staff_channel_id` | string or null | no |
| `staff_channel_kind` | string or null | no |
| `is_enabled` | boolean or null | no |
| `ticket_channels_enabled` | boolean or null | no |
| `ticket_category_prefix` | string or null | no |
| `staff_role_id` | string or null | no |
| `max_ticket_channels` | integer or null | no |
| `community_chat_enabled` | boolean or null | no |
| `community_invite_url` | string or null | no |
| `community_hidden_channels` | array of string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `configured` | boolean |
| `application_id` | string or null |
| `public_key` | string or null |
| `guild_id` | string or null |
| `staff_channel_id` | string or null |
| `staff_channel_kind` | string |
| `is_enabled` | boolean |
| `has_bot_token` | boolean |
| `commands_registered_at` | string (date-time) or null |
| `interactions_url` | string or null |
| `last_error` | string or null |
| `gateway_status` | string |
| `bot_user_id` | string or null |
| `ticket_channels_enabled` | boolean |
| `ticket_category_prefix` | string |
| `staff_role_id` | string or null |
| `max_ticket_channels` | integer |
| `community_chat_enabled` | boolean |
| `community_invite_url` | string or null |
| `community_hidden_channels` | array of string |

### Switch the bot off and forget the token {#op-delete-api-v1-orgs-org-slug-discord}

`DELETE /api/v1/orgs/{org_slug}/discord`

Switch the bot off and forget the token.

The row stays so the channel and application ids do not have to be re-entered,
but the credential does not linger on a disabled integration.

#### 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. |

### Rebuild the public-channel allowlist from Discord's own permissions {#op-post-api-v1-orgs-org-slug-discord-community-sync-channels}

`POST /api/v1/orgs/{org_slug}/discord/community/sync-channels`

Rebuild the public-channel allowlist from Discord's own permissions.

#### 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. |

### Probe the bot, the guild, the staff channel and the job queue {#op-get-api-v1-orgs-org-slug-discord-diagnostics}

`GET /api/v1/orgs/{org_slug}/discord/diagnostics`

Probe the bot, the guild, the staff channel and the job queue.

Answers "why did my ticket not appear in Discord?" without needing shell access.

#### 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. |

### Register commands {#op-post-api-v1-orgs-org-slug-discord-register-commands}

`POST /api/v1/orgs/{org_slug}/discord/register-commands`

#### 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. |

### List role menus {#op-get-api-v1-orgs-org-slug-discord-role-menus}

`GET /api/v1/orgs/{org_slug}/discord/role-menus`

#### 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. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].channel_id` | string or null |
| `[].menu_key` | string or null |
| `[].message_id` | string or null |
| `[].title` | string |
| `[].description` | string or null |
| `[].options` | array of RoleOption |
| `[].options[].role_id` | string |
| `[].options[].label` | string |
| `[].options[].key` | string or null |
| `[].options[].emoji` | string or null |
| `[].options[].description` | string or null |
| `[].is_enabled` | boolean |
| `[].published` | boolean |

### Create role menu {#op-post-api-v1-orgs-org-slug-discord-role-menus}

`POST /api/v1/orgs/{org_slug}/discord/role-menus`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `channel_id` | string or null | no |
| `menu_key` | string or null | no |
| `title` | string | yes |
| `description` | string or null | no |
| `options` | array of RoleOption | no |
| `options[].role_id` | string | yes |
| `options[].label` | string | yes |
| `options[].key` | string or null | no |
| `options[].emoji` | string or null | no |
| `options[].description` | string or null | no |
| `is_enabled` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `channel_id` | string or null |
| `menu_key` | string or null |
| `message_id` | string or null |
| `title` | string |
| `description` | string or null |
| `options` | array of RoleOption |
| `options[].role_id` | string |
| `options[].label` | string |
| `options[].key` | string or null |
| `options[].emoji` | string or null |
| `options[].description` | string or null |
| `is_enabled` | boolean |
| `published` | boolean |

### Update role menu {#op-put-api-v1-orgs-org-slug-discord-role-menus-menu-id}

`PUT /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `menu_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `channel_id` | string or null | no |
| `menu_key` | string or null | no |
| `title` | string | yes |
| `description` | string or null | no |
| `options` | array of RoleOption | no |
| `options[].role_id` | string | yes |
| `options[].label` | string | yes |
| `options[].key` | string or null | no |
| `options[].emoji` | string or null | no |
| `options[].description` | string or null | no |
| `is_enabled` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `channel_id` | string or null |
| `menu_key` | string or null |
| `message_id` | string or null |
| `title` | string |
| `description` | string or null |
| `options` | array of RoleOption |
| `options[].role_id` | string |
| `options[].label` | string |
| `options[].key` | string or null |
| `options[].emoji` | string or null |
| `options[].description` | string or null |
| `is_enabled` | boolean |
| `published` | boolean |

### Delete role menu {#op-delete-api-v1-orgs-org-slug-discord-role-menus-menu-id}

`DELETE /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `menu_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Post the menu to its channel, or edit the message already posted for it {#op-post-api-v1-orgs-org-slug-discord-role-menus-menu-id-publish}

`POST /api/v1/orgs/{org_slug}/discord/role-menus/{menu_id}/publish`

Post the menu to its channel, or edit the message already posted for it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `menu_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The roles in the org's guild, so a menu can be built by picking not typing {#op-get-api-v1-orgs-org-slug-discord-roles}

`GET /api/v1/orgs/{org_slug}/discord/roles`

The roles in the org's guild, so a menu can be built by picking not typing.

#### 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. |

### List staff links {#op-get-api-v1-orgs-org-slug-discord-staff}

`GET /api/v1/orgs/{org_slug}/discord/staff`

#### 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. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].discord_user_id` | string |
| `[].user_id` | integer or null |
| `[].admin_user_id` | integer or null |
| `[].role` | string |
| `[].email` | string or null |

### Put staff link {#op-put-api-v1-orgs-org-slug-discord-staff}

`PUT /api/v1/orgs/{org_slug}/discord/staff`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `discord_user_id` | string | yes |
| `user_id` | integer or null | no |
| `admin_user_id` | integer or null | no |
| `role` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `discord_user_id` | string |
| `user_id` | integer or null |
| `admin_user_id` | integer or null |
| `role` | string |
| `email` | string or null |

### Delete staff link {#op-delete-api-v1-orgs-org-slug-discord-staff-discord-user-id}

`DELETE /api/v1/orgs/{org_slug}/discord/staff/{discord_user_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `discord_user_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Cloud Compute

> Every Organization API operation tagged Org Cloud Compute.

Source: https://www.coritan.com/docs/api/reference/organizations/org-cloud-compute/

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}/vps`](#op-get-api-v1-orgs-org-slug-vps) | Org list instances |
| GET | [`/api/v1/orgs/{org_slug}/vps/templates`](#op-get-api-v1-orgs-org-slug-vps-templates) | Org list templates |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}`](#op-get-api-v1-orgs-org-slug-vps-uuid) | Org get instance |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/backups`](#op-get-api-v1-orgs-org-slug-vps-uuid-backups) | Org list backups |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/backups`](#op-post-api-v1-orgs-org-slug-vps-uuid-backups) | Org create backup |
| DELETE | [`/api/v1/orgs/{org_slug}/vps/{uuid}/backups/{backup_id}`](#op-delete-api-v1-orgs-org-slug-vps-uuid-backups-backup-id) | Org delete backup |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/backups/{backup_id}/restore`](#op-post-api-v1-orgs-org-slug-vps-uuid-backups-backup-id-restore) | Org restore backup |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/bandwidth`](#op-get-api-v1-orgs-org-slug-vps-uuid-bandwidth) | Org bandwidth |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/cloud-init/regenerate`](#op-post-api-v1-orgs-org-slug-vps-uuid-cloud-init-regenerate) | Org regenerate cloud init |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/config`](#op-get-api-v1-orgs-org-slug-vps-uuid-config) | Org config |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/console`](#op-get-api-v1-orgs-org-slug-vps-uuid-console) | Org console |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/graphs`](#op-get-api-v1-orgs-org-slug-vps-uuid-graphs) | Org graphs |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/guest`](#op-get-api-v1-orgs-org-slug-vps-uuid-guest) | Org guest |
| PATCH | [`/api/v1/orgs/{org_slug}/vps/{uuid}/hostname`](#op-patch-api-v1-orgs-org-slug-vps-uuid-hostname) | Org hostname |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/ips`](#op-get-api-v1-orgs-org-slug-vps-uuid-ips) | Org IPs |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/power`](#op-post-api-v1-orgs-org-slug-vps-uuid-power) | Org power |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/rebuild`](#op-post-api-v1-orgs-org-slug-vps-uuid-rebuild) | Org rebuild |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/rescue/enter`](#op-post-api-v1-orgs-org-slug-vps-uuid-rescue-enter) | Org rescue enter |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/rescue/exit`](#op-post-api-v1-orgs-org-slug-vps-uuid-rescue-exit) | Org rescue exit |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/rescue/media`](#op-get-api-v1-orgs-org-slug-vps-uuid-rescue-media) | Org rescue media |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/reset-password`](#op-post-api-v1-orgs-org-slug-vps-uuid-reset-password) | Org reset password |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/snapshots`](#op-get-api-v1-orgs-org-slug-vps-uuid-snapshots) | Org list snapshots |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/snapshots`](#op-post-api-v1-orgs-org-slug-vps-uuid-snapshots) | Org create snapshot |
| DELETE | [`/api/v1/orgs/{org_slug}/vps/{uuid}/snapshots/{snapshot_id}`](#op-delete-api-v1-orgs-org-slug-vps-uuid-snapshots-snapshot-id) | Org delete snapshot |
| POST | [`/api/v1/orgs/{org_slug}/vps/{uuid}/snapshots/{snapshot_id}/rollback`](#op-post-api-v1-orgs-org-slug-vps-uuid-snapshots-snapshot-id-rollback) | Org rollback snapshot |
| PUT | [`/api/v1/orgs/{org_slug}/vps/{uuid}/ssh-keys`](#op-put-api-v1-orgs-org-slug-vps-uuid-ssh-keys) | Org SSH keys |
| GET | [`/api/v1/orgs/{org_slug}/vps/{uuid}/status`](#op-get-api-v1-orgs-org-slug-vps-uuid-status) | Org status |

### Org list instances {#op-get-api-v1-orgs-org-slug-vps}

`GET /api/v1/orgs/{org_slug}/vps`

#### 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. |

### Org list templates {#op-get-api-v1-orgs-org-slug-vps-templates}

`GET /api/v1/orgs/{org_slug}/vps/templates`

#### 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. |

### Org get instance {#op-get-api-v1-orgs-org-slug-vps-uuid}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org list backups {#op-get-api-v1-orgs-org-slug-vps-uuid-backups}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/backups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org create backup {#op-post-api-v1-orgs-org-slug-vps-uuid-backups}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/backups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `note` | string or null | no |
| `mode` | string | no |
| `compress` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org delete backup {#op-delete-api-v1-orgs-org-slug-vps-uuid-backups-backup-id}

`DELETE /api/v1/orgs/{org_slug}/vps/{uuid}/backups/{backup_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org restore backup {#op-post-api-v1-orgs-org-slug-vps-uuid-backups-backup-id-restore}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/backups/{backup_id}/restore`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org bandwidth {#op-get-api-v1-orgs-org-slug-vps-uuid-bandwidth}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/bandwidth`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org regenerate cloud init {#op-post-api-v1-orgs-org-slug-vps-uuid-cloud-init-regenerate}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/cloud-init/regenerate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org config {#op-get-api-v1-orgs-org-slug-vps-uuid-config}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/config`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org console {#op-get-api-v1-orgs-org-slug-vps-uuid-console}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/console`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org graphs {#op-get-api-v1-orgs-org-slug-vps-uuid-graphs}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/graphs`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `timeframe` | query | string | no | Default: `hour`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org guest {#op-get-api-v1-orgs-org-slug-vps-uuid-guest}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/guest`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org hostname {#op-patch-api-v1-orgs-org-slug-vps-uuid-hostname}

`PATCH /api/v1/orgs/{org_slug}/vps/{uuid}/hostname`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |
| `reboot` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org IPs {#op-get-api-v1-orgs-org-slug-vps-uuid-ips}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/ips`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org power {#op-post-api-v1-orgs-org-slug-vps-uuid-power}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/power`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `action` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org rebuild {#op-post-api-v1-orgs-org-slug-vps-uuid-rebuild}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/rebuild`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `template_id` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org rescue enter {#op-post-api-v1-orgs-org-slug-vps-uuid-rescue-enter}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/rescue/enter`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `iso_volid` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org rescue exit {#op-post-api-v1-orgs-org-slug-vps-uuid-rescue-exit}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/rescue/exit`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org rescue media {#op-get-api-v1-orgs-org-slug-vps-uuid-rescue-media}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/rescue/media`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org reset password {#op-post-api-v1-orgs-org-slug-vps-uuid-reset-password}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/reset-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org list snapshots {#op-get-api-v1-orgs-org-slug-vps-uuid-snapshots}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/snapshots`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org create snapshot {#op-post-api-v1-orgs-org-slug-vps-uuid-snapshots}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/snapshots`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `description` | string or null | no |
| `vmstate` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org delete snapshot {#op-delete-api-v1-orgs-org-slug-vps-uuid-snapshots-snapshot-id}

`DELETE /api/v1/orgs/{org_slug}/vps/{uuid}/snapshots/{snapshot_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org rollback snapshot {#op-post-api-v1-orgs-org-slug-vps-uuid-snapshots-snapshot-id-rollback}

`POST /api/v1/orgs/{org_slug}/vps/{uuid}/snapshots/{snapshot_id}/rollback`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org SSH keys {#op-put-api-v1-orgs-org-slug-vps-uuid-ssh-keys}

`PUT /api/v1/orgs/{org_slug}/vps/{uuid}/ssh-keys`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `ssh_keys` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org status {#op-get-api-v1-orgs-org-slug-vps-uuid-status}

`GET /api/v1/orgs/{org_slug}/vps/{uuid}/status`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Community Forum

> Every Organization API operation tagged Org Community Forum.

Source: https://www.coritan.com/docs/api/reference/organizations/org-community-forum/

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}/admin/community/forum/seo`](#op-get-api-v1-orgs-org-slug-admin-community-forum-seo) | Org admin seo summary |
| POST | [`/api/v1/orgs/{org_slug}/admin/community/forum/seo/preview`](#op-post-api-v1-orgs-org-slug-admin-community-forum-seo-preview) | Score one thread or member against the current policy, showing the working |
| POST | [`/api/v1/orgs/{org_slug}/admin/community/forum/seo/rescore`](#op-post-api-v1-orgs-org-slug-admin-community-forum-seo-rescore) | Org admin rescore |

### Org admin seo summary {#op-get-api-v1-orgs-org-slug-admin-community-forum-seo}

`GET /api/v1/orgs/{org_slug}/admin/community/forum/seo`

#### 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. |

### Score one thread or member against the current policy, showing the working {#op-post-api-v1-orgs-org-slug-admin-community-forum-seo-preview}

`POST /api/v1/orgs/{org_slug}/admin/community/forum/seo/preview`

Score one thread or member against the current policy, showing the working.

The same function the sitemap uses, so "why is this not indexed" has one
answer rather than a guess and a different code path.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `thread_id` | query | integer or null | no |
| `handle` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org admin rescore {#op-post-api-v1-orgs-org-slug-admin-community-forum-seo-rescore}

`POST /api/v1/orgs/{org_slug}/admin/community/forum/seo/rescore`

#### 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. |

# Organization API: Org Community Guides

> Every Organization API operation tagged Org Community Guides.

Source: https://www.coritan.com/docs/api/reference/organizations/org-community-guides/

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 |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/admin/community/guides/articles/{article_id}/approve`](#op-post-api-v1-orgs-org-slug-admin-community-guides-articles-article-id-approve) | Org admin approve |
| POST | [`/api/v1/orgs/{org_slug}/admin/community/guides/articles/{article_id}/reject`](#op-post-api-v1-orgs-org-slug-admin-community-guides-articles-article-id-reject) | Org admin reject |
| GET | [`/api/v1/orgs/{org_slug}/admin/community/guides/moderators`](#op-get-api-v1-orgs-org-slug-admin-community-guides-moderators) | List moderators |
| POST | [`/api/v1/orgs/{org_slug}/admin/community/guides/moderators`](#op-post-api-v1-orgs-org-slug-admin-community-guides-moderators) | Add moderator |
| DELETE | [`/api/v1/orgs/{org_slug}/admin/community/guides/moderators/{org_customer_id}`](#op-delete-api-v1-orgs-org-slug-admin-community-guides-moderators-org-customer-id) | Remove moderator |

### Org admin approve {#op-post-api-v1-orgs-org-slug-admin-community-guides-articles-article-id-approve}

`POST /api/v1/orgs/{org_slug}/admin/community/guides/articles/{article_id}/approve`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Org admin reject {#op-post-api-v1-orgs-org-slug-admin-community-guides-articles-article-id-reject}

`POST /api/v1/orgs/{org_slug}/admin/community/guides/articles/{article_id}/reject`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List moderators {#op-get-api-v1-orgs-org-slug-admin-community-guides-moderators}

`GET /api/v1/orgs/{org_slug}/admin/community/guides/moderators`

#### 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. |

### Add moderator {#op-post-api-v1-orgs-org-slug-admin-community-guides-moderators}

`POST /api/v1/orgs/{org_slug}/admin/community/guides/moderators`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `org_customer_id` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove moderator {#op-delete-api-v1-orgs-org-slug-admin-community-guides-moderators-org-customer-id}

`DELETE /api/v1/orgs/{org_slug}/admin/community/guides/moderators/{org_customer_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Container Catalog

> Every Organization API operation tagged Org Container Catalog.

Source: https://www.coritan.com/docs/api/reference/organizations/org-container-catalog/

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}/containers/catalog`](#op-get-api-v1-orgs-org-slug-containers-catalog) | Browse platform + this org's specializations for versioned deploy UX |
| GET | [`/api/v1/orgs/{org_slug}/containers/catalog/{slug}/compose`](#op-get-api-v1-orgs-org-slug-containers-catalog-slug-compose) | Compose versions + recommended runtimes for an org-visible specialization |

### Browse platform + this org's specializations for versioned deploy UX {#op-get-api-v1-orgs-org-slug-containers-catalog}

`GET /api/v1/orgs/{org_slug}/containers/catalog`

Browse platform + this org's specializations for versioned deploy UX.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `category` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].uuid` | string |
| `[].slug` | string or null |
| `[].name` | string |
| `[].description` | string or null |
| `[].runtime_template_slug` | string or null |
| `[].org_id` | integer or null |
| `[].default_variables` | object or null |
| `[].metadata` | object or null |
| `[].category` | string or null |
| `[].versioned` | boolean |
| `[].version_variable` | string or null |
| `[].version_source_slug` | string or null |
| `[].software_identifier` | string or null |
| `[].runtime_family` | string or null |
| `[].icon_url` | string or null |
| `[].color` | string or null |
| `[].group` | string or null |
| `[].deprecated` | boolean |

### Compose versions + recommended runtimes for an org-visible specialization {#op-get-api-v1-orgs-org-slug-containers-catalog-slug-compose}

`GET /api/v1/orgs/{org_slug}/containers/catalog/{slug}/compose`

Compose versions + recommended runtimes for an org-visible specialization.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `slug` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `supported_only` | query | boolean | no | Default: `True`. |
| `include_snapshots` | query | boolean | no | Default: `False`. |
| `limit` | query | integer | no | Default: `200`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `slug` | string or null |
| `uuid` | string |
| `name` | string |
| `description` | string or null |
| `runtime_template_slug` | string or null |
| `default_variables` | object or null |
| `metadata` | object or null |
| `category` | string or null |
| `versioned` | boolean |
| `version_variable` | string or null |
| `version_source_slug` | string or null |
| `software_identifier` | string or null |
| `adapter_type` | string or null |
| `runtime_family` | string or null |
| `versions` | array of CatalogVersionOption |
| `versions[].version_id` | string |
| `versions[].name` | string |
| `versions[].release_date` | string or null |
| `versions[].supported` | boolean or null |
| `versions[].required_java` | integer or null |
| `versions[].build_number` | integer or null |
| `versions[].recommended_runtime_slug` | string or null |
| `versions[].recommended_runtime_uuid` | string or null |
| `versions[].recommended_runtime_name` | string or null |
| `versions[].game_versions` | array of string |
| `versions[].metadata` | object or null |
| `versions[].runtime_template_slug` | string or null |
| `versions[].runtime_template_uuid` | string or null |
| `runtime_versions` | array of CatalogVersionOption |
| `runtime_versions[].version_id` | string |
| `runtime_versions[].name` | string |
| `runtime_versions[].release_date` | string or null |
| `runtime_versions[].supported` | boolean or null |
| `runtime_versions[].required_java` | integer or null |
| `runtime_versions[].build_number` | integer or null |
| `runtime_versions[].recommended_runtime_slug` | string or null |
| `runtime_versions[].recommended_runtime_uuid` | string or null |
| `runtime_versions[].recommended_runtime_name` | string or null |
| `runtime_versions[].game_versions` | array of string |
| `runtime_versions[].metadata` | object or null |
| `runtime_versions[].runtime_template_slug` | string or null |
| `runtime_versions[].runtime_template_uuid` | string or null |
| `runtimes` | array of CatalogRuntimeOption |
| `runtimes[].uuid` | string |
| `runtimes[].slug` | string |
| `runtimes[].name` | string |
| `runtimes[].docker_image` | string or null |
| `runtimes[].description` | string or null |
| `defaults` | Defaults |

# Organization API: Org Mail

> Every Organization API operation tagged Org Mail.

Source: https://www.coritan.com/docs/api/reference/organizations/org-mail/

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Mail](/docs/api/reference/organizations/org-mail/mail/) | 45 |

# Organization API: Org Mail: Mail

> The 45 Organization API operations for mail.

Source: https://www.coritan.com/docs/api/reference/organizations/org-mail/mail/

Part of [Org Mail](/docs/api/reference/organizations/org-mail/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/mail/overview`](#op-get-api-v1-orgs-org-slug-mail-overview) | Org mail overview |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants`](#op-get-api-v1-orgs-org-slug-mail-tenants) | List org tenants |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id) | Get summary |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/aliases`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-aliases) | List aliases |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/aliases`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-aliases) | Create alias |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/aliases/{account_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-aliases-account-id) | Delete alias |
| PATCH | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/category`](#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-category) | Set category |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials) | List credentials |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials) | Create credential |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials/{account_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials-account-id) | Delete credential |
| PATCH | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials/{account_id}/enabled`](#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials-account-id-enabled) | Credential enabled |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials/{account_id}/rotate`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials-account-id-rotate) | Rotate credential |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains) | List domains |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains) | Add domain |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains/{domain_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains-domain-id) | Remove domain |
| PATCH | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains/{domain_id}/dmarc`](#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains-domain-id-dmarc) | Set DMARC |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains/{domain_id}/records`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains-domain-id-records) | Domain records |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains/{domain_id}/verify`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains-domain-id-verify) | Verify domain |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/events`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-events) | List events |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/limits/increase-request`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-limits-increase-request) | Request limit increase |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes) | List mailboxes |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes) | Create mailbox |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id) | Delete mailbox |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/app-passwords`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-app-passwor) | Mailbox app passwords |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/app-passwords`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-app-passwo) | Mailbox app password create |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/app-passwords/{credential_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-app-pass) | Mailbox app password delete |
| PATCH | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/enabled`](#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-enabled) | Mailbox enabled |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports) | Mailbox imports |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports) | Mailbox import start |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports/oauth`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports-oa) | Mailbox import sign in |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports/upload`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports-up) | Mailbox import upload |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports/{import_id}/{action}`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports-im) | Mailbox import steer |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/password`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-password) | Mailbox password |
| PATCH | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/quota`](#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-quota) | Mailbox quota |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/sessions`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-sessions) | Mailbox sessions |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/sessions`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-sessions) | Mailbox sessions end |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/sessions/{session_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-sessions) | Mailbox session end |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/totp`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-totp) | Mailbox totp enable |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/totp`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-totp) | Mailbox totp disable |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/messages`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-messages) | Send message |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/reputation`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-reputation) | Reputation report |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/suppressions`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-suppressions) | List suppressions |
| POST | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/suppressions`](#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-suppressions) | Add suppression |
| DELETE | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/suppressions/{suppression_id}`](#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-suppressions-suppression-id) | Remove suppression |
| GET | [`/api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/usage`](#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-usage) | Usage report |

### Org mail overview {#op-get-api-v1-orgs-org-slug-mail-overview}

`GET /api/v1/orgs/{org_slug}/mail/overview`

#### 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. |

### List org tenants {#op-get-api-v1-orgs-org-slug-mail-tenants}

`GET /api/v1/orgs/{org_slug}/mail/tenants`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `customer_id` | query | integer or null | no |  |
| `kind` | query | string or null | no |  |
| `q` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get summary {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List aliases {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-aliases}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/aliases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create alias {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-aliases}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/aliases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `targets` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete alias {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-aliases-account-id}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/aliases/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set category {#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-category}

`PATCH /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/category`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `default_category` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List credentials {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create credential {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `label` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete credential {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials-account-id}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Credential enabled {#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials-account-id-enabled}

`PATCH /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials/{account_id}/enabled`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rotate credential {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-credentials-account-id-rotate}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/credentials/{account_id}/rotate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List domains {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add domain {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain` | string | yes |
| `primary` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove domain {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains-domain-id}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains/{domain_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set DMARC {#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains-domain-id-dmarc}

`PATCH /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains/{domain_id}/dmarc`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `stage` | string or null | no |
| `pinned` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Domain records {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains-domain-id-records}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains/{domain_id}/records`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Verify domain {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-domains-domain-id-verify}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/domains/{domain_id}/verify`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `domain_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List events {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-events}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/events`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `tenant_id` | path | integer | yes |  |
| `category` | query | string or null | no |  |
| `recipient` | query | string or null | no |  |
| `hours` | query | integer | no | Default: `24`. |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Request limit increase {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-limits-increase-request}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/limits/increase-request`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `requested_per_hour` | integer | yes |  |
| `reason` | string | no | What the relay sends and why the volume is going up |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List mailboxes {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create mailbox {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `domain_id` | integer | yes |
| `local_part` | string | yes |
| `password` | string or null | no |
| `display_name` | string or null | no |
| `quota_bytes` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete mailbox {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app passwords {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-app-passwor}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/app-passwords`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app password create {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-app-passwo}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/app-passwords`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `label` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox app password delete {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-app-pass}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/app-passwords/{credential_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `credential_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox enabled {#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-enabled}

`PATCH /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/enabled`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox imports {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import start {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `preset` | string | no |
| `host` | string or null | no |
| `username` | string | yes |
| `password` | string | yes |
| `folders` | array of string | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import sign in {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports-oa}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports/oauth`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `provider` | string, one of `google`, `microsoft` | yes |
| `return_path` | string or null | no |
| `since` | string (date) or null | no |
| `until` | string (date) or null | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import upload {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports-up}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports/upload`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `file` | string (binary) | yes |
| `kind` | string | no |
| `folder` | string | no |
| `cpanel_mailbox` | string | no |
| `trash` | boolean | no |
| `spam` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox import steer {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-imports-im}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/imports/{import_id}/{action}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `import_id` | path | integer | yes |
| `action` | path | string, one of `pause`, `resume`, `cancel` | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox password {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-password}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `password` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox quota {#op-patch-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-quota}

`PATCH /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/quota`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `quota_bytes` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox sessions {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-sessions}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox sessions end {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-sessions}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox session end {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-sessions}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/sessions/{session_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `session_id` | path | string | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `204` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox totp enable {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-totp}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/totp`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mailbox totp disable {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-mailboxes-account-id-totp}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/mailboxes/{account_id}/totp`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `account_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Send message {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-messages}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/messages`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `from` | string | yes |
| `from_name` | string or null | no |
| `to` | array of string | yes |
| `cc` | array of string | no |
| `subject` | string | no |
| `text` | string or null | no |
| `html` | string or null | no |
| `reply_to` | string or null | no |
| `headers` | Headers | no |
| `category` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `202` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Reputation report {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-reputation}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/reputation`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `tenant_id` | path | integer | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List suppressions {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-suppressions}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/suppressions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add suppression {#op-post-api-v1-orgs-org-slug-mail-tenants-tenant-id-suppressions}

`POST /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/suppressions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `address` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove suppression {#op-delete-api-v1-orgs-org-slug-mail-tenants-tenant-id-suppressions-suppression-id}

`DELETE /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/suppressions/{suppression_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `suppression_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `tenant_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Usage report {#op-get-api-v1-orgs-org-slug-mail-tenants-tenant-id-usage}

`GET /api/v1/orgs/{org_slug}/mail/tenants/{tenant_id}/usage`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `tenant_id` | path | integer | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Staff Auth

> Every Organization API operation tagged Org Staff Auth.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-auth/

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}/staff/team`](#op-get-api-v1-orgs-org-slug-staff-team) | The people a ticket can be assigned to: every member of this brand |

### The people a ticket can be assigned to: every member of this brand {#op-get-api-v1-orgs-org-slug-staff-team}

`GET /api/v1/orgs/{org_slug}/staff/team`

The people a ticket can be assigned to: every member of this brand.

Read-only and open to any staff member, because the assignee picker in the
inbox needs names and ``/members`` returns only ids. Members who have not set a
password yet are listed but flagged, so nobody hands a ticket to someone
who cannot sign in to see it.

#### 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. |

# Organization API: Org Staff Billing

> Every Organization API operation tagged Org Staff Billing.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-billing/

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}/staff/disputes`](#op-get-api-v1-orgs-org-slug-staff-disputes) | Staff disputes |
| GET | [`/api/v1/orgs/{org_slug}/staff/dunning`](#op-get-api-v1-orgs-org-slug-staff-dunning) | Staff dunning |
| GET | [`/api/v1/orgs/{org_slug}/staff/dunning/stats`](#op-get-api-v1-orgs-org-slug-staff-dunning-stats) | How many invoices the retry job holds in each state, and what they still owe |
| GET | [`/api/v1/orgs/{org_slug}/staff/transactions`](#op-get-api-v1-orgs-org-slug-staff-transactions) | Every payment, refund and wallet movement the brand has recorded |
| GET | [`/api/v1/orgs/{org_slug}/staff/transactions/export.csv`](#op-get-api-v1-orgs-org-slug-staff-transactions-export-csv) | The transactions list as it is filtered, as a CSV, for the books |
| GET | [`/api/v1/orgs/{org_slug}/staff/transactions/stats`](#op-get-api-v1-orgs-org-slug-staff-transactions-stats) | Totals per type over the window, for the strip above the list |

### Staff disputes {#op-get-api-v1-orgs-org-slug-staff-disputes}

`GET /api/v1/orgs/{org_slug}/staff/disputes`

Chargebacks against this brand's customers, with the customer and the
invoice named: ``customer_name`` (first and last name, else ``null``),
``customer_email`` and ``customer`` for the person, ``invoice_number``
beside ``org_invoice_id`` for the invoice the payment was on. It costs two
outer joins on the one statement, and nothing per row.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff dunning {#op-get-api-v1-orgs-org-slug-staff-dunning}

`GET /api/v1/orgs/{org_slug}/staff/dunning`

Invoices the retry job is working, with the stage, the next attempt and
the last error, so failing payments are a list rather than a surprise.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### How many invoices the retry job holds in each state, and what they still owe {#op-get-api-v1-orgs-org-slug-staff-dunning-stats}

`GET /api/v1/orgs/{org_slug}/staff/dunning/stats`

How many invoices the retry job holds in each state, and what they
still owe. ``owed_by_currency`` is that balance per invoice currency
(``{"USD": "32.97", "EUR": "12.99"}``, decimal strings in the currency's
own units like every amount here); ``owed`` stays as the sum across
currencies for older clients, and is only a real figure when the queue is
in one currency.

#### 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. |

### Every payment, refund and wallet movement the brand has recorded {#op-get-api-v1-orgs-org-slug-staff-transactions}

`GET /api/v1/orgs/{org_slug}/staff/transactions`

Every payment, refund and wallet movement the brand has recorded.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `type` | query | string or null | no |  |
| `gateway` | query | string or null | no |  |
| `customer_id` | query | integer or null | no |  |
| `q` | query | string or null | no |  |
| `since` | query | string (date) or null | no |  |
| `until` | query | string (date) or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The transactions list as it is filtered, as a CSV, for the books {#op-get-api-v1-orgs-org-slug-staff-transactions-export-csv}

`GET /api/v1/orgs/{org_slug}/staff/transactions/export.csv`

The transactions list as it is filtered, as a CSV, for the books.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `type` | query | string or null | no |
| `gateway` | query | string or null | no |
| `since` | query | string (date) or null | no |
| `until` | query | string (date) or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Totals per type over the window, for the strip above the list {#op-get-api-v1-orgs-org-slug-staff-transactions-stats}

`GET /api/v1/orgs/{org_slug}/staff/transactions/stats`

Totals per type over the window, for the strip above the list.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Staff Community

> Every Organization API operation tagged Org Staff Community.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-community/

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}/staff/community/forum/reports`](#op-get-api-v1-orgs-org-slug-staff-community-forum-reports) | The report queue |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/mute`](#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-mute) | Mute the member behind a report in the forum and community chat |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/quarantine`](#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-quarantine) | Take the reported post or thread off the forum until Tier 2 decides |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/remove`](#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-remove) | Delete the reported post or thread, quarantined or still up, and close every report on it |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/resolve`](#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-resolve) | Close a report without touching what it pointed at |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/restore`](#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-restore) | Put quarantined content back: the report was not worth acting on |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/forum/threads/{thread_id}/flags`](#op-post-api-v1-orgs-org-slug-staff-community-forum-threads-thread-id-flags) | Pin, lock or hide a thread |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/guides/articles/{article_id}/approve`](#op-post-api-v1-orgs-org-slug-staff-community-guides-articles-article-id-approve) | Staff approve guide |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/guides/articles/{article_id}/reject`](#op-post-api-v1-orgs-org-slug-staff-community-guides-articles-article-id-reject) | Staff reject guide |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/guides/comments/{comment_id}/approve`](#op-post-api-v1-orgs-org-slug-staff-community-guides-comments-comment-id-approve) | Staff approve guide comment |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/guides/comments/{comment_id}/reject`](#op-post-api-v1-orgs-org-slug-staff-community-guides-comments-comment-id-reject) | Staff reject guide comment |
| GET | [`/api/v1/orgs/{org_slug}/staff/community/guides/moderators`](#op-get-api-v1-orgs-org-slug-staff-community-guides-moderators) | Staff list guide moderators |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/guides/moderators`](#op-post-api-v1-orgs-org-slug-staff-community-guides-moderators) | Staff add guide moderator |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/community/guides/moderators/{customer_id}`](#op-delete-api-v1-orgs-org-slug-staff-community-guides-moderators-customer-id) | Staff remove guide moderator |
| GET | [`/api/v1/orgs/{org_slug}/staff/community/guides/queue`](#op-get-api-v1-orgs-org-slug-staff-community-guides-queue) | Staff guides queue |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/guides/reports/{report_id}/resolve`](#op-post-api-v1-orgs-org-slug-staff-community-guides-reports-report-id-resolve) | Staff resolve guide report |
| GET | [`/api/v1/orgs/{org_slug}/staff/community/listings`](#op-get-api-v1-orgs-org-slug-staff-community-listings) | Staff listings |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/community/listings/{listing_id}`](#op-patch-api-v1-orgs-org-slug-staff-community-listings-listing-id) | Staff moderate listing |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/community/listings/{listing_id}`](#op-delete-api-v1-orgs-org-slug-staff-community-listings-listing-id) | Delete a listing and its ratings |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/listings/{listing_id}/hold`](#op-post-api-v1-orgs-org-slug-staff-community-listings-listing-id-hold) | Take a listing off the public list until Tier 2 looks at it |
| POST | [`/api/v1/orgs/{org_slug}/staff/community/listings/{listing_id}/release`](#op-post-api-v1-orgs-org-slug-staff-community-listings-listing-id-release) | The hold was not warranted: the listing goes back as its owner left it |
| GET | [`/api/v1/orgs/{org_slug}/staff/community/summary`](#op-get-api-v1-orgs-org-slug-staff-community-summary) | Staff community summary |

### The report queue {#op-get-api-v1-orgs-org-slug-staff-community-forum-reports}

`GET /api/v1/orgs/{org_slug}/staff/community/forum/reports`

The report queue. ``quarantined`` is what Tier 1 hid and Tier 2 has
to decide on; each row names the member behind the reported content and
whether they are muted.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string | no | Default: `open`. |
| `page` | query | integer | no | Default: `1`. |
| `page_size` | query | integer | no | Default: `25`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Mute the member behind a report in the forum and community chat {#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-mute}

`POST /api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/mute`

Mute the member behind a report in the forum and community chat.

Tiers 1 and 2 may mute for up to a week; Tier 3 for up to a year. A mute
already running longer is left as it is. The report stays where it is,
so the content can still be quarantined or dismissed.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `report_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hours` | integer | yes |
| `reason` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Take the reported post or thread off the forum until Tier 2 decides {#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-quarantine}

`POST /api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/quarantine`

Take the reported post or thread off the forum until Tier 2 decides.

It is marked ``quarantined`` and soft-deleted, so every reader that hides
deleted content hides it with nothing else to change; restoring undoes
both. The report, and any other open report on the same content, waits
in the quarantine queue.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `report_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete the reported post or thread, quarantined or still up, and close every report on it {#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-remove}

`POST /api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/remove`

Delete the reported post or thread, quarantined or still up, and close
every report on it. It stays in the database for the record, marked
``removed``, and leaves every list and the search index.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `report_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Close a report without touching what it pointed at {#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-resolve}

`POST /api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/resolve`

Close a report without touching what it pointed at. A quarantined
report is Tier 2's to decide; restore or remove closes it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `report_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `resolution` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Put quarantined content back: the report was not worth acting on {#op-post-api-v1-orgs-org-slug-staff-community-forum-reports-report-id-restore}

`POST /api/v1/orgs/{org_slug}/staff/community/forum/reports/{report_id}/restore`

Put quarantined content back: the report was not worth acting on.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `report_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Pin, lock or hide a thread {#op-post-api-v1-orgs-org-slug-staff-community-forum-threads-thread-id-flags}

`POST /api/v1/orgs/{org_slug}/staff/community/forum/threads/{thread_id}/flags`

Pin, lock or hide a thread. Hiding soft-deletes it: the posts stay for
the record and the thread leaves every list and the search index.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `thread_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `is_sticky` | boolean or null | no |
| `is_locked` | boolean or null | no |
| `hidden` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff approve guide {#op-post-api-v1-orgs-org-slug-staff-community-guides-articles-article-id-approve}

`POST /api/v1/orgs/{org_slug}/staff/community/guides/articles/{article_id}/approve`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff reject guide {#op-post-api-v1-orgs-org-slug-staff-community-guides-articles-article-id-reject}

`POST /api/v1/orgs/{org_slug}/staff/community/guides/articles/{article_id}/reject`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `article_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff approve guide comment {#op-post-api-v1-orgs-org-slug-staff-community-guides-comments-comment-id-approve}

`POST /api/v1/orgs/{org_slug}/staff/community/guides/comments/{comment_id}/approve`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `comment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff reject guide comment {#op-post-api-v1-orgs-org-slug-staff-community-guides-comments-comment-id-reject}

`POST /api/v1/orgs/{org_slug}/staff/community/guides/comments/{comment_id}/reject`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `comment_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff list guide moderators {#op-get-api-v1-orgs-org-slug-staff-community-guides-moderators}

`GET /api/v1/orgs/{org_slug}/staff/community/guides/moderators`

#### 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. |

### Staff add guide moderator {#op-post-api-v1-orgs-org-slug-staff-community-guides-moderators}

`POST /api/v1/orgs/{org_slug}/staff/community/guides/moderators`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `customer_id` | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff remove guide moderator {#op-delete-api-v1-orgs-org-slug-staff-community-guides-moderators-customer-id}

`DELETE /api/v1/orgs/{org_slug}/staff/community/guides/moderators/{customer_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `customer_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff guides queue {#op-get-api-v1-orgs-org-slug-staff-community-guides-queue}

`GET /api/v1/orgs/{org_slug}/staff/community/guides/queue`

#### 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. |

### Staff resolve guide report {#op-post-api-v1-orgs-org-slug-staff-community-guides-reports-report-id-resolve}

`POST /api/v1/orgs/{org_slug}/staff/community/guides/reports/{report_id}/resolve`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `report_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff listings {#op-get-api-v1-orgs-org-slug-staff-community-listings}

`GET /api/v1/orgs/{org_slug}/staff/community/listings`

Every public server listing the brand's customers made, including the
unpublished, the ones staff hid and the ones held for review.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `only` | query | string | no | Default: `all`. |
| `q` | query | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff moderate listing {#op-patch-api-v1-orgs-org-slug-staff-community-listings-listing-id}

`PATCH /api/v1/orgs/{org_slug}/staff/community/listings/{listing_id}`

Hide a listing from the public list (the customer's own switch stays as
they set it), or (Tier 3) feature it at the top. Hiding or showing a held
listing is the decision the hold waited for, so it ends the hold.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `listing_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hidden` | boolean or null | no |
| `reason` | string or null | no |
| `featured` | boolean or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete a listing and its ratings {#op-delete-api-v1-orgs-org-slug-staff-community-listings-listing-id}

`DELETE /api/v1/orgs/{org_slug}/staff/community/listings/{listing_id}`

Delete a listing and its ratings. Its owner may list the server again
from scratch; one that should stay down is hidden instead. The audit row
keeps what the listing said.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `listing_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Take a listing off the public list until Tier 2 looks at it {#op-post-api-v1-orgs-org-slug-staff-community-listings-listing-id-hold}

`POST /api/v1/orgs/{org_slug}/staff/community/listings/{listing_id}/hold`

Take a listing off the public list until Tier 2 looks at it. The
reason is what the reviewer, and the listing's owner, read.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `listing_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `reason` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The hold was not warranted: the listing goes back as its owner left it {#op-post-api-v1-orgs-org-slug-staff-community-listings-listing-id-release}

`POST /api/v1/orgs/{org_slug}/staff/community/listings/{listing_id}/release`

The hold was not warranted: the listing goes back as its owner left it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `listing_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff community summary {#op-get-api-v1-orgs-org-slug-staff-community-summary}

`GET /api/v1/orgs/{org_slug}/staff/community/summary`

#### 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. |

# Organization API: Org Staff Containers

> Every Organization API operation tagged Org Staff Containers.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-containers/

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).

## Pages in this area

| Page | Operations |
| --- | --- |
| [Staff](/docs/api/reference/organizations/org-staff-containers/staff/) | 77 |

# Organization API: Org Staff Containers: Staff

> The 77 Organization API operations for staff.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-containers/staff/

Part of [Org Staff Containers](/docs/api/reference/organizations/org-staff-containers/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers`](#op-get-api-v1-orgs-org-slug-staff-servers) | Staff fleet |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/bulk`](#op-post-api-v1-orgs-org-slug-staff-servers-bulk) | Suspend, unsuspend, terminate, or ban the owners of, a selection of this brand's servers |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/heal-installs`](#op-post-api-v1-orgs-org-slug-staff-servers-heal-installs) | Staff heal installs |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/live`](#op-get-api-v1-orgs-org-slug-staff-servers-live) | Live state, usage and players for the brand's servers on one screen |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/stats`](#op-get-api-v1-orgs-org-slug-staff-servers-stats) | How many servers sit in each bucket, and the nodes they sit on |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid) | Staff server detail |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-allocations) | Staff list allocations |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-allocations) | Staff create allocation |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/available-ports`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-allocations-available-ports) | Staff available ports |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}`](#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-allocations-allocation-id) | Staff delete allocation |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}/primary`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-allocations-allocation-id-primary) | Staff set primary allocation |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}/publish-port`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-allocations-allocation-id-publish-p) | Publish a port on 25565 / 19132 of the customer's floating IP, or clear it |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-backups) | Staff list backups |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-backups) | Staff create backup |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}`](#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-backups-backup-uuid) | Staff delete backup |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}/lock`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-backups-backup-uuid-lock) | Staff toggle backup lock |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}/restore`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-backups-backup-uuid-restore) | Staff restore backup |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/command`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-command) | Staff command |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-databases) | Staff list databases |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-databases) | Staff create database |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}`](#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-databases-database-id) | Staff delete database |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/credentials`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-databases-database-id-credentials) | Staff database credentials |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/retry`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-databases-database-id-retry) | Staff retry database |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/rotate-password`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-databases-database-id-rotate-passwo) | Staff rotate database password |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/chmod`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-chmod) | Staff chmod files |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/compress`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-compress) | Staff compress files |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/contents`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-files-contents) | A file's text; below Tier 3, only inside logs/ and crash-reports/ |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/copy`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-copy) | Staff copy file |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/decompress`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-decompress) | Staff decompress file |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/delete`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-delete) | Staff delete files |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/download`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-files-download) | One file, streamed; below Tier 3, only inside logs/ and crash-reports/ |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/list`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-files-list) | A directory; below Tier 3, only inside logs/ and crash-reports/ |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/mkdir`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-mkdir) | Staff mkdir |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/pull`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-pull) | Staff pull file |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/pull/status`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-files-pull-status) | Staff pull status |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/rename`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-rename) | Staff rename files |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/upload`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-upload) | Staff upload files |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/write`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-write) | Staff write file |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/heal-install`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-heal-install) | Run the platform's install self-healing on one of this brand's servers |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/install-log`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-install-log) | Staff install log |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/permissions`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-permissions) | Staff grantable permissions |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/power`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-power) | Staff power |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/reinstall`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-reinstall) | Staff reinstall |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/resources`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-resources) | Staff resources |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/retry-install`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-retry-install) | Run the install again for a server in installfailed or stuck installing |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-schedules) | Staff list schedules |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid) | Staff get schedule |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}`](#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid) | Staff delete schedule |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/execute`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid-execute) | Staff execute schedule |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/runs`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid-runs) | Staff schedule runs |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/toggle`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid-toggle) | Pause a schedule that is hurting the server, or resume one |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/sleep`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-sleep) | Sleep and start-queue state of a free server; policy: none for a paid one |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-snapshots) | Staff list snapshots |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-snapshots) | Staff create snapshot |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/estimate`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-estimate) | Staff snapshot estimate |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}`](#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-snapshot-uuid) | Staff delete snapshot |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/download`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-snapshot-uuid-download) | Staff download snapshot |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/lock`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-snapshot-uuid-lock) | Staff toggle snapshot lock |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/restore`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-snapshot-uuid-restore) | Staff restore snapshot |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/software`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software) | Staff installed software |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/catalog`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software-catalog) | Staff software catalog |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/catalog/{key}/versions`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software-catalog-key-versions) | Staff software catalog versions |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/change`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-software-change) | Staff change software |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/context`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software-context) | Staff software context |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software-installs) | Staff software installs |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs/{install_uuid}/cancel`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-software-installs-install-uuid-canc) | Staff cancel install |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs/{install_uuid}/retry`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-software-installs-install-uuid-retr) | Staff retry install |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/startup`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-startup) | How the server starts: runtime, command (override and default), variables |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/startup`](#op-patch-api-v1-orgs-org-slug-staff-servers-uuid-startup) | Change the runtime, the startup command or the variables |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/startup-variables`](#op-patch-api-v1-orgs-org-slug-staff-servers-uuid-startup-variables) | Staff patch startup variables |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/subdomain`](#op-patch-api-v1-orgs-org-slug-staff-servers-uuid-subdomain) | Staff patch subdomain |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/users`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-users) | Staff list subusers |
| PUT | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/users/{subuser_id}`](#op-put-api-v1-orgs-org-slug-staff-servers-uuid-users-subuser-id) | Staff update subuser |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/users/{subuser_id}`](#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-users-subuser-id) | Staff remove subuser |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/wake`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-wake) | Start a sleeping free server on the customer's behalf |
| POST | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/wake-queue/kick`](#op-post-api-v1-orgs-org-slug-staff-servers-uuid-wake-queue-kick) | Staff kick wake |
| GET | [`/api/v1/orgs/{org_slug}/staff/servers/{uuid}/websocket`](#op-get-api-v1-orgs-org-slug-staff-servers-uuid-websocket) | The live console |

### Staff fleet {#op-get-api-v1-orgs-org-slug-staff-servers}

`GET /api/v1/orgs/{org_slug}/staff/servers`

Every container behind one of this brand's services, failing installs
first, newest after that. Tier 2 and above; everything that acts on a
server from here is Tier 3. ``FleetFilters`` narrows it further: by name,
owner, software, creation day, extra ports or uptime, all optional.

``status`` is the admin list's two filters in one word (:data:`STATUS_WORDS`):
a power word matches what the daemon was last seen doing, never the
lifecycle column, which reads ``running`` for a stopped server too.

``sort`` orders the whole fleet, not the page, by one of
:data:`FLEET_SORT_KEYS`, which are the admin list's words. Every key but
``players`` and ``join_address`` is a column; those two are decided from
the proxies' snapshot and the gameproxy routes over every matching id
before the page is cut, unknown last.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `status` | query | string or null | no | One bucket. The daemon's recorded power state, among servers whose lifecycle lets them run: running, offline, starting, stopping, unknown (never read). The lifecycle: installing, install_failed, suspended, transferring. The console's: attention, watch, free. Unset or all: every server. |
| `node_id` | query | integer or null | no |  |
| `customer_id` | query | integer or null | no |  |
| `customer_ids` | query | string or null | no | Comma-separated; the servers of a selection of customers, for review |
| `audience` | query | string or null | no |  |
| `sort` | query | string or null | no | Order the brand's fleet by: created, updated, name, status, players, join_address, ip, port, node, owner, template, cpu, memory, disk (in use), cpu_limit, memory_limit, disk_limit, uptime, id. Unset keeps failing installs first, newest after. |
| `dir` | query | string or null | no | asc or desc; each key has its own default (names ascending, figures descending). |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |
| `name` | query | string or null | no |  |
| `owner` | query | string or null | no |  |
| `software` | query | string or null | no |  |
| `created_after` | query | string (date) or null | no |  |
| `created_before` | query | string (date) or null | no |  |
| `min_extra_ports` | query | integer or null | no |  |
| `up_days_min` | query | integer or null | no |  |
| `cpu_window` | query | string | no | Default: `1h`. |
| `cpu_min` | query | number or null | no |  |
| `cpu_of_limit_min` | query | integer or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Suspend, unsuspend, terminate, or ban the owners of, a selection of this brand's servers {#op-post-api-v1-orgs-org-slug-staff-servers-bulk}

`POST /api/v1/orgs/{org_slug}/staff/servers/bulk`

Suspend, unsuspend, terminate, or ban the owners of, a selection of
this brand's servers.

Support may suspend and unsuspend, as they can order by order. Anything
that ends a server or an account (terminate, ban, a suspension with a
deletion date) takes an org admin who has stepped up in the last ten
minutes, the same gate the single-order terminate and the customer
standing change have. Servers outside the brand or already ending are
skipped and listed in the answer, not refused.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `uuids` | array of string | yes |
| `action` | string | yes |
| `reason` | string | yes |
| `delete_after_days` | integer or null | no |
| `open_ticket` | boolean | no |
| `notify_customer` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff heal installs {#op-post-api-v1-orgs-org-slug-staff-servers-heal-installs}

`POST /api/v1/orgs/{org_slug}/staff/servers/heal-installs`

Heal every broken install behind this brand's services, oldest first:
``install_failed`` rows and ``installing`` rows nothing has driven for 45 s.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `25`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Live state, usage and players for the brand's servers on one screen {#op-get-api-v1-orgs-org-slug-staff-servers-live}

`GET /api/v1/orgs/{org_slug}/staff/servers/live`

Live state, usage and players for the brand's servers on one screen.

The admin list's ``/servers/live`` for the brand: ``items`` maps each UUID
the daemons answered for to ``state`` (the daemon's word, or ``missing``
when it no longer knows the server), ``usage`` (the same shape as a list
row's, measured just now), ``players_online`` and ``join_address``. A
server with no answer is left out and ``degraded`` is true; the page
keeps what it had.

Only UUIDs behind one of this brand's services are asked about. One from
another brand is dropped before any daemon is spoken to and never
answered, not even with an error, so the poll cannot be used to learn
which UUIDs exist elsewhere.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `uuids` | query | string | yes | Comma-separated server UUIDs, the rows on screen; at most 100. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### How many servers sit in each bucket, and the nodes they sit on {#op-get-api-v1-orgs-org-slug-staff-servers-stats}

`GET /api/v1/orgs/{org_slug}/staff/servers/stats`

How many servers sit in each bucket, and the nodes they sit on.

A power word counts the servers its filter lists: the daemon's recorded
word, among servers whose lifecycle lets them run.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `audience` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff server detail {#op-get-api-v1-orgs-org-slug-staff-servers-uuid}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}`

One server as staff see it, with the customer who owns it named:
``customer_email`` and ``customer_name`` (first and last name, ``null``
when the account has neither) come off the one customer row the record
already loads.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff list allocations {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-allocations}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff create allocation {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-allocations}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `port` | integer or null | no |
| `notes` | string or null | no |
| `on_dedicated_ip` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff available ports {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-allocations-available-ports}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/available-ports`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff delete allocation {#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-allocations-allocation-id}

`DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff set primary allocation {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-allocations-allocation-id-primary}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}/primary`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Publish a port on 25565 / 19132 of the customer's floating IP, or clear it {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-allocations-allocation-id-publish-p}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/allocations/{allocation_id}/publish-port`

Publish a port on 25565 / 19132 of the customer's floating IP, or clear it.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `allocation_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `port` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff list backups {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-backups}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff create backup {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-backups}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `ignored_files` | array of string or null | no |
| `is_locked` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff delete backup {#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-backups-backup-uuid}

`DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff toggle backup lock {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-backups-backup-uuid-lock}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}/lock`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff restore backup {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-backups-backup-uuid-restore}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/backups/{backup_uuid}/restore`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `backup_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff command {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-command}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/command`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `command` | query | string or null | no |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `command` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff list databases {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-databases}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff create database {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-databases}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `Idempotency-Key` | header | string or null | no |

#### Request body

`application/json`

Type: object or null.

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff delete database {#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-databases-database-id}

`DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff database credentials {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-databases-database-id-credentials}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/credentials`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff retry database {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-databases-database-id-retry}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/retry`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff rotate database password {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-databases-database-id-rotate-passwo}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/databases/{database_id}/rotate-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `database_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff chmod files {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-chmod}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/chmod`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of object | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff compress files {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-compress}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/compress`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A file's text; below Tier 3, only inside logs/ and crash-reports/ {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-files-contents}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/contents`

A file's text; below Tier 3, only inside logs/ and crash-reports/.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `path` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff copy file {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-copy}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/copy`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `location` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff decompress file {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-decompress}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/decompress`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `file` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff delete files {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-delete}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/delete`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### One file, streamed; below Tier 3, only inside logs/ and crash-reports/ {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-files-download}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/download`

One file, streamed; below Tier 3, only inside logs/ and crash-reports/.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `path` | query | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A directory; below Tier 3, only inside logs/ and crash-reports/ {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-files-list}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/list`

A directory; below Tier 3, only inside logs/ and crash-reports/.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `directory` | query | string | no | Default: `/`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff mkdir {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-mkdir}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/mkdir`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `name` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff pull file {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-pull}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/pull`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `url` | string | yes |
| `destination_path` | string | yes |
| `filename` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff pull status {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-files-pull-status}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/pull/status`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff rename files {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-rename}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/rename`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `root` | string | no |
| `files` | array of object | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff upload files {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-upload}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/upload`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `directory` | query | string | no | Default: `/`. |

#### Request body

`multipart/form-data` (required)

| Field | Type | Required |
| --- | --- | --- |
| `files` | array of string (binary) | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff write file {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-files-write}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/files/write`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `path` | string | yes |
| `content` | string | no |
| `expected_hash` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Run the platform's install self-healing on one of this brand's servers {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-heal-install}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/heal-install`

Run the platform's install self-healing on one of this brand's servers.

Reads the disk first: files in place means the row is marked running with
nothing reinstalled; otherwise the install is driven again through the
retry ladder. The same code the watchdog runs, so brand staff can clear a
server that broke before it existed.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `start_after` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff install log {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-install-log}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/install-log`

What the install script printed: the log it leaves in the volume, and
the output recorded off the daemon while it ran. The daemon's own log is
read over SSH on the node and stays with the platform.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff grantable permissions {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-permissions}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/permissions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff power {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-power}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/power`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `signal` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff reinstall {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-reinstall}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/reinstall`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff resources {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-resources}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/resources`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Run the install again for a server in installfailed or stuck installing {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-retry-install}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/retry-install`

Run the install again for a server in ``install_failed`` or stuck
``installing``. Refused for a server in any other state: a reinstall of a
working server is the reinstall route, which wipes it and says so.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff list schedules {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-schedules}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].id` | integer |
| `[].uuid` | string |
| `[].server_id` | integer |
| `[].name` | string |
| `[].cron_minute` | string |
| `[].cron_hour` | string |
| `[].cron_day_of_month` | string |
| `[].cron_month` | string |
| `[].cron_day_of_week` | string |
| `[].is_active` | boolean |
| `[].only_when_online` | boolean |
| `[].is_processing` | boolean |
| `[].timezone` | string |
| `[].catch_up` | boolean |
| `[].revision` | integer |
| `[].current_run_id` | string or null |
| `[].last_run_status` | string or null |
| `[].next_run_at` | string (date-time) or null |
| `[].last_run_at` | string (date-time) or null |
| `[].last_run_failed` | boolean |
| `[].last_failure_message` | string or null |
| `[].created_at` | string (date-time) |
| `[].updated_at` | string (date-time) or null |
| `[].tasks` | array of TaskResponse |
| `[].tasks[].id` | integer |
| `[].tasks[].sequence_id` | integer |
| `[].tasks[].action` | string |
| `[].tasks[].payload` | Payload |
| `[].tasks[].time_offset` | integer |
| `[].tasks[].continue_on_failure` | boolean |
| `[].tasks[].is_queued` | boolean |

### Staff get schedule {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `cron_minute` | string |
| `cron_hour` | string |
| `cron_day_of_month` | string |
| `cron_month` | string |
| `cron_day_of_week` | string |
| `is_active` | boolean |
| `only_when_online` | boolean |
| `is_processing` | boolean |
| `timezone` | string |
| `catch_up` | boolean |
| `revision` | integer |
| `current_run_id` | string or null |
| `last_run_status` | string or null |
| `next_run_at` | string (date-time) or null |
| `last_run_at` | string (date-time) or null |
| `last_run_failed` | boolean |
| `last_failure_message` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `tasks` | array of TaskResponse |
| `tasks[].id` | integer |
| `tasks[].sequence_id` | integer |
| `tasks[].action` | string |
| `tasks[].payload` | Payload |
| `tasks[].time_offset` | integer |
| `tasks[].continue_on_failure` | boolean |
| `tasks[].is_queued` | boolean |

### Staff delete schedule {#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid}

`DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff execute schedule {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid-execute}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/execute`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `revision` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff schedule runs {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid-runs}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/runs`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `schedule_uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

A `200` response is a list; each item has these fields:

| Field | Type |
| --- | --- |
| `[].uuid` | string |
| `[].trigger` | string |
| `[].status` | string |
| `[].started_at` | string (date-time) or null |
| `[].finished_at` | string (date-time) or null |
| `[].failure_message` | string or null |
| `[].created_at` | string (date-time) or null |
| `[].steps` | array of ScheduleRunStepResponse |
| `[].steps[].task_id` | integer |
| `[].steps[].sequence_id` | integer |
| `[].steps[].action` | string |
| `[].steps[].payload` | Payload |
| `[].steps[].time_offset` | integer |
| `[].steps[].continue_on_failure` | boolean |
| `[].steps[].status` | string |
| `[].steps[].started_at` | string (date-time) or null |
| `[].steps[].finished_at` | string (date-time) or null |
| `[].steps[].error` | string or null |

### Pause a schedule that is hurting the server, or resume one {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-schedules-schedule-uuid-toggle}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/schedules/{schedule_uuid}/toggle`

Pause a schedule that is hurting the server, or resume one.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `schedule_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `is_active` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `id` | integer |
| `uuid` | string |
| `server_id` | integer |
| `name` | string |
| `cron_minute` | string |
| `cron_hour` | string |
| `cron_day_of_month` | string |
| `cron_month` | string |
| `cron_day_of_week` | string |
| `is_active` | boolean |
| `only_when_online` | boolean |
| `is_processing` | boolean |
| `timezone` | string |
| `catch_up` | boolean |
| `revision` | integer |
| `current_run_id` | string or null |
| `last_run_status` | string or null |
| `next_run_at` | string (date-time) or null |
| `last_run_at` | string (date-time) or null |
| `last_run_failed` | boolean |
| `last_failure_message` | string or null |
| `created_at` | string (date-time) |
| `updated_at` | string (date-time) or null |
| `tasks` | array of TaskResponse |
| `tasks[].id` | integer |
| `tasks[].sequence_id` | integer |
| `tasks[].action` | string |
| `tasks[].payload` | Payload |
| `tasks[].time_offset` | integer |
| `tasks[].continue_on_failure` | boolean |
| `tasks[].is_queued` | boolean |

### Sleep and start-queue state of a free server; policy: none for a paid one {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-sleep}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/sleep`

Sleep and start-queue state of a free server; ``policy: none`` for a paid one.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff list snapshots {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-snapshots}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots`

This server's snapshots, or every snapshot the owning account holds
judged for restoring onto this server.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `scope` | query | string | no | Default: `this`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff create snapshot {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-snapshots}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `name` | string | yes |
| `ignored_files` | array of string or null | no |
| `is_locked` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff snapshot estimate {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-estimate}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/estimate`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff delete snapshot {#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-snapshot-uuid}

`DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff download snapshot {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-snapshot-uuid-download}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/download`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff toggle snapshot lock {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-snapshot-uuid-lock}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/lock`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff restore snapshot {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-snapshots-snapshot-uuid-restore}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/snapshots/{snapshot_uuid}/restore`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `snapshot_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required |
| --- | --- | --- |
| `target_server_uuid` | string or null | no |
| `truncate` | boolean | no |
| `allow_mismatch` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff installed software {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff software catalog {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software-catalog}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/catalog`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff software catalog versions {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software-catalog-key-versions}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/catalog/{key}/versions`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `uuid` | path | string | yes |  |
| `key` | path | string | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `200`. |
| `include_unsupported` | query | boolean | no | Default: `False`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff change software {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-software-change}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/change`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | 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. |

### Staff software context {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software-context}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/context`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff software installs {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-software-installs}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |
| `status` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff cancel install {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-software-installs-install-uuid-canc}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs/{install_uuid}/cancel`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `install_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff retry install {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-software-installs-install-uuid-retr}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/software/installs/{install_uuid}/retry`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `install_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### How the server starts: runtime, command (override and default), variables {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-startup}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/startup`

How the server starts: runtime, command (override and default), variables.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Change the runtime, the startup command or the variables {#op-patch-api-v1-orgs-org-slug-staff-servers-uuid-startup}

`PATCH /api/v1/orgs/{org_slug}/staff/servers/{uuid}/startup`

Change the runtime, the startup command or the variables. Admin, stepped up.

Applies on the next start; nothing here stops or starts the server.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `runtime_template_slug` | string or null | no |
| `startup_command` | string or null | no |
| `reset_startup_command` | boolean | no |
| `variables` | object or null | no |
| `remove_variables` | array of string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff patch startup variables {#op-patch-api-v1-orgs-org-slug-staff-servers-uuid-startup-variables}

`PATCH /api/v1/orgs/{org_slug}/staff/servers/{uuid}/startup-variables`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `variables` | Variables | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff patch subdomain {#op-patch-api-v1-orgs-org-slug-staff-servers-uuid-subdomain}

`PATCH /api/v1/orgs/{org_slug}/staff/servers/{uuid}/subdomain`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `subdomain` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff list subusers {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-users}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/users`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff update subuser {#op-put-api-v1-orgs-org-slug-staff-servers-uuid-users-subuser-id}

`PUT /api/v1/orgs/{org_slug}/staff/servers/{uuid}/users/{subuser_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `subuser_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `permissions` | array of string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff remove subuser {#op-delete-api-v1-orgs-org-slug-staff-servers-uuid-users-subuser-id}

`DELETE /api/v1/orgs/{org_slug}/staff/servers/{uuid}/users/{subuser_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `subuser_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Start a sleeping free server on the customer's behalf {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-wake}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/wake`

Start a sleeping free server on the customer's behalf.

No Turnstile: the risk challenge exists to slow down a scripted customer,
and a signed-in staff member is neither.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff kick wake {#op-post-api-v1-orgs-org-slug-staff-servers-uuid-wake-queue-kick}

`POST /api/v1/orgs/{org_slug}/staff/servers/{uuid}/wake-queue/kick`

Get a free server's stuck start moving: settle it against the daemon
now and, if it is still not up, admit it past the admission gate and
start it. Scoped to the brand's own servers.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The live console {#op-get-api-v1-orgs-org-slug-staff-servers-uuid-websocket}

`GET /api/v1/orgs/{org_slug}/staff/servers/{uuid}/websocket`

The live console. Below Tier 3 the relay lets it be watched, not typed
into (``STAFF_WATCH_PERMISSIONS`` in the console relay).

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `token` | string |
| `socket` | string |

# Organization API: Org Staff Coupons

> Every Organization API operation tagged Org Staff Coupons.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-coupons/

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}/staff/coupons`](#op-get-api-v1-orgs-org-slug-staff-coupons) | Staff list coupons |
| POST | [`/api/v1/orgs/{org_slug}/staff/coupons`](#op-post-api-v1-orgs-org-slug-staff-coupons) | Staff create coupon |
| POST | [`/api/v1/orgs/{org_slug}/staff/coupons/feature`](#op-post-api-v1-orgs-org-slug-staff-coupons-feature) | Turn coupons on or off for the brand |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/coupons/{coupon_id}`](#op-patch-api-v1-orgs-org-slug-staff-coupons-coupon-id) | Staff patch coupon |
| GET | [`/api/v1/orgs/{org_slug}/staff/coupons/{coupon_id}/redemptions`](#op-get-api-v1-orgs-org-slug-staff-coupons-coupon-id-redemptions) | Staff coupon redemptions |

### Staff list coupons {#op-get-api-v1-orgs-org-slug-staff-coupons}

`GET /api/v1/orgs/{org_slug}/staff/coupons`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `status` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff create coupon {#op-post-api-v1-orgs-org-slug-staff-coupons}

`POST /api/v1/orgs/{org_slug}/staff/coupons`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `code` | string | yes |
| `description` | string or null | no |
| `kind` | string | no |
| `value` | number or string | yes |
| `currency` | string or null | no |
| `applies_to` | array of integer or null | no |
| `first_invoice_only` | boolean | no |
| `max_redemptions` | integer or null | no |
| `per_customer_limit` | integer | no |
| `starts_at` | string (date-time) or null | no |
| `ends_at` | string (date-time) or null | no |
| `status` | string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Turn coupons on or off for the brand {#op-post-api-v1-orgs-org-slug-staff-coupons-feature}

`POST /api/v1/orgs/{org_slug}/staff/coupons/feature`

Turn coupons on or off for the brand. Off means the checkout shows no
code field and every code is refused, whatever its status.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `enabled` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff patch coupon {#op-patch-api-v1-orgs-org-slug-staff-coupons-coupon-id}

`PATCH /api/v1/orgs/{org_slug}/staff/coupons/{coupon_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `coupon_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `description` | string or null | no |
| `value` | number or string or null | no |
| `applies_to` | array of integer or null | no |
| `clear_applies_to` | boolean | no |
| `max_redemptions` | integer or null | no |
| `clear_max_redemptions` | boolean | no |
| `per_customer_limit` | integer or null | no |
| `starts_at` | string (date-time) or null | no |
| `ends_at` | string (date-time) or null | no |
| `clear_ends_at` | boolean | no |
| `status` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff coupon redemptions {#op-get-api-v1-orgs-org-slug-staff-coupons-coupon-id-redemptions}

`GET /api/v1/orgs/{org_slug}/staff/coupons/{coupon_id}/redemptions`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `coupon_id` | path | integer | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `100`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Staff Insight

> Every Organization API operation tagged Org Staff Insight.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-insight/

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}/staff/activity`](#op-get-api-v1-orgs-org-slug-staff-activity) | The org's audit log |
| GET | [`/api/v1/orgs/{org_slug}/staff/activity/actions`](#op-get-api-v1-orgs-org-slug-staff-activity-actions) | The action names that have occurred, for the filter |
| GET | [`/api/v1/orgs/{org_slug}/staff/insights`](#op-get-api-v1-orgs-org-slug-staff-insights) | Money, orders, customers and support over the window, by day |
| GET | [`/api/v1/orgs/{org_slug}/staff/insights/export.csv`](#op-get-api-v1-orgs-org-slug-staff-insights-export-csv) | The daily series as one CSV: a column per measure, a row per day |

### The org's audit log {#op-get-api-v1-orgs-org-slug-staff-activity}

`GET /api/v1/orgs/{org_slug}/staff/activity`

The org's audit log. Admins read all of it. Tier 3 and billing must
name the customer, order or server they are looking at, or ask for
their own actions, which is all Tiers 1 and 2 may see.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `customer_id` | query | integer or null | no |  |
| `service_id` | query | integer or null | no |  |
| `server_uuid` | query | string or null | no |  |
| `actor_id` | query | integer or null | no |  |
| `action` | query | string or null | no |  |
| `resource_type` | query | string or null | no |  |
| `since` | query | string (date) or null | no |  |
| `until` | query | string (date) or null | no |  |
| `q` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The action names that have occurred, for the filter {#op-get-api-v1-orgs-org-slug-staff-activity-actions}

`GET /api/v1/orgs/{org_slug}/staff/activity/actions`

The action names that have occurred, for the filter. Below Tier 3,
only the ones the caller took.

#### 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. |

### Money, orders, customers and support over the window, by day {#op-get-api-v1-orgs-org-slug-staff-insights}

`GET /api/v1/orgs/{org_slug}/staff/insights`

Money, orders, customers and support over the window, by day.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The daily series as one CSV: a column per measure, a row per day {#op-get-api-v1-orgs-org-slug-staff-insights-export-csv}

`GET /api/v1/orgs/{org_slug}/staff/insights/export.csv`

The daily series as one CSV: a column per measure, a row per day.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `days` | query | integer | no | Default: `30`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Staff Notices

> Every Organization API operation tagged Org Staff Notices.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-notices/

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}/staff/notices`](#op-get-api-v1-orgs-org-slug-staff-notices) | Staff list notices |
| POST | [`/api/v1/orgs/{org_slug}/staff/notices`](#op-post-api-v1-orgs-org-slug-staff-notices) | Staff create notice |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/notices/{notice_id}`](#op-patch-api-v1-orgs-org-slug-staff-notices-notice-id) | Staff patch notice |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/notices/{notice_id}`](#op-delete-api-v1-orgs-org-slug-staff-notices-notice-id) | Staff delete notice |
| POST | [`/api/v1/orgs/{org_slug}/staff/notices/{notice_id}/updates`](#op-post-api-v1-orgs-org-slug-staff-notices-notice-id-updates) | A line on the timeline |

### Staff list notices {#op-get-api-v1-orgs-org-slug-staff-notices}

`GET /api/v1/orgs/{org_slug}/staff/notices`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `status` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff create notice {#op-post-api-v1-orgs-org-slug-staff-notices}

`POST /api/v1/orgs/{org_slug}/staff/notices`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `kind` | string | no |
| `title` | string | yes |
| `body` | string or null | no |
| `audience` | string | no |
| `placement` | string | no |
| `status` | string | no |
| `starts_at` | string (date-time) or null | no |
| `ends_at` | string (date-time) or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff patch notice {#op-patch-api-v1-orgs-org-slug-staff-notices-notice-id}

`PATCH /api/v1/orgs/{org_slug}/staff/notices/{notice_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `notice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `kind` | string or null | no |
| `title` | string or null | no |
| `body` | string or null | no |
| `audience` | string or null | no |
| `placement` | string or null | no |
| `status` | string or null | no |
| `starts_at` | string (date-time) or null | no |
| `ends_at` | string (date-time) or null | no |
| `clear_starts_at` | boolean | no |
| `clear_ends_at` | boolean | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff delete notice {#op-delete-api-v1-orgs-org-slug-staff-notices-notice-id}

`DELETE /api/v1/orgs/{org_slug}/staff/notices/{notice_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `notice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A line on the timeline {#op-post-api-v1-orgs-org-slug-staff-notices-notice-id-updates}

`POST /api/v1/orgs/{org_slug}/staff/notices/{notice_id}/updates`

A line on the timeline. ``resolved`` also resolves the notice.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `notice_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `state` | string | no |
| `body` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Staff Ops

> Every Organization API operation tagged Org Staff Ops.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-ops/

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}/staff/ops-summary`](#op-get-api-v1-orgs-org-slug-staff-ops-summary) | Staff ops summary |
| GET | [`/api/v1/orgs/{org_slug}/staff/orders`](#op-get-api-v1-orgs-org-slug-staff-orders) | Staff orders |
| GET | [`/api/v1/orgs/{org_slug}/staff/orders/stats`](#op-get-api-v1-orgs-org-slug-staff-orders-stats) | Staff orders stats |
| GET | [`/api/v1/orgs/{org_slug}/staff/orders/{service_id}`](#op-get-api-v1-orgs-org-slug-staff-orders-service-id) | Staff order hub |
| GET | [`/api/v1/orgs/{org_slug}/staff/refund-requests`](#op-get-api-v1-orgs-org-slug-staff-refund-requests) | Staff refund requests |
| GET | [`/api/v1/orgs/{org_slug}/staff/refund-requests/{request_id}`](#op-get-api-v1-orgs-org-slug-staff-refund-requests-request-id) | Staff refund request |
| POST | [`/api/v1/orgs/{org_slug}/staff/refund-requests/{request_id}/approve`](#op-post-api-v1-orgs-org-slug-staff-refund-requests-request-id-approve) | Staff approve refund request |
| POST | [`/api/v1/orgs/{org_slug}/staff/refund-requests/{request_id}/reject`](#op-post-api-v1-orgs-org-slug-staff-refund-requests-request-id-reject) | Staff reject refund request |
| GET | [`/api/v1/orgs/{org_slug}/staff/search`](#op-get-api-v1-orgs-org-slug-staff-search) | Staff search |

### Staff ops summary {#op-get-api-v1-orgs-org-slug-staff-ops-summary}

`GET /api/v1/orgs/{org_slug}/staff/ops-summary`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `audience` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff orders {#op-get-api-v1-orgs-org-slug-staff-orders}

`GET /api/v1/orgs/{org_slug}/staff/orders`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `q` | query | string or null | no |  |
| `customer_id` | query | integer or null | no |  |
| `status_filter` | query | string or null | no |  |
| `audience` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff orders stats {#op-get-api-v1-orgs-org-slug-staff-orders-stats}

`GET /api/v1/orgs/{org_slug}/staff/orders/stats`

One count per order status for the tiles above the list, under the
audience the request carries. ``cancelled`` is spelled as the status
value is (the way the invoice stats spell theirs); ``stuck`` folds
pending, provisioning and failed orders that are paid for (or were never
invoiced), from the clause the ``stuck`` list filters with.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `audience` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff order hub {#op-get-api-v1-orgs-org-slug-staff-orders-service-id}

`GET /api/v1/orgs/{org_slug}/staff/orders/{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. |

### Staff refund requests {#op-get-api-v1-orgs-org-slug-staff-refund-requests}

`GET /api/v1/orgs/{org_slug}/staff/refund-requests`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff refund request {#op-get-api-v1-orgs-org-slug-staff-refund-requests-request-id}

`GET /api/v1/orgs/{org_slug}/staff/refund-requests/{request_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff approve refund request {#op-post-api-v1-orgs-org-slug-staff-refund-requests-request-id-approve}

`POST /api/v1/orgs/{org_slug}/staff/refund-requests/{request_id}/approve`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `resolution` | string | no |
| `note` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff reject refund request {#op-post-api-v1-orgs-org-slug-staff-refund-requests-request-id-reject}

`POST /api/v1/orgs/{org_slug}/staff/refund-requests/{request_id}/reject`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `request_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `note` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff search {#op-get-api-v1-orgs-org-slug-staff-search}

`GET /api/v1/orgs/{org_slug}/staff/search`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `q` | query | string | yes |
| `audience` | query | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Staff Team

> Every Organization API operation tagged Org Staff Team.

Source: https://www.coritan.com/docs/api/reference/organizations/org-staff-team/

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 |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/staff/team`](#op-post-api-v1-orgs-org-slug-staff-team) | Staff invite member |
| GET | [`/api/v1/orgs/{org_slug}/staff/team/detail`](#op-get-api-v1-orgs-org-slug-staff-team-detail) | Everyone on the brand, with role, last sign-in and whether they can sign in at all |
| GET | [`/api/v1/orgs/{org_slug}/staff/team/policy`](#op-get-api-v1-orgs-org-slug-staff-team-policy) | Staff team policy |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/team/policy`](#op-patch-api-v1-orgs-org-slug-staff-team-policy) | Require a second factor of everyone on the brand |
| PATCH | [`/api/v1/orgs/{org_slug}/staff/team/{member_id}`](#op-patch-api-v1-orgs-org-slug-staff-team-member-id) | Staff change role |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/team/{member_id}`](#op-delete-api-v1-orgs-org-slug-staff-team-member-id) | Staff remove member |
| GET | [`/api/v1/orgs/{org_slug}/staff/team/{member_id}/customer-link`](#op-get-api-v1-orgs-org-slug-staff-team-member-id-customer-link) | Which storefront customer account a teammate is, if any |
| PUT | [`/api/v1/orgs/{org_slug}/staff/team/{member_id}/customer-link`](#op-put-api-v1-orgs-org-slug-staff-team-member-id-customer-link) | Attach a teammate to an existing customer account, or make them one with their email |
| DELETE | [`/api/v1/orgs/{org_slug}/staff/team/{member_id}/customer-link`](#op-delete-api-v1-orgs-org-slug-staff-team-member-id-customer-link) | Make a teammate console-only |
| POST | [`/api/v1/orgs/{org_slug}/staff/team/{member_id}/reset-mfa`](#op-post-api-v1-orgs-org-slug-staff-team-member-id-reset-mfa) | For a teammate who lost their phone: remove their second factor and end their sessions |
| POST | [`/api/v1/orgs/{org_slug}/staff/team/{member_id}/reset-password`](#op-post-api-v1-orgs-org-slug-staff-team-member-id-reset-password) | Staff reset member password |
| POST | [`/api/v1/orgs/{org_slug}/staff/team/{member_id}/revoke-sessions`](#op-post-api-v1-orgs-org-slug-staff-team-member-id-revoke-sessions) | Staff revoke member sessions |

### Staff invite member {#op-post-api-v1-orgs-org-slug-staff-team}

`POST /api/v1/orgs/{org_slug}/staff/team`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `email` | string (email) | yes |
| `name` | string or null | no |
| `role` | string | no |
| `send_invite_email` | boolean | no |
| `password` | string or null | no |
| `customer_link` | string | no |
| `customer_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Everyone on the brand, with role, last sign-in and whether they can sign in at all {#op-get-api-v1-orgs-org-slug-staff-team-detail}

`GET /api/v1/orgs/{org_slug}/staff/team/detail`

Everyone on the brand, with role, last sign-in and whether they can
sign in at all. The picker route (``/staff/team``) stays small; this is
the team page.

#### 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. |

### Staff team policy {#op-get-api-v1-orgs-org-slug-staff-team-policy}

`GET /api/v1/orgs/{org_slug}/staff/team/policy`

#### 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. |

### Require a second factor of everyone on the brand {#op-patch-api-v1-orgs-org-slug-staff-team-policy}

`PATCH /api/v1/orgs/{org_slug}/staff/team/policy`

Require a second factor of everyone on the brand. From the next sign-in
a member without one can only enrol until they have. The admin turning
it on must already have theirs, or they would be the first one locked
into enrolment.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `require_mfa` | boolean | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff change role {#op-patch-api-v1-orgs-org-slug-staff-team-member-id}

`PATCH /api/v1/orgs/{org_slug}/staff/team/{member_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `role` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff remove member {#op-delete-api-v1-orgs-org-slug-staff-team-member-id}

`DELETE /api/v1/orgs/{org_slug}/staff/team/{member_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Which storefront customer account a teammate is, if any {#op-get-api-v1-orgs-org-slug-staff-team-member-id-customer-link}

`GET /api/v1/orgs/{org_slug}/staff/team/{member_id}/customer-link`

Which storefront customer account a teammate is, if any.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Attach a teammate to an existing customer account, or make them one with their email {#op-put-api-v1-orgs-org-slug-staff-team-member-id-customer-link}

`PUT /api/v1/orgs/{org_slug}/staff/team/{member_id}/customer-link`

Attach a teammate to an existing customer account, or make them one
with their email. Whoever holds the account holds its servers and its
money, so this is a step-up action, and any storefront sessions the
console opened on a previous account end.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `mode` | string | no |
| `customer_id` | integer or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Make a teammate console-only {#op-delete-api-v1-orgs-org-slug-staff-team-member-id-customer-link}

`DELETE /api/v1/orgs/{org_slug}/staff/team/{member_id}/customer-link`

Make a teammate console-only. The customer account stays as it is,
with its servers and invoices; only the tie to this teammate goes.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### For a teammate who lost their phone: remove their second factor and end their sessions {#op-post-api-v1-orgs-org-slug-staff-team-member-id-reset-mfa}

`POST /api/v1/orgs/{org_slug}/staff/team/{member_id}/reset-mfa`

For a teammate who lost their phone: remove their second factor and end
their sessions. They sign in with the password and, if the brand requires
it, enrol again straight away. Never for yourself (disable your own with
a code), and never for the owner from here.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff reset member password {#op-post-api-v1-orgs-org-slug-staff-team-member-id-reset-password}

`POST /api/v1/orgs/{org_slug}/staff/team/{member_id}/reset-password`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `send_email` | boolean | no |
| `password` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Staff revoke member sessions {#op-post-api-v1-orgs-org-slug-staff-team-member-id-revoke-sessions}

`POST /api/v1/orgs/{org_slug}/staff/team/{member_id}/revoke-sessions`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `member_id` | path | integer | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Org Ticket Requests

> Every Organization API operation tagged Org Ticket Requests.

Source: https://www.coritan.com/docs/api/reference/organizations/org-ticket-requests/

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}/staff/me/server-access`](#op-get-api-v1-orgs-org-slug-staff-me-server-access) | My server access |
| POST | [`/api/v1/orgs/{org_slug}/staff/me/server-access/{server_uuid}/leave`](#op-post-api-v1-orgs-org-slug-staff-me-server-access-server-uuid-leave) | Stop being a subuser on a server |

### My server access {#op-get-api-v1-orgs-org-slug-staff-me-server-access}

`GET /api/v1/orgs/{org_slug}/staff/me/server-access`

The servers the caller's own storefront account is a subuser on, whether
lent by a ticket or shared by a customer some other way.

#### 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. |

### Stop being a subuser on a server {#op-post-api-v1-orgs-org-slug-staff-me-server-access-server-uuid-leave}

`POST /api/v1/orgs/{org_slug}/staff/me/server-access/{server_uuid}/leave`

Stop being a subuser on a server. A ticket that lent the access says so.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `server_uuid` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Organization apps

> The organization's own Apps, as /api/v1/client/apps serves an account's: deployments, build logs, rollbacks, environment variables and domains.

Source: https://www.coritan.com/docs/api/reference/organizations/organization-apps/

The organization's own Apps, as `/api/v1/client/apps` serves an account's: deployments, build logs, rollbacks, environment variables and domains.

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}/apps`](#op-get-api-v1-orgs-org-slug-apps) | List apps |
| POST | [`/api/v1/orgs/{org_slug}/apps`](#op-post-api-v1-orgs-org-slug-apps) | Create an app and, unless deploy is false, its first deployment |
| GET | [`/api/v1/orgs/{org_slug}/apps/regions`](#op-get-api-v1-orgs-org-slug-apps-regions) | Regions |
| GET | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}`](#op-get-api-v1-orgs-org-slug-apps-app-uuid) | Get one app with its domains, recent deployments and current replicas |
| PATCH | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}`](#op-patch-api-v1-orgs-org-slug-apps-app-uuid) | Change an app's settings |
| DELETE | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}`](#op-delete-api-v1-orgs-org-slug-apps-app-uuid) | Delete app |
| GET | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments`](#op-get-api-v1-orgs-org-slug-apps-app-uuid-deployments) | List an app's deployments, newest first, a page at a time |
| POST | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments`](#op-post-api-v1-orgs-org-slug-apps-app-uuid-deployments) | Create app deployment |
| GET | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}`](#op-get-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid) | Get one deployment of an app, with each of its replicas |
| POST | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/cancel`](#op-post-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid-cancel) | Cancel a deployment that is still queued, building or deploying |
| GET | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/log`](#op-get-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid-log) | The end of the deployment's build log (secrets redacted as it was written) |
| POST | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`](#op-post-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid-rollback) | Rollback app |
| GET | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/domains`](#op-get-api-v1-orgs-org-slug-apps-app-uuid-domains) | List an app's domains: its platform name first, then its custom domains |
| POST | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/domains`](#op-post-api-v1-orgs-org-slug-apps-app-uuid-domains) | Add a custom domain |
| DELETE | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/domains/{hostname}`](#op-delete-api-v1-orgs-org-slug-apps-app-uuid-domains-hostname) | Remove a custom domain from an app |
| POST | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/domains/{hostname}/verify`](#op-post-api-v1-orgs-org-slug-apps-app-uuid-domains-hostname-verify) | Look for the domain's TXT record |
| GET | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/env`](#op-get-api-v1-orgs-org-slug-apps-app-uuid-env) | List an app's environment variables without their values |
| PUT | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/env`](#op-put-api-v1-orgs-org-slug-apps-app-uuid-env) | Set many variables; a variable given without value keeps its saved one |
| PUT | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/env/{key}`](#op-put-api-v1-orgs-org-slug-apps-app-uuid-env-key) | Set one environment variable, creating it when it is new |
| DELETE | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/env/{key}`](#op-delete-api-v1-orgs-org-slug-apps-app-uuid-env-key) | Delete one environment variable |
| POST | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/redeploy`](#op-post-api-v1-orgs-org-slug-apps-app-uuid-redeploy) | Redeploy app |
| POST | [`/api/v1/orgs/{org_slug}/apps/{app_uuid}/webhook/rotate`](#op-post-api-v1-orgs-org-slug-apps-app-uuid-webhook-rotate) | A new secret for the push webhook, shown once; the old one stops verifying at once |

### List apps {#op-get-api-v1-orgs-org-slug-apps}

`GET /api/v1/orgs/{org_slug}/apps`

The caller's apps, newest first, each with its current deployment,
replica counts and domains.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `status` | query | string or null | no |  |
| `limit` | query | integer | no | Default: `50`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create an app and, unless deploy is false, its first deployment {#op-post-api-v1-orgs-org-slug-apps}

`POST /api/v1/orgs/{org_slug}/apps`

Create an app and, unless ``deploy`` is false, its first deployment.
An app whose first deployment cannot start yet is still created, with
the reason in ``deploy_error``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `repo_url` | string or null | no |  |
| `repo_branch` | string or null | no |  |
| `repo_subdir` | string or null | no |  |
| `repo_token` | string or null | no | Write only; an empty string removes it |
| `image_ref` | string or null | no |  |
| `framework` | string or null | no |  |
| `install_command` | string or null | no |  |
| `build_command` | string or null | no |  |
| `start_command` | string or null | no |  |
| `dockerfile_path` | string or null | no |  |
| `port` | integer or null | no |  |
| `health_check_path` | string or null | no |  |
| `instance_size` | string or null | no |  |
| `regions` | array of string or null | no |  |
| `min_replicas` | integer or null | no |  |
| `max_replicas` | integer or null | no |  |
| `slug` | string or null | no | The name on the platform; derived from name when left out |
| `source_type` | string | no |  |
| `env` | array of EnvVarIn or null | no |  |
| `env[].key` | string | yes |  |
| `env[].value` | string or null | no | Left out: the saved value is kept |
| `env[].secret` | boolean or null | no | Redacted from build logs; new variables default to true |
| `env[].target` | string or null | no |  |
| `deploy` | boolean | no | Start the first deployment at once |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Regions {#op-get-api-v1-orgs-org-slug-apps-regions}

`GET /api/v1/orgs/{org_slug}/apps/regions`

What the create form offers: the regions that can run apps now,
the instance sizes, the replica bounds and the owner's app limit.

#### 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. |

### Get one app with its domains, recent deployments and current replicas {#op-get-api-v1-orgs-org-slug-apps-app-uuid}

`GET /api/v1/orgs/{org_slug}/apps/{app_uuid}`

Get one app with its domains, recent deployments and current replicas.
``deployments`` holds the five newest and ``deployments_total`` counts
them all; ``replicas`` are those of the deployment that serves the app,
failed ones left out. Another owner's app answers 404, as one that does
not exist does.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Change an app's settings {#op-patch-api-v1-orgs-org-slug-apps-app-uuid}

`PATCH /api/v1/orgs/{org_slug}/apps/{app_uuid}`

Change an app's settings. ``redeploy_required`` and
``rebuild_required`` say whether running replicas pick the change up
only with a new deployment or a new build.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string or null | no |  |
| `repo_url` | string or null | no |  |
| `repo_branch` | string or null | no |  |
| `repo_subdir` | string or null | no |  |
| `repo_token` | string or null | no | Write only; an empty string removes it |
| `image_ref` | string or null | no |  |
| `framework` | string or null | no |  |
| `install_command` | string or null | no |  |
| `build_command` | string or null | no |  |
| `start_command` | string or null | no |  |
| `dockerfile_path` | string or null | no |  |
| `port` | integer or null | no |  |
| `health_check_path` | string or null | no |  |
| `instance_size` | string or null | no |  |
| `regions` | array of string or null | no |  |
| `min_replicas` | integer or null | no |  |
| `max_replicas` | integer or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete app {#op-delete-api-v1-orgs-org-slug-apps-app-uuid}

`DELETE /api/v1/orgs/{org_slug}/apps/{app_uuid}`

Delete the app: deployments on their way are canceled, its routes
and domains removed, its replicas drained and their servers removed,
its environment and secrets erased. It cannot be undone.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |  |
| `org_slug` | path | string | yes |  |
| `confirm` | query | string | yes | The app's name on the platform, typed to confirm |
| `reason` | query | string or null | no |  |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List an app's deployments, newest first, a page at a time {#op-get-api-v1-orgs-org-slug-apps-app-uuid-deployments}

`GET /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments`

List an app's deployments, newest first, a page at a time.
``limit`` takes 1 to 100 (20 when left out) and ``total`` counts every
deployment. Each one carries its status, source, build and replica
counts.

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |  |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Default: `20`. |
| `offset` | query | integer | no | Default: `0`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Create app deployment {#op-post-api-v1-orgs-org-slug-apps-app-uuid-deployments}

`POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments`

Deploy: a git app builds ``git_ref`` (its branch when left out); an
image app runs ``image_ref`` (its own when left out). A branch or
commit for an image app, or an image for a git app, is refused with
``source_mismatch`` rather than ignored.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `git_ref` | string or null | no | Branch, tag or commit; the app's branch when left out |
| `git_sha` | string or null | no |  |
| `image_ref` | string or null | no | An image app's reference; the app's when left out |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get one deployment of an app, with each of its replicas {#op-get-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid}

`GET /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}`

Get one deployment of an app, with each of its replicas.
``replica_list`` gives each replica's region, state, failed health checks
in a row and last error. A deployment of another app answers 404.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Cancel a deployment that is still queued, building or deploying {#op-post-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid-cancel}

`POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/cancel`

Cancel a deployment that is still queued, building or deploying.
Its build stops and its replicas are removed, and the deployment that
serves the app goes on serving. A deployment that has finished answers
409.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### The end of the deployment's build log (secrets redacted as it was written) {#op-get-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid-log}

`GET /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/log`

The end of the deployment's build log (secrets redacted as it was
written). An image deployment has none.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Rollback app {#op-post-api-v1-orgs-org-slug-apps-app-uuid-deployments-deployment-uuid-rollback}

`POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`

A new deployment of this earlier ready deployment's image; its
replicas that still have servers are started again instead of placed.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `deployment_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List an app's domains: its platform name first, then its custom domains {#op-get-api-v1-orgs-org-slug-apps-app-uuid-domains}

`GET /api/v1/orgs/{org_slug}/apps/{app_uuid}/domains`

List an app's domains: its platform name first, then its custom domains.
Each says whether it is verified and whether its certificate is issued,
and an unverified one carries the TXT record to publish in
``verification``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Add a custom domain {#op-post-api-v1-orgs-org-slug-apps-app-uuid-domains}

`POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/domains`

Add a custom domain. It gets no route until the TXT record in
``verification`` is published and checked.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `hostname` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Remove a custom domain from an app {#op-delete-api-v1-orgs-org-slug-apps-app-uuid-domains-hostname}

`DELETE /api/v1/orgs/{org_slug}/apps/{app_uuid}/domains/{hostname}`

Remove a custom domain from an app. The hostname stops reaching the
app, and its route and certificate are deleted. The platform name cannot
be removed (409 ``platform_domain``), and a hostname the app does not
have answers 404.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `hostname` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Look for the domain's TXT record {#op-post-api-v1-orgs-org-slug-apps-app-uuid-domains-hostname-verify}

`POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/domains/{hostname}/verify`

Look for the domain's TXT record. Found: the domain is verified, its
route is created and, once replicas serve it, its certificate ordered.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `hostname` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### List an app's environment variables without their values {#op-get-api-v1-orgs-org-slug-apps-app-uuid-env}

`GET /api/v1/orgs/{org_slug}/apps/{app_uuid}/env`

List an app's environment variables without their values.
Each key comes with its ``target``, whether it is ``secret`` and, for a
value of eight characters or more, its last four as ``hint``.
``readable`` is false when a saved value can no longer be read; set it
again.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set many variables; a variable given without value keeps its saved one {#op-put-api-v1-orgs-org-slug-apps-app-uuid-env}

`PUT /api/v1/orgs/{org_slug}/apps/{app_uuid}/env`

Set many variables; a variable given without ``value`` keeps its
saved one. With ``replace`` every variable not listed is deleted.
Changes reach replicas with the next deployment.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `vars` | array of EnvVarIn | yes |  |
| `vars[].key` | string | yes |  |
| `vars[].value` | string or null | no | Left out: the saved value is kept |
| `vars[].secret` | boolean or null | no | Redacted from build logs; new variables default to true |
| `vars[].target` | string or null | no |  |
| `replace` | boolean | no | Delete every variable not in vars |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Set one environment variable, creating it when it is new {#op-put-api-v1-orgs-org-slug-apps-app-uuid-env-key}

`PUT /api/v1/orgs/{org_slug}/apps/{app_uuid}/env/{key}`

Set one environment variable, creating it when it is new.
A new variable needs a ``value`` and is secret unless ``secret`` is
false; leave ``value`` out to keep the saved one while ``secret`` or
``target`` change. A key the platform sets itself, such as ``PORT`` or
one starting ``CORITAN_``, is refused with 422. Replicas get the change
with the next deployment.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `key` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `value` | string or null | no |
| `secret` | boolean or null | no |
| `target` | string or null | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Delete one environment variable {#op-delete-api-v1-orgs-org-slug-apps-app-uuid-env-key}

`DELETE /api/v1/orgs/{org_slug}/apps/{app_uuid}/env/{key}`

Delete one environment variable. Running replicas keep it until the
next deployment. A key the app does not have answers 404.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `key` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Redeploy app {#op-post-api-v1-orgs-org-slug-apps-app-uuid-redeploy}

`POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/redeploy`

Deploy the current version again (picking up environment, size,
region and replica changes), or build the branch afresh with ``rebuild``.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rebuild` | boolean | no | Build the branch again instead of reusing the current image |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### A new secret for the push webhook, shown once; the old one stops verifying at once {#op-post-api-v1-orgs-org-slug-apps-app-uuid-webhook-rotate}

`POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/webhook/rotate`

A new secret for the push webhook, shown once; the old one stops
verifying at once.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `app_uuid` | path | string (uuid) | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

# Organization API: Partners

> Server-to-server calls from the brand's partners, such as the Medal quest that grants a free server a RAM boost.

Source: https://www.coritan.com/docs/api/reference/organizations/partners/

Server-to-server calls from the brand's partners, such as the Medal quest that grants a free server a RAM boost. Authenticated with that brand's partner key (`Authorization: Bearer`), never a staff or customer token.

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 |
| --- | --- | --- |
| POST | [`/api/v1/orgs/{org_slug}/partners/medal/boosts`](#op-post-api-v1-orgs-org-slug-partners-medal-boosts) | Grant a free server the brand's Medal RAM boost |

### Grant a free server the brand's Medal RAM boost {#op-post-api-v1-orgs-org-slug-partners-medal-boosts}

`POST /api/v1/orgs/{org_slug}/partners/medal/boosts`

Grant a free server the brand's Medal RAM boost.

Authenticated with ``Authorization: Bearer <key>``, the brand's Medal key.
``server_address`` is the one required field, in a JSON or form body or
the query string. An optional ``claim_id`` makes a retry answer with the
grant it already made; ``dry_run`` checks the address and every rule and
grants nothing. The contract is in ``API_DOCS.md``.

#### 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. |

# Organization API: Resource Tags

> Every Organization API operation tagged Resource Tags.

Source: https://www.coritan.com/docs/api/reference/organizations/resource-tags/

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}/tags/sources/{source_type}/{source_id}`](#op-get-api-v1-orgs-org-slug-tags-sources-source-type-source-id) | Get org resource tags |
| POST | [`/api/v1/orgs/{org_slug}/tags/sources/{source_type}/{source_id}`](#op-post-api-v1-orgs-org-slug-tags-sources-source-type-source-id) | Add org resource tag |
| PUT | [`/api/v1/orgs/{org_slug}/tags/sources/{source_type}/{source_id}`](#op-put-api-v1-orgs-org-slug-tags-sources-source-type-source-id) | Replace org resource tags |
| DELETE | [`/api/v1/orgs/{org_slug}/tags/sources/{source_type}/{source_id}/{tag}`](#op-delete-api-v1-orgs-org-slug-tags-sources-source-type-source-id-tag) | Remove org resource tag |
| GET | [`/api/v1/orgs/{org_slug}/tags/vocabulary`](#op-get-api-v1-orgs-org-slug-tags-vocabulary) | List org tag vocabulary |

### Get org resource tags {#op-get-api-v1-orgs-org-slug-tags-sources-source-type-source-id}

`GET /api/v1/orgs/{org_slug}/tags/sources/{source_type}/{source_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | path | string | yes |
| `source_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `source_type` | string |
| `source_id` | string |
| `tags` | array of string |

### Add org resource tag {#op-post-api-v1-orgs-org-slug-tags-sources-source-type-source-id}

`POST /api/v1/orgs/{org_slug}/tags/sources/{source_type}/{source_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | path | string | yes |
| `source_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `tag` | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `tags` | array of string |

### Replace org resource tags {#op-put-api-v1-orgs-org-slug-tags-sources-source-type-source-id}

`PUT /api/v1/orgs/{org_slug}/tags/sources/{source_type}/{source_id}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | path | string | yes |
| `source_id` | path | string | yes |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required |
| --- | --- | --- |
| `tags` | array of string | no |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `tags` | array of string |

### Remove org resource tag {#op-delete-api-v1-orgs-org-slug-tags-sources-source-type-source-id-tag}

`DELETE /api/v1/orgs/{org_slug}/tags/sources/{source_type}/{source_id}/{tag}`

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `source_type` | path | string | yes |
| `source_id` | path | string | yes |
| `tag` | path | string | yes |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `tags` | array of string |

### List org tag vocabulary {#op-get-api-v1-orgs-org-slug-tags-vocabulary}

`GET /api/v1/orgs/{org_slug}/tags/vocabulary`

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `source_type` | query | string | yes | e.g. org_service, vps, container_server |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

Fields of a `200` response:

| Field | Type |
| --- | --- |
| `items` | array of TagVocabularyItem |
| `items[].tag` | string |
| `items[].resource_count` | integer |
| `source_type` | string or null |