AI Providers
The credentialed model vendors a project generates through — and the models and prices each one carries.
Overview
An AI provider is a project-scoped record naming a vendor (openai,
anthropic, bedrock, ollama, …), a default_model, and the
secret holding the credential to authenticate with. An agent either pins one provider directly
(ai_provider_id) or generates through a model route whose
targets each name one.
A provider is project configuration, written over this API and
formations only: a builtin tool may read
providers, never write them (Tool actions).
Every project also lists the shared naturali provider,
which serves the whole managed offering under one id, with no credential of
yours, metered at the catalog's pricing. Every provider a
project creates is its own: register your credential as a
secret and the vendor bills you directly; naturali adds no LLM
cost.
This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → AI Providers.
Data Model
AiProvider
| Field | Type | Description |
|---|---|---|
id | string | |
name | string | |
provider | string | |
default_model | string | |
project_id | string | |
secret_id | string, nullable | |
base_url | string | |
config | object | Additional provider-specific configuration. Never carries a credential. |
model_aliases | object | Alias → the model id sent to the vendor, or { ai_provider_id, model } naming another provider of the project that serves it. A model named beside this provider may be an alias; reads, usage, prices and traces answer the alias and this provider, and only the vendor call uses the target and the id. Empty when the provider has none. |
model_alias_names | string[] | The alias names of model_aliases, on a shared projection only. |
model_aliases_only | boolean | When true, a model that is not one of model_aliases is refused with MODEL_NOT_OFFERED (400). |
require_priced_model | boolean | When true, a generation on this provider whose model no price-book row covers is refused with MODEL_NOT_PRICED (409) before the provider is called, as the project's require_priced_model does for every provider of the project. |
created_at | string (date-time) | |
updated_at | string (date-time) |
name, provider and default_model are required on create. provider is a
vendor slug you bring a credential for: openai, anthropic, google, xai,
groq, ollama, azure, bedrock, vertex, gateway, custom; any other
value, naturali included, is 400 VALIDATION_FAILED with meta.allowed.
default_model is the model used when an agent names none. secret_id names
the secret holding the credential, base_url overrides the
vendor's (a self-hosted or gateway endpoint), and config holds
vendor-specific configuration, such as a region for bedrock. model_aliases and model_aliases_only are covered in
Model aliases.
Key Concepts
The shared naturali provider
Every project lists one provider it did not create: the managed offering,
shared by naturali and named naturali. It is first on the first page
of GET /v1/projects/{project_id}/ai-providers,
and its id is the same in every project. It serves every model
GET /v1/models lists, whatever vendor serves
it, by that model's public name, and meters it at the catalog's pricing.
Read it with
GET /v1/projects/{project_id}/ai-providers/{ai_provider_id}:
it answers id, name, provider, default_model and model_alias_names
(the public names it serves), never a credential, config or prices. Its
provider names the vendor behind its default model; it serves every catalog
model whatever the vendor. It is
read-only: an update, a delete, a price write or a model listing on it is
404 AI_PROVIDER_NOT_FOUND.
An agent, a model-route target or a chat names its id and a public model name:
- CLI
- SDK
- curl
naturali create-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--ai-provider-id aip_N4tur4l1Sh4r3d0 \
--model gemini-3.1-flash-lite \
--name support-triage
const { data: agent } = await naturali.agents.createAgent({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
ai_provider_id: 'aip_N4tur4l1Sh4r3d0',
model: 'gemini-3.1-flash-lite',
name: 'support-triage',
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/agents \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"ai_provider_id": "aip_N4tur4l1Sh4r3d0",
"model": "gemini-3.1-flash-lite",
"name": "support-triage"
}'
Its usage events land in your project and answer the public name. A model the
offering does not serve is 400 MODEL_NOT_OFFERED, one it does not price is
refused with 409 MODEL_NOT_PRICED before any vendor is called, and a vendor
failure is 502 AI_PROVIDER_ERROR without the vendor's answer.
Bring your own key, in two calls
Credentials are never passed inline. Store the key as a secret first, then create the provider naming that secret:
- CLI
- SDK
- curl
SECRET_ID=$(naturali create-secret \
--project-id proj_V1StGXR8Z5jdHi6B \
--name openai-production \
--value "$OPENAI_API_KEY" | jq -r .id)
naturali create-ai-provider \
--project-id proj_V1StGXR8Z5jdHi6B \
--name openai-production \
--provider openai \
--default-model gpt-4o-mini \
--secret-id "$SECRET_ID"
const { data: secret } = await naturali.secrets.createSecret({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { name: 'openai-production', value: process.env.OPENAI_API_KEY! },
});
const { data: provider } = await naturali.aiProviders.createAiProvider({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'openai-production',
provider: 'openai',
default_model: 'gpt-4o-mini',
secret_id: secret!.id,
},
});
SECRET_ID=$(curl -s -X POST \
https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/secrets \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{ \"name\": \"openai-production\", \"value\": \"$OPENAI_API_KEY\" }" | jq -r .id)
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/ai-providers \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"openai-production\",
\"provider\": \"openai\",
\"default_model\": \"gpt-4o-mini\",
\"secret_id\": \"$SECRET_ID\"
}"
A provider that needs no credential — a local ollama, say — takes a
base_url and no secret_id.
bedrock, vertex and anthropic must carry a credential of their own:
a secret_id. These vendors would otherwise sign with the serving
environment's own identity, so a bedrock or vertex provider without one is
400 VALIDATION_FAILED with meta.field naming secret_id, and an
anthropic provider without one is refused when it would generate
(AI_PROVIDER_MISCONFIGURED). The rule holds for a direct call and a
formation deploy alike. To generate without credentials of your own, use
the shared naturali provider.
Model aliases
model_aliases maps a name you use beside a provider of your own to the model
id the vendor is called with:
{ "default_model": "fast", "model_aliases": { "fast": "gpt-4o-mini", "smart": "gpt-4o" } }
Wherever a model is named beside the provider (its default_model, an agent's
model, a model route target, a generation's model, a
formation resource), an alias is accepted and stored as written. Reads, usage,
price rows and traces answer the alias; only the vendor call uses the id. A
name that is not an alias reaches the vendor as written.
An alias may instead forward to another provider of the same project:
{ "model_aliases": { "smart": { "ai_provider_id": "aip_V1StGXR8Z5jdHi6B", "model": "gpt-4o" } } }
The vendor call goes through the target provider and its credential; reads,
usage, price rows and traces answer the alias and the provider holding it. A
forward is one hop: the target forwards nothing and is never the provider
itself.
model_aliases_only: true closes the list: a model that is not one of the
aliases is 400 MODEL_NOT_OFFERED, on the write that names it and on any call
that would send it.
require_priced_model: true refuses a generation on the provider whose model
no price row covers with 409 MODEL_NOT_PRICED, before the model is called;
error.meta.unpriced_rows names each row to price. The project's
require_priced_model holds every provider of the project.
Which models a credential can actually run
GET /v1/projects/{project_id}/ai-providers/{ai_provider_id}/models
asks the vendor, using this record's own credential and configuration, and
returns provider-native model ids — the same strings default_model and an
agent's model carry. Reachability is a property of the credential, not of the
vendor: two records for the same vendor can answer differently, so read the list
from the record you intend to generate with.
Create a provider uses it as the proof
a new credential works.
The shared naturali provider has no credential
of yours to ask with: this route answers 404 there, and its models are the
ones GET /v1/models lists.
Price overrides
GET and
PUT /v1/projects/{project_id}/ai-providers/{ai_provider_id}/prices
carry per-provider price overrides, keyed on (model, effective_from). An
override prices this provider record — an enterprise-negotiated rate, or a
gateway with markup — and wins over the platform default when cost is computed.
effective_from must be in the future for a (model, component) that is
already priced, so a rate change never rewrites the cost of calls already made.
A first price for a pair nothing prices yet may be dated now, so a new override
starts metering immediately rather than after a gap.
The shared naturali provider is the
exception: a price write on it is 404. It meters at the prices GET /v1/models
publishes. Every provider of your own takes overrides — an override on a
credential you pay for is yours to set.
Deleting a provider in use
DELETE /v1/projects/{project_id}/ai-providers/{ai_provider_id}
answers 409 AI_PROVIDER_HAS_DEPENDENTS while an agent, a
model route target or another provider's
model_aliases forward still names it (meta.ai_provider_ids
lists those providers), and force does not override that — repoint or
delete those first. Deleting the provider does not
delete the secret it authenticated with.
Price overrides, metered usage and shares another project has accepted also
answer 409, but force=true clears them: it deletes the overrides, revokes
the shares and unlinks the usage history, which is kept —
the spend stays on your usage rollup, it simply stops naming a
provider that no longer exists. error.meta reports the counts and a forcible
flag saying whether a force=true retry would succeed.
The shared naturali provider is not yours to delete: a delete on it is 404.
Formations
A formation template declares a provider of your own as an
ai_provider, whose properties are AiProviderResourceProperties in the
formations spec. It is held to the
credential rule a direct create is. A
{"ref": …} to a secret resource in the same template counts as the
credential, and resolves to a real secret before the provider is created:
parameters:
Slug:
type: String
default: bedrock
resources:
Key:
type: secret
properties: { name: vendor-key, value: { param: VendorKey } }
Provider:
type: ai_provider
properties:
name: my-bedrock
provider: { param: Slug }
secret_id: { ref: Key }
An agent on the shared naturali provider names its id directly, with a parameter for it:
parameters:
SharedProviderId:
type: String
resources:
Support:
type: agent
properties:
name: support
instructions: Answer questions about an order.
ai_provider_id: { param: SharedProviderId }
model: nova-lite-v1
A naturali_ai_provider resource is not declarable: validate and plan
report it in errors, and a deploy creating or updating one fails. Removing
one from a formation that holds it, or deleting the formation, releases it.
Examples
List a project's providers
- CLI
- SDK
- curl
naturali list-ai-providers --project-id proj_V1StGXR8Z5jdHi6B
const { data: providers } = await naturali.aiProviders.listAiProviders({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
});
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/ai-providers \
-H "Authorization: Bearer $NATURALI_TOKEN"
Ask a provider which models it can run
- CLI
- SDK
- curl
naturali list-ai-provider-models \
--project-id proj_V1StGXR8Z5jdHi6B \
--ai-provider-id aip_V1StGXR8Z5jdHi6B
const { data } = await naturali.aiProviders.listAiProviderModels({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
ai_provider_id: 'aip_V1StGXR8Z5jdHi6B',
},
});
curl https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/ai-providers/aip_V1StGXR8Z5jdHi6B/models \
-H "Authorization: Bearer $NATURALI_TOKEN"
Rotate to a new credential
- CLI
- SDK
- curl
naturali update-ai-provider \
--project-id proj_V1StGXR8Z5jdHi6B \
--ai-provider-id aip_V1StGXR8Z5jdHi6B \
--secret-id sec_9fJk2LmNpQrStUvW
await naturali.aiProviders.updateAiProvider({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
ai_provider_id: 'aip_V1StGXR8Z5jdHi6B',
},
body: { secret_id: 'sec_9fJk2LmNpQrStUvW' },
});
curl -X PATCH https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/ai-providers/aip_V1StGXR8Z5jdHi6B \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "secret_id": "sec_9fJk2LmNpQrStUvW" }'