Serving API

11 operations. Paths are relative to the API host (http://localhost:5080 in local development). Every operation accepts an OIDC bearer token (Authorization: Bearer …) or a workspace API key (X-Api-Key: keel_live_…); errors are RFC 9457 Problem Details with a code (error codes). Permissions: matrix.

Method	Path	Summary
GET	/api/v1/serving/{endpoint}/catalog	Metrics (with trust), dimensions and segments the endpoint exposes to the caller.
POST	/api/v1/serving/{endpoint}/compile	Compile a semantic query to SQL without running it (the endpoint must expose SQL, or the caller edits models).
POST	/api/v1/serving/{endpoint}/query	Run a semantic query on the endpoint's release: access policies applied, cached, with trust scores (docs/04 §5).
GET	/api/v1/workspaces/{workspaceId}/serving/endpoints	The workspace's serving endpoints with their usage in the last 7 days.
POST	/api/v1/workspaces/{workspaceId}/serving/endpoints	Publish a model (a pinned release or the latest) as a serving endpoint (Govern; audited).
GET	/api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}	One serving endpoint.
PUT	/api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}	Replace an endpoint's settings (the slug never changes; Govern; audited).
DELETE	/api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}	Delete an endpoint (soft, audited); its slug becomes free.
POST	/api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}:disable	Turn an endpoint off: queries get 403 Serving.EndpointDisabled (audited).
POST	/api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}:enable	Turn an endpoint on (audited).
GET	/api/v1/workspaces/{workspaceId}/serving/endpoints/stats	Calls per day, p95 duration and error rate of each endpoint over the last 30 days (query-log metadata only).

ServingCatalog

GET /api/v1/serving/{endpoint}/catalog

Metrics (with trust), dimensions and segments the endpoint exposes to the caller.

Parameter	In	Type	Required	Notes
endpoint	path	string	yes

Status	Description	Body
200	OK	ServingCatalogResponse

Response 200: ServingCatalogResponse

Field	Type	Notes
description	string?
dimensions	ServingCatalogDimensionDto[]
metrics	ServingCatalogMetricDto[]
name	string
release	ServingReleaseDto
segments	ServingCatalogSegmentDto[]
slug	string

ServingCompile

POST /api/v1/serving/{endpoint}/compile

Compile a semantic query to SQL without running it (the endpoint must expose SQL, or the caller edits models).

Parameter	In	Type	Required	Notes
endpoint	path	string	yes

Request body (application/json): ServingQueryBody

Field	Type	Notes
dimensions	string[]?
filters	ServingFilterBody[]?
limit	int32?
metrics	string[]
options	ServingOptionsBody?
orderBy	ServingOrder[]?
segments	string[]?

Status	Description	Body
200	OK	ServingCompileResponse
422	Unprocessable Entity	ProblemDetails
429	Too Many Requests	ProblemDetails

Response 200: ServingCompileResponse

Field	Type	Notes
columns	ServingColumnDto[]
dialect	string
limit	int32
parameters	ServingParameterDto[]
release	ServingReleaseDto
sql	string
warnings	string[]

ServingQuery

POST /api/v1/serving/{endpoint}/query

Run a semantic query on the endpoint's release: access policies applied, cached, with trust scores (docs/04 §5).

Parameter	In	Type	Required	Notes
endpoint	path	string	yes

Request body (application/json): ServingQueryBody

Field	Type	Notes
dimensions	string[]?
filters	ServingFilterBody[]?
limit	int32?
metrics	string[]
options	ServingOptionsBody?
orderBy	ServingOrder[]?
segments	string[]?

Status	Description	Body
200	OK	ServingQueryResponse
422	Unprocessable Entity	ProblemDetails
429	Too Many Requests	ProblemDetails

Response 200: ServingQueryResponse

Field	Type	Notes
cache	ServingCacheDto
columns	ServingColumnDto[]
durationMs	int64
release	ServingReleaseDto
rows	none[][]
sql	string?
truncated	boolean
trust	ServingTrustDto
warnings	string[]

ListServingEndpoints

GET /api/v1/workspaces/{workspaceId}/serving/endpoints

The workspace's serving endpoints with their usage in the last 7 days.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Status	Description	Body
200	OK	ServingEndpointDto[]

CreateServingEndpoint

POST /api/v1/workspaces/{workspaceId}/serving/endpoints

Publish a model (a pinned release or the latest) as a serving endpoint (Govern; audited).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Request body (application/json): CreateServingEndpointRequest

Field	Type	Notes
settings	EndpointSettingsRequest
slug	string

Status	Description	Body
201	Created	CreatedResponse

Response 201: CreatedResponse

Field	Type	Notes
id	uuid

GetServingEndpoint

GET /api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}

One serving endpoint.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
endpointId	path	uuid	yes

Status	Description	Body
200	OK	ServingEndpointDto

Response 200: ServingEndpointDto

Field	Type	Notes
allowedApiKeyIds	uuid[]
allowedDimensions	string[]
allowedMetrics	string[]
cacheTtlSeconds	int32
createdAt	date-time
description	string?
enabled	boolean
exposeSql	boolean
id	uuid
lastQueriedAt	date-time?
modelId	uuid
name	string
owner	string?
path	string
queries7d	int64
rateLimitPerMinute	int32
releaseId	uuid?
slug	string
updatedAt	date-time?

UpdateServingEndpoint

PUT /api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}

Replace an endpoint's settings (the slug never changes; Govern; audited).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
endpointId	path	uuid	yes

Request body (application/json): EndpointSettingsRequest

Field	Type	Notes
allowedApiKeyIds	uuid[]?
allowedDimensions	string[]?
allowedMetrics	string[]?
cacheTtlSeconds	int32?
description	string?
exposeSql	boolean?
modelId	uuid
name	string
owner	string?
rateLimitPerMinute	int32?
releaseId	uuid?

Status	Description	Body
204	No Content	—

DeleteServingEndpoint

DELETE /api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}

Delete an endpoint (soft, audited); its slug becomes free.

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
endpointId	path	uuid	yes

Status	Description	Body
204	No Content	—

DisableServingEndpoint

POST /api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}:disable

Turn an endpoint off: queries get 403 Serving.EndpointDisabled (audited).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
endpointId	path	uuid	yes

Status	Description	Body
204	No Content	—

EnableServingEndpoint

POST /api/v1/workspaces/{workspaceId}/serving/endpoints/{endpointId}:enable

Turn an endpoint on (audited).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes
endpointId	path	uuid	yes

Status	Description	Body
204	No Content	—

GetServingEndpointStats

GET /api/v1/workspaces/{workspaceId}/serving/endpoints/stats

Calls per day, p95 duration and error rate of each endpoint over the last 30 days (query-log metadata only).

Parameter	In	Type	Required	Notes
workspaceId	path	uuid	yes

Status	Description	Body
200	OK	ServingEndpointStatsDto[]