Version 2.2.6 · latest Download OpenAPI Markdown

AI assistant

Model connection settings and connection test, the model rating table, availability and quota, conversation history, and the assistant look.

aiAI assistantAuthentication: User21 endpoints

List all users' AI conversations

GET/api/v2/ai/admin/conversations

Authentication: Admin only

Query parameters

Field	Type	Required	Description
page	integer	—	Page number, starting from 1 Default `1`
page_size	integer	—	Items per page Default `20`
user_id	integer	—	Only this user's conversations.
since	string	—	Start time (inclusive), RFC 3339; the conversation's last message is not before it.
until	string	—	End time (exclusive), RFC 3339; the conversation started before it.
kind	string	—	all (default); changed: a plan changed a site (a site was created or a plan finished); failed: a plan failed. Values `["all","changed","failed"]`
q	string	—	Search by a substring of the title or message text.

Get any user's AI conversation

GET/api/v2/ai/admin/conversations/{id}

Authentication: Admin only

List my AI conversations

GET/api/v2/ai/conversations

Authentication: User

Query parameters

Field	Type	Required	Description
page	integer	—	Page number, starting from 1 Default `1`
page_size	integer	—	Items per page Default `20`
q	string	—	Search by a substring of the title or message text.

Get my AI conversation

GET/api/v2/ai/conversations/{id}

Authentication: User

Delete my AI conversation

DELETE/api/v2/ai/conversations/{id}

Authentication: User

Get my assistant look

GET/api/v2/ai/look

Authentication: User

Save my assistant look

PUT/api/v2/ai/look

Authentication: User

Request body application/json

Field	Type	Required	Description
name	string	Required	Assistant name; empty means the default name.
pet	AiPet	Required	Assistant figure: orb, cat, dog, bot, or ai (drawn from the custom parameters in spec). Values `["orb","cat","dog","bot","ai"]`
spec	AiLookSpec	—	Parameters of the AI custom figure (whitelisted values only; the panel draws it from fixed SVG parts). Absent from AiLook when never customised. Required when saving with pet ai or theme custom (code required); omitted means the stored one is kept. The server re-checks and normalises it (lowercase colours, primary darkened until white text is readable).
theme	AiTheme	Required	Assistant accent colour: blue, teal, sunset, morandi, ink, or custom (the three colours in the custom parameters, spec). Applies to the assistant panel only. Values `["blue","teal","sunset","morandi","ink","custom"]`

Get my uploaded assistant avatar

GET/api/v2/ai/look/avatar

Authentication: User

Upload my assistant avatar

PUT/api/v2/ai/look/avatar

Authentication: User

Remove my uploaded assistant avatar

DELETE/api/v2/ai/look/avatar

Authentication: User

Generate a custom assistant figure from a description

POST/api/v2/ai/look/generate

Authentication: User

Request body application/json

Field	Type	Required	Description
text	string	Required	The look you want, at most 60 characters after control characters and angle brackets are removed.

Send a message to the AI assistant

POST/api/v2/ai/messages

Authentication: User

Request body application/json

Field	Type	Required	Description
context	AiContext	—	Current page context: only the page name and the ID of the open item; the server fetches the data. Pages with detailed data: home, attack_logs (ref = record ID), sites (ref = site ID); other pages pass only the name.
conversation_id	integer	—	Conversation to continue; omit to start a new one (titled from this message).
text	string	Required	The look you want, at most 60 characters after control characters and angle brackets are removed.

List AI model ratings

GET/api/v2/ai/models

Authentication: Admin only

Cancel an AI assistant plan

POST/api/v2/ai/plans/cancel

Authentication: User

Request body application/json

Field	Type	Required	Description
plan_id	AiPlanKey	Required	Plan id (random, 32 hex digits).

Execute an AI assistant plan

POST/api/v2/ai/plans/execute

Authentication: User

Request body application/json

Field	Type	Required	Description
password	string	—	Current login password.
plan_id	AiPlanKey	Required	Plan id (random, 32 hex digits).
totp_code	string	—	Current 6-digit TOTP code; the account must have TOTP enabled.

Revise the parameters of an AI assistant plan

POST/api/v2/ai/plans/revise

Authentication: User

Request body application/json

