AI Providers

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

array

Show item properties

string (uuid)

Profile ID.

string

Profile name.

string

Base URL of the AI API endpoint.

string

API key (partially redacted in responses).

string

Model identifier to use (e.g. gpt-4o, claude-3-5-sonnet).

string

Default system prompt sent with AI requests.

boolean

Whether this is the active profile used for enrichment.

string (ISO 8601)

Creation timestamp.

string (ISO 8601)

Last update timestamp.

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

string

required

A descriptive name for this profile (e.g. OpenAI GPT-4o).

string

required

The base URL of the AI API. For OpenAI-compatible APIs, this is typically https://api.openai.com/v1.

string

required

The API key for authenticating with the AI service.

string

required

The model to use (e.g. gpt-4o, claude-3-5-sonnet-20241022).

string

Optional default system prompt to include in all AI requests made through this profile.

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

string (uuid)

required

The unique identifier of the profile to update.

Request body

string

New profile name. Omit to leave unchanged.

string

New API base URL. Omit to leave unchanged.

string

New API key. Omit to leave unchanged.

string

New model name. Omit to leave unchanged.

string

New default system prompt. Omit to leave unchanged.

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

string (uuid)

required

The unique identifier of the profile to delete.

Response

object

Show properties

string (uuid)

ID of the deleted profile.

boolean

Whether this profile was active at the time of deletion.

string

Final status.

string (ISO 8601)

Deletion timestamp.

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

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.

string

API base URL to test. Required if profileId is not provided.

string

API key to test. Required if profileId is not provided.

string

Model name to test.

string

Optional system prompt to include in the test request.

Response

object

Show properties

boolean

Whether the test request to the AI service succeeded.

string

A test caption generated by the model, confirming connectivity and that the model can process images.

string

The model name that was actually used.

string

The API base URL that was actually used.

string

Error message if succeeded is false.

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
  }
}

Overview

Endpoints

List AI provider profiles

Response

Example

Get the active AI provider profile

Response

Example

Create an AI provider profile

Request body

Response — 201 Created

Example

Update an AI provider profile

Path parameters

Request body

Response — 200 OK

Example

Delete an AI provider profile

Path parameters

Response

Example

Test an AI provider configuration

Request body

Response

Example

​List AI provider profiles

​Response

​Example

​Get the active AI provider profile

​Response

​Example

​Create an AI provider profile

​Request body

​Response — 201 Created

​Example

​Update an AI provider profile

​Path parameters

​Request body

​Response — 200 OK

​Example

​Delete an AI provider profile

​Path parameters

​Response

​Example

​Test an AI provider configuration

​Request body

​Response

​Example

List AI provider profiles

Response

Example

Get the active AI provider profile

Response

Example

Create an AI provider profile

Request body

Response — 201 Created

Example

Update an AI provider profile

Path parameters

Request body

Response — 200 OK

Example

Delete an AI provider profile

Path parameters

Response

Example

Test an AI provider configuration

Request body

Response

Example