---
title: "Proxy a HEAD request"
description: "HEAD /providers/{providerConnectionId}/{providerPath} — Proxy a HEAD request"
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Proxy a HEAD request

## Endpoint

```http
HEAD /providers/{providerConnectionId}/{providerPath}
```

Operation ID: `proxyProviderHead`

## Authentication

Send the WorkspaceAccess-bound Inference Key as `Authorization: Bearer <inference-key>`. A Management Key cannot call the Gateway.

## Idempotency

This operation does not declare an `Idempotency-Key` requirement in the accepted OpenAPI contract.

## Request

### Parameters

| Name                   | Location | Required | Schema          | Description                                                                                                                            |
| ---------------------- | -------- | -------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `providerConnectionId` | path     | Yes      | `string / uuid` | ProviderConnection UUID belonging to the Workspace resolved from the inference key.                                                    |
| `providerPath`         | path     | Yes      | `string`        | Greedy suffix after the provider-scoped Nexus Base URL. It may contain `/` and is appended to the selected ProviderConnection baseUrl. |

### Body

_This operation has no request body._

## Responses

| Status | Description                                                                             | Content type                                                  | Schema                                |
| ------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------- |
| `200`  | Provider response proxied with its status, supported headers and content type.          | application/json, text/event-stream, application/octet-stream | `object`, `string`, `string / binary` |
| `400`  | Invalid proxy request or unsafe path/header.                                            | application/json                                              | `Error`                               |
| `401`  | Inference key is invalid or expired.                                                    | application/json                                              | `Error`                               |
| `403`  | Workspace access is unavailable or the selected connection is not allowed.              | application/json                                              | `Error`                               |
| `404`  | No active ProviderConnection has this ID in the authenticated Workspace.                | application/json                                              | `Error`                               |
| `409`  | Endpoint has no Usage Inspector and the Workspace does not allow unmetered passthrough. | application/json                                              | `Error`                               |
| `429`  | Quota is insufficient before provider invocation.                                       | application/json                                              | `Error`                               |
| `502`  | Connection or upstream provider failure.                                                | application/json                                              | `Error`                               |

### `200` response headers

| Header                    | Schema                          | Description |
| ------------------------- | ------------------------------- | ----------- |
| `x-nexus-request-id`      | `string`                        | —           |
| `x-nexus-metering-status` | `string (metered \| unmetered)` | —           |
| `x-nexus-quota-remaining` | `string`                        | —           |
| `x-nexus-quota-reset`     | `string / date-time`            | —           |

### `200` application/json schema

Type: `object`

_No named object fields._

### `200` text/event-stream schema

Type: `string`

_No named object fields._

### `200` application/octet-stream schema

Type: `string / binary`

_No named object fields._

### `400` application/json schema

Type: `Error`

| Field              | Required | Type                 | Description |
| ------------------ | -------- | -------------------- | ----------- |
| `error`            | Yes      | `object`             | —           |
| `error.message`    | Yes      | `string`             | —           |
| `error.type`       | Yes      | `string`             | —           |
| `error.code`       | Yes      | `string`             | —           |
| `error.param`      | No       | `string,null`        | —           |
| `error.request_id` | No       | `string`             | —           |
| `error.reset_at`   | No       | `string / date-time` | —           |

### `401` application/json schema

Type: `Error`

| Field              | Required | Type                 | Description |
| ------------------ | -------- | -------------------- | ----------- |
| `error`            | Yes      | `object`             | —           |
| `error.message`    | Yes      | `string`             | —           |
| `error.type`       | Yes      | `string`             | —           |
| `error.code`       | Yes      | `string`             | —           |
| `error.param`      | No       | `string,null`        | —           |
| `error.request_id` | No       | `string`             | —           |
| `error.reset_at`   | No       | `string / date-time` | —           |

### `403` application/json schema

Type: `Error`

| Field              | Required | Type                 | Description |
| ------------------ | -------- | -------------------- | ----------- |
| `error`            | Yes      | `object`             | —           |
| `error.message`    | Yes      | `string`             | —           |
| `error.type`       | Yes      | `string`             | —           |
| `error.code`       | Yes      | `string`             | —           |
| `error.param`      | No       | `string,null`        | —           |
| `error.request_id` | No       | `string`             | —           |
| `error.reset_at`   | No       | `string / date-time` | —           |

### `404` application/json schema

Type: `Error`

| Field              | Required | Type                 | Description |
| ------------------ | -------- | -------------------- | ----------- |
| `error`            | Yes      | `object`             | —           |
| `error.message`    | Yes      | `string`             | —           |
| `error.type`       | Yes      | `string`             | —           |
| `error.code`       | Yes      | `string`             | —           |
| `error.param`      | No       | `string,null`        | —           |
| `error.request_id` | No       | `string`             | —           |
| `error.reset_at`   | No       | `string / date-time` | —           |

### `409` application/json schema

Type: `Error`

| Field              | Required | Type                 | Description |
| ------------------ | -------- | -------------------- | ----------- |
| `error`            | Yes      | `object`             | —           |
| `error.message`    | Yes      | `string`             | —           |
| `error.type`       | Yes      | `string`             | —           |
| `error.code`       | Yes      | `string`             | —           |
| `error.param`      | No       | `string,null`        | —           |
| `error.request_id` | No       | `string`             | —           |
| `error.reset_at`   | No       | `string / date-time` | —           |

### `429` application/json schema

Type: `Error`

| Field              | Required | Type                 | Description |
| ------------------ | -------- | -------------------- | ----------- |
| `error`            | Yes      | `object`             | —           |
| `error.message`    | Yes      | `string`             | —           |
| `error.type`       | Yes      | `string`             | —           |
| `error.code`       | Yes      | `string`             | —           |
| `error.param`      | No       | `string,null`        | —           |
| `error.request_id` | No       | `string`             | —           |
| `error.reset_at`   | No       | `string / date-time` | —           |

### `502` application/json schema

Type: `Error`

| Field              | Required | Type                 | Description |
| ------------------ | -------- | -------------------- | ----------- |
| `error`            | Yes      | `object`             | —           |
| `error.message`    | Yes      | `string`             | —           |
| `error.type`       | Yes      | `string`             | —           |
| `error.code`       | Yes      | `string`             | —           |
| `error.param`      | No       | `string,null`        | —           |
| `error.request_id` | No       | `string`             | —           |
| `error.reset_at`   | No       | `string / date-time` | —           |

## Examples

### TypeScript fetch

The Gateway keeps provider payloads opaque; use the provider-compatible client or Fetch API rather than the Management SDK.

```ts
const response = await fetch(
  'https://gateway.nexus.microvoid.io/providers/533c4e1e-2823-4349-86b9-d6f1a869a2ca/chat/completions',
  {
    method: 'HEAD',
    headers: {
      Authorization: `Bearer ${process.env.NEXUS_INFERENCE_KEY}`,
    },
  },
);

if (!response.ok) throw new Error(`Nexus request failed: ${response.status}`);
```

### curl

```bash
curl --request HEAD \
  "https://gateway.nexus.microvoid.io/providers/533c4e1e-2823-4349-86b9-d6f1a869a2ca/chat/completions" \
  --header "Authorization: Bearer ${NEXUS_INFERENCE_KEY}"
```

## Related guide

- [Use my Nexus access](/docs/quickstarts/use-my-nexus-access)
- [API Reference overview](/api-reference)

Source: https://nexus.microvoid.io/api-reference/gateway/operations/proxy-provider-head/index.mdx