API Endpoints

Team Hub exposes a JSON HTTP API for shared collections, environments, folders, and saved requests. All routes except GET /health require a valid bearer token — see Authentication.

Overview

• Base URL: http://127.0.0.1:8788 (default from server.yaml)
• Content-Type: application/json for request and response bodies
• Protected routes: Authorization: Bearer hbk_...

Example authenticated request:

curl -s http://127.0.0.1:8788/collections \
  -H "Authorization: Bearer hbk_your_token_here"

Conventions

Timestamps

Date fields in responses are ISO 8601 strings (for example "2026-01-01T00:00:00.000Z").

Errors

Failed requests return a JSON body:

{ "error": "Human-readable message" }

Status	When
400	Validation failure or missing required field
401	Missing, malformed, unknown, or revoked bearer token
404	Entity not found

Empty responses

Routes that return 204 No Content send a null body.

Shared types

These shapes appear in multiple request and response payloads.

Variable — collection or environment variable:

{ "key": "baseUrl", "value": "https://api.example.com", "defaultValue": "", "share": false }

KeyValue — header or query parameter with enable toggle:

{ "key": "Accept", "value": "application/json", "enabled": true }

AuthConfig — authorization on collections and saved requests:

{
  "type": "none",
  "basic": { "username": "", "password": "" },
  "bearer": { "token": "" }
}

type is one of none, basic, or bearer.

BodyType — saved request body format: none, json, text, multipart, or urlencoded.

HTTP methods for saved requests: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

Health

GET /health

Public health check for load balancers and HarborClient connectivity probes. No authentication required.

Response 200:

{ "status": "ok", "version": "0.1.0" }

curl -s http://127.0.0.1:8788/health

Authentication

GET /auth/session

Returns the authenticated user account, API token metadata, and derived capability flags. Requires a valid bearer token.

Use this route to discover whether a token belongs to a user or admin account and which API surfaces it may call. HarborClient can probe this endpoint when saving a team hub connection to gate administration UI.

Response 200:

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "alice",
    "role": "user"
  },
  "token": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "prefix": "hbk_AbCd1234"
  },
  "capabilities": {
    "dataApi": true,
    "managementApi": false,
    "llm": true
  }
}

Capability	user role	admin role
dataApi	true	false
managementApi	false	true
llm	true when llmAccess is enabled	false

Response 401: Missing, malformed, unknown, or revoked bearer token.

curl -s http://127.0.0.1:8788/auth/session \
  -H "Authorization: Bearer hbk_your_token_here"

Administration

Management routes require an admin-role bearer token. user-role tokens receive 403 Forbidden.

GET /admin/users

Lists user accounts on the Team Hub server. The internal system account used for migrations and CLI attribution is omitted.

Response 200:

{
  "users": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "alice",
      "role": "user",
      "collectionAccess": ["*"],
      "environmentAccess": ["*"],
      "llmAccess": true,
      "llmModels": ["*"],
      "llmMonthlyTokenLimit": 100000,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "warnings": []
    }
  ]
}

Each user entry includes a warnings array. When stored access lists reference collection, environment, or LLM model ids that no longer exist on the hub, warnings describe the stale references (for example Unknown collection id "deleted-col".). An empty array means all referenced ids are valid.

Response 403: Authenticated user-role token.

Response 401: Missing, malformed, unknown, or revoked bearer token.

curl -s http://127.0.0.1:8788/admin/users \
  -H "Authorization: Bearer hbk_your_admin_token_here"

PUT /admin/users/:id

Updates a user account. The internal system account cannot be modified (403).

Request body (all fields optional):

{
  "name": "alice",
  "role": "user",
  "collectionAccess": ["*"],
  "environmentAccess": ["*"],
  "llmAccess": true,
  "llmModels": ["*"],
  "llmMonthlyTokenLimit": 100000
}

Response 200: Updated user record (same shape as a user entry in GET /admin/users, excluding the warnings field).

Response 400: Invalid access list (for example wildcard combined with specific ids), unknown collection/environment/LLM model id in a submitted access list, or invalid user name. Example:

{ "error": "Unknown collection id: missing-col." }

Only access lists explicitly included in the request body are validated against GET /admin/collections, GET /admin/environments, and GET /admin/llm/models. Partial updates that omit access fields leave existing stored access unchanged, even when those stored ids are stale.

Response 403: Authenticated user-role token, or attempt to modify the system account.

Response 404: Unknown user id.

curl -s -X PUT http://127.0.0.1:8788/admin/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer hbk_your_admin_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"alice-renamed"}'

DELETE /admin/users/:id

