Assistant

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

POST
/scopes/{scopeId}/assistant/conversations/{conversationId}/messages

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).

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

conversationId*string
Lengthlength <= 64

Request Body

application/json
  1. body

The next user message. The server keeps the history; nothing else is accepted.

text*string
Length1 <= length <= 2000

Response Body

The turn's events (tool steps, navigation, proposals, the answer) and its token cost.

application/json
  1. response
conversationId*string
events*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  }}