Model access and publishing API

List the models an organization sees, set who may call them, publish a tenant's models to other tenants, and manage their Owner and Grant Managers through the BSQAI API.

Agentic Friendly

Every model that the BSQAI API serves is a serving endpoint, identified by the ID of its model route. This page is for AI engineers and administrators who manage model access with the API. Model access in Studio describes the same rules in the Portal.

Two decisions control who may call a model:

  • Which tenants may use it. A model serves its owning organization. A platform administrator decides which other tenants may use a Global model, and a tenant's administrators decide whether to publish their tenant's language models to every tenant.
  • Who in a tenant may call it. Each tenant sets allow rules on the models offered to it. Without a rule, nobody in the tenant can call the model, except the model's owner in its own tenant.

Before you begin

Authenticate with a platform token or a BSQAI API key, sent as Authorization: Bearer .... Every call acts in the caller's active tenant: an API key carries its tenant, and a token that belongs to more than one organization also sends X-Tenant-Id.

export BSQAI_API="https://<bsqai-api-host>"
export TOKEN="<access-token-or-api-key>"
TaskPermissionWho has it
List the models you seetenant.readEvery member
List a model's allow rules, and its Owner and Grant Managersauthorization.resource_grant.listEvery member
Add or remove an allow rule, a Grant Manager, or an Ownerauthorization.resource_grant.create and authorization.resource_grant.revokeEvery member
Publish or unpublish a model the tenant ownsinference.endpoint.publishTenant Administrators. It cannot be given through a custom role.
Let a tenant publish its modelsPlatform administratorPlatform administrators
Choose which tenants may use a modelplatform.global_service.manage in the Global organizationPlatform administrators

The permission is the operation gate. Whether the call succeeds also depends on the caller's place on the model: only the people who manage a model's rules may change them. They are:

  • in a customer organization, its Tenant Administrators, for every model that the Global organization or another tenant offers to it;
  • in the Global organization, platform administrators;
  • in the organization that owns a model, its Owner and Grant Managers. That organization's Tenant Administrators do not manage the rules of its own models: they can only assign a new Owner when the Owner has left.

A caller who may see the model but not change it gets 403 permission_denied. A caller who may not see it gets 404 serving_endpoint_not_found, so probing for IDs reveals nothing.

List the models you see

GET /v1/serving-endpoints lists the models the caller sees in the active tenant: every model the tenant owns, and every other model the tenant holds a rule on. Each entry of the response's endpoints list has these fields:

curl -sS "$BSQAI_API/v1/serving-endpoints" -H "Authorization: Bearer $TOKEN"
FieldMeaning
idThe serving endpoint ID, the model route's ID. The Model Installer reports it as route_id.
aliasThe model name that callers send
modechat, embedding, rerank, predictive, or unknown
global_owned, owned_by_this_tenantWhether the Global organization or the active tenant owns the model
audienceWhich tenants besides its owner may use it: owner, everyone, or listed
can_invokeWhether the caller may call the model
can_viewWhether the caller sees the model
can_manage_accessWhether the caller may list and change the tenant's rules on it
can_publishWhether the caller may publish or unpublish it
can_operateWhether the caller is an Inference Operator of the owning tenant, who sees its Owner, Grant Managers and rules without changing them
can_assign_ownerWhether the caller may assign a new Owner, because the Owner left the tenant

Manage allow rules

An allow rule lets a user, a group, or All Members of the active tenant call a model there. A rule applies only in the tenant where it was set.

MethodPathUse
GET/v1/serving-endpoints/{id}/grantsList the tenant's rules on the model
POST/v1/serving-endpoints/{id}/grantsAdd a rule
POST/v1/serving-endpoints/{id}/grants/revokeRemove a rule. Removing one that does not exist changes nothing.
curl -sS -X POST "$BSQAI_API/v1/serving-endpoints/<endpoint-id>/grants" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subject_type": "group", "subject_id": "<group-uuid>", "relation": "invoker"}'

subject_type is user, group, or all_members. subject_id names the user or group and is omitted for All Members. The user or group must belong to the tenant. relation is invoker, which lets the subject call the model.

A new viewer rule is refused with 400 serving_endpoint_viewer_rule_retired, because every member already sees the models their tenant owns or allows. A viewer rule made earlier is still listed and can be removed. A rule that would let nobody call the model who cannot already is refused with 409 serving_endpoint_grant_changes_nothing: a rule that exists, a rule for the model's owner, or any other rule while All Members may call it.

