Create an Instance

This endpoint allows an authenticated provider to list a new GPU instance on the marketplace. The request will be validated against the provider's instance limit and the integrity of the submitted data.

Endpoint

POST /api/v1/instances

Authentication

Type	Required	Location	Description
Provider Key	`true`	Header	The key must be sent as `x-api-key: PROVIDER_KEY`.

📘
This endpoint is for providers only. You must provide your unique Provider API Key to authenticate the request.

Request Body

The body of the request must be a JSON object containing the full specifications of the GPU instance.

Field	Type	Required	Description
`gpu_model`	string	`true`	The specific model of the GPU (e.g., "NVIDIA A100 80GB"). Max 70 chars.
`interconnect_details`	string	`true`	Details about GPU-to-GPU communication (e.g., "NVLink 600 GB/s"). Max 120 chars.
`total_gpus`	string	`true`	The total number of GPUs in the instance (e.g., "4", "8"). Max 50 chars.
`os`	string	`true`	The operating system provided (e.g., "Ubuntu 22.04 LTS"). Max 80 chars.
`cpu`	string	`true`	vCPU details (e.g., "2 x AMD EPYC 7742"). Max 50 chars.
`ram`	string	`true`	The amount of RAM (e.g., "1024GB DDR4"). Max 50 chars.
`storage`	string	`true`	Storage type and size (e.g., "4TB NVMe SSD"). Max 150 chars.
`network_and_bandwidth_details`	string	`true`	Network connectivity details (e.g., "200 Gbps Infiniband"). Max 250 chars.
`location`	string	`true`	The physical or regional locations of the instance (e.g., "Mumbai, India"). Max 200 chars.
`support_options`	string	`true`	Available support channels (e.g., "Email & Phone Support 24/7"). Max 150 chars.
`instance_backing`	string	`true`	The backing infrastructure type (e.g., "Secured", "Community", "P2P"). Max 30 chars.
`instance_type`	string	`true`	The type of instance (e.g., "Bare Metal", "VM"). Max 15 chars.
`additional_details`	string	`true`	Any other relevant information or features. Max 1050 chars.
`time_period_options`	array of strings	`true`	A list of available rental periods. Valid options: `"1w"`, `"2w"`, `"3w"`, `"1m"`, `"3m"`, `"6m"`, `"1y"`, `"1.5y"`, `"2y"`, `"2.5y"`, `"3y"`.
`original_price`	object	`true`	A dictionary mapping periods from `time_period_options` to their original (non-discounted) price as a string.
`offered_price`	object	`true`	A dictionary mapping periods from `time_period_options` to the special offered price as a string.
`time_extension_details`	object	`true`	An object specifying contract extension rules.
↳ `allowed`	boolean	`true`	`true` if the customer can request a time extension.
↳ `at_same_cost`	boolean	`true`	`true` if the extension is offered at the same discounted rate.

Request Validation

The keys in original_price and offered_price must exactly match order the values in time_period_options.
For each period, the value in offered_price must be numerically less than the corresponding value in original_price.
All required fields must be present in the request body.

Example Request

curl -X POST 'https://offers.dataoorts.com/api/v1/instances' \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_PROVIDER_API_KEY' \
-d '{
    "gpu_model": "NVIDIA A100 80GB",
    "interconnect_details": "NVLink 600 GB/s",
    "total_gpus": "8",
    "os": "Ubuntu 22.04 LTS",
    "cpu": "2 x AMD EPYC 7742",
    "ram": "1024GB DDR4",
    "storage": "4TB NVMe SSD",
    "network_and_bandwidth_details": "200 Gbps Infiniband",
    "location": "Mumbai, India",
    "support_options": "Email & Phone Support 24/7",
    "instance_backing": "Secured",
    "instance_type": "Bare Metal",
    "additional_details": "This is a high-performance instance for AI training.",
    "time_period_options": ["1m", "3m"],
    "original_price": {
        "1m": "5000.00",
        "3m": "14500.00"
    },
    "offered_price": {
        "1m": "4899.99",
        "3m": "13999.50"
    },
    "time_extension_details": {
        "allowed": false,
        "at_same_cost": false
    }
}'

Responses

✅ Success Response (201 Created)

Returned when the instance data is valid and successfully saved to the database.

Body

{
  "status": "Instance created successfully",
  "instance_id": "IID_21052024103005123"
}

❌ Error Response (400 Bad Request)

Returned for various validation errors in the request body.

Body (Example: Price Validation Error)

{
  "error": "Bad Request: Invalid instance data",
  "details": [
    "For period '1m', the offered price (5100.0) must be less than the original price (5000.0)."
  ]
}

Body (Example: Missing Field)

{
    "error": "Bad Request: Missing required field in JSON data",
    "details": "Missing key: 'gpu_model'"
}

❌ Error Response (401 Unauthorized)

Returned if the x-api-key header is missing or the provided key is invalid.

Body

{
  "error": "Unauthorized: Invalid API key."
}

❗️
More than three failed auth attempts will result in a permanent IP block.

❌ Error Response (403 Forbidden)

Returned if the provider has reached their maximum allowed number of active instances.

Body

{
  "error": "Forbidden: Instance limit reached.",
  "details": "Your limit is 10 & you have 10 instances, Please delete few or contact us!"
}

📘
To increase your instance offer quota or extend the retention period, email us at [email protected]

❌ Error Response (500 Internal Server Error)

Returned for database errors or other unexpected issues on the server.

Body

{
  "error": "Database error during authentication.",
  "details": "Specific error message from the database driver."
}