API Reference

Base URL and authentication

Use https://api.hostnotgpu.ae/v1 for the customer API. Send Authorization: Bearer YOUR_API_KEY from your server. An active account with a verified email address and a non-expired, non-revoked key is required. Each route checks its scope; configured IP restrictions also apply. See creating and revoking API keys and credential security.

For model discovery and inference, the dedicated base URL is https://serverless.hostnotgpu.ae/v1. Keep the /v1 prefix. The OpenAPI document is available for discovery; the endpoint-specific behavior below describes the current handlers.

Read customer resources

Paths below are relative to the base URL. List responses use {"data":[...]}. Wallet and individual-instance responses are objects without that list envelope. Money fields such as customerRate and customerCharge are decimal strings; preserve their precision.

• GET /gpus — requires gpus:read. Returns up to 100 available, visible offerings, ordered by underlying catalog rate before customer pricing. Fields include id, gpuType, gpuCount, region, tier, capacityClass, available, customerRate, cpu, ramGb, and storageGb. Use the returned id as offeringId when requesting a deployment quote.
• GET /instances — requires instances:read. Lists your instances newest first, with public identifiers, status, rates, and connection details. Use the returned publicId in GET /instances/{publicId} for one instance. Wait for readiness and verify the fingerprint before connecting; see SSH connections and fingerprints.
• GET /wallet — requires wallet:read. Returns currency, balance, reserved, available, and held. held equals reserved; available funds are balance minus reservations, with a minimum of zero. See wallet reservations and billing.
• GET /usage — requires usage:read. Returns GPU-instance usage records with times, decimal customer charges, units, and instance identifiers. Optional start and end date parameters select records starting on or after start and ending on or before end. End defaults to now; start defaults to 30 days before end. Supply ISO 8601 timestamps with a timezone. This route is not a combined serverless usage export.
• GET /templates — requires gpus:read. Returns visible deployment templates, hardware requirements, and environment-variable descriptors. The additional capability field is read_only when templates exist or unavailable when none exist.
• GET /models — requires pricing:read. Returns public model IDs, names, authors, modalities, context lengths, and displayed pricing. Optional modality filters the catalog. Use the returned public id as the inference model; see model selection.

Pagination and public availability

These handlers do not implement cursor, page, offset, or limit query parameters. Do not assume that adding them paginates results. In particular, the GPU list is capped at 100 offerings and does not return a next-page cursor. Use the documented usage time window and model modality filter where appropriate.

For anonymous inventory comparisons, use the separate Public GPU Availability API. Its deduplicated configurations and customer hourly prices do not contain deployment offering IDs and are not a substitute for the authenticated /gpus response.

First read request

Set HOSTNOTGPU_API_KEY in your server environment or secret store. This example reads available offerings; it does not launch an instance.

curl (Linux or macOS shell)

curl --fail-with-body --max-time 30 \
  "https://api.hostnotgpu.ae/v1/gpus" \
  -H "Authorization: Bearer $HOSTNOTGPU_API_KEY"

PowerShell

$headers = @{ Authorization = "Bearer $env:HOSTNOTGPU_API_KEY" }
Invoke-RestMethod -Method Get -TimeoutSec 30 -Uri "https://api.hostnotgpu.ae/v1/gpus" -Headers $headers

For more language examples, continue to API examples or the PowerShell guide.

Quote, launch, and manage an instance

POST /instances requires instances:write, a JSON body, and a non-empty Idempotency-Key of at most 255 characters. It accepts one machine per request (machineCount: 1). GPU deployment requires a USD wallet, available capacity, compatible configuration, and sufficient authorization funds.

1. Select a current offering from GET /gpus. Prepare offeringId and name (1–80 characters). Optional configuration fields include tier, environment, templateId, diskGb, env, and sshKeyIds. Their values must match the selected offering, template, and synchronized customer SSH keys. Unknown fields are rejected.
2. Send the chosen configuration with intent: "quote". The response contains data.selectedCustomerRate, data.authorizedMaxCustomerRate, data.capacityClass, data.instantBoot, and data.currency. A quote does not launch a machine.
3. Review both rates. To authorize launch, submit the same configuration with intent: "launch" and the reviewed authorizedMaxCustomerRate. Launch is the default intent when omitted. If the current ceiling no longer matches, the handler returns 409; obtain and review a fresh quote.
4. An accepted launch returns HTTP 202 with orderId, instanceId, status, and rate fields. Acceptance is not readiness. Read GET /instances/{instanceId} to follow status and obtain connection details.

Use a distinct key for each new launch, and reuse that same key for retries of that same launch. A launch whose order already has an instance returns that existing instance rather than creating a new one. Do not reuse the key for a different configuration.

PATCH /instances/{publicId} renames an instance with {"name":"new-name"}; it requires instances:write and a provider-ready instance. DELETE /instances/{publicId} requests termination and returns HTTP 202 with STOPPING or TERMINATED. These two handlers do not consume a client Idempotency-Key; do not infer create-style replay behavior for every mutation. Confirm termination before sending DELETE, then check status. See instance lifecycle guidance.

Serverless requests

POST /inference/chat, POST /inference/image, and POST /inference/video require inference:write, JSON, and a non-empty Idempotency-Key of at most 255 characters. Availability depends on the current model and supported capability. Chat accepts stream: false or no stream field; stream: true is rejected. Do not assume streaming or full compatibility with another vendor's API. Follow the Serverless API guide and first inference workflow.

Errors, rate limits, and support evidence

Handled API errors use {"error":{"code":"...","message":"..."}}. Field-validation errors can also include error.fields. Inspect the HTTP status and response content type before parsing; an intermediary failure may not be JSON. The instrumented customer routes return X-Request-Id for diagnosis.

• 400: correct invalid fields or a missing required idempotency key. Validation errors use INVALID_REQUEST.
• 401 / 403: check account verification, key validity, scopes, and IP restrictions. Retrying unchanged credentials will not fix the request.
• 402: insufficient wallet funds; review available balance and reservations.
• 404 / 409: check the public identifier, ownership, capacity, configuration, or changed pricing. Refresh the relevant resource and resolve the conflict before submitting again.
• 429: reduce concurrency and honor Retry-After when present. The platform limiter returns RATE_LIMITED with that header; upstream rate-limit responses may omit it. Limits are configurable for accounts, keys, and request categories, rather than one universal fixed allowance.
• 5xx: use bounded retries with backoff for transient read failures. For mutations, first reconcile status and retain the operation's key where supported; a timeout alone does not prove that work failed.

For a support request, include UTC time, method and path, HTTP status, request ID, and a redacted error. Keep authorization headers and secrets out of logs. See serverless error handling or support and human handoff.