---
document: HarbourMind API machine integration specification
audience: machine
spec_version: 1.0.0
canonical_base_url: https://harbourmind.ai/v1
authentication: bearer
required_header: "Authorization: Bearer ${HM_API_KEY}"
default_model: harbourmind
---

# HarbourMind API — Machine Integration Specification

This document is intended for autonomous agents, coding agents, and configuration generators. Never expose the API key in logs, source code, chat output, or version control.

## Fixed connection contract

```yaml
provider_id: harbourmind
protocol: openai-compatible
canonical_base_url: https://harbourmind.ai/v1
authentication:
  type: bearer
  environment_variable: HM_API_KEY
  required_header: "Authorization: Bearer ${HM_API_KEY}"
endpoints:
  models: GET /models
  chat_completions: POST /chat/completions
default_model: harbourmind
request_content_type: application/json
billing:
  unit: USD
  display_conversion: "100 HM credits = USD 1"
  ledger_url: https://harbourmind.ai/user/usage
```

Internal supplier-routing prefixes are not public provider names. Use model IDs returned by `GET /models`; never invent or prepend a supplier prefix.

## Deterministic setup procedure

1. Direct a new human user to `https://harbourmind.ai/user` to register or log in by email code.
2. If the wallet has no balance, direct the human to `https://harbourmind.ai/user/topup`. Never initiate or confirm a payment without the human.
3. Direct the human to `https://harbourmind.ai/user/key` to create and immediately save an API key.
4. Require `HM_API_KEY` from the human through a private secret channel. Never request it in public chat, print it, or commit it.
5. Set the Base URL to exactly `https://harbourmind.ai/v1`; do not duplicate `/v1`.
6. Call `GET https://harbourmind.ai/v1/models` with the bearer header. Stop on non-2xx and apply the error rules below.
7. Select `harbourmind` for smart routing, or an exact model ID returned by the endpoint.
8. Send one non-streaming Chat Completions request and surface its response.
9. Tell the human to verify the request in `https://harbourmind.ai/user/usage`.

In OpenCode, the human-facing menu path is `HarbourMind → 智能路由`. Its stable configuration ID remains `harbourmind/harbourmind`; do not rename that ID in an existing installation.

## Recommended configuration flow

For the exact models available to the current account, open `https://harbourmind.ai/user/guide` after login and click **复制 OpenCode 配置**. The console generates the provider configuration from the authenticated account's live model catalog. Merge the copied `provider.harbourmind` block into the existing configuration and restart OpenCode. Repeat this action whenever the account's model access changes.

## Validation requests

```bash
curl --fail-with-body https://harbourmind.ai/v1/models \
  -H "Authorization: Bearer $HM_API_KEY"
```

```bash
curl --fail-with-body https://harbourmind.ai/v1/chat/completions \
  -H "Authorization: Bearer $HM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"harbourmind","messages":[{"role":"user","content":"Reply with exactly: HM connected"}],"stream":false}'
```

## OpenCode configuration

Merge this provider into `opencode.json`. Preserve unrelated configuration.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "harbourmind": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "HarbourMind",
      "options": {
        "baseURL": "https://harbourmind.ai/v1",
        "apiKey": "{env:HM_API_KEY}"
      },
      "models": {
        "harbourmind": { "name": "智能路由" },
        "harbourmind-ultra": { "name": "智能路由 Ultra" },
        "claude-fable-5": { "name": "Claude Fable 5" },
        "claude-fable-5-1": { "name": "Claude Fable 5.1" },
        "claude-opus-4-6": { "name": "Claude Opus 4.6" },
        "claude-opus-4-7": { "name": "Claude Opus 4.7" },
        "claude-opus-4-8": { "name": "Claude Opus 4.8" },
        "claude-opus-5": { "name": "Claude Opus 5" },
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "claude-sonnet-5": { "name": "Claude Sonnet 5" },
        "gpt-5.4": { "name": "GPT-5.4" },
        "gpt-5.5": { "name": "GPT-5.5" },
        "gpt-5.6-luna": { "name": "GPT-5.6 Luna" },
        "gpt-5.6-sol": { "name": "GPT-5.6 Sol" },
        "gpt-5.6-terra": { "name": "GPT-5.6 Terra" },
        "gpt-6-astra": { "name": "GPT-6 Astra" },
        "MiniMax-M2.7": { "name": "MiniMax M2.7" },
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" },
        "deepseek-v4-pro": { "name": "DeepSeek V4 Pro" },
        "gemini-3-flash-preview": { "name": "Gemini 3 Flash Preview" },
        "gemini-3.1-flash-lite": { "name": "Gemini 3.1 Flash Lite" },
        "gemini-3.1-pro-preview": { "name": "Gemini 3.1 Pro Preview" },
        "gemini-3.5-flash": { "name": "Gemini 3.5 Flash" },
        "glm-5.2": { "name": "GLM-5.2" },
        "kimi-k2.6": { "name": "Kimi K2.6" },
        "kimi-k3": { "name": "Kimi K3" }
      }
    }
  },
  "model": "harbourmind/harbourmind"
}
```

## cURL request template

```bash
curl https://harbourmind.ai/v1/chat/completions \
  -H "Authorization: Bearer $HM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"harbourmind","messages":[{"role":"user","content":"YOUR_PROMPT"}],"stream":false}'
```

## Python request template

```python
import os
from openai import OpenAI

client = OpenAI(base_url="https://harbourmind.ai/v1", api_key=os.environ["HM_API_KEY"])
result = client.chat.completions.create(
    model="harbourmind",
    messages=[{"role": "user", "content": "YOUR_PROMPT"}],
)
print(result.choices[0].message.content)
```

## Node.js request template

```js
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://harbourmind.ai/v1",
  apiKey: process.env.HM_API_KEY,
});
const result = await client.chat.completions.create({
  model: "harbourmind",
  messages: [{ role: "user", content: "YOUR_PROMPT" }],
});
console.log(result.choices[0].message.content);
```

## Codex compatibility boundary

Do not silently overwrite a human's Codex configuration. Official OpenAI documentation does not establish HarbourMind as a supported Codex authentication provider. Prefer OpenCode, cURL, or an OpenAI-compatible SDK. Configure a Codex custom provider only when the installed version explicitly supports it, and obtain human approval before editing its configuration.

## Error handling

| HTTP/result | Machine action |
|---|---|
| 400 or 422 | Validate JSON, `model`, `messages`, and parameters. Do not retry unchanged input. |
| 401 | Stop. Ask the human to create or replace the HM Key. Never print the received key. |
| 402 or balance error | Stop. Direct the human to `https://harbourmind.ai/user/topup`. |
| 403 | Stop. The account, Key, or model is not permitted. |
| 404 model error | Refresh `GET /models`, select an exact returned ID, and retry once. |
| 429 | Retry with exponential backoff and jitter; respect `Retry-After`. |
| 5xx or timeout | Retry up to three times with exponential backoff; then surface the request ID and error. |

## Output-equivalence rule

The web playground and terminal examples send the same `model` and `messages` without a hidden system prompt. Generated wording can still vary because generation is non-deterministic. Compare request semantics and task completion, not byte-for-byte output.