Deletes a user account and permanently removes all of their API tokens. The internal system account cannot be deleted (403).

Response 204: User deleted.

Response 403: Authenticated user-role token, or attempt to delete the system account.

Response 404: Unknown user id.

curl -s -X DELETE http://127.0.0.1:8788/admin/users/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer hbk_your_admin_token_here"

POST /admin/users

Creates a user account and an initial API bearer token. The plaintext token secret is returned once in the response and is not stored on the server.

Request body:

{
  "name": "alice",
  "role": "user",
  "collectionAccess": ["*"],
  "environmentAccess": ["*"],
  "llmAccess": false,
  "llmModels": [],
  "llmMonthlyTokenLimit": null
}

Response 201:

{
  "user": { "id": "...", "name": "alice", "role": "user", "..." : "..." },
  "token": {
    "id": "...",
    "userId": "...",
    "name": "alice",
    "tokenPrefix": "hbk_AbCd1234",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "lastUsedAt": null,
    "revokedAt": null
  },
  "secret": "hbk_..."
}

Response 400: Invalid access lists, duplicate name, or unknown resource ids.

Response 403: Authenticated user-role token.

curl -s -X POST http://127.0.0.1:8788/admin/users \
  -H "Authorization: Bearer hbk_your_admin_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"alice","role":"user","collectionAccess":["*"],"environmentAccess":["*"]}'

GET /admin/tokens

Lists all API bearer tokens across user accounts (metadata only; never includes secrets).

Response 200:

{
  "tokens": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Desktop",
      "tokenPrefix": "hbk_AbCd1234",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "lastUsedAt": null,
      "revokedAt": null
    }
  ]
}

Response 403: Authenticated user-role token.

curl -s http://127.0.0.1:8788/admin/tokens \
  -H "Authorization: Bearer hbk_your_admin_token_here"

POST /admin/users/:id/tokens

Creates an additional API bearer token for an existing user account. The plaintext secret is returned once.

Request body:

{ "name": "Desktop" }

Response 201:

{
  "token": {
    "id": "...",
    "userId": "...",
    "name": "Desktop",
    "tokenPrefix": "hbk_AbCd1234",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "lastUsedAt": null,
    "revokedAt": null
  },
  "secret": "hbk_..."
}

Response 403: Authenticated user-role token, or attempt to create a token for the system account.

Response 404: Unknown user id.

curl -s -X POST http://127.0.0.1:8788/admin/users/550e8400-e29b-41d4-a716-446655440000/tokens \
  -H "Authorization: Bearer hbk_your_admin_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Desktop"}'

DELETE /admin/tokens/:id

Permanently deletes an API bearer token by id. Tokens owned by the internal system account cannot be deleted (403).

Response 204: Token deleted.

Response 403: Authenticated user-role token, or attempt to delete a system account token.

Response 404: Unknown token id.

curl -s -X DELETE http://127.0.0.1:8788/admin/tokens/770e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer hbk_your_admin_token_here"

GET /admin/collections

Lists all collections as lightweight { id, name } records for operator user management.

Response 200:

{
  "collections": [
    { "id": "550e8400-e29b-41d4-a716-446655440000", "name": "Shared API" }
  ]
}

Response 403: Authenticated user-role token.

curl -s http://127.0.0.1:8788/admin/collections \
  -H "Authorization: Bearer hbk_your_admin_token_here"

GET /admin/environments

Lists all environments as lightweight { id, name } records for operator user management.

Response 200:

{
  "environments": [
    { "id": "660e8400-e29b-41d4-a716-446655440001", "name": "Production" }
  ]
}

Response 403: Authenticated user-role token.

curl -s http://127.0.0.1:8788/admin/environments \
  -H "Authorization: Bearer hbk_your_admin_token_here"

GET /admin/llm/models

Lists all hub-offered LLM models from server.yaml for operator user management. Unlike GET /llm/models, this route is not filtered by the authenticated admin's own model access list.

Response 200: Same shape as GET /llm/models.

Response 403: Authenticated user-role token.

Response 503: LLM support is not configured on this Team Hub.

curl -s http://127.0.0.1:8788/admin/llm/models \
  -H "Authorization: Bearer hbk_your_admin_token_here"

Collections

Collections are top-level workspaces that hold folders, saved requests, and collection-scoped defaults (variables, headers, scripts, auth).

Collection record:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Shared API",
  "variables": [],
  "headers": [],
  "auth": { "type": "none", "basic": { "username": "", "password": "" }, "bearer": { "token": "" } },
  "preRequestScript": "",
  "postRequestScript": "",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

GET /collections

