Admin / Global Settings¶

Global settings manage API keys, storage providers, and database type across the entire system. These are user-level preferences stored in the user_api_keys table.

Base path: /api/settings

GET /api/settings/api-keys¶

List the status of every supported API key slot for the current user. Shows whether each key is set, its source (user-saved, server config, or none), and a masked preview.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "keys": [
      {
        "key_name": "openrouter_api_key",
        "is_set": true,
        "source": "user",
        "masked_value": "sk-or-...****1234"
      },
      {
        "key_name": "openai_api_key",
        "is_set": true,
        "source": "server",
        "masked_value": "sk-...****5678"
      },
      {
        "key_name": "mistral_api_key",
        "is_set": false,
        "source": "none",
        "masked_value": null
      }
    ]
  }
}

Source Value	Meaning
`"user"`	Key saved by user in the database
`"server"`	Key from server `.env` configuration
`"none"`	No key configured anywhere

Code	Cause
`401`	Invalid or missing token

curl http://localhost:8000/api/settings/api-keys \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.get(
    "http://localhost:8000/api/settings/api-keys",
    headers={"Authorization": f"Bearer {token}"},
)
keys = response.json()["data"]["keys"]
for k in keys:
    status = "SET" if k["is_set"] else "---"
    print(f"  {k['key_name']}: [{status}] source={k['source']}")

PUT /api/settings/api-keys¶

Save or update one or more API keys for the current user. Unknown key names are silently skipped.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Body:

{
  "keys": {
    "openrouter_api_key": "sk-or-v1-abc123...",
    "mistral_api_key": "mis-xyz789..."
  }
}

Field	Type	Required	Default	Description
`keys`	object	Yes	--	Key-value map of `key_name` to `key_value`

Status: 200 OK

{
  "success": true,
  "data": {
    "updated": 2
  }
}

Code	Cause
`401`	Invalid or missing token

curl -X PUT http://localhost:8000/api/settings/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keys": {"openrouter_api_key": "sk-or-v1-abc123"}}'

import httpx

response = httpx.put(
    "http://localhost:8000/api/settings/api-keys",
    headers={"Authorization": f"Bearer {token}"},
    json={"keys": {"openrouter_api_key": "sk-or-v1-abc123"}},
)
print(f"Updated: {response.json()['data']['updated']}")

DELETE /api/settings/api-keys/{key_name}¶

Remove a user-saved API key so the system falls back to server configuration.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "deleted": true
  }
}

Code	Cause
`401`	Invalid or missing token

curl -X DELETE http://localhost:8000/api/settings/api-keys/openrouter_api_key \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.delete(
    "http://localhost:8000/api/settings/api-keys/openrouter_api_key",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json()["data"])

POST /api/settings/api-keys/test¶

Test an API key by making a lightweight HTTP call to the provider. Returns whether the key is valid and a human-readable message.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Body:

{
  "service": "openrouter",
  "api_key": "sk-or-v1-abc123..."
}

Field	Type	Required	Default	Description
`service`	string	Yes	--	Service name (e.g. `"openrouter"`, `"openai"`, `"mistral"`)
`api_key`	string	Yes	--	Key to test

Status: 200 OK

{
  "success": true,
  "data": {
    "valid": true,
    "message": "OpenRouter API key is valid"
  }
}

Code	Cause
`401`	Invalid or missing token

curl -X POST http://localhost:8000/api/settings/api-keys/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service": "openrouter", "api_key": "sk-or-v1-abc123"}'

import httpx

response = httpx.post(
    "http://localhost:8000/api/settings/api-keys/test",
    headers={"Authorization": f"Bearer {token}"},
    json={"service": "openrouter", "api_key": "sk-or-v1-abc123"},
)
result = response.json()["data"]
print(f"Valid: {result['valid']}, {result['message']}")

GET /api/settings/storage¶

Get the current storage provider setting for the user.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "provider": "supabase"
  }
}

Provider Value	Description
`"supabase"`	Supabase Storage (default)
`"s3"`	S3-compatible storage
`"local"`	Local filesystem
`"none"`	Disabled (blocks re-ingestion)

Code	Cause
`401`	Invalid or missing token

curl http://localhost:8000/api/settings/storage \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.get(
    "http://localhost:8000/api/settings/storage",
    headers={"Authorization": f"Bearer {token}"},
)
print(f"Provider: {response.json()['data']['provider']}")

PUT /api/settings/storage¶

Set the storage provider.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Body:

{
  "provider": "s3"
}

Field	Type	Required	Default	Description
`provider`	string	Yes	--	`"supabase"`, `"s3"`, `"local"`, or `"none"`

Status: 200 OK

{
  "success": true,
  "data": {
    "provider": "s3"
  }
}

Code	Cause
`400`	Invalid provider value
`401`	Invalid or missing token

curl -X PUT http://localhost:8000/api/settings/storage \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider": "s3"}'

import httpx

