Endpoint
POST /providers/{providerConnectionId}/{providerPath}Operation ID: proxyProviderPost
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. |
application/json body
Required: No
Type: object
No named object fields.
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.
const response = await fetch(
'https://gateway.nexus.microvoid.io/providers/533c4e1e-2823-4349-86b9-d6f1a869a2ca/chat/completions',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.NEXUS_INFERENCE_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
},
);
if (!response.ok) throw new Error(`Nexus request failed: ${response.status}`);curl
curl --request POST \
"https://gateway.nexus.microvoid.io/providers/533c4e1e-2823-4349-86b9-d6f1a869a2ca/chat/completions" \
--header "Authorization: Bearer ${NEXUS_INFERENCE_KEY}" \
--header "Content-Type: application/json" \
--data "{}"