Custom API connectors
Connect an API that is not in the directory with the Generic REST / OpenAPI connector, and expose your own API to agents.
Updated 07/10/2026
On this page
When to use a custom connector
Use the Generic REST / OpenAPI connector (generic-rest-openapi) for an internal API, a partner API or any provider that is not yet in the connector directory. You describe the operations; Nexra runs them with the same safety controls as built-in connectors.
Quick setup in the console
Open Dashboard → Connect → Custom → Connect your own API and fill in:
Project and name.
Base URL: HTTPS only, with no user name, password, query string or fragment. Only this host is ever called, and redirects are not followed.
Read endpoint: the path that lists records (for example /v1/customers), the JSON path to the records array (for example data.items) and the field names to expose.
Authentication: Bearer token or None. For a bearer token, enter the Key Vault secret reference that holds it.
Optional receive endpoint: a POST path that accepts new records. Nexra sends the mapped fields as the request body.
Save, then Test read connection. The test calls the read endpoint once.
The console builder creates sandbox connections with a bearer token or no authentication. For other authentication types, more operations, pagination or production, create the connection through the API as described below.
Full configuration over the API
POST /api/console/connect/connections with connectorKey: "generic-rest-openapi":
{
"connectorKey": "generic-rest-openapi",
"projectId": "<project-id>",
"name": "Warehouse API",
"environment": "sandbox",
"configuration": {
"baseUrl": "https://api.example.com",
"secretReference": "https://<vault>.vault.azure.net/secrets/connect-<workspace-id>-warehouse",
"authentication": { "type": "bearer" },
"operations": {
"stock.list": {
"method": "GET",
"path": "/v2/stock",
"responseRecordsPath": "items",
"responseIdPath": "sku",
"pagination": { "cursorInputName": "cursor", "nextCursorPath": "next" },
"outputSchema": {
"type": "object",
"properties": { "sku": { "type": "string" }, "quantity": { "type": "number" } }
}
},
"stock.update": {
"method": "PUT",
"path": "/v2/stock/{sku}",
"requestBodyPath": "body",
"idempotencyHeader": "Idempotency-Key",
"inputSchema": {
"type": "object",
"required": ["quantity"],
"properties": { "quantity": { "type": "number" } }
}
}
}
}
}Authentication types
authentication.type | Secret JSON stored in Key Vault | Sent as |
|---|---|---|
none | None | Nothing |
bearer | {"token": "..."} | Authorization: Bearer ... |
basic | {"username": "...", "password": "..."} | Authorization: Basic ... |
api_key_header | {"apiKey": "..."} | The header named in authentication.name |
api_key_query | {"apiKey": "..."} | The query parameter named in authentication.name. Prefer a header where the API allows it. |
oauth2_client_credentials | {"clientId": "...", "clientSecret": "..."} | Bearer token from authentication.tokenUrl (optional scope) |
Operation fields
| Field | Purpose |
|---|---|
| Operation key (the object key) | <entity>.<action>, where the action is one of list, get, search, create, update, upsert, send or generate |
method | GET, POST, PUT, PATCH or DELETE |
path | Starts with /; {name} placeholders are filled from pathParameters and URL-encoded. .. and // are refused. |
responseRecordsPath, responseIdPath | Where the records and their IDs sit in the response |
requestBodyPath | Which input field becomes the request body (default body) |
pagination | cursorInputName and nextCursorPath for cursor paging |
idempotencyHeader | Header that receives Nexra's idempotency key on writes. Without it, writes are never retried automatically. |
inputSchema, outputSchema | JSON Schemas used for mapping and previews |
GET operations are reads. Every other method is a write and requires approval before production use. DELETE operations are treated as high risk.
Inputs at run time
Operations receive pathParameters, query (string, number or boolean values) and cursor, plus the body field. Every call carries X-Correlation-Id. Errors are classified as for built-in connectors: 401 is authentication, 403 permission, 404 not found, 429 rate limit (with Retry-After honoured), other 4xx validation and 5xx provider.
Storing the credential
Custom API secrets must already be in your workspace's Key Vault, named connect-<workspace-id>-…, before you reference them. Ask a workspace administrator to create the secret, then paste its URI into the connection. In production the reference must sit in the managed vault.
Expose your own API to agents
To let AI agents call your API rather than move data with it, import its OpenAPI document into an MCP server instead. See Use the Nexra MCP server.