Providers

Model provider credentials an Agent runs against — naturali-managed or bring-your-own-key (BYOK).

Overview

Two ways to run: naturali models (zero setup, billed through the shared credit pool) or BYOK — register your own provider credentials (e.g. Bedrock, Anthropic, OpenAI, Google) as a write-only secret; your agents run on your provider account while the platform still meters every run. Provider health is observable without any secret readback.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Providers.

Data Model

Provider

Field	Type	Description
id	string	Public provider ID (aip_ prefix).
project_id	string	The owning project.
name	string	Human-readable label.
provider	string	The upstream provider kind (e.g. bedrock, openai).
default_model	string, nullable	Default model used by an agent bound to this provider when it doesn't set its own model.
kind	string	managed (naturali models, platform-keyed) or byok.
has_secret	boolean	Whether BYOK credentials are configured — never returns the credential itself.
base_url	string, nullable	Override endpoint, for compatible self-hosted providers.
created_at	string (date-time)
updated_at	string (date-time)

Key Concepts

Secrets are write-only

BYOK credentials are accepted on write, never returned — a read reports only has_secret. Provider key validity/quota health is observable without any secret readback.

What each kind takes on create

The two modes are created from different fields, and neither accepts the other's:

kind	Required	Optional
managed	model — a catalog model id offered as managed	name
byok	provider, default_model, api_key	name, base_url

A managed provider takes no credential: it runs on naturali's own model access.

Not every catalog model can be managed

A managed provider is priced at naturali's own cost, so a model is only offerable as managed if there is an authoritative published price for it. The Anthropic Claude family currently has none, and is therefore BYOK-only.

status: "available" on a model means it is in the catalog, not that it can be managed — the two are independent. Ask the catalog which models qualify rather than finding out on create:

CLI

naturali list-models --managed true

SDK

const { data } = await naturali.models.listModels({
  query: { managed: true },
});

curl

curl -G https://api.naturali.ai/v1/models \
  -H "Authorization: Bearer $NATURALI_API_KEY" \
  -d managed=true

Creating a managed provider on a model whose managed is false fails fast rather than provisioning something unpriced:

{
  "error": {
    "code": "bad_request",
    "message": "`model` is not available as a managed model."
  }
}

The amazon.nova-* family is managed-eligible and inexpensive, which makes it a good default for a first run.

A new managed provider is priced a moment after it is created

Creating a managed provider sets a per-provider price whose effective_from is a few seconds ahead, to stay clear of clock skew between naturali and the metering platform. For that brief window the provider exists and can generate, but no price applies yet.

Cost is frozen at write time and is not backfilled, so a generation that runs inside that window reports cost_usd: null on its usage receipt permanently — re-reading the receipt later will not fill it in. Automation that provisions a provider and immediately generates should allow a moment in between if it depends on the cost record; every later generation on the provider is priced normally.

Examples

Creating a BYOK provider — the credential is stored write-only, so it is the one field you can never read back:

CLI

naturali create-provider \
  --project-id proj_V1StGXR8Z5jdHi6B \
  --name bedrock-prod \
  --kind byok \
  --provider bedrock \
  --default-model us.anthropic.claude-haiku-4-5-20251001-v1:0 \
  --api-key "$BEDROCK_CREDENTIALS"

SDK

const { data: provider } = await naturali.providers.createProvider({
  path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
  body: {
    name: 'bedrock-prod',
    kind: 'byok',
    provider: 'bedrock',
    default_model: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
    api_key: process.env.BEDROCK_CREDENTIALS,
  },
});

curl

curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/providers \
  -H "Authorization: Bearer $NATURALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg key "$BEDROCK_CREDENTIALS" '{
        name: "bedrock-prod",
        kind: "byok",
        provider: "bedrock",
        default_model: "us.anthropic.claude-haiku-4-5-20251001-v1:0",
        api_key: $key
      }')"

For the managed equivalent, and for binding either one to an agent and pricing what it runs, see Tutorials → Your first agent generation.