LLM Settings API — Configure AI Providers Per User

The LLM Settings endpoints let each user choose and configure the AI backend that powers Ghostly’s assisted test generation. Settings are stored per-user in the user_llm_settings table. When no per-user settings exist, Ghostly transparently falls back to environment variable configuration — the envFallback field in the GET response tells you which case applies. All endpoints in this group require a JWT (dashboard session); API key authentication is not accepted here.

API keys submitted through the PUT endpoint are masked in all subsequent responses. The raw key is never returned once saved. Only the first four and last four characters are exposed as a hint (e.g. sk-t••••1234).

GET /v1/settings/llm — Get current LLM settings

Returns the currently saved LLM configuration for the authenticated user, together with a live connectivity status check.

Response — 200 OK

boolean

required

Always true on success.

settings

object | null

required

The user’s saved settings, or null if no per-user configuration has been saved yet.

Show settings fields

providerId

string

The ID of the configured provider (e.g. "openai", "cursor-cli", "ollama").

model

string

The active model identifier (e.g. "gpt-4o-mini", "auto").

baseUrl

string | null

The endpoint URL in use. Falls back to the provider’s defaultBaseUrl when not explicitly set. null for CLI-based providers.

apiKeyConfigured

boolean

true if an API key is stored for this user.

apiKeyHint

string | null

Partially masked key hint in the form "sk-t••••1234", or null if no key is configured.

status

LlmStatus

required

Live connectivity probe result.

Show LlmStatus fields

available

boolean

Whether the provider responded successfully during this request.

providerId

string

The catalog ID of the active provider.

model

string

The active model identifier.

source

"user" | "env" | "none"

Where the configuration originates: "user" (saved in DB), "env" (environment variables), or "none" (no config found).

cursorCli

object

Only present when the active provider is cursor-cli.

Show cursorCli fields

installed

boolean

Whether the Cursor Agent CLI binary is detected.

loggedIn

boolean

Whether agent login has been completed.

message

string

Human-readable status message.

envFallback

boolean

required

true when no per-user settings exist but Ghostly detected a valid LLM configuration in the server’s environment variables. In this case settings will be null.

curl example

curl https://your-ghostly-host/v1/settings/llm \
  -H "Authorization: Bearer <jwt>"

Example response

{
  "ok": true,
  "settings": {
    "providerId": "openai",
    "model": "gpt-4o-mini",
    "baseUrl": "https://api.openai.com/v1/chat/completions",
    "apiKeyConfigured": true,
    "apiKeyHint": "sk-t••••4321"
  },
  "status": {
    "available": true,
    "providerId": "openai",
    "model": "gpt-4o-mini",
    "source": "user"
  },
  "envFallback": false
}

PUT /v1/settings/llm — Save LLM settings

Saves or replaces the user’s LLM configuration. If an apiKey was previously stored and you want to remove it without supplying a new one, pass "clearApiKey": true.

Request body

providerId

string

required

The catalog ID of the provider to configure. Must match one of the IDs returned by GET /v1/settings/llm/providers (e.g. "openai", "cursor-cli", "mistral").

model

string

required

The model identifier to use. Must be a non-empty string; falls back to the provider’s defaultModel if blank.

apiKey

string

The plaintext API key for the provider. Only required for providers where needsApiKey is true. Omit this field (or leave it blank) to keep an existing key unchanged.

baseUrl

string

Override the provider’s endpoint URL. Falls back to the provider’s defaultBaseUrl when omitted. Required for providers where needsBaseUrl is true and no default is defined.

clearApiKey

boolean

Set to true to remove any previously stored API key for this provider. Takes precedence over any value in apiKey.

Response — 200 OK

Returns the updated settings object and a fresh connectivity status.

{
  "ok": true,
  "settings": {
    "providerId": "openai",
    "model": "gpt-4o-mini",
    "baseUrl": "https://api.openai.com/v1/chat/completions",
    "apiKeyConfigured": true,
    "apiKeyHint": "sk-t••••4321"
  },
  "status": {
    "available": true,
    "providerId": "openai",
    "model": "gpt-4o-mini",
    "source": "user"
  }
}

Response — 400 Bad Request

Returned for the following cases:

providerId does not match any entry in the catalog
model is missing or blank (and no default can be resolved)
apiKey is missing for a provider that requires one (and no key was previously stored)
baseUrl is missing for a provider that requires one (and no default URL exists)

curl example

curl -X PUT https://your-ghostly-host/v1/settings/llm \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "openai",
    "model": "gpt-4o-mini",
    "apiKey": "sk-your-openai-key",
    "baseUrl": "https://api.openai.com/v1/chat/completions"
  }'

POST /v1/settings/llm/test — Test the LLM connection

Runs a live connectivity check against the user’s currently saved LLM configuration and returns the result. No request body is required.

Response — 200 OK

{
  "ok": true,
  "status": {
    "available": true,
    "providerId": "openai",
    "model": "gpt-4o-mini",
    "source": "user"
  }
}

curl example

