Provision and Manage Compute Nodes with the HTTP API

The Nodepick HTTP API gives you direct, language-agnostic access to every node operation. You can use it from any HTTP client — curl, Postman, Python’s requests library, or your own custom integration — without installing the Python SDK. This guide walks you through authentication, all core endpoints, and a working Python example using raw HTTP calls.

Base URL

All API requests are made to the following base URL:

https://api.nodepick.ai

Authentication

Every request to the Nodepick API must include your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Never expose your API key in client-side code or public repositories. Use environment variables or a secrets manager to store and access it securely.

Endpoints

Create a Node

Provision a new Linux kernel node. The node begins provisioning immediately after the request is accepted. POST /nodes

curl -X POST https://api.nodepick.ai/nodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response 201 Created

{
  "id": "node_abc123",
  "status": "provisioning",
  "ip_address": null,
  "created_at": "2024-01-15T10:30:00Z"
}

The ip_address field is null while the node is still provisioning. Poll GET /nodes/{id} until status is running to get the assigned IP address.

List All Nodes

Retrieve a list of all nodes associated with your account, including their current statuses. GET /nodes

curl -X GET https://api.nodepick.ai/nodes \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

[
  {
    "id": "node_abc123",
    "status": "running",
    "ip_address": "203.0.113.42",
    "created_at": "2024-01-15T10:30:00Z"
  }
]

Get Node Details

Fetch the full details of a specific node, including its IP address and current status. GET /nodes/{id}

curl -X GET https://api.nodepick.ai/nodes/node_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "node_abc123",
  "status": "running",
  "ip_address": "203.0.113.42",
  "created_at": "2024-01-15T10:30:00Z"
}

Delete a Node

Permanently delete a node. Billing stops immediately once the node is deleted. DELETE /nodes/{id}

curl -X DELETE https://api.nodepick.ai/nodes/node_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content with an empty response body on success.

Using the API from Python

If you prefer not to use the SDK, you can call the Nodepick API directly using Python’s requests library:

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.nodepick.ai"
headers = {"Authorization": f"Bearer {API_KEY}"}

# Create a node
response = requests.post(f"{BASE_URL}/nodes", headers=headers)
node = response.json()
print(f"Node ID: {node['id']}")

# Get node details
node_id = node["id"]
response = requests.get(f"{BASE_URL}/nodes/{node_id}", headers=headers)
details = response.json()
print(f"Status: {details['status']}")
print(f"IP Address: {details.get('ip_address', 'Not yet assigned')}")

# Delete the node
requests.delete(f"{BASE_URL}/nodes/{node_id}", headers=headers)
print("Node deleted")

HTTP Status Codes

Familiarize yourself with the status codes the API returns so you can handle errors gracefully in your integration:

Status Code	Meaning
`200 OK`	The request succeeded and a response body is returned.
`201 Created`	A new resource (e.g. a node) was successfully created.
`204 No Content`	The request succeeded (used for DELETE operations) with no body.
`400 Bad Request`	The request was malformed or contained invalid parameters.
`401 Unauthorized`	Your API key is missing, invalid, or has been revoked.
`403 Forbidden`	Your API key does not have permission to perform this action.
`404 Not Found`	The requested node ID does not exist or has already been deleted.
`500 Internal Server Error`	An unexpected error occurred on the Nodepick side. Retry the request, or contact support if it persists.

This guide covers the most common operations. For the full list of request parameters, optional fields, and detailed response schemas, see the API Reference.

Get Started

Nodes

Guides

Provision and Manage Compute Nodes with the HTTP API

Base URL

Authentication

Endpoints

Create a Node

List All Nodes

Get Node Details

Delete a Node

Using the API from Python

HTTP Status Codes

​Base URL

​Authentication

​Endpoints

​Create a Node

​List All Nodes

​Get Node Details

​Delete a Node

​Using the API from Python

​HTTP Status Codes

Base URL

Authentication

Endpoints

Create a Node

List All Nodes

Get Node Details

Delete a Node

Using the API from Python

HTTP Status Codes