Providers API

This page is for developers who want to connect AI model providers from their own code. A provider is a company whose AI models you use (for example OpenAI, Anthropic or Mistral), connected once with your own key. For example, a setup script for a new organization can connect its provider keys in one call. In the app, this is Models → Connect a provider; see Connect a provider.

REST API reference for connecting and managing providers.

Endpoints

Connect a provider

One request that saves the provider, checks its key with one real call, and lists its models. On success every model it lists is usable. On failure nothing is saved.

curl -X POST https://api.almyty.com/llm-providers/connect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "openai", "configuration": { "apiKey": "sk-..." } }'

{
  "success": true,
  "data": {
    "provider": { "id": "7c1e...", "name": "OpenAI", "type": "openai", "isHealthy": true, "...": "..." },
    "models": [{ "id": "4f2a...", "vendorModelId": "gpt-5", "selectable": true, "effectivePricing": { "inPerMTok": 1.25, "outPerMTok": 10 }, "...": "..." }],
    "check": { "ok": true, "responseTime": 412 }
  }
}

A failure answers 400 with one plain sentence in message, the vendor’s own words in detail and the vendor’s key page in keyUrl:

The vendor’s own 401 never reaches you as a 401, so a client does not mistake it for its own session ending.

Which models a connection offers

Every model a connection’s key reaches is offered by default. Three fields, on connect, create and PATCH /llm-providers/:id, narrow that:

Both lists are kept whichever way the switch is set, so flipping it back loses nothing. Pin a key to one model:

curl -X PATCH https://api.almyty.com/llm-providers/7c1e... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "allowNewModels": false, "allowedModels": ["meta-llama/Llama-3.3-70B-Instruct"] }'

A model the connection does not offer reads allowed: false and selectable: false on GET /models, the router never plans it, and a chat call that names it through this connection answers 400 with MODEL_NOT_ALLOWED before anything reaches the provider. A call that names no model uses the connection’s default model when it is offered, else the best offered one. Changing these fields spends no key check. A change that would take away a model an agent uses is refused with 409 and MODEL_IN_USE; the body names the models, the agents the caller can see ({ id, name }) and a count of otherAgents, and nothing is saved. A rename changes the name of the key the connection made for itself too.

Add a provider

type picks the vendor, and everything else about the connection (the key, the base URL, the default call parameters) lives under configuration.

curl -X POST https://api.almyty.com/llm-providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "OpenAI Production",
    "type": "openai",
    "configuration": {
      "apiKey": "sk-...",
      "model": "gpt-4o",
      "temperature": 0.7,
      "maxTokens": 4096
    }
  }'

Parameters

Creating, updating, and deleting a provider require the admin or owner role. Reading, testing, and chatting are open to member as well.

configuration

Every field is optional; what a given vendor needs depends on its type.

Response

The provider comes back with its secrets stripped: configuration is reduced to the non-secret call settings, and the key is referenced rather than returned.

{
  "success": true,
  "data": {
    "id": "prov-uuid",
    "name": "OpenAI Production",
    "type": "openai",
    "status": "active",
    "configuration": {
      "model": "gpt-4o",
      "maxTokens": 4096,
      "temperature": 0.7,
      "apiUrl": null
    },
    "totalRequests": 0,
    "totalCost": 0,
    "createdAt": "2026-03-01T10:00:00Z"
  },
  "message": "Provider added"
}

status is one of active, inactive, error, or maintenance.

Test connection

Verify a saved provider is configured correctly. The platform makes one short real call, using the provider’s configured model or, when it has none, whatever the vendor currently serves:

curl -X POST https://api.almyty.com/llm-providers/{id}/test \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "isHealthy": true,
    "responseTime": 450
  },
  "message": "Connection test completed"
}

A failed probe returns isHealthy: false with an error string rather than an HTTP error.

To check a key before saving anything, post the pair to /llm-providers/test-connection:

curl -X POST https://api.almyty.com/llm-providers/test-connection \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "openai", "apiKey": "sk-..." }'

That returns {ok, latencyMs, modelCount}. Ollama is keyless, so apiKey may be omitted for it.

Send a chat message

The body is a message list, not a single string:

curl -X POST https://api.almyty.com/llm-providers/{id}/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello, what can you do?" }
    ],
    "sessionId": "optional-session-uuid"
  }'

messages is required. model overrides the provider default; maxTokens (1–200000), temperature (0–2), topP (0–1), topK (0–100), frequencyPenalty and presencePenalty (−2–2), stopSequences, tools, toolIds, and stream are all optional. Pass routing instead of model to let the model catalog pick, in which case the response carries a routing attribution saying which card answered.

Sessions maintain conversation history. Omit sessionId for one-off messages.

Supported providers

Which vendors almyty can call is registry data, not a list frozen in these docs, and which models are usable is a property of your organization’s catalog rather than of the platform. Three endpoints answer it live:

A model is usable once it is active, points at a callable provider, and that provider’s key check has passed; the check covers every model the provider lists. GET /models lists them with that state and POST /models/sync reads a provider’s list again. See the Models guide for the whole flow.

custom is the escape hatch: any OpenAI-compatible API, pointed at with configuration.apiUrl and shaped with configuration.custom.