> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nodepick.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Provision and Manage Compute Nodes with the HTTP API

> Use the Nodepick HTTP API to provision and manage compute nodes from any language or tool. Authenticate with your API key as a Bearer token.

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
```

<Warning>
  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.
</Warning>

## Endpoints

### Create a Node

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

**`POST /nodes`**

```bash theme={null}
curl -X POST https://api.nodepick.ai/nodes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

**Response** `201 Created`

```json theme={null}
{
  "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`**

```bash theme={null}
curl -X GET https://api.nodepick.ai/nodes \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response** `200 OK`

```json theme={null}
[
  {
    "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}`**

```bash theme={null}
curl -X GET https://api.nodepick.ai/nodes/node_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Response**

```json theme={null}
{
  "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}`**

```bash theme={null}
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:

```python theme={null}
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. |

<Tip>
  This guide covers the most common operations. For the full list of request parameters, optional fields, and detailed response schemas, see the [API Reference](/api-reference).
</Tip>