The API

The API

AI models are pretty resource intensive, and we don't just run everything on one piece of hardware. The SiteHost AI API - accessible at https://ai.sitehost.nz/ - is what brings everything together. It's OpenAI (Cohere, for embeddings/reranking) compatible, so you can plug many existing harnesses into it.

Routing

The API's primary job is to handle routing. This means you hit a single endpoint, and your request is sent to the lowest-load AI backend that's serving the model you're looking for. You might want to make use of the cache (for now, faster requests, but we're working on also exposing cheaper rates for cached requests). You can do this by pinning your session with an X-Session-ID request header (we also accept some common alternatives). Some harnesses such as OpenCode will handle this for you.

Because we route requests based on model, if you hit an invalid endpoint with a valid model - for example, an embedding endpoint with a generative model - you'll get an HTTP 404 Not Found as the model in question won't be serving the invalid endpoint.

Status

To check the status of the API, we recommend using the /health endpoint which requires no authentication. If the API is serving normally, you should get a 200 response code with a {"status":"ok"} body. To check the service status of any particular model, you should use the /v1/models endpoint outlined in the authentication section.

Authentication

To gain access to the API, you'll need to create an AI API Key. You are able to set certain restrictions on the key that will determine what it can access, and where from. You need to include a valid authorisation header (e.g. Authorization: Bearer YOUR_KEY_HERE along with any requests to the API for access.

You can validate a key using the /v1/models OpenAI-compatible endpoint, which exposes all currently-available and authenticated models for a given key:

❯ curl -s https://ai.sitehost.nz/v1/models -H "Authorization: Bearer YOUR_KEY_HERE" | jq
{
  "object": "list",
  "data": [
    {
      "id": "Qwen/Qwen3-VL-Embedding-8B",
      "object": "model",
      "created": 1782767710,
      "owned_by": "sitehost"
    },
    {
      "id": "Qwen/Qwen3.6-27B",
      "object": "model",
      "created": 1782767710,
      "owned_by": "sitehost"
    }
  ]
}

Errors

When making requests against the API, you may on occasion encounter error responses - you'll never be billed for a failed request, but errors can be informational. Any 'good' response will come alongside an HTTP 2xx response code.

Client Errors

HTTP 4xx response codes are client errors. Alongside the error codes, you will usually get a descriptive message indicating what issue has been encountered.

Authentication/Permission Errors

An HTTP 401 will occur when an API key is invalid or is missing.
An HTTP 403 will occur when a key attempts to access a model/capability that isn't permitted or a request comes from a source IP address which is not allowed.
An HTTP 429 will occur when an API key's rate limit or cost limit are reached.

Validation Errors

An HTTP 400 indicates that your request's body cannot be read to forward to the backend, it is not valid JSON, or it is missing a model key (required for routing).
An HTTP 413 error indicates that your request's body is too large. We set an upper limit of 60MB.
An HTTP 422 error comes from one of our backends - typically indicating that the request body is malformed for the endpoint you've reached. This usually includes a Pydantic error message with details about what was expected/missing from your request body.

Not Found/Wrong Method Errors

An HTTP 404 can occur either when you attempt to reach an invalid endpoint, or when you try to reach a model that does not exist.
An HTTP 405 error can occur if you try to make the wrong request type to a valid endpoint (e.g. a GET request to an endpoint expecting POST).

Server Errors

Any HTTP 5xx errors indicate something is wrong with the server. Typically, we'd recommend retrying your request after waiting a few seconds, as these are typically temporary. If you're experiencing recurrent HTTP 5xx errors, especially if triggered by certain inputs, please get in touch with us at support@sitehost.co.nz.

Endpoints & Examples

For specific details regarding different capabilities, check out the following sections:

Inference

Embedding

Reranking