Skip to main content

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​

FieldTypeDescription
idstring
namestring
providerstring
default_modelstring
project_idstring
secret_idstring, nullable
base_urlstring
configobjectAdditional provider-specific configuration. Never carries a credential.
model_aliasesobjectAlias → 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_namesstring[]The alias names of model_aliases, on a shared projection only.
model_aliases_onlybooleanWhen true, a model that is not one of model_aliases is refused with MODEL_NOT_OFFERED (400).
require_priced_modelbooleanWhen 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_atstring (date-time)
updated_atstring (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:

naturali create-agent \
--project-id proj_V1StGXR8Z5jdHi6B \
--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:

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"

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​

naturali list-ai-providers --project-id proj_V1StGXR8Z5jdHi6B

Ask a provider which models it can run​

naturali list-ai-provider-models \
--project-id proj_V1StGXR8Z5jdHi6B \
--ai-provider-id aip_V1StGXR8Z5jdHi6B

Rotate to a new credential​

naturali update-ai-provider \
--project-id proj_V1StGXR8Z5jdHi6B \
--ai-provider-id aip_V1StGXR8Z5jdHi6B \
--secret-id sec_9fJk2LmNpQrStUvW