Removing a rule stops new calls at once. Work already running, such as a Deep Research run, finishes with its model.

Publish a tenant's model

A tenant's language model serves only that tenant until it is published. Publishing offers it to every tenant, and each tenant then decides with its own rules which of its members may call it. The owning tenant keeps running and paying for the model. Other tenants see the model, never its deployment.

A platform administrator first lets the tenant publish:

curl -sS -X PUT "$BSQAI_API/v1/admin/tenants/<lifecycle-id>/inference/publishing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

The tenant's response reports inference_publishing. Sending {"enabled": false} unpublishes every model that the tenant published. Other tenants' rules on them stay, and apply again if the models are published again. In the Portal, this is Let this tenant publish its models under Publishing to all tenants, on the tenant's Deployment policy tab in Administration. See Let a tenant publish its models.

A Tenant Administrator of the owning tenant then publishes one model:

curl -sS -X PUT "$BSQAI_API/v1/serving-endpoints/<endpoint-id>/publication" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"published": true}'

{"published": false} unpublishes it. Unpublishing does not need the tenant's permission to publish. In the Portal, this is Publish to all tenants under Access on the model.

StatusCodeCause
409serving_endpoint_publishing_disabledA platform administrator has not let the tenant publish its models.
409serving_endpoint_not_publishableThe model is a predictive model. Only language models are published.
409serving_endpoint_audience_set_by_platformThe model is a Global model, or a platform administrator chose which tenants may use it.
403permission_deniedAnother tenant owns the model.

Choose which tenants may use a model

A platform administrator sets a model's audience with PUT /v1/admin/model-routes/{id}/audience:

curl -sS -X PUT "$BSQAI_API/v1/admin/model-routes/<route-id>/audience" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"audience": "listed", "tenant_ids": ["<tenant-organization-uuid>"]}'
audienceWho may use the model besides its owner
everyoneEvery tenant
listedOnly the tenants in tenant_ids, which is required for this value and empty otherwise
ownerNobody

A Global model takes any audience, including a model that the Model Installer deployed. A tenant's model reaches other tenants only after its owner publishes it. A platform administrator can then narrow it to chosen tenants, open it to every tenant again, or unpublish it with owner. The deployment keeps running in every case. Each tenant still decides with its own rules which of its members may call the model.

The response is the route, with owner_tenant_id, audience, and audience_tenant_ids. In the Portal, this is the Who may use it column under Model routing in Studio, changed with the people button at the end of the route's row, with the choices All tenants, Chosen tenants, and Owner only.

StatusCodeCause
400serving_endpoint_audience_tenant_unknownA tenant in tenant_ids does not exist.
409serving_endpoint_not_publishedThe tenant that owns the model has not published it.
409serving_endpoint_not_publishableThe tenant's model is a predictive model.

Owner and Grant Managers

In a customer organization, the person who deploys a model becomes its Owner. The Owner calls the model without a rule and names the Grant Managers, users or groups of the tenant who manage the model's rules with the Owner. A Global model has neither, and these routes answer 409 serving_endpoint_global_owned for it. Only the tenant that owns a model reaches them.

MethodPathUse
GET/v1/serving-endpoints/{id}/stewardshipRead the model's Owner and Grant Managers, and what the caller may change. For the Owner, Grant Managers, Inference Operators, and Tenant Administrators of the owning tenant.
POST/v1/serving-endpoints/{id}/grant-managersName a Grant Manager: {"subject_type": "user" or "group", "subject_id": "<uuid>"}. Owner only.
POST/v1/serving-endpoints/{id}/grant-managers/revokeRemove a Grant Manager, with the same body. Owner only.
PUT/v1/serving-endpoints/{id}/ownerAssign a current member as Owner: {"user_id": "<uuid>"}. Tenant Administrators only, and only after the Owner left the tenant.

The stewardship response lists owners, each with user_id and is_member, and grant_managers. needs_owner is true when no Owner is still a member of the tenant. An Owner who left manages nothing. Assigning a new Owner while the Owner is still a member answers 409 serving_endpoint_owner_still_member.

A Grant Manager or Owner change on a model applies to its LoRA adapters too.

On this page