Skip to main content
AI provider profiles define the connection details for the language model used by NekoHub’s asset enrichment and skills system. All endpoints require authentication via JWT Bearer token or API key. Only one profile can be active at a time. The active profile is used for all automatic enrichment and on-demand skill runs.

​
List AI provider profiles

GET /api/v1/system/ai/providers
Returns all configured AI provider profiles. Required permission: aiProviders.read

​
Response

​
data
array

​
Example

curl http://localhost:5121/api/v1/system/ai/providers \
  -H "Authorization: Bearer <token>"

​
Get the active AI provider profile

GET /api/v1/system/ai/providers/active
Returns the currently active AI provider profile, or null in data if none is configured as active. Required permission: aiProviders.read

​
Response

Returns the same profile object as items in List AI provider profiles, or { "data": null } if no active profile exists.

​
Example

curl http://localhost:5121/api/v1/system/ai/providers/active \
  -H "Authorization: Bearer <token>"

​
Create an AI provider profile

POST /api/v1/system/ai/providers
Creates a new AI provider profile. If you set isActive: true, any previously active profile is automatically deactivated. Required permission: aiProviders.create

​
Request body

​
name
string
required
A descriptive name for this profile (e.g. OpenAI GPT-4o).
​
apiBaseUrl
string
required
The base URL of the AI API. For OpenAI-compatible APIs, this is typically https://api.openai.com/v1.
​
apiKey
string
required
The API key for authenticating with the AI service.
​
modelName
string
required
The model to use (e.g. gpt-4o, claude-3-5-sonnet-20241022).
​
defaultSystemPrompt
string
Optional default system prompt to include in all AI requests made through this profile.
​
isActive
boolean
Whether to make this the active profile immediately. Only one profile can be active at a time.

​
Response — 201 Created

Returns the created AI provider profile object.

​
Example

curl -X POST http://localhost:5121/api/v1/system/ai/providers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI GPT-4o",
    "apiBaseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "modelName": "gpt-4o",
    "defaultSystemPrompt": "You are a helpful image analysis assistant.",
    "isActive": true
  }'

​
Update an AI provider profile

PATCH /api/v1/system/ai/providers/{id}
Updates an existing AI provider profile. Only fields you include are changed. Required permission: aiProviders.update

​
Path parameters

​
id
string (uuid)
required
The unique identifier of the profile to update.

​
Request body

​
name
string
New profile name. Omit to leave unchanged.
​
apiBaseUrl
string
New API base URL. Omit to leave unchanged.
​
apiKey
string
New API key. Omit to leave unchanged.
​
modelName
string
New model name. Omit to leave unchanged.
​
defaultSystemPrompt
string
New default system prompt. Omit to leave unchanged.
​
isActive
boolean
New active state. Setting to true deactivates any currently active profile.

​
Response — 200 OK

Returns the updated AI provider profile object.

​
Example

curl -X PATCH http://localhost:5121/api/v1/system/ai/providers/01956f8d-0000-0000-0000-000000000020 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"modelName": "gpt-4o-mini", "isActive": true}'

​
Delete an AI provider profile

DELETE /api/v1/system/ai/providers/{id}
Deletes an AI provider profile. If you delete the active profile, enrichment and skills will stop working until a new active profile is configured. Required permission: aiProviders.delete

​
Path parameters

​
id
string (uuid)
required
The unique identifier of the profile to delete.

​
Response

​
data
object

​
Example

curl -X DELETE http://localhost:5121/api/v1/system/ai/providers/01956f8d-0000-0000-0000-000000000020 \
  -H "Authorization: Bearer <token>"

​
Test an AI provider configuration

POST /api/v1/system/ai/providers/test
Tests an AI provider configuration by sending a real request to the AI service. Use this to verify your credentials and model name before saving a profile. You can test either an existing saved profile (by profileId) or an ad-hoc configuration (by providing connection details directly). Required permission: aiProviders.update

​
Request body

​
profileId
string (uuid)
Optional. The ID of an existing profile to test. If provided, the saved configuration is used as the base, and any other fields in the request override it.
​
apiBaseUrl
string
API base URL to test. Required if profileId is not provided.
​
apiKey
string
API key to test. Required if profileId is not provided.
​
modelName
string
Model name to test.
​
defaultSystemPrompt
string
Optional system prompt to include in the test request.

​
Response

​
data
object

​
Example

curl -X POST http://localhost:5121/api/v1/system/ai/providers/test \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "apiBaseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "modelName": "gpt-4o"
  }'

{
  "data": {
    "succeeded": true,
    "caption": "A sample test caption generated by the model.",
    "resolvedModelName": "gpt-4o",
    "resolvedApiBaseUrl": "https://api.openai.com/v1",
    "errorMessage": null
  }
}