Complete public API reference

This page is generated from the FastAPI external route surface and the curated public OpenAPI contract. It lists every operation available to an external OAuth or MCP service client; admin, desktop-internal, and website BFF routes are excluded.

All Bearer-token calls are server-to-server. Do not put access tokens, codes, client secrets, or call-context tokens in browser JavaScript, AI prompts, URLs, or logs.

OAuth

GET /oauth/authorize

Authorize an open agent

Starts the authorization-code flow. Team authorization should include an exact team_id. Public clients use PKCE S256.

Authentication: Browser authorization session

Parameters

Name	In	Required	Type	Description
response_type	query	yes	string
client_id	query	yes	string
redirect_uri	query	yes	string
scope	query	no	string
state	query	no	string
code_challenge	query	no	string
code_challenge_method	query	no	string
team_id	query	no	string

Responses

Status	Description	Schema
302	Redirects to login, consent, Team selection, or the registered callback.	—
400	Invalid client, redirect URI, scope, Team context, or PKCE input.	—

POST /oauth/authorize

Authorize Submit

Authentication: Browser authorization session

Request body

• application/x-www-form-urlencoded: Body_authorize_submit_oauth_authorize_post (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /oauth/revoke

Revoke an open-agent token

Authentication: Open-agent client credentials

Request body

• application/x-www-form-urlencoded: object (required)

Responses

Status	Description	Schema
200	Revocation is idempotent.	—
400	Invalid client credentials.	—

POST /oauth/token

Exchange an authorization code

Consumes a five-minute single-use authorization code. New exchanges return a 7-day access token and no refresh token.

Authentication: Open-agent client credentials

Request body

• application/x-www-form-urlencoded: object (required)

Responses

Status	Description	Schema
200	Access token response. Team exchanges also include team_id and team_authorization_id.	OAuthTokenResponse
400	OAuth error	OAuthError

Open context

GET /api/v1/open/balance

Get the Personal balance

Rejects Team-bound tokens.

Authentication: OAuth Bearer; scopes: balance

Responses

Status	Description	Schema
200		—
default		—

POST /api/v1/open/charge

Charge

Authentication: OAuth Bearer; scopes: charge

Request body

• application/json: OpenAgentChargeInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/desktop-execution-grants

Create Grant

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
Idempotency-Key	header	yes	string

Request body

• application/json: DesktopExecutionGrantInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

DELETE /api/v1/open/desktop-execution-grants/{grant_id}

Revoke Grant

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
grant_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/desktop-execution-grants/{grant_id}/runs

Admit Run

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
grant_id	path	yes	string

Request body

• application/json: DesktopExecutionRunInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/desktop-execution-grants/{grant_id}/runs/{run_id}/model-results/{sequence}

Model Result

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
grant_id	path	yes	string
run_id	path	yes	string
sequence	path	yes	integer
requestFingerprint	query	yes	string
X-Xiaoya-Team-Id	header	no	string / null

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/employee-generation-results/{operation_digest}

Generation Result

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
operation_digest	path	yes	string
requestFingerprint	query	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

PATCH /api/v1/open/employee-instances/{instance_id}

Open Patch Instance

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
instance_id	path	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Request body

• application/json: EmployeeInstancePatch (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

DELETE /api/v1/open/employee-instances/{instance_id}

Open Archive Instance

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
instance_id	path	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/employee-instances/{instance_id}/boundary

Open Instance Boundary

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
instance_id	path	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/employee-instances/{instance_id}/copy

Open Copy Instance

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
instance_id	path	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Request body

• application/json: EmployeeCopyInput (required)

Responses

Status	Description	Schema
201	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/employee-instances/{instance_id}/dependencies/{item_type}/{item_id}/package

Open Dependency Package

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
instance_id	path	yes	string
item_type	path	yes	string
item_id	path	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

PATCH /api/v1/open/employee-instances/{instance_id}/studio-link

Open Studio Link

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
instance_id	path	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Request body

• application/json: EmployeeStudioLinkInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/employee-instances/{instance_id}/upgrade

Open Upgrade Instance

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
instance_id	path	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Request body

• application/json: EmployeeUpgradeInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/employee-market/{template_id}/cloud-installation

Open Cloud Installation

Authentication: See the operation contract

Parameters

Name	In	Required	Type	Description
template_id	path	yes	string
operationId	query	yes	string
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/me

Get the current agent-scoped user

Authentication: OAuth Bearer; scopes: profile

Responses

Status	Description	Schema
200	Current subject	SuccessEnvelope + object
default		—

POST /api/v1/open/refund

Refund

Authentication: OAuth Bearer; scopes: charge

Request body

• application/json: OpenAgentRefundInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/usage

Get Personal usage attributed to the current agent

Rejects Team-bound tokens. Team overview is not equivalent to this detail contract.

Authentication: OAuth Bearer; scopes: usage

Responses

Status	Description	Schema
200		—
default		—

Personal account

GET /api/v1/open/account/bootstrap

Bootstrap

Authentication: OAuth Bearer; scopes: account

Responses

Status	Description	Schema
200	Successful Response	object

GET /api/v1/open/account/entitlements

Open Personal State

Authentication: OAuth Bearer; scopes: account

Responses

Status	Description	Schema
200	Successful Response	object

POST /api/v1/open/account/gift-cards/redeem

Redeem Card

Authentication: OAuth Bearer; scopes: account

Parameters

Name	In	Required	Type	Description
Idempotency-Key	header	yes	string

Request body

• application/json: GiftCardInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/account/orders

Orders

Authentication: OAuth Bearer; scopes: payment

Parameters

Name	In	Required	Type	Description
page	query	no	integer
pageSize	query	no	integer

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/account/payments/wechat

Create Wechat Order

Authentication: OAuth Bearer; scopes: payment

Request body

• application/json: RechargeOrderInput (required)

Responses

Status	Description	Schema
201	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/account/payments/{order_id}

Payment Order

Authentication: OAuth Bearer; scopes: payment

Parameters

Name	In	Required	Type	Description
order_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/account/performance

Performance

Authentication: OAuth Bearer; scopes: account

Parameters

Name	In	Required	Type	Description
range	query	no	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/account/products

Products

Authentication: OAuth Bearer; scopes: payment

Responses

Status	Description	Schema
200	Successful Response	object

PATCH /api/v1/open/account/profile

Update Profile

Authentication: OAuth Bearer; scopes: account

Request body

• application/json: ProfileInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/account/profile/avatar

Upload Profile Avatar

Authentication: OAuth Bearer; scopes: account

Request body

• multipart/form-data: Body_upload_profile_avatar_api_v1_open_account_profile_avatar_post (required)

Responses

Status	Description	Schema
201	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/account/referral

Referral

Authentication: OAuth Bearer; scopes: account

Responses

Status	Description	Schema
200	Successful Response	object

GET /api/v1/open/account/refunds

Refunds

Authentication: OAuth Bearer; scopes: payment

Parameters

Name	In	Required	Type	Description
page	query	no	integer
pageSize	query	no	integer

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

Models

GET /api/v1/open/models

List models available to the Personal context

Requires a Personal-bound token with the model scope.

Authentication: OAuth Bearer; scopes: model

Responses

Status	Description	Schema
200	Personal model catalog	SuccessEnvelope + object
default		—

Team

GET /api/v1/open/teams

List Team contexts visible to the current subject

Authentication: OAuth Bearer; scopes: profile

Responses

Status	Description	Schema
200	Team contexts	SuccessEnvelope + object
default		—

POST /api/v1/open/teams

Create Open Team

Authentication: OAuth Bearer; scopes: profile

Request body

• application/json: TeamCreateInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/invitations/accept

Accept Open Invitation

Authentication: OAuth Bearer; scopes: profile

Request body

• application/json: TeamInvitationAcceptInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/audit

Audit Log

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
page	query	no	integer
pageSize	query	no	integer

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/balance

Get the exact Team balance

Authentication: OAuth Bearer; scopes: balance

Parameters

Name	In	Required	Type	Description
undefined	undefined	no	—

Responses

Status	Description	Schema
200		—
default		—

POST /api/v1/open/teams/{team_id}/charge

Team Charge

Authentication: OAuth Bearer; scopes: charge

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: OpenAgentTeamChargeInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/context

Resolve one Team context

Authentication: OAuth Bearer; scopes: profile

Parameters

Name	In	Required	Type	Description
undefined	undefined	no	—

Responses

Status	Description	Schema
200	Team context	SuccessEnvelope + object
default		—

GET /api/v1/open/teams/{team_id}/entitlements

Open Team State

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/invitations

Invitations

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/invitations

Create Invitation

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: TeamInvitationInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

DELETE /api/v1/open/teams/{team_id}/invitations/{invitation_id}

Revoke Invitation

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
invitation_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/join-links

Join Links

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/join-links

Create Join Link

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: TeamJoinLinkCreateInput (required)

Responses

Status	Description	Schema
201	Successful Response	object
422	Validation Error	HTTPValidationError

DELETE /api/v1/open/teams/{team_id}/join-links/{link_id}

Revoke Join Link

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
link_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/knowledge/search

Open Agent Search

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: KnowledgeAgentSearchInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/member-credits

Member Credits

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/member-credits/allocate

Allocate Credits

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: TeamCreditChangeInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/member-credits/reclaim

Reclaim Credits

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: TeamCreditChangeInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

PUT /api/v1/open/teams/{team_id}/member-credits/{member_id}/quota

Update Member Credit Quota

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
member_id	path	yes	string

Request body

• application/json: TeamMemberQuotaInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/members

Members

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

PUT /api/v1/open/teams/{team_id}/members/{member_id}/organization

Update Member Org

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
member_id	path	yes	string

Request body

• application/json: TeamMemberOrganizationInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

PATCH /api/v1/open/teams/{team_id}/members/{member_id}/role

Update Role

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
member_id	path	yes	string

Request body

• application/json: TeamMemberRoleInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

PATCH /api/v1/open/teams/{team_id}/members/{member_id}/status

Update Status

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
member_id	path	yes	string

Request body

• application/json: TeamMemberStatusInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/membership

Open Team Current Membership

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/membership/orders

List Open Team Membership Orders

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
page	query	no	integer
pageSize	query	no	integer

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/membership/orders

Create Open Team Membership Order

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: TeamMembershipOrderInput (required)

Responses

Status	Description	Schema
201	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/membership/orders/{order_id}

Get Open Team Membership Order

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
order_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/membership/orders/{order_id}/refunds

List Open Team Membership Refunds

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
order_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/membership/plans

Open Team Membership Plans

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/models

List models available to the exact Team context

Authentication: OAuth Bearer; scopes: model

Parameters

Name	In	Required	Type	Description
undefined	undefined	no	—

Responses

Status	Description	Schema
200	Versioned Team model catalog	SuccessEnvelope + object
default		—

GET /api/v1/open/teams/{team_id}/organization

Get Organization

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/organization/{kind}

Create Org Item

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
kind	path	yes	string

Request body

• application/json: TeamOrganizationItemInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/overview

Open Team Overview

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/open/teams/{team_id}/profile

Team Profile

Authentication: OAuth Bearer; scopes: team_read / team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

PATCH /api/v1/open/teams/{team_id}/profile

Update Team Profile

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: TeamProfileInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/refund

Team Refund

Authentication: OAuth Bearer; scopes: charge

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: OpenAgentTeamRefundInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open/teams/{team_id}/wallet/fund

Fund Wallet

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Request body

• application/json: TeamWalletFundingInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

Model gateway

POST /api/proxy/v1/chat/completions

Call the compatible Chat Completions gateway

Personal open-agent tokens support streaming. A Team-bound token requires every X-Xiaoya workflow header and currently rejects stream=true.

Authentication: OAuth Bearer; scopes: model

Parameters

Name	In	Required	Type	Description
undefined	undefined	no	—
undefined	undefined	no	—
undefined	undefined	no	—
undefined	undefined	no	—
undefined	undefined	no	—
X-Request-ID	header	yes	string	Stable client request ID. Reuse the same value only when retrying the same request in the same billing account context.

Request body

• application/json: object (required)

Responses

Status	Description	Schema
200	JSON completion or text/event-stream for a supported Personal streaming request.	object / string
default		—

TTS gateway

POST /api/proxy/v1/audio/speech

Create Speech

Authentication: OAuth Bearer; scopes: model

Parameters

Name	In	Required	Type	Description
X-Xiaoya-Team-Id	header	no	string / null
X-Request-ID	header	yes	string	Stable client request ID. Reuse the same value only when retrying the same request in the same billing account context.

Request body

• application/json: TtsSpeechInput (required)

Responses

Status	Description	Schema
200	Generated speech audio. The response is never cached.	string / string / string / string
422	Validation Error	HTTPValidationError

GET /api/proxy/v1/tts/options

List Tts Options

Authentication: OAuth Bearer; scopes: model

Parameters

Name	In	Required	Type	Description
X-Xiaoya-Team-Id	header	no	string / null

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

Sponsored billing

POST /api/v1/open/public-billing-sessions

Create Public Billing Session

Authentication: OAuth Bearer; scopes: model

Request body

• application/json: PublicBillingSessionInput (required)

Responses

Status	Description	Schema
201	Successful Response	object
422	Validation Error	HTTPValidationError

DELETE /api/v1/open/public-billing-sessions/{session_id}

Revoke Public Billing Session

Authentication: OAuth Bearer; scopes: model

Parameters

Name	In	Required	Type	Description
session_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

Runtime assets

GET /api/v1/runtime-assets/{item_type}

List Runtime Assets

Authentication: OAuth Bearer; scopes: skill

Parameters

Name	In	Required	Type	Description
item_type	path	yes	MarketItemType
X-Xiaoya-Team-Id	header	no	string / null
X-Xiaoya-Team-Context-Version	header	no	integer / null

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/runtime-assets/{item_type}/{item_id}/package

Download Runtime Asset Package

Authentication: OAuth Bearer; scopes: skill

Parameters

Name	In	Required	Type	Description
item_type	path	yes	MarketItemType
item_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

Execution grants

GET /api/v1/teams/{team_id}/execution-grants

Execution Grants

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/teams/{team_id}/execution-grants

Create Execution Grant

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
Idempotency-Key	header	yes	string

Request body

• application/json: TeamExecutionGrantInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

DELETE /api/v1/teams/{team_id}/execution-grants/{grant_id}

Revoke Execution Grant

Authentication: OAuth Bearer; scopes: team_manage

Parameters

Name	In	Required	Type	Description
team_id	path	yes	string
grant_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

Sandbox

GET /api/v1/sandbox-runtime/computer/capabilities

Configured Capabilities

Authentication: OAuth Bearer; scopes: sandbox

Responses

Status	Description	Schema
200	Successful Response	object

POST /api/v1/sandbox-runtime/workspaces

Create Sandbox Workspace

Authentication: OAuth Bearer; scopes: sandbox

Request body

• application/json: SandboxWorkspaceCreateInput (required)

Responses

Status	Description	Schema
201	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/sandbox-runtime/workspaces/{sandbox_id}

Sandbox Workspace Status

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

DELETE /api/v1/sandbox-runtime/workspaces/{sandbox_id}

Destroy Sandbox Workspace

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/commands

Execute Sandbox Command

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: SandboxCommandInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/sandbox-runtime/workspaces/{sandbox_id}/computer

Status

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/computer/control

Acquire

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: ControlAcquireInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/computer/control/heartbeat

Heartbeat

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: ControlLeaseInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/computer/control/release

Release

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: ControlLeaseInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/computer/key

Key

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: KeyInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/computer/mouse

Mouse

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: MouseInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/computer/screenshot

Screenshot

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

GET /api/v1/sandbox-runtime/workspaces/{sandbox_id}/computer/status

Status

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/files

Upload Sandbox File

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: SandboxFileUploadInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/files/download

Download Sandbox File

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: SandboxFileDownloadInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/pause

Pause Sandbox Workspace

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/sandbox-runtime/workspaces/{sandbox_id}/resume

Resume Sandbox Workspace

Authentication: OAuth Bearer; scopes: sandbox

Parameters

Name	In	Required	Type	Description
sandbox_id	path	yes	string

Request body

• application/json: SandboxResumeInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

MCP service callbacks

POST /api/v1/open-agent-tools/call-context/introspect

Introspect Open Agent Call Context

Authentication: Open-agent client credentials in the JSON body

Request body

• application/json: OpenAgentCallContextIntrospectionInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

POST /api/v1/open-agent-tools/callbacks/{invocation_id}

Complete Open Agent Async Tool

Authentication: X-Xiaoya-Call-Context

Parameters

Name	In	Required	Type	Description
invocation_id	path	yes	string
X-Xiaoya-Call-Context	header	yes	string

Request body

• application/json: OpenAgentAsyncResultInput (required)

Responses

Status	Description	Schema
200	Successful Response	object
422	Validation Error	HTTPValidationError

Component schemas

Body_authorize_submit_oauth_authorize_post

Field	Required	Type	Description
client_id	yes	string	maxLength=32
redirect_uri	yes	string	maxLength=2000
scope	no	string	maxLength=500
state_value	no	string / null
code_challenge	no	string / null
code_challenge_method	no	string / null
csrf_token	yes	string	maxLength=200
decision	yes	string	maxLength=10
team_id	no	string / null
team_consent_proof	no	string / null

Body_upload_profile_avatar_api_v1_open_account_profile_avatar_post

Field	Required	Type	Description
file	yes	string	format=binary

ChatMessage

Field	Required	Type	Description
role	yes	string	enum=system, user, assistant, tool
content	yes	object

ControlAcquireInput

Field	Required	Type	Description
conversationId	yes	string	format=uuid

ControlLeaseInput

Field	Required	Type	Description
conversationId	yes	string	format=uuid
fence	yes	integer	min=1

DesktopExecutionGrantInput

Field	Required	Type	Description
purpose	no	ExecutionGrantPurpose
workspaceId	yes	string	minLength=1; maxLength=36
employeeId	yes	string	minLength=1; maxLength=36
desktopSessionId	yes	string	minLength=1; maxLength=36
deviceId	yes	string	minLength=1; maxLength=128
scopes	yes	array<string>
expiresInSeconds	no	integer	min=3600; max=31536000

DesktopExecutionRunInput

Field	Required	Type	Description
runId	yes	string	minLength=36; maxLength=36

EmployeeCopyInput

Field	Required	Type	Description
operationId	yes	string	minLength=8; maxLength=120

EmployeeInstancePatch

Field	Required	Type	Description
expectedConfigVersion	yes	integer	min=1
changes	yes	object

EmployeeStudioLinkInput

Field	Required	Type	Description
operationId	yes	string	minLength=8; maxLength=120
studioEmployeeId	yes	string	minLength=1; maxLength=36

EmployeeUpgradeInput

Field	Required	Type	Description
expectedConfigVersion	yes	integer	min=1
operationId	yes	string	minLength=8; maxLength=120
version	yes	string	minLength=1; maxLength=32
resolutions	no	object

ErrorEnvelope

Field	Required	Type	Description
success	yes	boolean
code	yes	string
message	yes	string
request_id	yes	string

ExecutionGrantPurpose

Shape: string

GiftCardInput

Field	Required	Type	Description
code	yes	string	minLength=12; maxLength=64

HTTPValidationError

Field	Required	Type	Description
detail	no	array<ValidationError>

KeyInput

Field	Required	Type	Description
keys	yes	array<string>

KnowledgeAgentSearchInput

Field	Required	Type	Description
query	yes	string	minLength=1; maxLength=4000
knowledgeBaseIds	no	array<string>
limit	no	integer	min=1; max=20

MarketItemType

Shape: string

MembershipBillingPeriod

Shape: string

ModelCatalogItem

Field	Required	Type	Description
modelCode	yes	string
displayName	yes	string
modelType	yes	string	enum=llm, image, video
acceptsText	no	boolean
acceptsImage	no	boolean
acceptsFile	no	boolean
outputsText	no	boolean
outputsImage	no	boolean
outputsAudio	no	boolean
outputsVideo	no	boolean
parameterSchemaVersion	yes	integer	min=1
parameterSpec	yes	object / null
structuredOutputMode	no	string	Explicit structured-output mode declared by the model catalog. Use prompt when this field is absent. The legacy supportsJson flag alone does not declare native json_object or json_schema support.; enum=prompt, json_object, json_schema

MouseInput

Field	Required	Type	Description
x	yes	integer	min=0
y	yes	integer	min=0
action	no	string	enum=move, click, down, up
button	no	string	enum=left, middle, right

OAuthError

Field	Required	Type	Description
error	yes	string	enum=invalid_client, invalid_grant, unsupported_grant_type
error_description	yes	string

OAuthTokenResponse

Field	Required	Type	Description
access_token	yes	string
token_type	yes	string
expires_in	yes	integer
scope	yes	string
team_id	no	string
team_authorization_id	no	string

OpenAgentAsyncResultInput

Field	Required	Type	Description
result	yes	object

OpenAgentCallContextIntrospectionInput

Field	Required	Type	Description
clientId	yes	string	minLength=3; maxLength=32
clientSecret	yes	string	minLength=1; maxLength=512
token	yes	string	minLength=1; maxLength=8192

OpenAgentChargeInput

Field	Required	Type	Description
points	yes	integer	min=1; max=1000000000000
reason	yes	string	minLength=1; maxLength=100
idempotencyKey	yes	string	minLength=8; maxLength=64

OpenAgentRefundInput

Field	Required	Type	Description
points	yes	integer	min=1; max=1000000000000
reason	yes	string	minLength=1; maxLength=100
idempotencyKey	yes	string	minLength=8; maxLength=64
chargeIdempotencyKey	yes	string	minLength=8; maxLength=64

OpenAgentTeamChargeInput

Field	Required	Type	Description
points	yes	integer	min=1; max=1000000000000
idempotencyKey	yes	string	minLength=8; maxLength=64

OpenAgentTeamRefundInput

Field	Required	Type	Description
points	yes	integer	min=1; max=1000000000000
idempotencyKey	yes	string	minLength=8; maxLength=64
chargeIdempotencyKey	yes	string	minLength=8; maxLength=64

OpenAgentUser

Field	Required	Type	Description
userId	yes	string	Stable subject isolated to the current open agent.
displayName	yes	string
avatarUrl	no	string / null	format=uri

PaymentOrderType

Shape: string

PaymentProvider

Shape: string

ProfileInput

Field	Required	Type	Description
displayName	no	string / null
avatarUrl	no	string / null

PublicBillingSessionInput

Field	Required	Type	Description
expires_in_seconds	no	integer	min=60; max=3600
max_points	no	integer	min=1; max=1000000000
max_calls	no	integer	min=1; max=10000

RechargeOrderInput

Field	Required	Type	Description
amount_cents	no	integer / null
order_type	no	PaymentOrderType
product_code	no	string / null
idempotency_key	yes	string	minLength=8; maxLength=120
catalog_version	no	string / null
billing_period	no	MembershipBillingPeriod / null

SandboxCommandInput

Field	Required	Type	Description
command	yes	array<string>
workingDirectory	no	string	minLength=1; maxLength=1000
environment	no	object
timeoutSeconds	no	integer	min=1; max=900

SandboxFileDownloadInput

Field	Required	Type	Description
sourcePath	yes	string	minLength=1; maxLength=1000

SandboxFileUploadInput

Field	Required	Type	Description
destinationPath	yes	string	minLength=1; maxLength=1000
contentBase64	yes	string	minLength=1; maxLength=45000000

SandboxResumeInput

Field	Required	Type	Description
snapshotId	no	string / null

SandboxWorkspaceCreateInput

Field	Required	Type	Description
employeeId	yes	string	format=uuid
logicalWorkspaceId	yes	string	format=uuid
idempotencyKey	yes	string	minLength=8; maxLength=160
cpuMilli	no	integer / null
memoryMb	no	integer / null
maxRunMinutes	no	integer / null
idlePauseSeconds	no	integer / null
environment	no	object

SuccessEnvelope

Field	Required	Type	Description
success	yes	boolean
data	yes	object
request_id	yes	string

TeamContext

Field	Required	Type	Description
teamId	yes	string
name	yes	string
status	yes	string
memberId	yes	string
memberStatus	yes	string
role	yes	string

TeamCreateInput

Field	Required	Type	Description
name	yes	string	minLength=1; maxLength=120
idempotencyKey	no	string / null

TeamCreditChangeInput

Field	Required	Type	Description
memberId	yes	string	minLength=1; maxLength=36
points	yes	integer	min=1; max=1000000000000
idempotencyKey	yes	string	minLength=8; maxLength=160

TeamExecutionGrantInput

Field	Required	Type	Description
subjectType	yes	TeamExecutionSubjectType
subjectId	yes	string	minLength=1; maxLength=128
scopes	yes	array<string>
expiresInSeconds	no	integer	min=3600; max=31536000

TeamExecutionSubjectType

Shape: string

TeamInvitationAcceptInput

Field	Required	Type	Description
token	yes	string	minLength=20; maxLength=200

TeamInvitationInput

Field	Required	Type	Description
invitee	yes	string	minLength=3; maxLength=320
role	yes	string	minLength=1; maxLength=32
expiresInHours	no	integer	min=1; max=168

TeamJoinLinkCreateInput

Field	Required	Type	Description
kind	no	TeamJoinLinkKind
role	no	string	minLength=1; maxLength=32
maxUses	no	integer	min=1; max=10000
expiresInHours	no	integer	min=1; max=720

TeamJoinLinkKind

Shape: string

TeamMemberOrganizationInput

Field	Required	Type	Description
departmentId	no	string / null
positionId	no	string / null
managerMemberId	no	string / null
roleIds	no	array<string>

TeamMemberQuotaInput

Field	Required	Type	Description
quotaLimit	no	integer / null
expectedVersion	yes	integer	min=0
idempotencyKey	yes	string	minLength=8; maxLength=160

TeamMemberRoleInput

Field	Required	Type	Description
role	yes	string	minLength=1; maxLength=32

TeamMembershipOrderAction

Shape: string

TeamMembershipOrderInput

Field	Required	Type	Description
provider	yes	PaymentProvider
planVersionId	yes	string	minLength=1; maxLength=36
action	yes	TeamMembershipOrderAction
idempotencyKey	yes	string	minLength=8; maxLength=120
expectedSubscriptionVersion	no	integer / null
seatCount	no	integer / null
billingPeriod	no	MembershipBillingPeriod / null

TeamMemberStatusInput

Field	Required	Type	Description
status	yes	string	minLength=1; maxLength=24

TeamModelCatalog

Field	Required	Type	Description
teamId	yes	string
teamContextVersion	yes	integer
planVersionId	yes	string
catalogVersion	yes	string
items	yes	array<ModelCatalogItem>

TeamOrganizationItemInput

Field	Required	Type	Description
name	yes	string	minLength=1; maxLength=120
parentId	no	string / null
description	no	string	maxLength=500

TeamProfileInput

Field	Required	Type	Description
name	yes	string	minLength=1; maxLength=120
avatarUrl	no	string / null
description	no	string	maxLength=500

TeamWalletFundingInput

Field	Required	Type	Description
points	yes	integer	min=1; max=1000000000000
idempotencyKey	yes	string	minLength=8; maxLength=160

TtsSpeechInput

Field	Required	Type	Description
tts_config_id	yes	string	minLength=3; maxLength=100
voice	yes	string	minLength=1; maxLength=256
input	yes	string	minLength=1; maxLength=9999
response_format	no	string	minLength=2; maxLength=20
speed	no	number	min=0.5; max=2
volume	no	number	max=10
pitch	no	integer	min=-12; max=12
emotion	no	string / null
sample_rate	no	integer	enum=8000, 16000, 22050, 24000, 32000, 44100
bitrate	no	integer	enum=32000, 64000, 128000, 256000
audio_channel	no	integer	enum=1, 2
language_boost	no	string	enum=Chinese, Chinese,Yue, English, Arabic, Russian, Spanish, French, Portuguese, German, Turkish, Dutch, Ukrainian, Vietnamese, Indonesian, Japanese, Italian, Korean, Thai, Polish, Romanian, Greek, Czech, Finnish, Hindi, Bulgarian, Danish, Hebrew, Malay, Persian, Slovak, Swedish, Croatian, Filipino, Hungarian, Norwegian, Slovenian, Catalan, Nynorsk, Tamil, Afrikaans, auto
text_normalization	no	boolean
latex_read	no	boolean

ValidationError

Field	Required	Type	Description
loc	yes	array<string / integer>
msg	yes	string
type	yes	string