# Aventail Link integration reference

Source: [https://docs.aventail.co.uk/docs/integration/your-own-software](https://docs.aventail.co.uk/docs/integration/your-own-software)

Use the local inference endpoint in your application and check readiness before sending requests. Model discovery and chat completions were tested with **Aventail Link 2.0.0**; the separate agent API details below describe **Locai Link (Legacy Aventail) 1.3.2**.

### Separate the two API roles

Process overview; detailed actions and examples are below.

1.  **Separate the two API roles**
    
    Local inference and hosted management use different interfaces.
    
    -   Link agent :20505: Health and configured model discovery
    -   Model server :8100/v1: Model IDs and chat requests; port may differ
    -   Control management: Use a supported management API contract

**Read the API integration reference**

For a working request and response, start with [Connect your software](https://docs.aventail.co.uk/docs/getting-started/run-first-interface). This reference covers the connection and lifecycle around that request.

## Endpoints

Match the endpoint to your installed version:

| Endpoint | Address in the tested setup | Purpose | Version checked |
| --- | --- | --- | --- |
| `GET /v1/models` | `http://127.0.0.1:8100` | Model IDs accepted by the inference router | Aventail 2.0.0 and Locai Link (Legacy Aventail) 1.3.2 |
| `POST /v1/chat/completions` | `http://127.0.0.1:8100` | Language-model chat requests | Aventail 2.0.0 and Locai Link (Legacy Aventail) 1.3.2 |
| `GET /healthz` | `http://127.0.0.1:20505` | Agent version and health metadata | Locai Link (Legacy Aventail) 1.3.2 only |
| `GET /models` | `http://127.0.0.1:20505` | Configured model pipelines and serving state | Locai Link (Legacy Aventail) 1.3.2 only |

Use the serving port shown in Control or a model's discovery entry; `8100` is the port used in this walkthrough.

The [Link 1.3.2 health-server implementation](https://github.com/locai-co-uk/locai-link/blob/v1.3.2/src/link/infra/health_server.py) binds port `20505` to loopback and checks the request's Host and Origin. It is intended for local clients, not arbitrary hosted web origins.

The serving listener has separate configuration. The 1.3.2 test displayed `0.0.0.0`, which can listen on all network interfaces. The 2.0.0 test used loopback as its client address; that does not establish its bind or access-control policy. Review access controls before connecting other machines.

## Discover readiness

For Aventail Link 2.0.0, use `aventail status` with the [installed executable path](https://docs.aventail.co.uk/docs/link-app/file-locations), fetch `/v1/models`, then make a small chat request. The router returned the installed model with status `unloaded` before our successful first request; a listed model need not already be loaded in memory.

For Locai Link (Legacy Aventail) 1.3.2, query `/models` from a native client on the Link machine. Entries include `alias`, `port`, `host` and `is_serving`. A configured entry does not prove an inference request will succeed.

Use a bounded timeout and distinguish:

| Observation | Application behaviour |
| --- | --- |
| Agent cannot be reached | Offer to start Link and show diagnostics; a timeout does not prove it is uninstalled |
| Agent responds, no serving entry | Ask the user to [start serving](https://docs.aventail.co.uk/docs/getting-started/initial-setup#serve-a-model) |
| Serving entry exists | Fetch `/v1/models`, select an exact ID and send a test request |
| Model listed but request fails | Show the response error and check engine startup and resources |

Do not use `/healthz`'s single-model fields as a complete view of multi-model readiness. Likewise, `/v1/models` may list a routed model that is not currently loaded in memory.

## Send requests

Configure an OpenAI-compatible **chat-completions** client with the serving base URL ending in `/v1`. Use the exact model ID from discovery. The tested endpoint did not require authentication; a client requiring a non-empty key can use a placeholder such as `locai-local`. Never substitute a Control account or registration key.

Check HTTP status and non-empty `choices[0].message.content`. The response's `model` value may be a file path rather than the requested alias. Tool use, embeddings, streaming and other APIs require separate capability tests.

## Browser applications

A hosted browser application also needs an allowed origin and any local-network permission required by the browser. A successful terminal request does not establish browser access.

Provide the Aventail team with the exact application origin when arranging model configuration. Do not use an unrestricted origin as a workaround. CORS controls browser access; it is not authentication or a substitute for network access controls.

## Installation and updates

Use the [supported installation paths](https://docs.aventail.co.uk/docs/introduction/versions-and-supported-models), then register the device and deploy its model. Follow the checksum and signing information supplied with that release.

For Aventail Link 2.0.0, use `aventail status`, `aventail update --check` and `aventail update` with the [installed executable path](https://docs.aventail.co.uk/docs/link-app/file-locations). Locai Link (Legacy Aventail) 1.x uses `locai status` and `locai update`. Treat updates and restarts as potential interruptions: allow current work to finish and verify the endpoint afterward. Test your application's compatibility with the installed release.

## Errors and data handling

Retry read-only discovery with a bounded delay. A disconnected or timed-out generation may have partially completed; make retry visible to the user, especially when application tools have side effects.

Separate inference traffic, application logging and Link's management traffic when assessing data handling. Review the [architecture](https://docs.aventail.co.uk/docs/introduction/platform-architecture) and [privacy settings](https://docs.aventail.co.uk/docs/privacy/usage-analytics) for the selected workflow rather than assuming every integration keeps all data on one device.