Breyta Docs
Docs
Reference

Provider And API Freshness Reference

Load this reference before creating or editing external API calls, auth shape,
provider config, rate-limit assumptions, LLM provider settings, or model ids.

Core Rule

Training data is typically stale for current API behavior. Verify against the
current source of truth before choosing endpoints, request bodies, auth, limits,
or models.

Use:

  • current official provider docs
  • provider API references
  • provider model-list APIs when credentials/tooling are available
  • relevant Breyta docs and approved templates
  • a draft run or isolated step run when feasible

Applies To All Providers

This rule is not only for OpenAI. Apply it to:

  • OpenAI
  • Anthropic/Claude
  • AWS Bedrock Claude
  • Google/Gemini
  • Chat Completions-compatible providers, including legacy :openai-compatible integrations
  • OpenRouter
  • HTTP APIs
  • databases
  • SaaS APIs
  • any vendor a flow calls

Connection And Credential Gate

Before third-party calls, classify credential ownership and put durable
credentials in :requires, not invocation text. Check existing connections; if
none fits, hand off the Breyta setup/connection URL. Do not ask for secrets in
chat. Protected setup/edit links should return through login.

Model Selection

  • Before adding or changing model ids, check the provider's current model docs or model-list API when credentials/tooling are available.
  • Verify the exact model id with a draft run or isolated step run before release when feasible.
  • For OpenAI-backed steps, use gpt-5.4 as Breyta's current API default where a default is needed, but still verify availability in the target environment.
  • Do not claim or use unreleased provider models without provider/API proof.
  • Preserve explicit user requests, such as gpt-5.4 or a specific Claude/Gemini model, unless current provider docs/API availability show the model is unavailable or unsuitable.
  • When editing existing flows, keep legacy models/APIs only if compatibility, cost, or evaluation history is intentional. Otherwise propose upgrading to the current verified provider/API choice.

OpenAI Connection Defaults

For OpenAI-backed :llm and :agent steps, use an :http-api requirement
with an OpenAI backend connection. The base URL should include /v1, and the
connection config must be a map rather than nil.

{:requires [{:slot :ai
             :type :http-api
             :provided-by :author
             :label "OpenAI"
             :base-url "https://api.openai.com/v1"
             :auth {:type :api-key}}]}

Use :provided-by :installer instead when every installer should bring their
own OpenAI account. For raw HTTP calls to OpenAI instead of the LLM provider
backend, use the same https://api.openai.com/v1 base and bearer-style
Authorization semantics from OpenAI's API reference.

AWS Bedrock Connection Defaults

For Bedrock-backed Claude calls, use an :http-api requirement with
:backend :bedrock and AWS SigV4 auth. Keep region/service metadata in the
auth config and store credentials in the referenced secret.

{:requires [{:slot :ai
             :type :http-api
             :provided-by :author
             :label "AWS Bedrock Claude"
             :backend :bedrock
             :base-url "https://bedrock-runtime.us-east-1.amazonaws.com"
             :auth {:type :aws-sigv4
                    :secret-ref :aws-bedrock
                    :region "us-east-1"
                    :service "bedrock"}}]}

Use a Bedrock Claude model id in :llm, for example
"anthropic.claude-3-5-sonnet-20241022-v2:0" or a region/inference-profile id
such as "us.anthropic.claude-3-5-sonnet-20241022-v2:0". Verify the model id
against the target AWS region before release.

For Bedrock Claude image input, use :type :image-resource for uploaded or
persisted files. Bedrock's Claude Messages API expects base64 image content
blocks, so do not treat res://... values or ordinary HTTPS image URLs as
provider-native Bedrock image URLs.

For Bedrock Claude Sonnet 4.5 and Haiku 4.5 model ids, choose either
:temperature or :top-p; do not set both on the same request.

API Shape Checks

Before changing an API integration, verify:

  • endpoint path and base URL
  • method and content type
  • auth method and token scope
  • required headers
  • request body shape
  • pagination and limits
  • retry and rate-limit behavior
  • response shape and error shape
  • idempotency keys for side effects
  • webhook signature or secret requirements

If docs and examples disagree, treat current official provider docs/API
reference as the source of truth and call out the mismatch.

Breyta Checks

Search Breyta docs/examples for the integration surface before editing:

  • breyta docs find "source:cli connections test"
  • breyta docs find "source:flows-api http request"
  • breyta docs find "source:flows-api llm model"
  • breyta flows search "<provider or integration> <task>" --limit 5
  • breyta flows grep "<literal provider config or tool name>" --tool-name <name>
  • breyta flows templates search "<provider or integration> <task>" --limit 5

Use approved templates to learn local structure, but do not copy stale endpoint
or model assumptions without verifying provider docs.

Reporting

In the final report, state:

  • which provider/API docs or model-list API were checked
  • the selected model or endpoint
  • whether the selection was verified by a draft run or isolated step run
  • any remaining availability or compatibility risk
As of May 21, 2026