Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Send a message to the console AI assistant
Runs ONE assistant turn on the caller's conversation and answers when it is done.
The model sees a fixed system prompt, the SERVER-SIDE history of this conversation and text
-- nothing else from the client. It may only call read tools (the resource layer and
the flavor / image / network lists, all read back as the caller), navigate (an allowlisted
console screen of this project) and propose_instance, which writes a PROPOSAL and creates
nothing: the user executes it with .../proposals/{proposalId}/actions/confirm. Tool output
is passed to the model as data. At most 8 tool rounds per message; links and images in the
answer are removed. Tokens are billed (assistant.input.ktoken / assistant.output.ktoken).
Validation: READ on compute -> 403 (compute:read for tokens); unreachable scope, or a
conversation that is not the caller's / not in this project / expired -> 404; text 1-2000
characters -> 422.
Feature flag: 404 while the assistant service is disabled.
Async & state: Synchronous (bounded by a turn time budget); appends to the conversation,
writes tool-call audit rows, proposals and token ledger rows.
Errors: 401; 403; 404; 409 CONFLICT with details.reason SUBSCRIPTION_FROZEN (paused
subscription) or ASSISTANT_UNPRICED (the token price is not published -- an unpriced
assistant is closed, not free); 422; 429 with details.reason ASSISTANT_BUDGET_EXCEEDED
(the subscription's daily token cap) or the edge rate limit; 500; 503 with details.reason
ASSISTANT_UNAVAILABLE (no model provider configured, or the provider failed).
Idempotency/Concurrency: Not idempotent (each call is a billed model turn).
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
conversationId*stringlength <= 64application/json- body
The next user message. The server keeps the history; nothing else is accepted.
text*string1 <= length <= 2000The turn's events (tool steps, navigation, proposals, the answer) and its token cost.
application/json- response
conversationId*stringevents*array<>usage*curl -X POST "https://example.com/scopes/string/assistant/conversations/string/messages" \ -H "Content-Type: application/json" \ -d '{ "text": "string" }'{ "conversationId": "string", "events": [ { "type": "tool", "name": "string", "status": "string", "routeKey": "string", "path": "string", "text": "string", "proposal": { "id": "string", "kind": "instance.create", "summary": { "name": "string", "region": "string", "flavor": { "id": "string", "name": "string", "vcpus": 0, "ramMb": 0, "diskGb": 0 }, "image": { "id": "string", "name": "string" }, "network": { "id": "string", "name": "string" }, "keyPairs": [ "string" ] }, "price": { "priceHourly": { "amount": 0, "currency": "USD" }, "priceMonthly": { "amount": 0, "currency": "USD" } }, "expiresAt": "2019-08-24T14:15:22Z" } } ], "usage": { "inputTokens": 0, "outputTokens": 0 }}