openapi: 3.0.0 info: title: Massed Compute VM API description: > **API documentation for our direct on-demand offering** Base URL: `https://vm.massedcompute.com/api/v1` Example — GPU inventory (copy this whole URL): `https://vm.massedcompute.com/api/v1/gpu-inventory` Do not use `api.massedcompute.com`. Customer API traffic goes to `vm.massedcompute.com`. *If you are a marketplace looking to leverage our GPU inventory please contact us at techadmin@massedcompute.com* # Authentication Authentication of every endpoint provided requres a API token. We leverage Bearer token authentication on our endpoints. | Header | Value | | --- | --- | | Authorization | Bearer {{api_token}} | To provision an API key, please see our [API Settings documentation](/docs/settings/api-settings). version: 1.0.0 servers: - url: https://vm.massedcompute.com/api/v1 paths: /gpu-inventory: get: summary: Retrieve a list of avaialable GPU configurations. description: >- An comprehensive list of all GPU types, configurations, and available inventory. responses: '200': description: A list of available GPUs content: application/json: schema: $ref: '#/components/schemas/GPUInventoryV1' /images: get: summary: Retrieve list of available images. description: An Image is a preconfigured operating system and software stack. responses: '200': description: A list of available images content: application/json: schema: $ref: '#/components/schemas/ImagesV1' /instance: get: summary: Retrieve list of all running instances. description: An instance is a virtual machine that is currently running. tags: - Instances responses: '200': description: A list of all running instances content: application/json: schema: $ref: '#/components/schemas/RetrieveAllRunningInstancesV1' /instance/{uuid}: get: summary: Retrieve single running instances. description: An instance is a virtual machine that is currently running. tags: - Instances responses: '200': description: A list of all running instances content: application/json: schema: $ref: '#/components/schemas/RetrieveSingleRunningInstanceV1' /instance/launch: post: summary: Deploy new instances. tags: - Instances requestBody: required: true content: application/json: schema: type: object required: - imageId - productName - regionName properties: imageId: type: integer description: The ID of the image to deploy required: true productName: type: string description: >- The product name of the GPU instance you want to deploy. Example = 'gpu_1x_l40' required: true regionName: type: string description: Set value equal to 'any' required: true instanceName: type: string description: The name of the instance you want to deploy coupon: type: string description: The coupon code you want to apply to the instance command: type: string description: The command you want to run on startup sshKeys: type: array items: type: string description: The SSH key you want to use to connect to the instance volumeIds: type: array items: type: string maxItems: 8 description: > **Beta.** Optional. Ids of storage to attach (Persistent Storage, powered by Backblaze), from `GET /storage-volumes`. At most 8. Each one mounts at `/persistent/` on the new instance. Each one must be `active` and in an instance group you can manage. Attach each storage to one instance at a time. Spell it `volumeIds`: a body containing `volume_ids` is refused with `422`. Errors: `403` if the account doesn't have Persistent Storage or you can't manage a storage's group; `404` for an id you can't see; `409` if a storage isn't `active`; `422` if the value isn't a list of strings or has more than 8 ids; `503` if Persistent Storage is unavailable right now. responses: '202': description: Success deploying instance content: application/json: schema: type: object properties: response: type: string example: 8b52a46b-uuid-4fde-xxxx-6d13226908f7 warning: type: string description: > Only present when `volumeIds` was sent and some storage didn't attach, or the attach couldn't be checked. The instance was still created and is billing. Check `GET /storage-volumes`; if the instance is missing from a storage's `attachedTo`, terminate the instance and launch again. /instance/restart: post: summary: Restart an instances. tags: - Instances requestBody: required: true content: application/json: schema: type: object properties: instanceUuids: type: array items: type: string description: The ID or IDs of instances to restart required: - instanceUuids example: instanceUuids: - string1 - string2 responses: '202': description: Success restarting instance content: application/json: schema: $ref: '#/components/schemas/RestartInstanceV1' /instance/terminate: post: summary: Terminate an instances. description: >- Termination completely removes the instance from the system and destroys all data. tags: - Instances requestBody: required: true content: application/json: schema: type: object properties: instanceUuids: type: array items: type: string description: The ID or IDs of instances to restart required: - instanceUuids example: instanceUuids: - string1 - string2 responses: '202': description: Success restarting instance content: application/json: schema: $ref: '#/components/schemas/TerminateInstanceV1' /coupon/information: post: summary: Retrieve information about a coupon. description: >- A coupon is a discount code that can be applied to an instance when deployed. tags: - Coupon requestBody: required: true content: application/json: schema: type: object properties: coupon: type: string description: The coupon code you want to retrieve information about required: - couponCode responses: '200': description: Success retrieving coupon information content: application/json: schema: $ref: '#/components/schemas/RetrieveCouponInformationV1' /coupon/accepted-products: post: summary: Retrieve products that a coupon is valid for. description: >- A coupon is a discount code that can be applied to an instance when deployed. tags: - Coupon requestBody: required: true content: application/json: schema: type: object properties: coupon: type: string description: The coupon code you want to retrieve information about required: - couponCode responses: '200': description: Success retrieving coupon information content: application/json: schema: $ref: '#/components/schemas/RetrieveAcceptProductsV1' /account/token/validation: post: summary: Validate an API token. description: An API token is required to access the API. tags: - Account responses: '200': description: Success validating token content: application/json: schema: type: object properties: message: type: string example: Valid Token /account/billing: get: summary: Retrieve billing information. description: Billing information for the account. tags: - Account responses: '200': description: Success retrieving billing information content: application/json: schema: $ref: '#/components/schemas/RetrieveBillingInformationV1' /ssh-keys: get: summary: Retrieve SSH keys associated with the account. description: An SSH key is a secure access credential used to connect to instances. tags: - SSH Keys responses: '200': description: Success retrieving SSH keys content: application/json: schema: $ref: '#/components/schemas/SSHKey' post: summary: Add an SSH key to the account. description: An SSH key is a secure access credential used to connect to instances. tags: - SSH Keys requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The name of the SSH key publicKey: type: string description: The public key associated with the SSH key required: - name - publicKey responses: '200': description: Success adding SSH key content: application/json: schema: $ref: '#/components/schemas/POSTSSHKey' /ssh-keys/{id}: delete: summary: Remove an SSH key from the account. description: An SSH key is a secure access credential used to connect to instances. tags: - SSH Keys parameters: - name: id in: path required: true schema: type: string description: The unique identifier for the SSH key to be removed responses: '200': description: Success removing SSH key content: application/json: schema: type: object properties: result: type: object /storage-volumes: get: summary: List your Persistent Storage. description: > **Beta.** Account owners and admins can join the beta under Settings → Profile, or by ticking "Join the beta program" at signup, and leave it under Settings → Profile. Accounts without Persistent Storage get `403`. Persistent Storage keeps its data after the instance it is attached to is terminated. This lists the storage in instance groups you can see. Instances it is attached to in groups you can't see are counted in `hiddenAttachedCount`, never named. Works with a read-only API key. Errors use the body `{ "message": "...", "code": "..." }`. tags: - Persistent Storage responses: '200': description: Success listing storage content: application/json: schema: $ref: '#/components/schemas/StorageVolumeList' '403': description: '`forbidden`: the account doesn''t have Persistent Storage.' '503': description: >- `upstream_error`: Persistent Storage is not available right now. Try again later. post: summary: Create Persistent Storage. description: > **Beta.** Account owners and admins can join the beta under Settings → Profile, or by ticking "Join the beta program" at signup, and leave it under Settings → Profile. Accounts without Persistent Storage get `403`. Creates storage. Storage is billed for the data stored in it, from the moment you store data until it is deleted. Needs a full-access API key and the **Manage persistent storage** team permission. The storage is created in `instanceGroup`, or in the account's default group if you leave it out. You must be able to manage that group. Names use lowercase letters, digits and hyphens, 1 to 22 characters, and can't start or end with a hyphen. A name must be unique among the account's storage. The name is the mount folder: `/persistent/`. If the connection drops, the storage may still have been created. List your storage before you retry; a retry with the same name answers `409` if the first request worked. tags: - Persistent Storage requestBody: required: true content: application/json: schema: type: object properties: name: type: string pattern: ^[a-z0-9](?:[a-z0-9-]{0,20}[a-z0-9])?$ maxLength: 22 example: datasets description: >- The storage name. It becomes the mount folder, /persistent/. instanceGroup: type: string nullable: true description: >- Optional uuid of an instance group you can manage. Leave it out to use the account's default group. required: - name responses: '201': description: Success creating the storage content: application/json: schema: $ref: '#/components/schemas/CreatedStorageVolume' '403': description: > `forbidden`: the account doesn't have Persistent Storage; or the API key is read-only; or you don't have the **Manage persistent storage** permission; or you left out `instanceGroup` and can't manage the account's default group (pass `instanceGroup`). '404': description: >- `not_found`: the `instanceGroup` doesn't exist, or you can't manage it. '409': description: > `conflict`: the name is already used by other storage on the account; or storage is still being set up for the account (try again in a minute). '422': description: >- `validation_error`: the body isn't a JSON object, or the name is missing or breaks the name rules. '503': description: > `upstream_error`: Persistent Storage is not available right now, or the storage service couldn't be reached. List your storage before you retry. /storage-volumes/{id}: delete: summary: Delete Persistent Storage. description: > **Beta.** Account owners and admins can join the beta under Settings → Profile, or by ticking "Join the beta program" at signup, and leave it under Settings → Profile. Accounts without Persistent Storage get `403`. **Destructive:** permanently deletes the storage and every file in it. This can't be undone. Needs a full-access API key, the **Manage persistent storage** team permission, and manage access to the storage's instance group. Storage that is still attached to any instance, including a stopped one, can't be deleted (`409`). Stop those instances and detach the storage under **My Instances > Storage** on the website, or terminate them. Detaching isn't on the REST API yet. Large storage can take more than one request to empty. `200` with `deleted: true` means it is gone. `202` with `deleted: false` means it is still being emptied: send the same request again until you get `200`. Repeating the request is safe. The storage shows status `deleting` in the meantime and is billed for whatever is still stored. tags: - Persistent Storage parameters: - name: id in: path required: true schema: type: string format: uuid description: The storage id from `GET /storage-volumes`. responses: '200': description: The storage is deleted. content: application/json: schema: $ref: '#/components/schemas/DeletedStorageVolume' '202': description: Still emptying. Send the same request again. content: application/json: schema: $ref: '#/components/schemas/DeletedStorageVolume' '403': description: > `forbidden`: the account doesn't have Persistent Storage; or the API key is read-only; or you don't have the **Manage persistent storage** permission; or the storage is in an instance group you can see but can't manage. '404': description: '`not_found`: no storage with this id that you can see.' '409': description: >- `conflict`: the storage is still attached to an instance. The message names the instances you can see. '422': description: '`validation_error`: the id isn''t a uuid.' '503': description: > `upstream_error`: the delete stopped part-way, the storage service couldn't be reached, or Persistent Storage is not available right now. Send the same request again. components: schemas: GPUInventoryV1: type: object properties: gpu_inventory: type: object additionalProperties: type: object properties: instance_type: type: object properties: name: type: string description: type: string price_cents_per_hour: type: integer specs: type: object properties: vcpu_count: type: integer memory_gib: type: integer storage_gb: type: integer regions_with_capacity_available: type: array items: type: object properties: name: type: string description: type: string capacity_available: type: integer ImagesV1: type: object properties: images: type: array items: type: object properties: vm_image_id: type: integer vm_image_name: type: string vm_image_description: type: string RetrieveAllRunningInstancesV1: type: object properties: runningInstances: type: array items: type: object properties: uuid: type: string example: 8b52a46b-a892-4fde-925c-6d13226908f7 name: type: string example: Halloween Test ip: type: string example: 1.1.1.1 username: type: string example: Ubuntu password: type: string example: 123456 status: type: string example: rented os_booted: type: integer example: 1 command_startup: type: string example: '' created: type: string example: '2024-08-07T16:41:43.000Z' active: type: integer example: 1 image: type: object properties: id: type: integer example: 7 name: type: string example: Art description: type: string example: >- AI-powered tools specifically designed for artists and creatives, providing you with the ability to easily incorporate AI-generated content into your work. By harnessing the power of these advanced technologies, you can take your art to new heights and explore uncharted territories in the creative world. Leverage the full potential of AI and transform your artistic process today. product: type: object properties: name: type: string example: gpu_1x_l40 description: type: string example: 1x L40 gpu_count: type: integer example: 1 vcpu: type: integer example: 26 ram: type: integer example: 128 storage: type: integer example: 625 price_hr: type: string example: 0.99 final_price_hr: type: string example: 0 RetrieveSingleRunningInstanceV1: type: object properties: runningInstance: type: object properties: uuid: type: string example: 8b52a46b-a892-4fde-925c-6d13226908f7 name: type: string example: Halloween Test ip: type: string example: 1.1.1.1 username: type: string example: Ubuntu password: type: string example: 123456 status: type: string example: rented os_booted: type: integer example: 1 command_startup: type: string example: '' created: type: string example: '2024-08-07T16:41:43.000Z' active: type: integer example: 1 image: type: object properties: id: type: integer example: 7 name: type: string example: Art description: type: string example: >- AI-powered tools specifically designed for artists and creatives, providing you with the ability to easily incorporate AI-generated content into your work. By harnessing the power of these advanced technologies, you can take your art to new heights and explore uncharted territories in the creative world. Leverage the full potential of AI and transform your artistic process today. product: type: object properties: name: type: string example: gpu_1x_l40 description: type: string example: 1x L40 gpu_count: type: integer example: 1 vcpu: type: integer example: 26 ram: type: integer example: 128 storage: type: integer example: 625 price_hr: type: string example: '0.990000' final_price_hr: type: string example: '0.000000' RestartInstanceV1: type: object properties: response: type: array items: type: object properties: id: type: string example: 2c56cd01-5f0b-4bc2-bb72-3c8e486505e2 name: type: string example: test api deploy1 ip: type: string example: 1.1.1.1 status: type: string example: booting ssh_key_names: type: array items: type: string file_system_names: type: array items: type: string region: type: object properties: name: type: string example: us-central-3 description: type: string example: Des Moines, IA instance_type: type: object properties: name: type: string example: gpu_1x_a6000 description: type: string example: 1x RTX A6000 price_cents_per_hour: type: integer example: 0 specs: type: object properties: vcpus: type: integer example: 6 memory_gib: type: integer example: 48 storage_gb: type: integer example: 256 jupyter_token: type: string jupyter_url: type: string TerminateInstanceV1: type: object properties: response: type: object properties: data: type: object properties: terminated_instances: type: array items: type: object properties: id: type: string example: 2c56cd01-5f0b-4bc2-bb72-3c8e486505e2 name: type: string example: test api deploy1 ip: type: string example: 1.1.1.1 status: type: string example: terminated ssh_key_names: type: array items: type: string file_system_names: type: array items: type: string region: type: object properties: name: type: string example: us-central-3 description: type: string example: Des Moines, IA instance_type: type: object properties: name: type: string example: gpu_1x_a6000 description: type: string example: 1x RTX A6000 price_cents_per_hour: 0 specs: type: object properties: vcpus: type: integer example: 6 memory_gib: type: integer example: 48 storage_gb: type: integer example: 256 jupyter_token: type: string example: '' jupyter_url: type: string example: '' RetrieveCouponInformationV1: type: object properties: coupon: type: object properties: code: type: string example: TestCoupon discountPercent: type: string example: 0.1 deactivationDate: type: string example: '2024-08-07T16:41:43.000Z' RetrieveAcceptProductsV1: type: object properties: couponValidation: type: object properties: coupon: type: object properties: code: type: string example: TestCoupon discountPercent: type: string example: 0.1 deactivationDate: type: string example: '2024-08-07T16:41:43.000Z' productDetails: type: array items: type: object properties: name: type: string example: gpu_1x_a6000 description: type: string example: 1x RTX A6000 pricePerHour: type: string example: '0.625000' inventoryAvailable: type: boolean example: true example: - name: gpu_1x_a6000 description: 1x RTX A6000 pricePerHour: '0.625000' inventoryAvailable: true - name: gpu_2x_a6000 description: 2x RTX A6000 pricePerHour: '1.250000' inventoryAvailable: true - name: gpu_4x_a6000 description: 4x RTX A6000 pricePerHour: '2.500000' inventoryAvailable: true - name: gpu_8x_a6000 description: 8x RTX A6000 pricePerHour: '5.000000' inventoryAvailable: false RetrieveBillingInformationV1: type: object properties: billingMethod: type: string example: creditcard rechargeThresholdCents: type: integer example: 1000 rechargeThreshold: type: string example: 10 rechargeAmountCents: type: integer example: 2000 rechargeAmount: type: string example: 20 SSHKeyItem: type: object properties: id: type: string description: The unique identifier for the SSH key name: type: string description: The name of the SSH key public_key: type: string description: The public key associated with the SSH key SSHKey: type: object properties: sshKeys: type: array items: $ref: '#/components/schemas/SSHKeyItem' POSTSSHKey: type: object properties: sshKey: type: object properties: id: type: string description: The unique identifier for the SSH key name: type: string description: The name of the SSH key StorageVolume: type: object properties: id: type: string format: uuid description: >- The storage id. Pass it in `volumeIds` on launch, or to delete the storage. name: type: string example: datasets description: The storage name. It is also the mount folder, /persistent/. status: type: string enum: - creating - active - deleting - error description: > `active` storage can be attached. `deleting` means a delete is under way: send the delete again to finish it. `error` means something went wrong; `statusMessage` may say more. statusMessage: type: string nullable: true description: Extra detail when the storage isn't active. createdAt: type: string format: date-time description: When the storage was created. mountPath: type: string example: /persistent/datasets description: Where the storage is mounted on the instance it is attached to. instanceGroup: type: string nullable: true description: >- The uuid of the storage's instance group, or null for the account's default group. instanceGroupName: type: string nullable: true description: The name of that instance group, or null for the default group. canManage: type: boolean description: >- Whether you can manage the storage's group, which you need to attach or delete it. attachedTo: type: array description: >- Instances the storage is attached to, in groups you can see. Stopped instances are included. items: type: object properties: uuid: type: string name: type: string status: type: string hiddenAttachedCount: type: integer description: >- How many instances the storage is attached to in groups you can't see. They are counted, never named. StorageVolumeList: type: object properties: storageVolumes: type: array items: $ref: '#/components/schemas/StorageVolume' CreatedStorageVolume: type: object properties: storageVolume: description: > The new storage. If it was created in a group you can't see, only `id` and `name` are returned. allOf: - $ref: '#/components/schemas/StorageVolume' warning: type: string description: > Present when the storage was created but couldn't be placed in the requested instance group. It is in the account's default group instead. DeletedStorageVolume: type: object properties: result: type: object properties: id: type: string name: type: string deleted: type: boolean description: >- true when the storage is gone. false means it is still being emptied; send the same request again. filesDeleted: type: integer description: Files removed in this pass. Only present when deleted is false. message: type: string description: Only present when deleted is false.