Client API: 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.

GET /api/v1/services/

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

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

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>.

application/json (required)

Fields of a 201 response:

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>.

Fields of a 200 response:

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

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

application/json (required)

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

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

application/json (required)

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

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

application/json (required)

Fields of a 200 response:

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

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

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

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

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

Fields of a 200 response: