API reference

List models available to BYOK operations

Returns the Git-owned provider/model allowlist, verified provider pricing, capabilities, and setup links. Stored-key metadata is never returned.

GET /v1/models

Request cURL

curl --request GET "https://yep.com/api/v1/models" \
  --header "Authorization: Bearer $YEP_API_KEY"

Responses

Response statuses

Status: 200
Description: Allowlisted BYOK model catalog.
Body: PublicAgentModelCatalog

Status: 401
Description: Authentication required.
Body: PublicApiError

Status: 403
Description: The API key lacks agent permission.
Body: PublicApiError

Status: 429
Description: The request exceeded a rate boundary.
Body: PublicApiError

Status: 500
Description: The service could not safely complete the operation.
Body: PublicApiError

Status: 503
Description: Verified model pricing is unavailable.
Body: PublicApiError

Schemas

AgentModelPricing

Exact current `OpenRouter` list price displayed beside a model choice.

AgentModelPricing fields

Field: input_usd_per_million_tokens
Required: No
Type: string | null
Description: Input price in USD per million tokens; absent for variable-price routing.
Constraints

Field: output_usd_per_million_tokens
Required: No
Type: string | null
Description: Output price in USD per million tokens; absent for variable-price routing.
Constraints

Field: request_usd
Required: No
Type: string | null
Description: Optional fixed USD price charged for one request.
Constraints

AgentModelRef

One allowlisted inference provider and model identifier.

AgentModelRef fields

Field: model
Required: Yes
Type: string
Description: Provider-native model identifier.
Constraints

Field: provider
Required: Yes
Type: ProviderKeyProvider
Description: Closed provider discriminator.
Constraints

AgentPricingSnapshot

Browser-visible provenance for model prices.

AgentPricingSnapshot fields

Field: fetched_at
Required: Yes
Type: string
Description: RFC 3339 timestamp of the last successful refresh.
Constraints

Field: provider
Required: Yes
Type: ProviderKeyProvider
Description: Provider supplying the displayed prices.
Constraints

Field: status
Required: Yes
Type: AgentPricingStatus
Description: Whether the snapshot remains within the freshness window.
Constraints

AgentPricingStatus

Freshness of the live provider price snapshot returned to the browser.

Request json

[
  "fresh",
  "stale"
]

AgentProviderOption

Browser-safe provider metadata from the pinned catalog.

AgentProviderOption fields

Field: credential_setup_url
Required: Yes
Type: string
Description: Provider-owned page where an inference key can be created.
Constraints

Field: default_model
Required: Yes
Type: AgentModelRef
Description: Model selected when the connection flow changes provider.
Constraints

Field: label
Required: Yes
Type: string
Description: Provider brand name.
Constraints

Field: provider
Required: Yes
Type: ProviderKeyProvider
Description: Closed provider discriminator.
Constraints

Field: supported_scopes
Required: Yes
Type: ProviderKeyScope[]
Description: Key ownership scopes implemented for this provider.
Constraints

ErrorCode

Machine-readable product API failure.

Request json

[
  "unauthenticated",
  "forbidden",
  "invalid_request",
  "not_found",
  "conflict",
  "payment_required",
  "too_many_requests",
  "upstream",
  "internal"
]

ErrorRecovery

Browser-safe recovery action selected by the authoritative product boundary.

ErrorRecovery alternatives

Variant: 1
Type: object

Variant: 2
Type: object

Variant: 3
Type: object

ProviderKeyProvider

Closed provider set exposed to product clients.

Request json

[
  "openrouter"
]

ProviderKeyScope

Ownership scope for a stored provider key.

Request json

[
  "personal",
  "workspace"
]

PublicAgentModelCatalog

Public BYOK model catalog shared by REST and MCP.

PublicAgentModelCatalog fields

Field: models
Required: Yes
Type: PublicAgentModelOption[]
Description: Git-owned provider/model allowlist joined with verified pricing.
Constraints

Field: pricing_snapshot
Required: Yes
Type: AgentPricingSnapshot
Description: Provenance and freshness of the displayed provider prices.
Constraints

Field: providers
Required: Yes
Type: AgentProviderOption[]
Description: Git-owned provider choices and their external key-creation links.
Constraints

Field: setup_url
Required: Yes
Type: string
Description: Signed-in Yep route for storing the selected provider credential.
Constraints

PublicAgentModelOption

Public model metadata used by HTTP and MCP callers.

PublicAgentModelOption fields

Field: context_tokens
Required: Yes
Type: integer
Description: Maximum provider context window.
Constraints: min: 0

Field: label
Required: Yes
Type: string
Description: Human-readable model name.
Constraints

Field: max_output_tokens
Required: Yes
Type: integer
Description: Maximum provider output window.
Constraints: min: 0

Field: model
Required: Yes
Type: string
Description: Provider-native model identifier accepted by agent endpoints.
Constraints

Field: pricing
Required: Yes
Type: AgentModelPricing
Description: Verified provider list pricing.
Constraints

Field: provider
Required: Yes
Type: ProviderKeyProvider
Description: Closed provider discriminator.
Constraints

Field: structured_output
Required: Yes
Type: boolean
Description: Whether the model supports constrained structured output.
Constraints

Field: tool_calling
Required: Yes
Type: boolean
Description: Whether the model supports tool calls.
Constraints

PublicApiError

Stable public error envelope for APIs whose reason vocabulary is extensible.

PublicApiError fields

Field: agent_session_id
Required: No
Type: string | null
Description: Agent execution correlation id, present after an invocation is admitted.
Constraints

Field: code
Required: Yes
Type: ErrorCode
Description: Closed status category suitable for program control flow.
Constraints

Field: message
Required: Yes
Type: string
Description: Safe diagnostic intended for operators, not program branching.
Constraints

Field: reason
Required: Yes
Type: string
Description: Extensible machine-readable detail; clients must accept unknown values.
Constraints

Field: recovery
Required: No
Type: null | ErrorRecovery
Description
Constraints

Field: validation
Required: No
Type: null | ValidationReport
Description
Constraints

ValidationIssue

One actionable, privacy-safe contract violation.

ValidationIssue fields

Field: allowed_values
Required: No
Type: array | null
Description
Constraints: max items: 16

Field: code
Required: Yes
Type: string
Description: Stable, extensible machine-readable category.
Constraints: max length: 64

Field: path
Required: Yes
Type: string
Description: RFC 6901 pointer to the rejected location; empty means the root value.
Constraints: max length: 1024

Field: suggestion
Required: Yes
Type: string
Description: Code-owned instruction for correcting the request.
Constraints: max length: 512

ValidationReport

Bounded validation feedback shared by model, REST, and MCP boundaries.

ValidationReport fields

Field: contract
Required: Yes
Type: string
Description: Stable contract name, normally the published schema component name.
Constraints: max length: 128

Field: issues
Required: Yes
Type: ValidationIssue[]
Description: At most eight deterministic violations. Correct every issue before retrying.
Constraints: max items: 8

Field: truncated
Required: Yes
Type: boolean
Description: Whether more violations were omitted; retry after correcting the listed issues.
Constraints

Models MCP model catalog tool