GraphQL reference: ai-inference-admin
Generated from the schema this service serves, so it cannot fall behind it. The same schema is published as a file for tools and agents.
| Endpoint | https://<your-host>/api/ai-inference/admin/graphql |
| Auth plane | identity — Instance-scoped administration. Takes the identity token login returns BEFORE a tenant is selected, and is authorized for the superuser or an operator. A tenant access token is rejected here. |
| Authorize with | identity token |
| Schema file | /schema/ai-inference-admin.graphql |
| Described | 113 of 113 elements |
Queries
aiFunctionAssignments · aiFunctions · aiProvider · aiProviderKinds · aiProviderTenantGrants · aiProviderTierGrants · aiProviders
aiFunctionAssignments
Lists the models chosen for one tenant, one per function, ordered by function. A choice is listed even if the tenant is no longer offered that model, so a stale choice can be found and fixed. Returns an empty list if the tenant has made none. Requires ai:admin.
Returns [AiFunctionAssignment!]!
| Argument | Type | Description |
|---|---|---|
tenant | String! | Token of the tenant. |
aiFunctions
Lists the functions a model can be assigned to. Currently only rule-drafting. Requires ai:admin.
Returns [AiFunction!]!
aiProvider
Returns the provider with the given token, or null if there is none. Requires ai:admin.
Returns AiProvider
| Argument | Type | Description |
|---|---|---|
token | String! | Token of the provider. |
aiProviderKinds
Lists the provider kinds this build can call, sorted alphabetically: anthropic and openai-compatible. Requires ai:admin.
Returns [String!]!
aiProviderTenantGrants
Lists the providers granted to one tenant individually, in addition to its tier. Returns an empty list if there are none. Requires ai:admin.
Returns [AiProviderTenantGrant!]!
| Argument | Type | Description |
|---|---|---|
tenant | String! | Token of the tenant. |
aiProviderTierGrants
Lists every tier grant on the instance, ordered by tier and then provider token. It includes grants whose tier no longer exists. Requires ai:admin.
Returns [AiProviderTierGrant!]!
aiProviders
Searches providers, newest created first, optionally by kind. Returns an empty page when nothing matches. Requires ai:admin.
Returns AiProviderSearchResults!
| Argument | Type | Description |
|---|---|---|
criteria | AiProviderSearchCriteria! | Filter and paging. |
Mutations
clearAiFunctionModel · clearAiTierDefault · createAiProvider · deleteAiProvider · grantAiProviderToTenant · grantAiProviderToTier · renameAiProvider · revokeAiProviderFromTenant · revokeAiProviderFromTier · setAiFunctionModel · setAiTierDefault · testAiProvider · updateAiProvider
clearAiFunctionModel
Removes the tenant's chosen model for a function. Returns true if a choice was removed and false if there was none. Afterwards the tenant gets its tier's default model for the function, if the tier has one and the tenant is still offered it. Fails if the function is not one returned by aiFunctions. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
function | String! | The function, one of the tokens returned by aiFunctions. |
tenant | String! | Token of the tenant. |
clearAiTierDefault
Removes the tier's default marking, keeping every grant. Afterwards a tenant on the tier that has no model assigned for a function has no model for it and must be assigned one. Harmless if there is no default. Always returns true. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
tier | String! | Token of the tier. |
createAiProvider
Registers a provider. It is offered to no tenant until granted to a tier or tenant. Rejects an unknown kind, a blank model, an invalid endpoint, params that are invalid or set any key (extensions.code UNSUPPORTED), an openai-compatible provider with no endpoint, and a token already in use. Requires ai:admin.
Returns AiProvider!
| Argument | Type | Description |
|---|---|---|
request | AiProviderCreateRequest! | The new provider's fields. |
deleteAiProvider
Permanently deletes a provider and its API key. Returns true if one was deleted and false if none has the token. Refused, with extensions.code REFERENCE_VIOLATION, while the provider is granted to any tier or tenant or assigned to any function; the error lists every reason. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
token | String! | Token of the provider to delete. |
grantAiProviderToTenant
Offers a provider to one tenant in addition to what its tier offers. It only adds choices. Granting twice is harmless. Always returns true. Fails if no provider has the token or the tenant token is not valid. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
provider | String! | Token of the provider. |
tenant | String! | Token of the tenant. |
grantAiProviderToTier
Offers a provider to every tenant on a tier. It adds to what the tier offers and does not change which model any tenant uses, and it never marks the provider as the tier's default; use setAiTierDefault for that. Granting twice is harmless. Always returns true. Fails if no provider has the token or the tier token is not valid. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
provider | String! | Token of the provider. |
tier | String! | Token of the tier. |
renameAiProvider
Changes a provider's token and nothing else. Its API key, grants and function assignments stay attached. Renaming to the token it already has succeeds without change. Fails if the new token is blank or already used by another provider (extensions.code CONFLICT), or if no provider has the old token. Requires ai:admin.
Returns AiProvider!
| Argument | Type | Description |
|---|---|---|
newToken | String! | The new token, which must be unused. |
token | String! | Current token of the provider. |
revokeAiProviderFromTenant
Withdraws a tenant's individual grant of a provider. Returns true if a grant was removed and false if there was none. What the tenant's tier offers is not affected. Fails if no provider has the token. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
provider | String! | Token of the provider. |
tenant | String! | Token of the tenant. |
revokeAiProviderFromTier
Withdraws a tier's offer of a provider. Returns true if a grant was removed and false if there was none. If it was the tier's default, the tier is left with no default. Fails if no provider has the token. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
provider | String! | Token of the provider. |
tier | String! | Token of the tier. |
setAiFunctionModel
Chooses the model a tenant uses for a function, replacing any earlier choice for the pair. The choice is accepted even if the tenant is not currently offered the model; it takes effect when it is, and until then the function has no model for that tenant. Always returns true. Fails if the function is not one returned by aiFunctions, the provider token matches nothing, or the tenant token is not valid. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
function | String! | The function, one of the tokens returned by aiFunctions. |
provider | String! | Token of the provider to use. |
tenant | String! | Token of the tenant. |
setAiTierDefault
Marks a provider that is already granted to the tier as the tier's default model, replacing any previous default. Fails, changing nothing, if the provider is not granted to the tier. Always returns true on success. Requires ai:admin.
Returns Boolean!
| Argument | Type | Description |
|---|---|---|
provider | String! | Token of the provider, which must already be granted to the tier. |
tier | String! | Token of the tier. |
testAiProvider
Sends a prompt to one specific provider to check that its endpoint and key work, even if the provider is disabled or granted to nobody. It does not require any tenant's consent to external routing. The provider must have an API key. Errors are returned in full detail. Token usage is counted like any other call. Requires ai:admin.
Returns InferenceResult!
| Argument | Type | Description |
|---|---|---|
request | InferenceRequest! | The test prompt. |
token | String! | Token of the provider to test. |
updateAiProvider
Partially updates a provider. Its grants are not changed. The whole update is rejected, with nothing written, if any part is invalid. Fails if no provider has the token. If expectedUpdatedAt is given and the provider has changed since, nothing is written and the call fails with "provider was modified by another writer; reload and try again" (no error code). Requires ai:admin.
Returns AiProvider!
| Argument | Type | Description |
|---|---|---|
expectedUpdatedAt | String | The updatedAt value you last read, as an RFC 3339 timestamp. Omit it to overwrite unconditionally. |
request | AiProviderUpdateRequest! | The fields to change. |
token | String! | Current token of the provider to update. |
Objects
AiFunction · AiFunctionAssignment · AiProvider · AiProviderSearchResults · AiProviderTenantGrant · AiProviderTierGrant · InferenceResult · SearchResultsPagination
AiFunction
object
A job that a model can be assigned to. The set of functions is fixed by the platform and cannot be edited; currently it has one member, rule-drafting.
| Field | Type | Description |
|---|---|---|
description | String! | What the function does. |
name | String! | Short human-readable name of the function. |
token | String! | The identifier used when assigning a model to the function, such as rule-drafting. |
AiFunctionAssignment
object
The model an operator has chosen for one tenant to use for one function. This is the stored choice, not necessarily what the tenant gets: if the tenant is no longer offered the model it still appears here, and the function then has no model until the model is offered again.
| Field | Type | Description |
|---|---|---|
function | String! | The function, one of the tokens returned by aiFunctions. |
provider | AiProvider! | The provider chosen for the function, shown even if the tenant is no longer offered it. |
AiProvider
object
A registered AI model provider: where a model is reached, which model to ask for, and whether it may be used. It is configuration for the whole instance, not for one tenant. Registering a provider offers it to nobody; tenants can use it only once it is granted to their tier or to the tenant. The API key is write-only and is never returned.
| Field | Type | Description |
|---|---|---|
createdAt | String | When the provider was created, as an RFC 3339 timestamp. |
description | String | Free-text description of the provider. |
enabled | Boolean! | Whether the provider may be used. A disabled provider keeps its grants but never serves a tenant call, so a model can be taken out of service without removing its grants. |
endpoint | String | Base URL of the provider's API, or null to use the kind's built-in address. Always set for openai-compatible providers. |
hasSecret | Boolean! | True when an API key is stored for the provider. The key itself is never returned. |
id | ID! | Server-assigned identifier. Address a provider by its token, not by this. |
kind | String! | The provider kind: one of the values returned by aiProviderKinds. It selects the protocol used to call the model. |
model | String! | The model identifier sent to the provider, such as a model name the provider recognizes. |
name | String | Human-readable name shown in provider lists. |
params | String | Free-form settings for the kind, as a JSON object serialized to a string, or null if none. No provider client reads them in this build, so new values cannot be set; a value stored earlier is returned as stored and is not applied. |
token | String! | Unique, caller-chosen identifier of the provider. Letters, digits, hyphens and underscores, starting with a letter or digit, at most 128 characters. Grants and function assignments refer to the provider by it. |
updatedAt | String | When the provider was last written, as an RFC 3339 timestamp. Pass it back as expectedUpdatedAt to make an update conditional on nobody else having changed the provider since you read it. |
AiProviderSearchResults
object
One page of providers and where it sits in the full result set.
| Field | Type | Description |
|---|---|---|
pagination | SearchResultsPagination! | Position of this page within the full result set. |
results | [AiProvider!]! | The providers on this page, newest created first (ties broken by token). |
AiProviderTenantGrant
object
An offer of one provider to a single tenant, in addition to what its tier offers. It can only add to a tenant's choices, never remove any.
| Field | Type | Description |
|---|---|---|
provider | AiProvider! | The provider offered to the tenant. |
tenant | String! | Token of the tenant the provider is offered to. |
AiProviderTierGrant
object
An offer of one provider to every tenant on one tier, optionally marked as the tier's default model.
| Field | Type | Description |
|---|---|---|
isDefault | Boolean! | True when this provider is the tier's default model: the one a tenant on the tier gets for a function it has not assigned a model to, as long as the tenant is still offered it. At most one grant per tier is the default, and only because an operator marked it with setAiTierDefault; granting never marks a default, and a tier can have none. |
provider | AiProvider! | The provider offered to the tier. |
tier | String! | Token of the tier. It is returned as stored even when no such tier exists, because this service cannot check the tier catalog; that lets a stale grant stay visible. |
InferenceResult
object
The model's answer to an inference request.
| Field | Type | Description |
|---|---|---|
candidate | String! | The model's text output, as produced. |
model | String! | Identifier of the model that answered, as reported by the provider. |
provider | String! | Token of the provider that served the call. |
SearchResultsPagination
object
Where a page of search results sits in the full result set. Positions are 1-based and inclusive.
| Field | Type | Description |
|---|---|---|
pageEnd | Int | Position of the last result on this page within the full result set (1-based, inclusive). |
pageStart | Int | Position of the first result on this page within the full result set (1-based). |
totalRecords | Int | Number of records matching the criteria across all pages. |
Input types
AiProviderCreateRequest · AiProviderSearchCriteria · AiProviderUpdateRequest · InferenceRequest
AiProviderCreateRequest
input
Fields for a new provider. The kind must be one returned by aiProviderKinds. A new provider is offered to no tenant until it is granted.
| Input field | Type | Description |
|---|---|---|
description | String | Free-text description of the provider. |
enabled | Boolean! | Whether the provider may be used. A disabled provider never serves a tenant call. |
endpoint | String | Base URL of the provider's API: an absolute http or https URL with a host and no query or fragment, to which the provider's API path is appended. Optional for anthropic, where it overrides the built-in address; required for openai-compatible. A blank value counts as omitted. |
kind | String! | The provider kind: one of the values returned by aiProviderKinds. |
model | String! | The model identifier to request from the provider. Required and must not be blank. |
name | String | Human-readable name shown in provider lists. |
params | String | Not supported in this build: a JSON object with any keys is refused with extensions.code UNSUPPORTED. Omit it, or send null, a blank string or {}. |
secret | String | The provider's API key. Write-only; stored encrypted and never returned. Omit it, or send an empty string, to store no key yet; a provider with no key cannot serve calls. |
token | String! | Unique identifier for the new provider. Letters, digits, hyphens and underscores, starting with a letter or digit, at most 128 characters. |
AiProviderSearchCriteria
input
Filter and paging for the aiProviders query.
| Input field | Type | Description |
|---|---|---|
kind | String | Return only providers of this kind. Omit it to return every kind. |
pageNumber | Int! | Page to return, starting at 1. A value below 1 is treated as 1. |
pageSize | Int! | Providers per page. A value below 1 is treated as 100; a value above 1000 is capped at 1000. |
AiProviderUpdateRequest
input
A partial update to a provider. Omit a field to leave the stored value alone, send a value to set it, or send an explicit null to clear it (except where noted). The provider is named by the mutation's token argument, so there is no token here; use renameAiProvider to change the token. Grants are not affected.
| Input field | Type | Description |
|---|---|---|
description | String | New description, or null to clear it. |
enabled | Boolean | Whether the provider may be used. Omit it to keep the stored value; an explicit null is refused. |
endpoint | String | New base URL, in the format described on AiProviderCreateRequest.endpoint, or null to remove the override and use the kind's built-in address. Null is refused for openai-compatible, which has no built-in address; a change of kind is checked against the stored endpoint in the same way. |
kind | String | New provider kind. Omit it to keep the stored kind; an explicit null is refused. |
model | String | New model identifier. Omit it to keep the stored one; an explicit null is refused. |
name | String | New name, or null to clear it. |
params | String | Omit it to keep the stored value, or send null or a blank string to clear it. Setting a JSON object with any keys is refused with extensions.code UNSUPPORTED, unless it is the document already stored, so resending an unchanged record is accepted. At most 16 KiB. |
secret | String | The write-only API key. Omit it to keep the stored key, send a value to replace it, or send null or an empty string to delete it. |
InferenceRequest
input
A prompt to send to the model. The output-token limit, endpoint and timeout are fixed by the server.
| Input field | Type | Description |
|---|---|---|
prompt | String! | The user prompt. Required, and must not be blank. The prompt and system prompt together may not exceed 128 KiB unless the operator configured a different limit. |
system | String | Optional system prompt (instructions or persona) sent ahead of the prompt. |