curl -X POST https://your-ghostly-host/v1/settings/llm/test \
  -H "Authorization: Bearer <jwt>"

GET /v1/settings/llm/providers — List available providers

Returns the full provider catalog. Use this to populate a provider picker in a UI or validate a providerId before saving settings.

Response — 200 OK

Returns { ok: true, providers: ProviderEntry[] }. Each entry in the providers array has the following shape:

string

required

Unique identifier for the provider (e.g. "openai", "cursor-cli", "ollama").

label

string

required

Display name shown in the UI (e.g. "OpenAI", "Cursor Agent CLI").

kind

"cli" | "http"

required

Transport kind. "cli" providers invoke a local binary; "http" providers call a REST endpoint.

description

string

required

Short human-readable description of the provider.

needsApiKey

boolean

required

Whether an API key must be supplied for this provider.

needsBaseUrl

boolean

required

Whether a base URL must be supplied or confirmed for this provider.

defaultBaseUrl

string | null

required

The provider’s default endpoint URL, or null for CLI providers.

defaultModel

string

required

The model used when no explicit model is specified.

supportsAutoModel

boolean

required

true for providers (like cursor-cli) that can select a model automatically.

supportsLiveModels

boolean

required

true if live model discovery is available via GET /v1/settings/llm/models.

modelOptions

array

required

Static list of known model options (or fallback models for live-capable providers).

Show modelOptions item

string

Model identifier used in API requests.

label

string

Human-readable display name.

Providers currently in the catalog:

id	label	kind	needsApiKey
`cursor-cli`	Cursor Agent CLI	`cli`	No
`openai`	OpenAI	`http`	Yes
`mistral`	Mistral	`http`	Yes
`anthropic`	Anthropic	`http`	Yes
`ollama`	Ollama (local)	`http`	No
`openrouter`	OpenRouter	`http`	Yes

curl example

curl https://your-ghostly-host/v1/settings/llm/providers \
  -H "Authorization: Bearer <jwt>"

GET /v1/settings/llm/models — List models for a provider

Returns available models for the specified provider. For providers that supportsLiveModels (currently cursor-cli), this attempts to query the CLI for a live list. All other providers return the static modelOptions array from the catalog.

Query parameters

providerId

string

The provider ID to list models for. Defaults to "cursor-cli" when omitted.

Response — 200 OK

boolean

required

Always true on success.

providerId

string

required

The resolved provider ID (echo of the query param or the default).

models

array

required

Array of model objects available for this provider. Each item has an id (model identifier string) and a label (human-readable display name).

source

"static" | "live" | "fallback"

required

"static" if the list came from the catalog; "live" if it was fetched dynamically from the CLI; "fallback" if a live fetch was attempted but failed and the static catalog list was returned instead.

curl example

curl "https://your-ghostly-host/v1/settings/llm/models?providerId=openai" \
  -H "Authorization: Bearer <jwt>"

Example response

{
  "ok": true,
  "providerId": "openai",
  "models": [
    { "id": "gpt-4o-mini", "label": "GPT-4o mini" },
    { "id": "gpt-4o", "label": "GPT-4o" },
    { "id": "gpt-4.1-mini", "label": "GPT-4.1 mini" }
  ],
  "source": "static"
}

Overview

Authentication

Runs

Projects

Settings

LLM Settings API — Configure AI Providers Per User

GET /v1/settings/llm — Get current LLM settings

Response — 200 OK

curl example

Example response

PUT /v1/settings/llm — Save LLM settings

Request body

Response — 200 OK

Response — 400 Bad Request

curl example

POST /v1/settings/llm/test — Test the LLM connection

Response — 200 OK

curl example

GET /v1/settings/llm/providers — List available providers

Response — 200 OK

curl example

GET /v1/settings/llm/models — List models for a provider

Query parameters

Response — 200 OK

curl example

Example response

Build docs developers (and LLMs) love

Overview

Authentication

Runs

Projects

Settings

Documentation Index

​GET /v1/settings/llm — Get current LLM settings

​Response — 200 OK

​curl example

​Example response

​PUT /v1/settings/llm — Save LLM settings

​Request body

​Response — 200 OK

​Response — 400 Bad Request

​curl example

​POST /v1/settings/llm/test — Test the LLM connection

​Response — 200 OK

​curl example

​GET /v1/settings/llm/providers — List available providers

​Response — 200 OK

​curl example

​GET /v1/settings/llm/models — List models for a provider

​Query parameters

​Response — 200 OK

​curl example

​Example response

Build docs developers (and LLMs) love

GET /v1/settings/llm — Get current LLM settings

Response — 200 OK

curl example

Example response

PUT /v1/settings/llm — Save LLM settings

Request body

Response — 200 OK

Response — 400 Bad Request

curl example

POST /v1/settings/llm/test — Test the LLM connection

Response — 200 OK

curl example

GET /v1/settings/llm/providers — List available providers

Response — 200 OK

curl example

GET /v1/settings/llm/models — List models for a provider

Query parameters

Response — 200 OK

curl example

Example response