Field	Type	Required	Description
domain	string	Required	Site domain.
origin	string	Required	Origin address (IP or hostname).
plan_id	AiPlanKey	Required	Plan id (random, 32 hex digits).
port	integer	Required	Origin port.
upid	integer	Required	Purchased package to use (must belong to the plan's owning tenant).

Get an AI assistant plan

GET/api/v2/ai/plans/{plan_id}

Authentication: User

Get AI assistant settings

GET/api/v2/ai/settings

Authentication: Admin only

Save AI assistant settings

PUT/api/v2/ai/settings

Authentication: Admin only

Request body application/json

Field	Type	Required	Description
api_key	string	—	API key; omit to keep the stored one, or send an empty string to clear it (which disables the assistant). Stored sealed and never returned.
api_type	AiApiType	Required	API type: openai is OpenAI-compatible (/chat/completions, also used by most providers in mainland China); claude is the native Anthropic API (/messages); moonshot is Kimi (OpenAI-compatible with a different default address). Values `["openai","claude","moonshot"]`
base_url	string	—	Service address (public HTTPS); empty if never saved.
model	string	Required	Model name.

Test AI assistant connection

POST/api/v2/ai/settings/probe

Authentication: Admin only

Request body application/json

Field	Type	Required	Description
api_key	string	—	API key; omit to keep the stored one, or send an empty string to clear it (which disables the assistant). Stored sealed and never returned.
api_type	AiApiType	Required	API type: openai is OpenAI-compatible (/chat/completions, also used by most providers in mainland China); claude is the native Anthropic API (/messages); moonshot is Kimi (OpenAI-compatible with a different default address). Values `["openai","claude","moonshot"]`
base_url	string	—	Service address (public HTTPS); empty if never saved.
model	string	Required	Model name.

Get AI assistant availability

GET/api/v2/ai/status

Authentication: User

AI assistant object

Field	Type	Required	Description
api_key	string	—	API key; omit to keep the stored one, or send an empty string to clear it (which disables the assistant). Stored sealed and never returned.
api_type	AiApiType	—	API type: openai is OpenAI-compatible (/chat/completions, also used by most providers in mainland China); claude is the native Anthropic API (/messages); moonshot is Kimi (OpenAI-compatible with a different default address). Values `["openai","claude","moonshot"]`
available	boolean	—	Whether the assistant is shown and usable; the same for a delegated session.
avatar_ver	integer	—	Avatar version; 0 means no uploaded avatar (the chosen figure is shown), above 0 fetch it with GET /ai/look/avatar; grows on every change.
base_url	string	—	Service address (public HTTPS); empty if never saved.
cert_id	integer	—	The requested certificate.
cname	string	—	CNAME target from the create response; while waiting for DNS the user points the domain to it.
code	string	—	Failure detail: blocked (address rejected, such as private), auth (key rejected), rate_limited (upstream rate limit), timeout, refused (model refused), protocol (malformed response), http (other status code), connect (unreachable).
connect_ms	integer	—	Connect time in milliseconds (latest request).
context	AiContext	—	Current page context: only the page name and the ID of the open item; the server fetches the data. Pages with detailed data: home, attack_logs (ref = record ID), sites (ref = site ID); other pages pass only the name.
conversation_id	integer	—	Conversation to continue; omit to start a new one (titled from this message).
created_at	string	—	Created at.
detail	string	—	Explanation for the admin (includes an upstream error excerpt, never the key).
domain	string	Required	Site domain.
error	string	—	Why the plan failed.
error_code	string	—	The error code part of the failure reason (the step API's code, or no_cname).
events	AiPlanEvent[]	—	Step records in order (only in conversation details).
expired	boolean	—	Waiting to run but past its deadline (computed by the server from expires_at).
expires_at	string	—	The plan cannot be executed after this time.
fetched_on	string	—	Date the data was fetched.
first_token_ms	integer	—	Slowest first-token time in milliseconds over the rounds run.
has_delegated	boolean	—	Some messages were sent from a delegated session.
high_risk	boolean	—	Re-authentication is required before executing.
id	integer	—	Conversation ID.
items	AiModel[]	—	By index, highest first.
key_set	boolean	—	Whether an API key is set (the key itself is never returned).
kind	AiPlanKind	—	create_site: add a site (HTTP first; the certificate is requested after DNS is set up); delete_site: delete a site (high risk, re-authentication required). Values `["create_site","delete_site"]`
last_plan	object	—	The most recently proposed plan; absent when there is none.
message_count	integer	—	Number of messages.
messages	AiMessage[]	—	All messages (only when getting a single conversation).
model	string	—	Model name.
name	string	—	Assistant name; empty means the default name.
ok	boolean	—	Whether the probe passed.
origin	string	Required	Origin address (IP or hostname).
outdated	boolean	—	Data is more than 90 days old; the panel shows that ratings may be outdated.
params	AiPlanParams	—	Frozen plan parameters. Adding a site: domain, origin, port, upid, package (plus tenant_id when an admin creates for a tenant); deleting a site: site_id, with site_name and domains for review.
password	string	—	Current login password.
pet	AiPet	—	Assistant figure: orb, cat, dog, bot, or ai (drawn from the custom parameters in spec). Values `["orb","cat","dog","bot","ai"]`
plan_count	integer	—	Number of plans proposed (including superseded ones).
plan_id	AiPlanKey	Required	Plan id (random, 32 hex digits).
plans	AiPlan[]	—	Plans proposed in this conversation, in order, with their step records (only when getting a single conversation).
port	integer	Required	Origin port.
probe_first_token_ms	integer	—	Slowest first-token time in milliseconds over the 3 probe rounds; 0 if not passed.
probe_ok	boolean	—	Whether the save-time probe passed; reset when the model or key changes.
probe_round_ms	integer	—	Slowest round time in milliseconds over the 3 probe rounds; 0 if not passed.
probed_at	string	—	When the probe passed; null if not passed.
ready	boolean	—	Whether the settings are usable (key set, model set and probe passed); the license is checked separately, see /ai/status.
reason	string	—	Why unavailable: unlicensed (not enabled), expired (license expired), not_configured (the admin has not connected a model), demo (demo mode); delegated is no longer returned (delegated sessions are now usable like the account owner) and is kept only for older panels. Values `["unlicensed","expired","not_configured","delegated","demo"]`
reauth_methods	AiReauthMethod[]	—	Re-authentication methods available for a high-risk plan; empty otherwise.
retention_days	integer	—	Days conversations are kept (setting retention.ai_chat_days, counted from the last message; expired conversations are removed with their query records and plans).
revoking_until	string	—	When the provider has revoked the license, usable until this time.
round_ms	integer	—	Slowest round time in milliseconds over the rounds run.
rounds	integer	—	Rounds completed (3 when passed).
site_id	integer	—	The created site.
spec	AiLookSpec	—	Parameters of the AI custom figure (whitelisted values only; the panel draws it from fixed SVG parts). Absent from AiLook when never customised. Required when saving with pet ai or theme custom (code required); omitted means the stored one is kept. The server re-checks and normalises it (lowercase colours, primary darkened until white text is readable).
state	AiPlanState	—	proposed: waiting to run; running: in progress; wait_dns: site created, waiting for the DNS record (executing again requests the certificate); done; failed (see error); cancelled; superseded: replaced by a revised plan. Values `["proposed","running","wait_dns","done","failed","cancelled","superseded"]`
step	string	—	Where a failed probe stopped: connect (unreachable or upstream error), tool (did not call the tool with the numbers), echo (wrong echo), first_token (first token too slow), round (round too slow). Values `["connect","tool","echo","first_token","round"]`
text	string	Required	The look you want, at most 60 characters after control characters and angle brackets are removed.
theme	AiTheme	—	Assistant accent colour: blue, teal, sunset, morandi, ink, or custom (the three colours in the custom parameters, spec). Applies to the assistant panel only. Values `["blue","teal","sunset","morandi","ink","custom"]`
title	string	—	Title (start of the first question).
tool_calls	AiToolCall[]	—	Read-only queries in order (only when getting a single conversation).
tool_count	integer	—	Number of read-only queries.
totp_code	string	—	Current 6-digit TOTP code; the account must have TOTP enabled.
updated_at	string	—	Time of the last message (retention counts from it).
upid	integer	Required	Purchased package to use (must belong to the plan's owning tenant).
usage	object	—	Your usage and quota after this generation (already counted).
user_deleted	boolean	—	The owner's account has been deleted (admin endpoints only).
user_id	integer	—	Owner of the conversation (admin endpoints only).
username	string	—	Owner's username (admin endpoints only; empty when the user was deleted).
version	string	—	Rating methodology version.

curl

# List all users' AI conversations
curl "https://panel.example.com/api/v2/ai/admin/conversations" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get any user's AI conversation
curl "https://panel.example.com/api/v2/ai/admin/conversations/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# List my AI conversations
curl "https://panel.example.com/api/v2/ai/conversations" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get my AI conversation
curl "https://panel.example.com/api/v2/ai/conversations/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Delete my AI conversation
curl -X DELETE "https://panel.example.com/api/v2/ai/conversations/{id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get my assistant look
curl "https://panel.example.com/api/v2/ai/look" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Save my assistant look
curl -X PUT "https://panel.example.com/api/v2/ai/look" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get my uploaded assistant avatar
curl "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Upload my assistant avatar
curl -X PUT "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Remove my uploaded assistant avatar
curl -X DELETE "https://panel.example.com/api/v2/ai/look/avatar" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Generate a custom assistant figure from a description
curl -X POST "https://panel.example.com/api/v2/ai/look/generate" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Send a message to the AI assistant
curl -X POST "https://panel.example.com/api/v2/ai/messages" \
  -H "X-API-Key: $GOCDN_API_KEY"

# List AI model ratings
curl "https://panel.example.com/api/v2/ai/models" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Cancel an AI assistant plan
curl -X POST "https://panel.example.com/api/v2/ai/plans/cancel" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Execute an AI assistant plan
curl -X POST "https://panel.example.com/api/v2/ai/plans/execute" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Revise the parameters of an AI assistant plan
curl -X POST "https://panel.example.com/api/v2/ai/plans/revise" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get an AI assistant plan
curl "https://panel.example.com/api/v2/ai/plans/{plan_id}" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get AI assistant settings
curl "https://panel.example.com/api/v2/ai/settings" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Save AI assistant settings
curl -X PUT "https://panel.example.com/api/v2/ai/settings" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Test AI assistant connection
curl -X POST "https://panel.example.com/api/v2/ai/settings/probe" \
  -H "X-API-Key: $GOCDN_API_KEY"

# Get AI assistant availability
curl "https://panel.example.com/api/v2/ai/status" \
  -H "X-API-Key: $GOCDN_API_KEY"