ai API · Marula PSA docs

API reference

9 operations in ai. Raw spec: openapi.json.

POST/api/v1/ai/chat/sessions/{session_id}/turns

POST /ai/chat/sessions/{session_id}/turns — run ONE bounded model turn on a granted surface, streaming loop frames over `text/event-stream`. Refusals (surface/model/cap/credential/agent capability), the hard cap and the rate limit answer typed BEFORE any stream begins — clients branch on codes without parsing frames.

Parameters

Name	In	Type	Required	Description
`session_id`	path	string	Yes

Request body

ChatTurnRequest

Responses

Status	Description
`200`	SSE stream of loop frames (text/event-stream)
`400`	validation
`403`	typed refusal: ai_surface_not_granted \| ai_surface_disabled \| ai_surface_internal \| ai_model_not_allowed \| ai_no_models_configured \| ai_hard_cap_reached \| ai_no_credential \| ai_agent_capability_not_granted
`429`	chat turn rate limit

Security: bearer

POST/api/v1/ai/me/authorize

POST /ai/me/authorize — the completion-edge resolution (typed refusals; degrade-never-5xx), delegating to the shared pipeline.

Request body

AiAuthorizeRequest

Responses

Status	Description
`200`
`403`	typed refusal: ai_surface_not_granted \| ai_surface_disabled \| ai_surface_internal \| ai_model_not_allowed \| ai_model_not_capable \| ai_no_models_configured \| ai_hard_cap_reached \| ai_no_credential
`404`	rls_sparse

Security: bearer

GET/api/v1/ai/me/credentials

GET /ai/me/credentials — the caller's personal credential summaries.

Responses

Status	Description
`200`

Security: bearer

PUT/api/v1/ai/me/credentials

PUT /ai/me/credentials — seal a PERSONAL credential (flag-gated).

Request body

PutAiCredentialRequest

Responses

Status	Description
`200`
`403`	personal credentials disabled by policy
`422`

Security: bearer

DELETE/api/v1/ai/me/credentials/{credential_id}

DELETE /ai/me/credentials/{credential_id} — revoke a PERSONAL credential.

Parameters

Name	In	Type	Required	Description
`credential_id`	path	string	Yes

Responses

Status	Description
`200`
`403`
`404`	rls_sparse

Security: bearer

PUT/api/v1/ai/me/model-picks/{surface_key}

PUT /ai/me/model-picks/{surface_key} — a sticky pick; the pair must sit inside the admin allowlist or the pick is typed-refused.

Parameters

Name	In	Type	Required	Description
`surface_key`	path	string	Yes

Request body

PutAiPickRequest

Responses

Status	Description
`200`
`403`
`404`	rls_sparse
`422`	model not in the admin allowlist

Security: bearer

DELETE/api/v1/ai/me/model-picks/{surface_key}

DELETE /ai/me/model-picks/{surface_key} — clears the sticky pick.

Parameters

Name	In	Type	Required	Description
`surface_key`	path	string	Yes

Responses

Status	Description
`200`
`403`
`404`	rls_sparse

Security: bearer

GET/api/v1/ai/me/surfaces

GET /ai/me/surfaces — which surfaces the CALLER may use (deny-by-default: only granted, enabled, non-internal rows surface).

Responses

Status	Description
`200`

Security: bearer

GET/api/v1/ai/me/usage

GET /ai/me/usage — personal progress against caps.

Responses

Status	Description
`200`

Security: bearer