Lists all collections ordered by name. Results are filtered by the authenticated user's collection access list. admin-role tokens receive an empty list (no scoped access) but may call this route so HarborClient can mount a hub configured with an admin token.

Auth: Bearer token required.

Response 200:

{ "collections": [ /* collection records */ ] }

curl -s http://127.0.0.1:8788/collections \
  -H "Authorization: Bearer hbk_your_token_here"

POST /collections

Creates a new collection with the given display name.

Auth: Bearer token required.

Request body:

{ "name": "Shared API" }

Response 200: Collection record.

Response 400: Validation error (for example empty name).

curl -s -X POST http://127.0.0.1:8788/collections \
  -H "Authorization: Bearer hbk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Shared API"}'

PUT /collections/:id

Updates a collection's name, variables, headers, scripts, and auth defaults.

Auth: Bearer token required.

Request body:

{
  "name": "Shared API",
  "variables": [],
  "headers": [],
  "preRequestScript": "",
  "postRequestScript": "",
  "auth": { "type": "none", "basic": { "username": "", "password": "" }, "bearer": { "token": "" } }
}

Response 200: Updated collection record.

Response 400: Validation error.

Response 404: Collection not found.

DELETE /collections/:id

Deletes a collection and all nested folders and saved requests.

Auth: Bearer token required.

Response 204: No content.

Response 404: Collection not found.

Environments

Environments hold named variable sets used across requests.

Environment record:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Production",
  "variables": [],
  "createdAt": "2026-01-01T00:00:00.000Z"
}

GET /environments

Lists all environments ordered by name.

Auth: Bearer token required.

Response 200:

{ "environments": [ /* environment records */ ] }

curl -s http://127.0.0.1:8788/environments \
  -H "Authorization: Bearer hbk_your_token_here"

POST /environments

Creates a new environment with the given display name.

Auth: Bearer token required.

Request body:

{ "name": "Production" }

Response 200: Environment record.

Response 400: Validation error.

curl -s -X POST http://127.0.0.1:8788/environments \
  -H "Authorization: Bearer hbk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production"}'

PUT /environments/:id

Updates an environment's name and variables.

Auth: Bearer token required.

Request body:

{
  "name": "Production",
  "variables": [{ "key": "baseUrl", "value": "https://api.example.com", "defaultValue": "", "share": false }]
}

Response 200: Updated environment record.

Response 400: Validation error.

Response 404: Environment not found.

DELETE /environments/:id

Deletes an environment by id.

Auth: Bearer token required.

Response 204: No content.

Response 404: Environment not found.

Folders

Folders organize saved requests within a collection.

Folder record:

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "collectionId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Users",
  "sortOrder": 0,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

GET /collections/:collectionId/folders

Lists folders in a collection ordered by sort order, then name.

Auth: Bearer token required.

Response 200:

{ "folders": [ /* folder records */ ] }

curl -s http://127.0.0.1:8788/collections/550e8400-e29b-41d4-a716-446655440000/folders \
  -H "Authorization: Bearer hbk_your_token_here"

POST /collections/:collectionId/folders

Creates a folder in the given collection.

Auth: Bearer token required.

Request body:

{ "name": "Users" }

Response 200: Folder record.

Response 400: Validation error.

curl -s -X POST http://127.0.0.1:8788/collections/550e8400-e29b-41d4-a716-446655440000/folders \
  -H "Authorization: Bearer hbk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Users"}'

PATCH /folders/:id

Renames a folder by id.

Auth: Bearer token required.

Request body:

{ "name": "User Management" }

Response 200: Updated folder record.

Response 400: Validation error.

Response 404: Folder not found.

DELETE /folders/:id

Deletes a folder and all saved requests inside it.

Auth: Bearer token required.

Response 204: No content.

Response 404: Folder not found.

PUT /collections/:collectionId/folders/reorder

Reorders folders within a collection.

Auth: Bearer token required.

Request body:

{
  "orderedFolderIds": [
    "550e8400-e29b-41d4-a716-446655440002",
    "550e8400-e29b-41d4-a716-446655440003"
  ]
}

Response 204: No content.

Response 404: Collection or folder not found.

Requests

Saved requests store HTTP method, URL, headers, params, body, scripts, and optional folder placement.

Saved request record:

