Managing external endpoints

External endpoints allow you to connect external API services, such as OpenAI, Azure OpenAI, other third-party inference services, or Neutree internal endpoints, to the AI Gateway through a unified proxy. This provides unified authentication, routing, and usage statistics, and avoids exposing provider API keys on the client side.

Creating an external endpoint

1. Log in to the Neutree management interface, click External Endpoints in the left navigation pane, then click Create on the right.

2. Fill in the configuration.

   • Basic Information

     Parameter	Description	Editable after creation
     Name	The name of the external endpoint. The name must contain only lowercase letters, digits, _, -, or ., can be up to 63 characters long, and must start and end with a letter or digit.	No
     Workspace	The workspace the external endpoint belongs to.	No

   • Configuration

     Set the timeout for waiting for an upstream response. The default is 60 seconds; 5 minutes is recommended. The timeout is the time Kong gateway waits for a complete response from the upstream after the connection is established. If the upstream server stalls and the idle time exceeds the configured value, Kong gateway triggers a timeout and returns a 504 Gateway Timeout response. Editable after creation.

   • Upstream

     You can configure one or more upstream providers for an external endpoint. Upstream providers support two types: External and Endpoint Ref.

     • External: Proxies requests to an external API address.

       Parameter	Description	Editable after creation
       Upstream URL	The complete URL of the external API (including the API path), for example https://api.openai.com/v1.	Yes
       API Key	The Bearer token for the upstream API.	Yes
       Model Mapping	Maps the externally exposed model name to the actual upstream model name. For example, if the exposed model name is fast and the upstream model name is gpt-4o-mini, requests for the fast model will be forwarded to gpt-4o-mini.	Yes

     • Endpoint Ref: Forwards requests to another endpoint in the same workspace.

       Parameter	Description	Editable after creation
       Internal Endpoint	The name of an internal endpoint in the same workspace on Neutree.	Yes
       Model mapping	Maps the externally exposed model name to the actual upstream model name. For example, if the exposed model name is fast and the upstream model name is gpt-4o-mini, requests for the fast model will be forwarded to gpt-4o-mini.	Yes

3. (Optional) Test the connection status of the upstream service. Click the Test Connection button in the upstream configuration. The system automatically verifies that the upstream URL and API key are available. After a successful test, the response latency and the number of available models are displayed.

4. After confirming the configuration, click Save to complete creation.

Viewing external endpoints

Log in to the Neutree management interface and click External Endpoints in the left navigation pane. The top of the right panel shows an overview of external endpoints, and the list below shows all current external endpoints. Click an external endpoint name to view its details.

The possible statuses of an external endpoint during operation are described below:

Status	Description
Pending	The external endpoint is waiting for the first synchronization.
Running	The external endpoint is running normally, and all upstreams are available.
Degraded	At least one upstream in the external endpoint is unavailable. Neutree excludes abnormal upstreams from the gateway configuration and continues to deliver configurations for other available upstreams. Clients can still call models corresponding to other available upstreams.
Failed	The external endpoint is abnormal. If all upstreams are unavailable, the external endpoint enters this status. Check the upstream status, error information, and logs.
Deleted	The external endpoint has been deleted.

On the external endpoint details page, you can also view the status of each upstream. The possible upstream statuses are described below:

Status	Description
Ready	The upstream has been successfully delivered to the gateway configuration.
Failed	The upstream is unavailable and has been excluded from the gateway configuration. The details page displays error information and Unavailable Models. Before the abnormal upstream recovers, requests sent to these models fail. Requests sent to other available models are not affected.

Getting the API URL

On the details page, Service URL is the API URL that external services use to call this external endpoint. Usage is the same as for a regular endpoint. After creating an API key for any OpenAI- or Anthropic-compatible client, you can use the API key to call this API URL for integration.

Information:

When using the API URL, make sure to append /v1 to the URL.

For example, to view the models of an external endpoint via API:

curl  <API_URL>/v1/models \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <api_key>'

Curl examples

1. Under Curl Example on the details page, select a model name, then click the copy icon to copy the corresponding command.

2. Create an API key for any OpenAI- or Anthropic-compatible client and save it securely.

3. Replace $ENDPOINT_API_KEY in the command copied in step 1 with the API key created in step 2 (or set the ENDPOINT_API_KEY environment variable), then run the command on the client to call the external endpoint’s API URL.

Editing an external endpoint

After an external endpoint is created, you can modify its upstream configuration as needed.

1. Log in to the Neutree management interface, click the menu icon (…) in the external endpoint list or details page, and select Edit.

2. Modify the configuration as needed. For parameter descriptions, see Creating an external endpoint.

3. After confirming the configuration, click Save to complete editing.

Deleting external endpoints

You can delete one or more external endpoints at a time.

1. Log in to the Neutree management interface, click the menu icon (…) in the external endpoint list or details page, and select Delete; or select multiple external endpoints in the list and click Delete above the list.

2. In the dialog that appears, confirm and click Delete. The selected external endpoints will be permanently deleted.