response = httpx.put(
    "http://localhost:8000/api/settings/storage",
    headers={"Authorization": f"Bearer {token}"},
    json={"provider": "s3"},
)
print(response.json()["data"])

POST /api/settings/storage/test-s3¶

Test S3 connectivity. Missing fields are resolved from the user's saved keys, then from server config.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Body:

{
  "endpoint": "https://s3.example.com",
  "access_key": "AKIAIOSFODNN7EXAMPLE",
  "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "bucket": "my-bucket",
  "region": "auto"
}

Field	Type	Required	Default	Description
`endpoint`	string	No	saved/server	S3 endpoint URL
`access_key`	string	No	saved/server	Access key ID
`secret_key`	string	No	saved/server	Secret access key
`bucket`	string	No	saved/server	Bucket name
`region`	string	No	`"auto"`	Region

Status: 200 OK

{
  "success": true,
  "data": {
    "valid": true,
    "message": "S3 connection successful"
  }
}

Code	Cause
`401`	Invalid or missing token

curl -X POST http://localhost:8000/api/settings/storage/test-s3 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"endpoint": "https://s3.example.com", "bucket": "my-bucket"}'

import httpx

response = httpx.post(
    "http://localhost:8000/api/settings/storage/test-s3",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "endpoint": "https://s3.example.com",
        "access_key": "AKIAIOSFODNN7EXAMPLE",
        "secret_key": "wJalrXUtnFEMI...",
        "bucket": "my-bucket",
    },
)
result = response.json()["data"]
print(f"Valid: {result['valid']}, {result['message']}")

POST /api/settings/storage/test-local¶

Test that the local storage path is writable.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Body:

{
  "path": "/data/storage"
}

Field	Type	Required	Default	Description
`path`	string	No	server config	Filesystem path to test

Status: 200 OK

{
  "success": true,
  "data": {
    "valid": true,
    "message": "Local storage path is writable"
  }
}

Code	Cause
`401`	Invalid or missing token

curl -X POST http://localhost:8000/api/settings/storage/test-local \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/data/storage"}'

import httpx

response = httpx.post(
    "http://localhost:8000/api/settings/storage/test-local",
    headers={"Authorization": f"Bearer {token}"},
    json={"path": "/data/storage"},
)
print(response.json()["data"])

GET /api/settings/db-type¶

Get the current database type setting (cloud or local).

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "db_type": "cloud",
    "local_url_set": true,
    "local_key_set": true
  }
}

Field	Type	Description
`db_type`	string	`"cloud"` or `"local"`
`local_url_set`	boolean	Whether `LOCAL_SUPABASE_URL` is configured in `.env`
`local_key_set`	boolean	Whether `LOCAL_SUPABASE_KEY` is configured in `.env`

Code	Cause
`401`	Invalid or missing token

curl http://localhost:8000/api/settings/db-type \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.get(
    "http://localhost:8000/api/settings/db-type",
    headers={"Authorization": f"Bearer {token}"},
)
data = response.json()["data"]
print(f"DB Type: {data['db_type']}")
print(f"Local configured: URL={data['local_url_set']}, Key={data['local_key_set']}")

PUT /api/settings/db-type¶

Switch between cloud and local database. Uses credentials from .env -- no user input needed. Invalidates the Supabase client cache so the next request connects to the correct instance.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Body:

{
  "db_type": "local"
}

Field	Type	Required	Default	Description
`db_type`	string	Yes	--	`"cloud"` or `"local"`

Status: 200 OK

{
  "success": true,
  "data": {
    "db_type": "local"
  }
}

Code	Cause
`400`	Invalid `db_type` value, or local DB key not configured
`401`	Invalid or missing token

curl -X PUT http://localhost:8000/api/settings/db-type \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"db_type": "local"}'

import httpx

response = httpx.put(
    "http://localhost:8000/api/settings/db-type",
    headers={"Authorization": f"Bearer {token}"},
    json={"db_type": "local"},
)
print(f"Switched to: {response.json()['data']['db_type']}")

POST /api/settings/db-type/test¶

Test connectivity to the local Supabase instance configured in .env. No request body needed.

Auth: User

RequestResponseErrorscurl ExamplePython Example

Headers:

Header	Value
`Authorization`	`Bearer <token>`

Status: 200 OK

{
  "success": true,
  "data": {
    "valid": true,
    "message": "Local DB connection successful."
  }
}

Possible failure messages:

"LOCAL_SUPABASE_URL and LOCAL_SUPABASE_KEY must be set in .env."
"Invalid key (401 Unauthorized)."
"Cannot connect -- check that local Supabase is running."
"Connection timed out after 10s."

Code	Cause
`401`	Invalid or missing token

curl -X POST http://localhost:8000/api/settings/db-type/test \
  -H "Authorization: Bearer $TOKEN"

import httpx

response = httpx.post(
    "http://localhost:8000/api/settings/db-type/test",
    headers={"Authorization": f"Bearer {token}"},
)
result = response.json()["data"]
if result["valid"]:
    print("Local DB connection OK")
else:
    print(f"Failed: {result['message']}")