LLM Provider Definitions API

Endpoints

• List LLM Provider Definitions - List all provider catalog definitions visible to a project
• Get LLM Provider Definition - Retrieve a single provider catalog definition by name
• Create LLM Provider Definition - Create (or upsert) a custom provider catalog definition
• Update LLM Provider Definition - Update an existing custom provider catalog definition
• Delete LLM Provider Definition - Delete a custom provider catalog definition

Authentication

All endpoints require authentication using a Personal API Access Token.

Header

Authorization: Bearer YOUR_TOKEN

Permissions

LLM provider definitions are part of the AI Gateway module and use the AI_DEVELOPMENT asset category.

• Read (list / get): requires AI_DEVELOPMENT + VIEW permission in the project
• Write (create / update / delete): requires AI_DEVELOPMENT + MANAGE permission in the project

LlmProviderDefinition vs. LLM Provider — two different concepts

This asset is easy to confuse with the LLM Providers API. They sit at different layers:

Aspect	LlmProviderDefinition (this asset)	LLM Provider (ConnectionConfigLlm)
What it represents	A provider type catalog entry — e.g. "OpenAI", "Anthropic", "DeepSeek"	A configured connection instance to a provider — endpoint + credential
APIops path	/apiops/projects/{p}/llm-provider-definitions/	/apiops/projects/{p}/llm-providers/
Secrets	None — the entity has no @SecretData fields	apiKey / apiSecret / serviceAccountJson — encrypted, masked on read
Built-in seed	13 platform-shipped entries loaded by Mongock	None — every connection is created by a user
Deployed to AI Gateway workers	No — catalog metadata only, never routes traffic	Yes — pushed to workers on save; used for live request routing
Typical use	Supplies the default endpoint / apiVersion / authScheme / authHeaderName a UI or API client can pre-fill when creating a provider connection	Actually referenced by AI proxies (aiRouting) to route LLM traffic

In short: an LlmProviderDefinition is a template; a ConnectionConfigLlm (LLM Provider) is an instance that may point back at one via providerDefinitionId. Creating, updating or deleting a provider definition never affects traffic routing — only the templates offered when someone configures a new provider connection.

Notes

• Name-based references: Provider catalog definitions are addressed by their name, never by internal ID. The definitionName in the path must match the (effective) name in the request body. If the body's name is blank, it falls back to code, then to the path variable itself.
• Built-in read-only: Entries seeded by Mongock (builtIn: true) are visible to every project but cannot be created, updated or deleted via this API — writes are rejected with a 400 Bad Request ("Built-in provider definitions are read-only.").
• Read scope: List and get return the union of built-in catalog entries and the calling project's own custom entries (builtIn ∪ project-owned).
• Write scope: Only the calling project's own custom entries can be created, updated or deleted.
• No secrets, no deploy: The entity carries no credential fields and creating/updating/deleting a definition never triggers an AI Gateway worker deploy — it is pure catalog metadata.

Related Documentation

• LLM Providers API - Configure actual provider connections (endpoint + credentials)
• AI Gateway API - Overview of AI Gateway configuration resources
• Authentication Guide - How to obtain and use API tokens
• Error Handling - Error response formats