Make your first API request

Start with a read-only request before you try actions that change an instance. This guide uses GET /instances to confirm that your API key works, the base URL is correct, and your client can read a JSON response.

Before you start

You’ll need:

A Compute with Hivenet account
An API key issued for that account
A terminal or API client

Production base URL: https://api.hivecompute.ai/v1 Staging base URL: https://staging-api.hivecompute.ai/v1

Use the production URL for normal integrations. Use staging only when you specifically need to test against the staging API.

Send a request

Prepare your API key

Store your key in an environment variable:

export HIVENET_API_KEY="YOUR_API_KEY"

List your instances

Send a GET request to /instances:

curl --request GET \
  --url "https://api.hivecompute.ai/v1/instances?size=10" \
  --header "Authorization: Bearer $HIVENET_API_KEY" \
  --header "Accept: application/json"

Check the response

A successful request returns 200 OK and a JSON response with a data array and pagination information.

{
  "data": [
    {
      "instance_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "my-training-run",
      "status": "RUNNING",
      "gpu_type": "RTX 5090",
      "region": "france-2"
    }
  ],
  "pagination": {
    "next": null,
    "size": 10
  }
}

An empty data array can still mean authentication succeeded. It may simply mean the account has no matching instances.

Region filters use codes such as FR, while the region field returned on an instance contains the datacenter location, such as france-2.

Read the response

Field	What it means
`data`	Instances returned by the request.
`instance_id`	The ID used for instance-specific requests.
`status`	The current lifecycle state.
`pagination.next`	Cursor for the next page, or `null` when there are no more pages.

Save an instance_id if you want to test GET /instances/{id} or GET /instances/{id}/logs next.

Common first errors

Status	Code	What to do
`400`	`VALIDATION_ERROR`	Check query parameters and allowed values.
`401`	`UNAUTHORIZED`	Check the `Authorization` header and API key.
`429`	`TOO_MANY_REQUESTS`	Wait for the `Retry-After` value before retrying.

Test authentication with read-only requests before using start, stop, or terminate actions.

Next step

Continue with Authenticate API requests for key-handling guidance.

Public API

API reference

Make your first API request

Before you start

Send a request

Read the response

Common first errors

Next step

​Before you start

​Send a request

​Read the response

​Common first errors

​Next step

Before you start

Send a request

Read the response

Common first errors

Next step