{
  "id": "550e8400-e29b-41d4-a716-446655440004",
  "collectionId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "List users",
  "method": "GET",
  "url": "https://api.example.com/users",
  "headers": [],
  "params": [],
  "auth": { "type": "none", "basic": { "username": "", "password": "" }, "bearer": { "token": "" } },
  "body": "",
  "bodyType": "none",
  "preRequestScript": "",
  "postRequestScript": "",
  "comment": "",
  "folderId": null,
  "sortOrder": 0,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

folderId is null when the request lives at the collection root.

GET /collections/:collectionId/requests

Lists saved requests in a collection.

Auth: Bearer token required.

Response 200:

{ "requests": [ /* saved request records */ ] }

curl -s http://127.0.0.1:8788/collections/550e8400-e29b-41d4-a716-446655440000/requests \
  -H "Authorization: Bearer hbk_your_token_here"

POST /collections/:collectionId/requests

Creates a new saved request in a collection.

Auth: Bearer token required.

Request body:

{
  "name": "List users",
  "method": "GET",
  "url": "https://api.example.com/users",
  "headers": [],
  "params": [],
  "auth": { "type": "none", "basic": { "username": "", "password": "" }, "bearer": { "token": "" } },
  "body": "",
  "bodyType": "none",
  "preRequestScript": "",
  "postRequestScript": "",
  "comment": "",
  "folderId": null
}

folderId is optional; omit it or set null for the collection root.

Response 200: Saved request record.

Response 400: Validation error.

Response 404: Collection or folder not found.

curl -s -X POST http://127.0.0.1:8788/collections/550e8400-e29b-41d4-a716-446655440000/requests \
  -H "Authorization: Bearer hbk_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"List users","method":"GET","url":"https://api.example.com/users","headers":[],"params":[],"auth":{"type":"none","basic":{"username":"","password":""},"bearer":{"token":""}},"body":"","bodyType":"none","preRequestScript":"","postRequestScript":"","comment":""}'

PUT /requests/:id

Updates an existing saved request by id.

Auth: Bearer token required.

Request body: Same fields as POST, plus required collectionId:

{
  "collectionId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "List users",
  "method": "GET",
  "url": "https://api.example.com/users",
  "headers": [],
  "params": [],
  "auth": { "type": "none", "basic": { "username": "", "password": "" }, "bearer": { "token": "" } },
  "body": "",
  "bodyType": "none",
  "preRequestScript": "",
  "postRequestScript": "",
  "comment": "",
  "folderId": null
}

Response 200: Updated saved request record.

Response 400: Validation error.

Response 404: Request, collection, or folder not found.

DELETE /requests/:id

Deletes a saved request by id.

Auth: Bearer token required.

Response 204: No content.

Response 404: Request not found.

PUT /collections/:collectionId/requests/reorder

Reorders saved requests within a folder or the collection root.

Auth: Bearer token required.

Request body:

{
  "folderId": null,
  "orderedRequestIds": [
    "550e8400-e29b-41d4-a716-446655440004",
    "550e8400-e29b-41d4-a716-446655440005"
  ]
}

Set folderId to null to reorder requests at the collection root.

Response 204: No content.

Response 404: Collection, folder, or request not found.

PUT /requests/:id/move

Moves a single saved request to another folder or a specific index at the collection root.

Auth: Bearer token required.

Request body:

{
  "folderId": "550e8400-e29b-41d4-a716-446655440002",
  "index": 0
}

Set folderId to null to move the request to the collection root at index.

Response 204: No content.

Response 404: Request or folder not found.

LLM routes

Hub-proxied LLM routes require bearer authentication and a user account with llmAccess enabled. When the llm section is absent from server.yaml, these routes return 503.

See LLM Proxy for configuration and CLI management.

GET /llm/models

Lists hub-offered models the authenticated user may use.

Auth: Bearer token required.

Response 200:

{
  "models": [
    {
      "id": "gpt-4o",
      "label": "GPT-4o",
      "provider": "openai"
    }
  ]
}

Response 403: User lacks LLM access or the route is forbidden.

Response 503: LLM support is not configured on the hub.

GET /llm/usage

Returns the authenticated user's current monthly token usage.

Auth: Bearer token required.

Response 200:

{
  "period": "2026-06",
  "totalTokens": 12345,
  "limit": 100000
}

limit is null when the user has no monthly cap.

POST /llm/chat/step

Runs one stateless LLM completion step using hub-configured provider keys.

Auth: Bearer token required.

Request body:

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "Hello" }
  ],
  "systemPrompt": "You are HarborClient assistant.",
  "tools": []
}

Response 200:

{
  "content": "Hi there.",
  "toolCalls": [
    {
      "id": "call_1",
      "name": "list_collections",
      "arguments": "{}"
    }
  ],
  "usage": {
    "promptTokens": 10,
    "completionTokens": 5,
    "totalTokens": 15
  }
}

Response 402: Monthly token limit reached for a new user turn.

Response 403: User lacks LLM access or the requested model is not allowed.

Response 503: LLM support is not configured on the hub.