# BMA Developer Docs > BeeOS Managed Agents (BMA): a managed agent platform with a Claude Managed Agents–compatible API, a native REST API, and the Executor Protocol for bringing your own hands and brains. ## Docs - [Introduction](/index): Run durable agents behind a Claude Managed Agents–compatible API, with the brain, the hands and the session kept apart. - [Quickstart](/quickstart): Create an agent, an environment and a session, send a message and stream the events, in about five minutes. - [Compatibility](/compatibility): The subset of the Claude Managed Agents API that BMA serves at /v1, what it does not support, where it behaves differently, and what it adds. - [Agents](/concepts/agents): An agent is a reusable definition: model, instructions, tools, MCP servers, skills and machine sources. - [Environments](/concepts/environments): An environment describes where a session's machines come from. In BMA it is a machine pool. - [Sessions & events](/concepts/sessions-and-events): A session is one durable conversation. Everything that happens in it is an event you can list, stream and resume. - [Machines & pools](/concepts/machines): Machines are the hands. They start on demand, pause when idle, and are rebuilt or restored without losing the session. - [Files & outputs](/concepts/files-and-outputs): Upload files once, mount them into sessions, and collect what the agent writes. - [Memory stores](/concepts/memory): Persistent files an agent keeps between sessions or shares with other agents. - [Skills](/concepts/skills): Reusable instructions and files that the agent loads only when it needs them. - [MCP servers](/concepts/mcp): Connect Model Context Protocol servers; credentials stay in BMA secrets. - [Approvals & questions](/concepts/interactions): Interactions pause the agent until a person approves a tool call or answers a question. - [Desktop & computer use](/concepts/desktop): Watch a machine's desktop, take over control, and attach terminals, without exposing VNC passwords or inbound ports. - [Context compaction](/concepts/context-compaction): How BMA keeps long tasks inside the model's context window, and what you see when it cannot. - [Executor Protocol](/executor/overview): How brains drive hands: roles, connection, deployment shapes and capability status. - [Agent capability](/executor/agent-capability): Run a BMA agent's sessions on your own agent loop, connected through the Executor Protocol. - [Brains roadmap](/executor/brains-roadmap): Today: the BMA server harness and external brains through the agent capability. Next: generic ACP brains. - [SDK overview](/sdks/overview): Which SDK to use: the official Anthropic SDKs, bma-sdk, or bma-executor-sdk. - [bma-sdk](/sdks/bma-sdk): Typed clients for the BMA native REST API and the BMA extensions to the Managed Agents API, in Go, TypeScript and Python. - [bma-executor-sdk](/sdks/bma-executor-sdk): Build executors (hands), harnesses (brains) and agent executors for the BMA Executor Protocol, in Go, TypeScript and Python. - [API reference](/api-reference/introduction): Native REST API and Managed Agents extensions: base URLs, authentication, errors and pagination. - [List event webhooks for one scope](/api-reference/native/events/list-event-webhooks-for-one-scope): Returns the webhooks directly attached to the requested scope, not inherited matches. - [Create an event webhook](/api-reference/native/events/create-an-event-webhook): Subscribes to future events from agents matching the scope. Each scope can have only one active webhook per URL; duplicates return 409. Matching scopes are additive. Requires project management permission. - [Delete an event webhook](/api-reference/native/events/delete-an-event-webhook): Deletes the webhook and stops new deliveries and pending attempts. Requests already in flight may finish. - [Update event webhook settings](/api-reference/native/events/update-event-webhook-settings): Updates a webhook's URL, event filters, and signing settings. The scope cannot change. Omitted fields stay unchanged; set signing_secret_id to null to remove signing. Event filters affect newly queued deliveries; URL and signing changes also apply to pending attempts. - [List turns](/api-reference/native/events/list-turns): Returns turns newest first. Use the returned next_before_turn_sequence as before_turn_sequence to fetch older turns. - [List turn events](/api-reference/native/events/list-turn-events): Returns one older event page for a turn, ordered chronologically within the page. Use the returned next_before_sequence as before_sequence to fetch older events. - [List events](/api-reference/native/events/list-events): Returns one page of agent events, chronological within the page. Forward pagination (after_sequence) walks from a known boundary toward the present using next_after_sequence. Backward pagination (before_sequence) starts at the latest events and walks toward the beginning using next_before_sequence; passing before_sequence takes precedence over after_sequence. - [Stream events](/api-reference/native/events/stream-events) - [List session artifacts](/api-reference/native/events/list-session-artifacts): Lists the artifacts this session owns (uploaded to it or produced by its tool calls), newest first. Another session's artifacts and agent-level artifacts are not included. - [Upload a session artifact](/api-reference/native/events/upload-a-session-artifact): Streams the request body (1 byte to 1 GiB) into object storage as an artifact owned by this session. The session's tool calls read it at the returned /artifacts/ path; other sessions cannot. - [Get session artifact content](/api-reference/native/events/get-session-artifact-content): Streams an artifact this session owns; any other artifact is 404. - [Get artifact](/api-reference/native/events/get-artifact) - [Get artifact content](/api-reference/native/events/get-artifact-content) - [List the authenticated user's personal access tokens](/api-reference/native/users-and-api-keys/list-the-authenticated-users-personal-access-tokens): Items are ordered by created_at descending, then id descending. - [Create personal access token](/api-reference/native/users-and-api-keys/create-personal-access-token) - [Revoke a personal access token](/api-reference/native/users-and-api-keys/revoke-a-personal-access-token) - [Get the authenticated user and their organizations](/api-reference/native/users-and-api-keys/get-the-authenticated-user-and-their-organizations) - [Delete the authenticated user's account](/api-reference/native/users-and-api-keys/delete-the-authenticated-users-account): Deletes the account, revokes all personal access tokens and browser sessions, removes all organization and project memberships, and releases the account's sign-in identity (emails, linked auth identities, and password credentials) so the same email can register a new account. Personal secrets and skills owned by the user are deleted with the account. Deletion is blocked while the user is the last owner of any organization (add another owner or delete the organization first), while a personal skill is referenced by an active agent's configuration, or while a personal secret is referenced by a model provider config, machine pool, or integration. Organization and project resources are unaffected, and agents, machines, and other records the user created are kept with their attribution. - [List pending invitations](/api-reference/native/users-and-api-keys/list-pending-invitations): Items are ordered by created_at ascending, then id ascending. - [Accept invitation](/api-reference/native/users-and-api-keys/accept-invitation) - [Decline invitation](/api-reference/native/users-and-api-keys/decline-invitation) - [List org API keys](/api-reference/native/users-and-api-keys/list-org-api-keys): Items are ordered by created_at descending, then id descending. Revoked keys are included. - [Create org API key](/api-reference/native/users-and-api-keys/create-org-api-key): Mints an org API key. The plaintext token is returned once and never stored. - [Get an org API key](/api-reference/native/users-and-api-keys/get-an-org-api-key) - [Update an org API key](/api-reference/native/users-and-api-keys/update-an-org-api-key): Renames the key and/or changes its org role. Revoked keys cannot be updated. - [Revoke an org API key](/api-reference/native/users-and-api-keys/revoke-an-org-api-key): Terminally revokes the key and removes its org and project roles. Idempotent. - [List an org API key's explicit project role grants](/api-reference/native/users-and-api-keys/list-an-org-api-keys-explicit-project-role-grants): Lists the key's explicit per-project role grants. Keys with the admin org role implicitly have admin access to every project and will not appear here for those projects. - [Set an org API key's role on a project](/api-reference/native/users-and-api-keys/set-an-org-api-keys-role-on-a-project): Creates or updates the key's explicit role grant on the project. - [Remove an org API key's project role grant](/api-reference/native/users-and-api-keys/remove-an-org-api-keys-project-role-grant) - [List the authenticated principal's organizations](/api-reference/native/organizations-and-projects/list-the-authenticated-principals-organizations): Users get every organization they belong to; org API keys get the organization that issued them. Items are ordered by organization name ascending. - [Create organization](/api-reference/native/organizations-and-projects/create-organization): Creates the organization and its local default resources atomically. An idempotency key determines the proposed organization ID; replaying it returns the existing organization. Without a key, each request is a fresh attempt. Optional default-provider provisioning begins after commit and retries asynchronously without failing organization creation. - [Delete organization](/api-reference/native/organizations-and-projects/delete-organization): Deletes the organization and everything in it: projects, memberships, pending invitations, profiles, integrations, machine pools and machines, model provider configs and configured models, and all skills. Agents are archived and their runtimes and queued work are stopped. Secrets are permanently deleted once machine teardown no longer needs them. Deletion fails if project agent teardown cannot complete. Only organization owners can delete an organization. - [Get org usage](/api-reference/native/organizations-and-projects/get-org-usage): Tallies model token usage and provider-reported cost across every project the caller can read in the organization, broken down by configured model. Optionally limits the tally to a time window or to a subset of those projects; including a project the caller can't read is not found. - [Get usage timeseries](/api-reference/native/organizations-and-projects/get-usage-timeseries): Buckets model usage over time for one metric, optionally broken down by configured model or agent profile. Covers every project the caller can read in the organization; `project_ids` and `agent_profile_ids` narrow that scope. Buckets are calendar days, weeks (starting Monday), or months in `timezone`. - [List visible projects](/api-reference/native/organizations-and-projects/list-visible-projects): Lists the projects the caller can access in the organization, newest first, with the caller's permissions on each. - [Create project](/api-reference/native/organizations-and-projects/create-project): Creates a project, makes the caller its admin, and returns it. The new project has no grants to organization models, machines, skills, or secrets. - [Delete project](/api-reference/native/organizations-and-projects/delete-project): Deletes the project, its memberships, profiles and profile versions, integrations and their interaction targets, project-owned skills and revisions, and grants owned by or targeting the project. Project-owned secrets are permanently deleted with their versions and grants. The project's agents are archived and their runtimes and queued work are stopped. Machine, machine-pool, and model grants are removed without deleting the shared machine, pool, or model. Deletion fails if agent teardown cannot complete. - [Get project usage](/api-reference/native/organizations-and-projects/get-project-usage): Tallies model token usage and provider-reported cost across every agent in the project, including subagents, broken down by configured model. Optionally limits the tally to a time window. - [List organization members](/api-reference/native/organizations-and-projects/list-organization-members): List organization members with server-side display-name filtering, sorting, and cursor pagination. - [Remove org member](/api-reference/native/organizations-and-projects/remove-org-member): Removes the user's organization membership and all project memberships in the organization. The member's personal secrets and skills in the organization are deleted with the membership. Removal is blocked when the user is the organization's last owner, while a personal skill is referenced by an active agent's configuration, or while a personal secret is referenced by a model provider config, machine pool, or integration. - [Update org member role](/api-reference/native/organizations-and-projects/update-org-member-role) - [List a member's explicit project role grants](/api-reference/native/organizations-and-projects/list-a-members-explicit-project-role-grants): Lists the member's explicit per-project role grants. Org owners and admins implicitly have admin access to every project and will not appear here for those projects. - [Set a member's role on a project](/api-reference/native/organizations-and-projects/set-a-members-role-on-a-project): Creates or updates the member's explicit role grant on the project. - [Remove a member's project role grant](/api-reference/native/organizations-and-projects/remove-a-members-project-role-grant): Removes only the member's explicit role grant for this project. No other memberships, grants, or resources are deleted, and there are no dependency blockers. - [List org invitations](/api-reference/native/organizations-and-projects/list-org-invitations): Every listed invitation is pending: accepting, declining, revoking, or organization deletion removes the invitation. Items are ordered by created_at descending, then id descending. - [Create org invitation](/api-reference/native/organizations-and-projects/create-org-invitation) - [Delete org invitation](/api-reference/native/organizations-and-projects/delete-org-invitation): Deletes the pending invitation so it can no longer be accepted. - [List agents across projects](/api-reference/native/agents/list-agents-across-projects): Lists agents in every project of the organization where the caller can read agents. Each agent carries its project_id. Items are ordered by created_at descending, then id descending. - [List agents](/api-reference/native/agents/list-agents): Lists the project's agents with their current activity, newest first by default. Archived agents and subagents are excluded unless requested. - [Create agent](/api-reference/native/agents/create-agent): Launch from a pinned config, optionally adding agent-local integration tools, subscriptions and interaction handlers and admitting an attributed initial text input in the same transaction. Adding integration capabilities requires project management permission; launching an existing config requires agent operate permission. Reusing an idempotency key returns the current agent even if the retry body differs. The retry body is not applied and integration references are not resolved again. - [Get agent](/api-reference/native/agents/get-agent): Returns one agent's state, model, profile, current config ID, activity (running, waiting_on_interaction, idle, or archived), attached machines, and MCP connection states. The conversation isn't included. - [Get agent usage](/api-reference/native/agents/get-agent-usage): Tallies this agent's model token usage and provider-reported cost, broken down by configured model. Optionally limits the tally to a time window. - [Archive agent](/api-reference/native/agents/archive-agent): Archives the agent: requests cancellation of its active runtime, cancels queued inputs and affected processes, removes its pending wakeup, releases explicit machine bindings, deletes pooled machines created for the agent, and deletes cron triggers targeting the agent. Every session of the agent that is still active, including the default session, is archived in the same transaction and reports `archived` with an `archived_at`. The agent, its sessions and its full event history stay readable by id; archived agents and sessions leave active listings. The agent's profile and configuration are retained, as are explicitly attached BYO machines. Archiving an already-archived agent is a no-op that returns the agent unchanged. - [Update agent config](/api-reference/native/agents/update-agent-config): Replaces an active agent's config without restarting its conversation and returns the new agent_config. Model, instruction, and tool changes apply at the agent's next model call; machine changes apply immediately, stopping processes on removed machines and deleting the agent's machines from removed pools. Send the complete config, not a patch. - [Read the session model override metadata](/api-reference/native/agents/read-the-session-model-override-metadata): Returns override metadata only. The API key is never returned. - [Create or replace the session model override](/api-reference/native/agents/create-or-replace-the-session-model-override): Materializes an ephemeral tenant secret, provider config, configured model and project grant for this agent's next model call. The agent config revision is never modified. The response contains only override metadata and a fingerprint/key hint; the API key is write-only and encrypted at rest. - [Revoke the session model override](/api-reference/native/agents/revoke-the-session-model-override): The next turn uses the agent configuration. Ephemeral rows are cleaned up later. - [Modify the session model override](/api-reference/native/agents/modify-the-session-model-override): Replaces the active override with the merged result. A new API key replaces the previous encrypted secret; the previous ephemeral rows are cleaned up after no turn can reference them. - [Read the agent executor binding](/api-reference/native/agents/read-the-agent-executor-binding): Returns the bound machine and the agent capability its executor last registered. - [Run the agent on an agent executor](/api-reference/native/agents/run-the-agent-on-an-agent-executor): Binds the agent to a machine whose executor runs a complete local agent (Executor Protocol capability agent). Session input then becomes turn.start / turn.input on that executor, session cancel turn.cancel and session archive session.close; the BMA harness does not run the agent's sessions. Input queues while the executor is offline. - [Read a session model override metadata](/api-reference/native/agents/read-a-session-model-override-metadata): Returns override metadata only. The API key is never returned. - [Create or replace a session model override](/api-reference/native/agents/create-or-replace-a-session-model-override): Materializes an ephemeral tenant secret, provider config, configured model and project grant for this session's next model call. The pinned session config revision is never modified. The response contains only override metadata and a fingerprint/key hint; the API key is write-only and encrypted at rest. - [Revoke a session model override](/api-reference/native/agents/revoke-a-session-model-override): The next turn uses the session config. Ephemeral rows are cleaned up later. - [Modify a session model override](/api-reference/native/agents/modify-a-session-model-override): Replaces the active override with the merged result. A new API key replaces the previous encrypted secret; the previous ephemeral rows are cleaned up after no turn can reference them. - [Create agent input](/api-reference/native/agents/create-agent-input): Sends a message to an agent and returns the stored input. Queued messages (the default) wait until the agent is ready for new work; steering messages reach it at its next model call. - [List agent sessions](/api-reference/native/agents/list-agent-sessions): Lists the agent's conversation sessions, newest first. The default session is the legacy /api/v1 target. - [Create agent session](/api-reference/native/agents/create-agent-session): Creates an independent conversation session for the agent. Sessions share agent-level memory stores. - [Get agent session](/api-reference/native/agents/get-agent-session) - [Update agent session](/api-reference/native/agents/update-agent-session) - [Archive agent session](/api-reference/native/agents/archive-agent-session) - [Cancel agent session](/api-reference/native/agents/cancel-agent-session): Stops the session's current turn and nothing else: cancels the turn's unfinished tool calls and open interactions, stops processes whose run_command hasn't returned yet, discards the session's pending steering messages and asks the session's runtime to stop. The agent's other sessions keep running. The session stays active, keeps its queued messages and its context, and its next message continues the conversation in the same session. Returns affected false and changes nothing when the session has no turn in progress, so repeated requests are safe. With per-session concurrent claims disabled, the agent runs one turn at a time and this request stops that turn only when it belongs to this session; otherwise it returns affected false. An archived session, or any session of an archived agent, cannot be canceled: the request fails with `state_transition_conflict`, matching input to it. - [Get an agent session by id](/api-reference/native/agents/get-an-agent-session-by-id): Resolves one agent session by its id inside the project, without naming its agent. The session reports the agent that executes it. A session in another project is not found. - [List tool calls](/api-reference/native/agents/list-tool-calls): Items are ordered by created_at ascending, then id ascending. - [Submit a result for a ready custom tool call](/api-reference/native/agents/submit-a-result-for-a-ready-custom-tool-call): Only ready custom tool calls accept externally supplied results. The first accepted result completes the call. Any later submission, or a result for a non-custom tool call, returns 409. - [Cancel agent](/api-reference/native/agents/cancel-agent): Stops the agent's current turn: cancels its unfinished tool calls and open interactions, stops processes whose run_command hasn't returned yet, and discards pending steering messages. The agent stays active and keeps its queued messages, and processes whose run_command already returned keep running. Returns affected false and changes nothing when no turn is in progress. With per-session concurrent claims the current turn of every session is stopped; use cancelAgentSession to stop one session only. An archived agent cannot be canceled: the request fails with `state_transition_conflict`, matching input to an archived session. - [List waiting backlog inputs](/api-reference/native/agents/list-waiting-backlog-inputs): Steering inputs are listed first, followed by queued inputs. Each group is ordered by input rank, queued_at ascending, then id ascending. - [Cancel queued backlog input](/api-reference/native/agents/cancel-queued-backlog-input) - [Move queued backlog input](/api-reference/native/agents/move-queued-backlog-input) - [Promote queued input to steering](/api-reference/native/agents/promote-queued-input-to-steering) - [Demote steering input to queued](/api-reference/native/agents/demote-steering-input-to-queued) - [List agent profiles across projects](/api-reference/native/configs-and-profiles/list-agent-profiles-across-projects): Lists agent profiles in every project of the organization the caller can read. Each profile carries its project_id. Items are ordered by created_at descending, then id descending. - [Resolve agent config tools](/api-reference/native/configs-and-profiles/resolve-agent-config-tools): Returns configured built-in and custom tools plus missing machine, skill, subagent, and retrieval defaults, including disabled entries. Accepts YAML/JSON source. Source previews validate tool-related fields only; they do not validate whether the config can be saved or launched. Does not resolve contextual integration tools, discover MCP tools, or change any configuration. - [Create agent config](/api-reference/native/configs-and-profiles/create-agent-config): Compiles and saves an immutable agent config (instruction, model, tools, machine_sources, and more) from YAML or JSON and returns it. Sending the same source again returns the existing config, as long as its names still resolve to the same resources. - [Get tool catalog](/api-reference/native/configs-and-profiles/get-tool-catalog): Lists the built-in tools agent configs can use, with each tool's description and permission settings, plus the permission modes for custom and MCP tools. - [Search the MCP server registry](/api-reference/native/configs-and-profiles/search-the-mcp-server-registry): Search the API's snapshot of the public MCP registry. The snapshot only holds active servers that publish a `streamable-http` remote. Results are ranked by relevance when `q` is set, otherwise ordered by name. - [List an MCP server's tools](/api-reference/native/configs-and-profiles/list-an-mcp-servers-tools): Connects to a remote MCP server over streamable HTTP, negotiates the protocol version (stateless `server/discover` first, falling back to the `initialize` handshake for session-based servers), and returns the server's `tools/list` result. The request is not stored; use it to preview which tools a server exposes before referencing it from an agent config. Authentication mirrors the agent config `mcp_servers..auth` shape and resolves secrets available to the project. When the server does not speak MCP, the API responds 422 without an `auth` hint. When the server or its authorization server does not respond or fails, including a malformed MCP response or a JSON-RPC internal error from the server, the API responds 424; retrying may succeed once the server recovers. When the authorization server rejects the configured OAuth secret, the API responds 422 with an `oauth` hint so the caller can log in again. When BMA times out reading or storing discovery state, the API responds 503. When the server rejects the connection with HTTP 401 or 403, the API probes the server's authorization requirements and responds 422 with an `auth` hint — `oauth` when the server advertises an OAuth authorization server, `bearer` when it expects a token but advertises no OAuth metadata. If that probe fails for a non-transient reason, the 422 carries no `auth` hint. - [Get agent config](/api-reference/native/configs-and-profiles/get-agent-config): Returns one agent config: its compiled definition with names resolved to IDs, and its source if it was saved with one. Configs BMA derives on its own, such as those for subagents and integration launches, have no source. - [Get generated agent config source](/api-reference/native/configs-and-profiles/get-generated-agent-config-source): Rebuilds a source from the config's compiled_definition, for configs saved without a source. - [List agent profiles](/api-reference/native/configs-and-profiles/list-agent-profiles): Lists the project's agent profiles, newest first by default, filterable by name. Items include a summary of each profile's current config, not its full compiled definition. - [Create agent profile](/api-reference/native/configs-and-profiles/create-agent-profile): Creates a named profile that points at an agent config and returns the profile with its current config. - [Get agent profile](/api-reference/native/configs-and-profiles/get-agent-profile): Returns one agent profile with its current config, current_config_id, and current_generation. - [Delete agent profile](/api-reference/native/configs-and-profiles/delete-agent-profile): Deletes the profile, all of its profile versions, and any cron triggers targeting the profile. Agents launched from the profile are retained and keep running: each agent holds an immutable snapshot of the configuration it was launched with, so its reference to the profile becomes historical provenance only. Integration settings may retain the public profile ID; future launches fail as unavailable until those settings reference an available profile. - [Rename agent profile](/api-reference/native/configs-and-profiles/rename-agent-profile): Renames an agent profile without changing its config. Agents and cron triggers reference the profile by ID and keep working, but configs that name the profile under subagents must use the new name the next time they're compiled. - [Get agent profile usage](/api-reference/native/configs-and-profiles/get-agent-profile-usage): Tallies model token usage and provider-reported cost across the top-level agents launched from this profile, broken down by configured model. Usage from subagents those agents spawned is included only when `include_subagents` is true. Optionally limits the tally to a time window. - [Update agent profile](/api-reference/native/configs-and-profiles/update-agent-profile): Points a profile at a different agent config. Existing agents keep their current config; agents launched from the profile afterward use the new one. Fails with 409 unless expected_current_config_id matches the profile's current config. - [List cron triggers](/api-reference/native/configs-and-profiles/list-cron-triggers): Lists the project's cron triggers, newest first by default, filterable by name, agent, profile, or integration. Each item includes its schedule and next_fire_at. - [Create cron trigger](/api-reference/native/configs-and-profiles/create-cron-trigger): Creates a cron trigger that fires on a schedule. A trigger targeting an agent profile launches a new agent from the profile's current config on each firing; a trigger targeting an agent sends an input to that agent. Missed firings are coalesced, matching standard cron behavior: if one or more scheduled times pass while firing is delayed, the trigger fires once for the oldest missed time and then resumes its schedule from the current time, without retroactively firing for the other missed times. - [Get cron trigger](/api-reference/native/configs-and-profiles/get-cron-trigger): Returns one cron trigger: its target, schedule, timezone, message template, enabled flag, and firing state (last_fired_at, next_fire_at, and any failure since the last successful firing). - [Delete cron trigger](/api-reference/native/configs-and-profiles/delete-cron-trigger): Deletes a cron trigger so it never fires again; there is no undo. Agents it already launched keep running. - [Update cron trigger](/api-reference/native/configs-and-profiles/update-cron-trigger): Updates the schedule, message template, or enabled state. The target is immutable; delete the trigger and create a new one to retarget. - [List skills visible through ownership authority](/api-reference/native/skills/list-skills-visible-through-ownership-authority): Items are ordered by created_at descending, then id descending. Without an owner filter, returns the deduplicated union of organization skills the caller may list, project skills the caller may list, and the caller's own user skills. Grants are managed separately and do not change ownership. - [Create skill](/api-reference/native/skills/create-skill): Uploads a skill archive. If a skill with the archive's name already exists for the requested owner, the upload becomes the skill's next revision. The owner is immutable after creation. - [Get skill through ownership authority](/api-reference/native/skills/get-skill-through-ownership-authority): Returns one skill with its latest SKILL.md text and file listing. - [Update skill by uploading a new revision](/api-reference/native/skills/update-skill-by-uploading-a-new-revision): Creates the skill's next revision from either a replacement archive or replacement SKILL.md content (which keeps every other file from the current revision). The SKILL.md frontmatter `name` must match the skill's existing name. - [Delete skill](/api-reference/native/skills/delete-skill): Deletes the skill together with all of its revisions and project grants; uploaded archive content is destroyed. No other resources are deleted. Deletion is blocked while an active agent's configuration references the skill. - [List skill grants](/api-reference/native/skills/list-skill-grants): Lists the projects a skill is shared with, one grant per project, most recently shared first by default. - [Create skill grant](/api-reference/native/skills/create-skill-grant): Shares a skill with another project so its agent configs can attach it, and returns the grant; ownership doesn't change. - [Delete skill grant](/api-reference/native/skills/delete-skill-grant): Deletes only this project grant. The skill, its revisions, the target project, and other grants are retained, and there are no dependency blockers. - [List skills available to project](/api-reference/native/skills/list-skills-available-to-project): Includes directly owned project skills and granted skills, ordered by created_at descending, then id descending. - [List memory stores across projects](/api-reference/native/memory-stores/list-memory-stores-across-projects): Lists memory stores in every project of the organization the caller can read. Each store carries its project_id. Items are ordered by name, then id. - [List memory stores](/api-reference/native/memory-stores/list-memory-stores) - [Create memory store](/api-reference/native/memory-stores/create-memory-store) - [Get memory store](/api-reference/native/memory-stores/get-memory-store) - [Delete memory store](/api-reference/native/memory-stores/delete-memory-store) - [Update memory store](/api-reference/native/memory-stores/update-memory-store) - [List memory files](/api-reference/native/memory-stores/list-memory-files): List a directory's immediate children in name order. Omit path to list the store root. - [Download memory file](/api-reference/native/memory-stores/download-memory-file) - [Write memory file](/api-reference/native/memory-stores/write-memory-file) - [Delete memory file](/api-reference/native/memory-stores/delete-memory-file) - [List secrets visible through ownership authority](/api-reference/native/secrets/list-secrets-visible-through-ownership-authority): Items are ordered by created_at descending, then id descending. Without an owner filter, returns the deduplicated union of organization secrets the caller may list, project secrets the caller may list, and the caller's own user secrets. - [Create secret](/api-reference/native/secrets/create-secret): Creates an encrypted secret holding one credential and returns its metadata; the value is never returned. owner sets whether the organization, a project, or the caller owns it. - [Start MCP OAuth for a new secret](/api-reference/native/secrets/start-mcp-oauth-for-a-new-secret) - [Get secret through ownership authority](/api-reference/native/secrets/get-secret-through-ownership-authority): Returns a secret's owner, kind, name, and current version; the secret value is never returned. - [Delete secret](/api-reference/native/secrets/delete-secret): Deletes the secret and permanently destroys all of its versions and project grants; the ciphertext cannot be recovered. Deletion is blocked while the secret is the credential of a model provider config, machine pool, or integration. - [Update secret metadata](/api-reference/native/secrets/update-secret-metadata): Renames a secret or replaces its metadata, and returns the updated secret without its value. The value, kind, and owner can't be changed here. References use the secret ID, so renaming doesn't break them. - [Create secret version](/api-reference/native/secrets/create-secret-version) - [List secret grants](/api-reference/native/secrets/list-secret-grants): Lists the projects a secret is shared with, one grant per project, most recently shared first by default. - [Create secret grant](/api-reference/native/secrets/create-secret-grant): Shares a secret with another project so that project's resources can use it, and returns the grant; ownership doesn't change. - [Delete secret grant](/api-reference/native/secrets/delete-secret-grant): Deletes only this project grant. The secret, its versions, the target project, and other grants are retained, and there are no dependency blockers. - [List secrets available to project](/api-reference/native/secrets/list-secrets-available-to-project): Includes directly owned and granted secrets, ordered by created_at descending, then id descending. - [Get secret available to project](/api-reference/native/secrets/get-secret-available-to-project) - [Connect an integration through OAuth](/api-reference/native/integrations/connect-an-integration-through-oauth): Starts OAuth for this integration (currently Slack). The callback pins the integration and setup revision, records verified credentials, and returns integration_oauth=success and integration_id to the supplied local return_to route. It requires a browser session for the initiating user and current project management access. Replayed, stale, or deleted-integration callbacks are rejected. - [Create a Slack provider app and connect it to an BMA integration](/api-reference/native/integrations/create-a-slack-provider-app-and-connect-it-to-an-bma-integration): Creates a provider-side Slack app using the supplied configuration token, name and optional icon, then starts OAuth for this saved BMA integration. The callback activates this integration only. It never creates another BMA integration or changes launcher settings. - [Start registration of a customer-owned GitHub App](/api-reference/native/integrations/start-registration-of-a-customer-owned-github-app): Starts guided registration on github.com for a never-connected GitHub integration. Requires a browser session and project management access. Submit manifest as a JSON-encoded form field to registration_url. The callback saves a project credential secret and redirects to the canonical integration page with github_setup=credentials_saved and credential_secret_id (a public secret ID). It does not connect an installation or change launcher settings. - [Inspect installations of a customer-owned GitHub App](/api-reference/native/integrations/inspect-installations-of-a-customer-owned-github-app): Verifies the supplied project-available GitHub credential secret using App authentication and returns one bounded page of installations. Requires a browser session and project management access. Inspection does not connect or change this integration. Explicit confirmation uses ConfigureIntegration with the returned provider_app_id, selected installation ID, credential secret ID and current expected setup revision. A saved secret remains usable while organization approval is pending; there is no expiring continuation. Guided links support github.com only. - [List integrations across projects](/api-reference/native/integrations/list-integrations-across-projects): Lists integrations in every project of the organization the caller can read. Each integration carries its project_id. Items are ordered by created_at descending, then id descending. - [List project integrations](/api-reference/native/integrations/list-project-integrations) - [Create an integration and optional launcher](/api-reference/native/integrations/create-an-integration-and-optional-launcher) - [Get project integration](/api-reference/native/integrations/get-project-integration) - [Update integration settings](/api-reference/native/integrations/update-integration-settings): Replaces integration-owned settings while preserving credentials. The request contains only settings; name and integration_kind are immutable and accepted only on create. Preserve integration-level fields when editing the launcher. Settings follow capabilities.settings.input_schema from the integration catalog. - [Delete integration setup and revoke its capabilities](/api-reference/native/integrations/delete-integration-setup-and-revoke-its-capabilities): Deletes the integration setup and its cron schedules, revokes its capabilities, and releases its credential reference. Existing agents, agent history, and provider messages are preserved. - [List integration conversation subscriptions](/api-reference/native/integrations/list-integration-conversation-subscriptions): Requires project read permission. Disconnected integrations retain their subscriptions and support listing. - [Attach an agent to an integration conversation](/api-reference/native/integrations/attach-an-agent-to-an-integration-conversation): Requires project management permission. Repeating an active attachment returns the same subscription. Subscriptions do not change the agent config or grant sending tools. - [Stop forwarding an integration conversation to an agent](/api-reference/native/integrations/stop-forwarding-an-integration-conversation-to-an-agent): Requires project management permission. Missing subscriptions are a no-op within an existing integration. Disconnected integrations support deletion. Stops future incoming forwarding for this subscription. The agent, sending tools, interaction handlers, and history remain available. Attaching the conversation again through the API resumes forwarding with a new subscription ID. - [Verify and configure integration credentials](/api-reference/native/integrations/verify-and-configure-integration-credentials): Requires a user principal with project management permission. Slack credentials are configured through OAuth. A stale expected_setup_revision or a credential changed during verification returns 409; reload the integration and retry setup. Setup preserves integration settings; verified provider identity scopes incoming events. - [Disconnect this integration without deleting its configuration](/api-reference/native/integrations/disconnect-this-integration-without-deleting-its-configuration) - [List repositories a GitHub integration can access](/api-reference/native/integrations/list-repositories-a-github-integration-can-access): Returns one page of up to 100 repositories the connected installation can access, for use in git_credentials.repository_ids. Requires project management access. - [List installed integration implementations and their capabilities](/api-reference/native/integrations/list-installed-integration-implementations-and-their-capabilities) - [List an agent's pooled machines](/api-reference/native/machines/list-an-agents-pooled-machines): Lists the pooled machines attached to an agent, in binding creation order, with each machine's kind. A persistent machine is kept for a person (for example a purchased BMA computer) and is never deleted for being idle; an ephemeral machine serves turns and is deleted after its idle window. - [Create a persistent machine for an agent](/api-reference/native/machines/create-a-persistent-machine-for-an-agent): Creates one machine for the agent from the requested sold template and disables idle deletion, so the machine stays until it is deleted. The machine is attached to the agent and consumes the project and organization pool-machine quotas like any other pooled machine. The machine pool defaults to the agent's only pool source. - [Delete an agent's persistent machine](/api-reference/native/machines/delete-an-agents-persistent-machine): Deletes one persistent machine attached to the agent through the same pool deletion used for machines that are no longer wanted: the provider machine is deleted, the agent binding is released and the pool quota is freed. Only a persistent machine of this agent can be deleted; an ephemeral machine, or a machine attached to another agent, is refused. The machine is marked for deletion before the response and the provider deletion is retried by maintenance until it succeeds. The call is idempotent: a machine that is already deleting or gone returns 204. - [List visible project machines](/api-reference/native/machines/list-visible-project-machines): Items are ordered by machine created_at descending, then machine id descending. - [Get machine interaction capabilities](/api-reference/native/machines/get-machine-interaction-capabilities): Reports whether the machine can offer a PTY terminal or a desktop and what the caller may do. Seeing a machine never implies shell or desktop access. - [Resume a paused or archived machine](/api-reference/native/machines/resume-a-paused-or-archived-machine): Resumes a paused machine, or restores an archived one, and waits until its daemon is online. Commands, terminal sessions and desktop sessions resume the machine on their own; this endpoint lets a client warm it up ahead of use. Concurrent calls share one resume. Returns 503 when the machine does not come online before the resume timeout; the machine and its disk are kept and a later call retries. - [List a machine's workspace backups](/api-reference/native/machines/list-a-machines-workspace-backups): Workspace backups keep a persistent pool machine's user files (by default /home/user) in BMA storage, independent of the provider host. BMA takes one before the machine pauses and periodically while it runs when files changed, and keeps the newest few. Items are ordered by created_at descending. - [Back up a machine's workspace now](/api-reference/native/machines/back-up-a-machines-workspace-now): Starts a backup of an online pool machine. The returned backup is uploading; list the backups to see it become ready or failed. Backups count against the project's machine backup storage limit. - [Recreate a machine from a workspace backup](/api-reference/native/machines/recreate-a-machine-from-a-workspace-backup): Replaces the machine with a new one created from its template and restores a backup (the newest ready one unless backup_id is given) before the machine comes online again. Only files under the backed-up paths are restored; system-level changes and running processes are not kept. The machine's lifecycle_reason_code reports restoring_from_backup, then restored_from_backup or backup_restore_failed. BMA does the same on its own when the provider loses a machine that has a backup. - [List project machine grants](/api-reference/native/machines/list-project-machine-grants): Lists explicit machine grants that can be deleted directly. Pool-derived machine access is managed through project machine pool grants. - [Create project machine grant](/api-reference/native/machines/create-project-machine-grant): Lets a project's agent configs use one BYO machine by name and returns the grant with the machine's record. Pooled machines can't be granted this way and return 404. - [Delete project machine grant](/api-reference/native/machines/delete-project-machine-grant): Removes the project's access to the machine. Processes that depended on the grant are stopped. The machine itself is retained, and there are no dependency blockers. - [List visible machines](/api-reference/native/machines/list-visible-machines): Lists the machines the caller can see, both BYO and pooled, newest first by default, with each one's connection state. Items are summaries without execution defaults or metadata. - [Create machine](/api-reference/native/machines/create-machine) - [Connect a BYO machine](/api-reference/native/machines/connect-a-byo-machine): Registers a machine you run yourself and returns its daemon token for installing bmad on it; the token is shown only in this response. The machine stays offline until its daemon connects. project_ids grants it to those projects in the same call, and their agent configs reference it by display_name. - [Get machine](/api-reference/native/machines/get-machine): Returns one active machine's full record: connection state, execution defaults (secret IDs only, never values), metadata, and the latest failure report. Machines in other lifecycle states, such as pool machines still provisioning, aren't returned. - [Delete machine](/api-reference/native/machines/delete-machine): Deletes a BYO machine, ends its active daemon runtimes and work, revokes its daemon tokens and project grants, and releases agent bindings. Pooled machines are managed through their machine pool and cannot be deleted through this route. There are no dependency blockers for a BYO machine. - [Update machine execution defaults](/api-reference/native/machines/update-machine-execution-defaults): Updates a machine's execution defaults: working directory, environment variables, and secret environment variables. env and secret_env replace the whole map, and changes apply to processes started afterward. - [List byo machine daemon tokens](/api-reference/native/machines/list-byo-machine-daemon-tokens): Items are ordered by created_at descending, then id descending. - [Create byo machine daemon token](/api-reference/native/machines/create-byo-machine-daemon-token) - [Revoke machine daemon token](/api-reference/native/machines/revoke-machine-daemon-token) - [List agent interactions](/api-reference/native/interactions/list-agent-interactions): Lists an agent's permission prompts and ask_question questions, oldest first, with each one's form and answers. state filters by open, resolved, or canceled. - [Resolve agent interaction](/api-reference/native/interactions/resolve-agent-interaction): Answers an open permission prompt or question so the paused agent resumes, and returns the resolved interaction. Send one answer per question with zero-based option_indices; permission prompts use 0 for Allow and 1 for Deny. - [List files](/api-reference/native/files/list-files): Lists the project's files, newest first. scope_id keeps the files scoped to one session (the files it produced); each metadata filter (key:value) must match a label of the file. Session instances created by mounting a file are never listed; read them through the session's resources. - [Upload a file](/api-reference/native/files/upload-a-file): Streams the request body (1 byte to 1 GiB) into object storage as a project file. A replay with the same Idempotency-Key, filename, content and labels returns the original file with 200; a different request under the key is 409. The project's files may not exceed its storage limit (409). - [Get file metadata](/api-reference/native/files/get-file-metadata) - [Delete a file](/api-reference/native/files/delete-a-file): Deletes the file: it is no longer readable, listable or mountable. Sessions that mounted it keep reading their own session instance until the resource is removed or the session is archived; the stored content is reclaimed after the last of them. Deleting a session instance removes its session resource. Artifacts the file was promoted from are kept. - [Download a file](/api-reference/native/files/download-a-file): Streams the file content with its length and SHA-256 digest. - [List session file resources](/api-reference/native/files/list-session-file-resources): Lists the files mounted into this session, ordered by created_at. - [Mount a file into a session](/api-reference/native/files/mount-a-file-into-a-session): Mounts a project file, read-only, at mount_path below /mnt/session/uploads (default /mnt/session/uploads/). The mount creates a new file_id, a session instance scoped to this session that references the same stored content: no bytes are copied, the instance does not count against the storage limit, and it stays readable after the original file is deleted. The session's storage tools read it at mount_path. Mounting the same file at the same path again returns the existing resource; another file at that path is 409. Only project files can be mounted, not session instances (404). A session holds at most 500 files. - [Unmount a file from a session](/api-reference/native/files/unmount-a-file-from-a-session): Removes the mount and its session instance; the original file, if it still exists, is kept. - [Promote a session artifact to a file](/api-reference/native/files/promote-a-session-artifact-to-a-file): Copies an artifact this session owns into a project file inside BMA, without the caller downloading it. The file is project-wide, or scoped to the session with scope "session" (listed by scope_id). The artifact is kept. An Idempotency-Key replay returns the original file with 200. - [Create a desktop session](/api-reference/native/desktops/create-a-desktop-session): Starts one desktop session for the machine. A caller without desktop control permission can only create a read-only session. A machine has at most one live desktop session per caller. - [Get a desktop session](/api-reference/native/desktops/get-a-desktop-session) - [Close a desktop session](/api-reference/native/desktops/close-a-desktop-session): Closing a session ends its bridge and revokes outstanding watch tickets. - [Get desktop control status](/api-reference/native/desktops/get-desktop-control-status) - [Acquire desktop control](/api-reference/native/desktops/acquire-desktop-control): Pauses the agent and takes the human-control lease. A concurrent holder returns 409 conflict. - [Renew desktop control](/api-reference/native/desktops/renew-desktop-control): Extends the current human-control lease. - [Release desktop control](/api-reference/native/desktops/release-desktop-control): Releases control. The agent stays paused until it re-observes the desktop. - [Hand control back](/api-reference/native/desktops/hand-control-back): Hands control back to the paused desktop. The agent stays paused until it re-observes. - [Capture the desktop](/api-reference/native/desktops/capture-the-desktop): Captures the current framebuffer. The image is returned base64-encoded in JSON. - [Send desktop input](/api-reference/native/desktops/send-desktop-input): Applies one human input action. The caller must hold control; the server rejects stale epochs, read-only sessions, and out-of-order sequences. - [Observe the desktop as the agent](/api-reference/native/desktops/observe-the-desktop-as-the-agent): Returns a real screenshot receipt and the generation that a later agent resume must present. - [Resume the agent after a takeover](/api-reference/native/desktops/resume-the-agent-after-a-takeover): Requires a generation obtained from an observation after the last control change. - [Submit an agent desktop action](/api-reference/native/desktops/submit-an-agent-desktop-action): Fences the action at the supplied generation and returns a pending action that must be confirmed after a fresh observation. - [Confirm a pending agent action](/api-reference/native/desktops/confirm-a-pending-agent-action) - [List terminal sessions](/api-reference/native/terminals/list-terminal-sessions) - [Create a terminal session](/api-reference/native/terminals/create-a-terminal-session): Creates a PTY-backed shell session. The PTY data plane is being wired to the machine daemon; until then this endpoint reports that terminal sessions are unavailable. - [Get a terminal session](/api-reference/native/terminals/get-a-terminal-session) - [Close a terminal session](/api-reference/native/terminals/close-a-terminal-session) - [Mint a terminal connection ticket](/api-reference/native/terminals/mint-a-terminal-connection-ticket): Mints a single-use, Origin-bound ticket for the terminal WebSocket. The ticket is returned once and is never placed in a URL. - [List project actors](/api-reference/native/actors/list-project-actors): Items are ordered by created_at ascending, then id ascending. - [Upsert an external actor](/api-reference/native/actors/upsert-an-external-actor): Upserts by (provider_tenant_id, provider_user_id). Omitted attributes keep their stored values; provided attributes are overwritten, including empty values. An unchanged actor is not rewritten. Actors written through this endpoint always have the external provider. - [Get a project actor](/api-reference/native/actors/get-a-project-actor) - [List model provider configs](/api-reference/native/models/list-model-provider-configs): List model provider configs with server-side filtering, sorting, and cursor pagination. - [Create model provider config](/api-reference/native/models/create-model-provider-config): Create a model provider config, validate the configured credential where the provider exposes a validation endpoint, then probe the provider's /models endpoint. The result is returned as model_catalog; a failed probe does not fail creation. - [Get model provider config](/api-reference/native/models/get-model-provider-config): Returns one model provider config's stored settings; secret values are never returned. The provider isn't contacted, so the response doesn't list its models. - [Update model provider config](/api-reference/native/models/update-model-provider-config): Updates a model provider config's connection settings, such as its credential and headers, and returns the updated config; omitted fields keep their values. The credential secret is checked to exist and match auth_kind, but the provider isn't contacted, so a credential the provider rejects isn't caught here. - [Delete model provider config](/api-reference/native/models/delete-model-provider-config): Deletes only the model provider config. Deletion is blocked while it has configured models. Cluster-managed provider configs cannot be deleted through this route. - [Get model catalog](/api-reference/native/models/get-model-catalog): Fetches the provider's live model catalog by validating the configured credential and probing the provider's /models endpoint. The call waits on the upstream provider, so it is slower than the other model provider config routes and can report failure as data. - [List configured models](/api-reference/native/models/list-configured-models): Lists the models configured under one model provider config, newest first, with each model's slug, token limits, and reasoning support. - [Create configured model](/api-reference/native/models/create-configured-model): Adds a provider model to this provider config under the name agent configs use as model.name, and returns it. The model slug isn't checked against the provider's catalog, and no project can use the model yet. - [Update configured model](/api-reference/native/models/update-configured-model): Updates a configured model's settings and returns the updated model; omitted fields keep their values. Agents already using the model pick up the change on their next model call. The update isn't checked against project grants or agent configs, so lowering a limit below their overrides or turning off tools or reasoning they rely on makes those agents' next model call fail. - [Delete configured model](/api-reference/native/models/delete-configured-model): Deletes only the configured model. Deletion is blocked while it has active project grants. Cluster-managed configured models cannot be deleted through this route. - [List project model grants](/api-reference/native/models/list-project-model-grants): Lists the configured models a project can use, most recently granted first by default, with each grant's overrides and the model's name and provider config. - [Create project model grant](/api-reference/native/models/create-project-model-grant): Lets a project's agent configs use a configured model and returns the new grant. Optional overrides can narrow the model for that project (lower token limits, tools or reasoning turned off, fewer reasoning efforts or modalities) and set its per-request defaults within those limits. - [Delete project model grant](/api-reference/native/models/delete-project-model-grant): Removes the project's access to the configured model. The grant is live policy: new launches can no longer select the model, and agents already using it lose access on their next model call. The model itself is retained, and there are no dependency blockers. - [Update project model grant](/api-reference/native/models/update-project-model-grant): Updates the project's overrides for the configured model. Omitted fields keep their current values; null, or [] for supported_reasoning_efforts, input_modalities, and output_modalities, clears an override so the project inherits from the configured model. Agents already using the model apply the updated overrides on their next model call. Updates are validated against the configured model's current revision but not against agent configs, so narrowing below a config's model settings, such as its context_window_tokens or reasoning effort, makes that agent's next model call fail. - [List machine pools](/api-reference/native/machine-pools/list-machine-pools): List machine pools with server-side filtering, sorting, and cursor pagination. - [Create machine pool](/api-reference/native/machine-pools/create-machine-pool) - [Check machine pool connection](/api-reference/native/machine-pools/check-machine-pool-connection): Checks a tenant-managed pool's provider credential and provider config by making read-only requests to the provider. - [Get machine pool](/api-reference/native/machine-pools/get-machine-pool): Returns one machine pool's configuration and current usage: provider, default machine settings, CPU, memory, and machine-count limits, and idle deletion policy. - [Update machine pool](/api-reference/native/machine-pools/update-machine-pool): Tenant-managed pools support every request field. Cluster-managed pools only allow changes to default CPU and memory, environment and secret environment variables, provider-supported per-machine CPU and memory limits, and the idle deletion policy. Other cluster-managed changes are rejected with 409 Conflict. - [Delete machine pool](/api-reference/native/machine-pools/delete-machine-pool): Deletes the machine pool and its pooled machines, revokes generated machine grants and project machine-pool grants, and stops processes that depended on those grants. Deleting a cluster-managed machine pool is rejected with 409 Conflict; there are no other dependency blockers. - [List project machine pool grants](/api-reference/native/machine-pools/list-project-machine-pool-grants): Lists the machine pools a project can create machines from, one grant per pool, most recently granted first by default. - [Create project machine pool grant](/api-reference/native/machine-pools/create-project-machine-pool-grant): Lets a project create machines from a machine pool, optionally with its own defaults and usage caps within the pool's limits, and returns the grant. No machines are created by this call. - [Get project machine pool grant](/api-reference/native/machine-pools/get-project-machine-pool-grant): Returns one project's grant for a machine pool, with the defaults and limits it sets on top of the pool's own. Null fields set no override, so the pool's value applies. - [Delete project machine pool grant](/api-reference/native/machine-pools/delete-project-machine-pool-grant): Removes the project's access to the machine pool, revokes machine grants generated through it, and stops processes that depended on those grants. The pool itself is retained, and there are no dependency blockers. - [Update project machine pool grant](/api-reference/native/machine-pools/update-project-machine-pool-grant): Updates the grant's overrides and limits. Omitted fields keep their current values; null clears an override so the grant follows the machine pool again. Overlay objects and metadata are replaced whole when present. Existing machines keep their configuration; the updated defaults and limits apply to new launches. - [Mint a desktop watch ticket for a session (BMA extension)](/api-reference/extensions/mint-a-desktop-watch-ticket-for-a-session-bma-extension): Returns a short-lived, single-use, origin-bound watch ticket and the WebSocket endpoint of the desktop session attached to the session's machine. The browser connects to `url` with `subprotocol` and the ticket; the tenant API key never reaches the browser. - [List files uploaded into the session (BMA extension)](/api-reference/extensions/list-files-uploaded-into-the-session-bma-extension) - [Upload one file into the session (BMA extension)](/api-reference/extensions/upload-one-file-into-the-session-bma-extension): Stores one multipart file (at most 8 MiB, non-empty, bare filename) in the session's read_write memory store under the session's own directory. Create-only: an existing filename is a 409 `file_already_exists`. A session without a read_write memory store is a 409 `session_files_unavailable`. - [Download one session file (BMA extension)](/api-reference/extensions/download-one-session-file-bma-extension): Streams one file's bytes. `file_id` is the `id` returned by the upload or list operations. The response carries `Content-Type`, `Content-Length` and `Content-Disposition` when known, and `X-BMA-File-Digest` with the sha256 of the bytes. A file of another session, or an unknown id, is a 404 `not_found_error`. - [List the session's mounted file resources (BMA extension)](/api-reference/extensions/list-the-sessions-mounted-file-resources-bma-extension) - [Mount one project file into the session (BMA extension)](/api-reference/extensions/mount-one-project-file-into-the-session-bma-extension): Mounts an uploaded project file by reference. The Anthropic contract mounts files through `resources` on `POST /v1/sessions`; this extension mounts into an existing session. The file is read-only at `mount_path` (default `/mnt/session/uploads/`), and the response `file_id` is the session instance created for the mount, not the project file's own id. - [Unmount one file resource from the session (BMA extension)](/api-reference/extensions/unmount-one-file-resource-from-the-session-bma-extension): Removes the mount and releases the session instance. The project file itself is kept; other sessions that mounted it keep their instances. - [Self-hosting](/self-hosting/overview): What it takes to run BMA yourself today, and its current limits. - [Changelog](/changelog): What changed on the early-access deployment and in the SDKs. - [Roadmap](/roadmap): Planned work. Nothing here is available yet, and no dates are committed. - [简介](/zh/index): 在兼容 Claude Managed Agents 的 API 之后运行持久化 Agent，大脑、双手与会话彼此分离。 - [快速开始](/zh/quickstart): 大约五分钟内创建 agent、environment 和 session，发送消息并流式读取事件。 - [兼容性](/zh/compatibility): BMA 在 /v1 提供的 Claude Managed Agents API 子集：不支持什么、哪些行为不同、额外提供什么。 - [Agents](/zh/concepts/agents): agent 是一个可复用的定义：模型、指令、工具、MCP 服务器、skill 和机器来源。 - [Environments](/zh/concepts/environments): environment 描述会话的机器从哪里来。在 BMA 中它是一个机器池。 - [会话与事件](/zh/concepts/sessions-and-events): session 是一次持久对话。其中发生的一切都是可列出、可流式订阅、可恢复的事件。 - [机器与机器池](/zh/concepts/machines): 机器就是“双手”。它们按需启动、空闲时暂停，重建或恢复时不会丢失会话。 - [文件与输出](/zh/concepts/files-and-outputs): 文件只需上传一次即可挂载到会话中，并收集 agent 写出的内容。 - [Memory stores](/zh/concepts/memory): agent 在会话之间保留、或与其他 agent 共享的持久文件。 - [Skills](/zh/concepts/skills): 可复用的指令和文件，agent 只在需要时加载。 - [MCP 服务器](/zh/concepts/mcp): 接入 Model Context Protocol 服务器；凭据保存在 BMA 密钥中。 - [审批与提问](/zh/concepts/interactions): 交互会让 agent 暂停，直到有人批准工具调用或回答问题。 - [桌面与 computer use](/zh/concepts/desktop): 观看机器桌面、接管控制、挂接终端，无需暴露 VNC 密码或入站端口。 - [上下文压缩](/zh/concepts/context-compaction): BMA 如何让长任务保持在模型上下文窗口内，以及做不到时你会看到什么。 - [Executor Protocol](/zh/executor/overview): 大脑如何驱动双手：角色、连接、部署形态与能力状态。 - [Agent capability](/zh/executor/agent-capability): 让 BMA agent 的会话运行在你自己的 agent 循环上，通过 Executor Protocol 接入。 - [大脑路线图](/zh/executor/brains-roadmap): 现状：BMA 服务端 harness，以及通过 agent capability 接入的外部大脑。下一步：通用 ACP 大脑。 - [SDK 概览](/zh/sdks/overview): 该用哪个 SDK：官方 Anthropic SDK、bma-sdk 还是 bma-executor-sdk。 - [bma-sdk](/zh/sdks/bma-sdk): BMA 原生 REST API 及 Managed Agents API 上 BMA 扩展的类型化客户端，提供 Go、TypeScript 和 Python 版本。 - [bma-executor-sdk](/zh/sdks/bma-executor-sdk): 为 BMA Executor Protocol 构建 executor（手）、harness（大脑）和 agent executor，提供 Go、TypeScript 和 Python 版本。 - [API 参考](/zh/api-reference/introduction): 原生 REST API 与 Managed Agents 扩展：base URL、认证、错误与分页。 - [List event webhooks for one scope](/zh/api-reference/native/events/list-event-webhooks-for-one-scope): Returns the webhooks directly attached to the requested scope, not inherited matches. - [Create an event webhook](/zh/api-reference/native/events/create-an-event-webhook): Subscribes to future events from agents matching the scope. Each scope can have only one active webhook per URL; duplicates return 409. Matching scopes are additive. Requires project management permission. - [Delete an event webhook](/zh/api-reference/native/events/delete-an-event-webhook): Deletes the webhook and stops new deliveries and pending attempts. Requests already in flight may finish. - [Update event webhook settings](/zh/api-reference/native/events/update-event-webhook-settings): Updates a webhook's URL, event filters, and signing settings. The scope cannot change. Omitted fields stay unchanged; set signing_secret_id to null to remove signing. Event filters affect newly queued deliveries; URL and signing changes also apply to pending attempts. - [List turns](/zh/api-reference/native/events/list-turns): Returns turns newest first. Use the returned next_before_turn_sequence as before_turn_sequence to fetch older turns. - [List turn events](/zh/api-reference/native/events/list-turn-events): Returns one older event page for a turn, ordered chronologically within the page. Use the returned next_before_sequence as before_sequence to fetch older events. - [List events](/zh/api-reference/native/events/list-events): Returns one page of agent events, chronological within the page. Forward pagination (after_sequence) walks from a known boundary toward the present using next_after_sequence. Backward pagination (before_sequence) starts at the latest events and walks toward the beginning using next_before_sequence; passing before_sequence takes precedence over after_sequence. - [Stream events](/zh/api-reference/native/events/stream-events) - [List session artifacts](/zh/api-reference/native/events/list-session-artifacts): Lists the artifacts this session owns (uploaded to it or produced by its tool calls), newest first. Another session's artifacts and agent-level artifacts are not included. - [Upload a session artifact](/zh/api-reference/native/events/upload-a-session-artifact): Streams the request body (1 byte to 1 GiB) into object storage as an artifact owned by this session. The session's tool calls read it at the returned /artifacts/ path; other sessions cannot. - [Get session artifact content](/zh/api-reference/native/events/get-session-artifact-content): Streams an artifact this session owns; any other artifact is 404. - [Get artifact](/zh/api-reference/native/events/get-artifact) - [Get artifact content](/zh/api-reference/native/events/get-artifact-content) - [List the authenticated user's personal access tokens](/zh/api-reference/native/users-and-api-keys/list-the-authenticated-users-personal-access-tokens): Items are ordered by created_at descending, then id descending. - [Create personal access token](/zh/api-reference/native/users-and-api-keys/create-personal-access-token) - [Revoke a personal access token](/zh/api-reference/native/users-and-api-keys/revoke-a-personal-access-token) - [Get the authenticated user and their organizations](/zh/api-reference/native/users-and-api-keys/get-the-authenticated-user-and-their-organizations) - [Delete the authenticated user's account](/zh/api-reference/native/users-and-api-keys/delete-the-authenticated-users-account): Deletes the account, revokes all personal access tokens and browser sessions, removes all organization and project memberships, and releases the account's sign-in identity (emails, linked auth identities, and password credentials) so the same email can register a new account. Personal secrets and skills owned by the user are deleted with the account. Deletion is blocked while the user is the last owner of any organization (add another owner or delete the organization first), while a personal skill is referenced by an active agent's configuration, or while a personal secret is referenced by a model provider config, machine pool, or integration. Organization and project resources are unaffected, and agents, machines, and other records the user created are kept with their attribution. - [List pending invitations](/zh/api-reference/native/users-and-api-keys/list-pending-invitations): Items are ordered by created_at ascending, then id ascending. - [Accept invitation](/zh/api-reference/native/users-and-api-keys/accept-invitation) - [Decline invitation](/zh/api-reference/native/users-and-api-keys/decline-invitation) - [List org API keys](/zh/api-reference/native/users-and-api-keys/list-org-api-keys): Items are ordered by created_at descending, then id descending. Revoked keys are included. - [Create org API key](/zh/api-reference/native/users-and-api-keys/create-org-api-key): Mints an org API key. The plaintext token is returned once and never stored. - [Get an org API key](/zh/api-reference/native/users-and-api-keys/get-an-org-api-key) - [Update an org API key](/zh/api-reference/native/users-and-api-keys/update-an-org-api-key): Renames the key and/or changes its org role. Revoked keys cannot be updated. - [Revoke an org API key](/zh/api-reference/native/users-and-api-keys/revoke-an-org-api-key): Terminally revokes the key and removes its org and project roles. Idempotent. - [List an org API key's explicit project role grants](/zh/api-reference/native/users-and-api-keys/list-an-org-api-keys-explicit-project-role-grants): Lists the key's explicit per-project role grants. Keys with the admin org role implicitly have admin access to every project and will not appear here for those projects. - [Set an org API key's role on a project](/zh/api-reference/native/users-and-api-keys/set-an-org-api-keys-role-on-a-project): Creates or updates the key's explicit role grant on the project. - [Remove an org API key's project role grant](/zh/api-reference/native/users-and-api-keys/remove-an-org-api-keys-project-role-grant) - [List the authenticated principal's organizations](/zh/api-reference/native/organizations-and-projects/list-the-authenticated-principals-organizations): Users get every organization they belong to; org API keys get the organization that issued them. Items are ordered by organization name ascending. - [Create organization](/zh/api-reference/native/organizations-and-projects/create-organization): Creates the organization and its local default resources atomically. An idempotency key determines the proposed organization ID; replaying it returns the existing organization. Without a key, each request is a fresh attempt. Optional default-provider provisioning begins after commit and retries asynchronously without failing organization creation. - [Delete organization](/zh/api-reference/native/organizations-and-projects/delete-organization): Deletes the organization and everything in it: projects, memberships, pending invitations, profiles, integrations, machine pools and machines, model provider configs and configured models, and all skills. Agents are archived and their runtimes and queued work are stopped. Secrets are permanently deleted once machine teardown no longer needs them. Deletion fails if project agent teardown cannot complete. Only organization owners can delete an organization. - [Get org usage](/zh/api-reference/native/organizations-and-projects/get-org-usage): Tallies model token usage and provider-reported cost across every project the caller can read in the organization, broken down by configured model. Optionally limits the tally to a time window or to a subset of those projects; including a project the caller can't read is not found. - [Get usage timeseries](/zh/api-reference/native/organizations-and-projects/get-usage-timeseries): Buckets model usage over time for one metric, optionally broken down by configured model or agent profile. Covers every project the caller can read in the organization; `project_ids` and `agent_profile_ids` narrow that scope. Buckets are calendar days, weeks (starting Monday), or months in `timezone`. - [List visible projects](/zh/api-reference/native/organizations-and-projects/list-visible-projects): Lists the projects the caller can access in the organization, newest first, with the caller's permissions on each. - [Create project](/zh/api-reference/native/organizations-and-projects/create-project): Creates a project, makes the caller its admin, and returns it. The new project has no grants to organization models, machines, skills, or secrets. - [Delete project](/zh/api-reference/native/organizations-and-projects/delete-project): Deletes the project, its memberships, profiles and profile versions, integrations and their interaction targets, project-owned skills and revisions, and grants owned by or targeting the project. Project-owned secrets are permanently deleted with their versions and grants. The project's agents are archived and their runtimes and queued work are stopped. Machine, machine-pool, and model grants are removed without deleting the shared machine, pool, or model. Deletion fails if agent teardown cannot complete. - [Get project usage](/zh/api-reference/native/organizations-and-projects/get-project-usage): Tallies model token usage and provider-reported cost across every agent in the project, including subagents, broken down by configured model. Optionally limits the tally to a time window. - [List organization members](/zh/api-reference/native/organizations-and-projects/list-organization-members): List organization members with server-side display-name filtering, sorting, and cursor pagination. - [Remove org member](/zh/api-reference/native/organizations-and-projects/remove-org-member): Removes the user's organization membership and all project memberships in the organization. The member's personal secrets and skills in the organization are deleted with the membership. Removal is blocked when the user is the organization's last owner, while a personal skill is referenced by an active agent's configuration, or while a personal secret is referenced by a model provider config, machine pool, or integration. - [Update org member role](/zh/api-reference/native/organizations-and-projects/update-org-member-role) - [List a member's explicit project role grants](/zh/api-reference/native/organizations-and-projects/list-a-members-explicit-project-role-grants): Lists the member's explicit per-project role grants. Org owners and admins implicitly have admin access to every project and will not appear here for those projects. - [Set a member's role on a project](/zh/api-reference/native/organizations-and-projects/set-a-members-role-on-a-project): Creates or updates the member's explicit role grant on the project. - [Remove a member's project role grant](/zh/api-reference/native/organizations-and-projects/remove-a-members-project-role-grant): Removes only the member's explicit role grant for this project. No other memberships, grants, or resources are deleted, and there are no dependency blockers. - [List org invitations](/zh/api-reference/native/organizations-and-projects/list-org-invitations): Every listed invitation is pending: accepting, declining, revoking, or organization deletion removes the invitation. Items are ordered by created_at descending, then id descending. - [Create org invitation](/zh/api-reference/native/organizations-and-projects/create-org-invitation) - [Delete org invitation](/zh/api-reference/native/organizations-and-projects/delete-org-invitation): Deletes the pending invitation so it can no longer be accepted. - [List agents across projects](/zh/api-reference/native/agents/list-agents-across-projects): Lists agents in every project of the organization where the caller can read agents. Each agent carries its project_id. Items are ordered by created_at descending, then id descending. - [List agents](/zh/api-reference/native/agents/list-agents): Lists the project's agents with their current activity, newest first by default. Archived agents and subagents are excluded unless requested. - [Create agent](/zh/api-reference/native/agents/create-agent): Launch from a pinned config, optionally adding agent-local integration tools, subscriptions and interaction handlers and admitting an attributed initial text input in the same transaction. Adding integration capabilities requires project management permission; launching an existing config requires agent operate permission. Reusing an idempotency key returns the current agent even if the retry body differs. The retry body is not applied and integration references are not resolved again. - [Get agent](/zh/api-reference/native/agents/get-agent): Returns one agent's state, model, profile, current config ID, activity (running, waiting_on_interaction, idle, or archived), attached machines, and MCP connection states. The conversation isn't included. - [Get agent usage](/zh/api-reference/native/agents/get-agent-usage): Tallies this agent's model token usage and provider-reported cost, broken down by configured model. Optionally limits the tally to a time window. - [Archive agent](/zh/api-reference/native/agents/archive-agent): Archives the agent: requests cancellation of its active runtime, cancels queued inputs and affected processes, removes its pending wakeup, releases explicit machine bindings, deletes pooled machines created for the agent, and deletes cron triggers targeting the agent. Every session of the agent that is still active, including the default session, is archived in the same transaction and reports `archived` with an `archived_at`. The agent, its sessions and its full event history stay readable by id; archived agents and sessions leave active listings. The agent's profile and configuration are retained, as are explicitly attached BYO machines. Archiving an already-archived agent is a no-op that returns the agent unchanged. - [Update agent config](/zh/api-reference/native/agents/update-agent-config): Replaces an active agent's config without restarting its conversation and returns the new agent_config. Model, instruction, and tool changes apply at the agent's next model call; machine changes apply immediately, stopping processes on removed machines and deleting the agent's machines from removed pools. Send the complete config, not a patch. - [Read the session model override metadata](/zh/api-reference/native/agents/read-the-session-model-override-metadata): Returns override metadata only. The API key is never returned. - [Create or replace the session model override](/zh/api-reference/native/agents/create-or-replace-the-session-model-override): Materializes an ephemeral tenant secret, provider config, configured model and project grant for this agent's next model call. The agent config revision is never modified. The response contains only override metadata and a fingerprint/key hint; the API key is write-only and encrypted at rest. - [Revoke the session model override](/zh/api-reference/native/agents/revoke-the-session-model-override): The next turn uses the agent configuration. Ephemeral rows are cleaned up later. - [Modify the session model override](/zh/api-reference/native/agents/modify-the-session-model-override): Replaces the active override with the merged result. A new API key replaces the previous encrypted secret; the previous ephemeral rows are cleaned up after no turn can reference them. - [Read the agent executor binding](/zh/api-reference/native/agents/read-the-agent-executor-binding): Returns the bound machine and the agent capability its executor last registered. - [Run the agent on an agent executor](/zh/api-reference/native/agents/run-the-agent-on-an-agent-executor): Binds the agent to a machine whose executor runs a complete local agent (Executor Protocol capability agent). Session input then becomes turn.start / turn.input on that executor, session cancel turn.cancel and session archive session.close; the BMA harness does not run the agent's sessions. Input queues while the executor is offline. - [Read a session model override metadata](/zh/api-reference/native/agents/read-a-session-model-override-metadata): Returns override metadata only. The API key is never returned. - [Create or replace a session model override](/zh/api-reference/native/agents/create-or-replace-a-session-model-override): Materializes an ephemeral tenant secret, provider config, configured model and project grant for this session's next model call. The pinned session config revision is never modified. The response contains only override metadata and a fingerprint/key hint; the API key is write-only and encrypted at rest. - [Revoke a session model override](/zh/api-reference/native/agents/revoke-a-session-model-override): The next turn uses the session config. Ephemeral rows are cleaned up later. - [Modify a session model override](/zh/api-reference/native/agents/modify-a-session-model-override): Replaces the active override with the merged result. A new API key replaces the previous encrypted secret; the previous ephemeral rows are cleaned up after no turn can reference them. - [Create agent input](/zh/api-reference/native/agents/create-agent-input): Sends a message to an agent and returns the stored input. Queued messages (the default) wait until the agent is ready for new work; steering messages reach it at its next model call. - [List agent sessions](/zh/api-reference/native/agents/list-agent-sessions): Lists the agent's conversation sessions, newest first. The default session is the legacy /api/v1 target. - [Create agent session](/zh/api-reference/native/agents/create-agent-session): Creates an independent conversation session for the agent. Sessions share agent-level memory stores. - [Get agent session](/zh/api-reference/native/agents/get-agent-session) - [Update agent session](/zh/api-reference/native/agents/update-agent-session) - [Archive agent session](/zh/api-reference/native/agents/archive-agent-session) - [Cancel agent session](/zh/api-reference/native/agents/cancel-agent-session): Stops the session's current turn and nothing else: cancels the turn's unfinished tool calls and open interactions, stops processes whose run_command hasn't returned yet, discards the session's pending steering messages and asks the session's runtime to stop. The agent's other sessions keep running. The session stays active, keeps its queued messages and its context, and its next message continues the conversation in the same session. Returns affected false and changes nothing when the session has no turn in progress, so repeated requests are safe. With per-session concurrent claims disabled, the agent runs one turn at a time and this request stops that turn only when it belongs to this session; otherwise it returns affected false. An archived session, or any session of an archived agent, cannot be canceled: the request fails with `state_transition_conflict`, matching input to it. - [Get an agent session by id](/zh/api-reference/native/agents/get-an-agent-session-by-id): Resolves one agent session by its id inside the project, without naming its agent. The session reports the agent that executes it. A session in another project is not found. - [List tool calls](/zh/api-reference/native/agents/list-tool-calls): Items are ordered by created_at ascending, then id ascending. - [Submit a result for a ready custom tool call](/zh/api-reference/native/agents/submit-a-result-for-a-ready-custom-tool-call): Only ready custom tool calls accept externally supplied results. The first accepted result completes the call. Any later submission, or a result for a non-custom tool call, returns 409. - [Cancel agent](/zh/api-reference/native/agents/cancel-agent): Stops the agent's current turn: cancels its unfinished tool calls and open interactions, stops processes whose run_command hasn't returned yet, and discards pending steering messages. The agent stays active and keeps its queued messages, and processes whose run_command already returned keep running. Returns affected false and changes nothing when no turn is in progress. With per-session concurrent claims the current turn of every session is stopped; use cancelAgentSession to stop one session only. An archived agent cannot be canceled: the request fails with `state_transition_conflict`, matching input to an archived session. - [List waiting backlog inputs](/zh/api-reference/native/agents/list-waiting-backlog-inputs): Steering inputs are listed first, followed by queued inputs. Each group is ordered by input rank, queued_at ascending, then id ascending. - [Cancel queued backlog input](/zh/api-reference/native/agents/cancel-queued-backlog-input) - [Move queued backlog input](/zh/api-reference/native/agents/move-queued-backlog-input) - [Promote queued input to steering](/zh/api-reference/native/agents/promote-queued-input-to-steering) - [Demote steering input to queued](/zh/api-reference/native/agents/demote-steering-input-to-queued) - [List agent profiles across projects](/zh/api-reference/native/configs-and-profiles/list-agent-profiles-across-projects): Lists agent profiles in every project of the organization the caller can read. Each profile carries its project_id. Items are ordered by created_at descending, then id descending. - [Resolve agent config tools](/zh/api-reference/native/configs-and-profiles/resolve-agent-config-tools): Returns configured built-in and custom tools plus missing machine, skill, subagent, and retrieval defaults, including disabled entries. Accepts YAML/JSON source. Source previews validate tool-related fields only; they do not validate whether the config can be saved or launched. Does not resolve contextual integration tools, discover MCP tools, or change any configuration. - [Create agent config](/zh/api-reference/native/configs-and-profiles/create-agent-config): Compiles and saves an immutable agent config (instruction, model, tools, machine_sources, and more) from YAML or JSON and returns it. Sending the same source again returns the existing config, as long as its names still resolve to the same resources. - [Get tool catalog](/zh/api-reference/native/configs-and-profiles/get-tool-catalog): Lists the built-in tools agent configs can use, with each tool's description and permission settings, plus the permission modes for custom and MCP tools. - [Search the MCP server registry](/zh/api-reference/native/configs-and-profiles/search-the-mcp-server-registry): Search the API's snapshot of the public MCP registry. The snapshot only holds active servers that publish a `streamable-http` remote. Results are ranked by relevance when `q` is set, otherwise ordered by name. - [List an MCP server's tools](/zh/api-reference/native/configs-and-profiles/list-an-mcp-servers-tools): Connects to a remote MCP server over streamable HTTP, negotiates the protocol version (stateless `server/discover` first, falling back to the `initialize` handshake for session-based servers), and returns the server's `tools/list` result. The request is not stored; use it to preview which tools a server exposes before referencing it from an agent config. Authentication mirrors the agent config `mcp_servers..auth` shape and resolves secrets available to the project. When the server does not speak MCP, the API responds 422 without an `auth` hint. When the server or its authorization server does not respond or fails, including a malformed MCP response or a JSON-RPC internal error from the server, the API responds 424; retrying may succeed once the server recovers. When the authorization server rejects the configured OAuth secret, the API responds 422 with an `oauth` hint so the caller can log in again. When BMA times out reading or storing discovery state, the API responds 503. When the server rejects the connection with HTTP 401 or 403, the API probes the server's authorization requirements and responds 422 with an `auth` hint — `oauth` when the server advertises an OAuth authorization server, `bearer` when it expects a token but advertises no OAuth metadata. If that probe fails for a non-transient reason, the 422 carries no `auth` hint. - [Get agent config](/zh/api-reference/native/configs-and-profiles/get-agent-config): Returns one agent config: its compiled definition with names resolved to IDs, and its source if it was saved with one. Configs BMA derives on its own, such as those for subagents and integration launches, have no source. - [Get generated agent config source](/zh/api-reference/native/configs-and-profiles/get-generated-agent-config-source): Rebuilds a source from the config's compiled_definition, for configs saved without a source. - [List agent profiles](/zh/api-reference/native/configs-and-profiles/list-agent-profiles): Lists the project's agent profiles, newest first by default, filterable by name. Items include a summary of each profile's current config, not its full compiled definition. - [Create agent profile](/zh/api-reference/native/configs-and-profiles/create-agent-profile): Creates a named profile that points at an agent config and returns the profile with its current config. - [Get agent profile](/zh/api-reference/native/configs-and-profiles/get-agent-profile): Returns one agent profile with its current config, current_config_id, and current_generation. - [Delete agent profile](/zh/api-reference/native/configs-and-profiles/delete-agent-profile): Deletes the profile, all of its profile versions, and any cron triggers targeting the profile. Agents launched from the profile are retained and keep running: each agent holds an immutable snapshot of the configuration it was launched with, so its reference to the profile becomes historical provenance only. Integration settings may retain the public profile ID; future launches fail as unavailable until those settings reference an available profile. - [Rename agent profile](/zh/api-reference/native/configs-and-profiles/rename-agent-profile): Renames an agent profile without changing its config. Agents and cron triggers reference the profile by ID and keep working, but configs that name the profile under subagents must use the new name the next time they're compiled. - [Get agent profile usage](/zh/api-reference/native/configs-and-profiles/get-agent-profile-usage): Tallies model token usage and provider-reported cost across the top-level agents launched from this profile, broken down by configured model. Usage from subagents those agents spawned is included only when `include_subagents` is true. Optionally limits the tally to a time window. - [Update agent profile](/zh/api-reference/native/configs-and-profiles/update-agent-profile): Points a profile at a different agent config. Existing agents keep their current config; agents launched from the profile afterward use the new one. Fails with 409 unless expected_current_config_id matches the profile's current config. - [List cron triggers](/zh/api-reference/native/configs-and-profiles/list-cron-triggers): Lists the project's cron triggers, newest first by default, filterable by name, agent, profile, or integration. Each item includes its schedule and next_fire_at. - [Create cron trigger](/zh/api-reference/native/configs-and-profiles/create-cron-trigger): Creates a cron trigger that fires on a schedule. A trigger targeting an agent profile launches a new agent from the profile's current config on each firing; a trigger targeting an agent sends an input to that agent. Missed firings are coalesced, matching standard cron behavior: if one or more scheduled times pass while firing is delayed, the trigger fires once for the oldest missed time and then resumes its schedule from the current time, without retroactively firing for the other missed times. - [Get cron trigger](/zh/api-reference/native/configs-and-profiles/get-cron-trigger): Returns one cron trigger: its target, schedule, timezone, message template, enabled flag, and firing state (last_fired_at, next_fire_at, and any failure since the last successful firing). - [Delete cron trigger](/zh/api-reference/native/configs-and-profiles/delete-cron-trigger): Deletes a cron trigger so it never fires again; there is no undo. Agents it already launched keep running. - [Update cron trigger](/zh/api-reference/native/configs-and-profiles/update-cron-trigger): Updates the schedule, message template, or enabled state. The target is immutable; delete the trigger and create a new one to retarget. - [List skills visible through ownership authority](/zh/api-reference/native/skills/list-skills-visible-through-ownership-authority): Items are ordered by created_at descending, then id descending. Without an owner filter, returns the deduplicated union of organization skills the caller may list, project skills the caller may list, and the caller's own user skills. Grants are managed separately and do not change ownership. - [Create skill](/zh/api-reference/native/skills/create-skill): Uploads a skill archive. If a skill with the archive's name already exists for the requested owner, the upload becomes the skill's next revision. The owner is immutable after creation. - [Get skill through ownership authority](/zh/api-reference/native/skills/get-skill-through-ownership-authority): Returns one skill with its latest SKILL.md text and file listing. - [Update skill by uploading a new revision](/zh/api-reference/native/skills/update-skill-by-uploading-a-new-revision): Creates the skill's next revision from either a replacement archive or replacement SKILL.md content (which keeps every other file from the current revision). The SKILL.md frontmatter `name` must match the skill's existing name. - [Delete skill](/zh/api-reference/native/skills/delete-skill): Deletes the skill together with all of its revisions and project grants; uploaded archive content is destroyed. No other resources are deleted. Deletion is blocked while an active agent's configuration references the skill. - [List skill grants](/zh/api-reference/native/skills/list-skill-grants): Lists the projects a skill is shared with, one grant per project, most recently shared first by default. - [Create skill grant](/zh/api-reference/native/skills/create-skill-grant): Shares a skill with another project so its agent configs can attach it, and returns the grant; ownership doesn't change. - [Delete skill grant](/zh/api-reference/native/skills/delete-skill-grant): Deletes only this project grant. The skill, its revisions, the target project, and other grants are retained, and there are no dependency blockers. - [List skills available to project](/zh/api-reference/native/skills/list-skills-available-to-project): Includes directly owned project skills and granted skills, ordered by created_at descending, then id descending. - [List memory stores across projects](/zh/api-reference/native/memory-stores/list-memory-stores-across-projects): Lists memory stores in every project of the organization the caller can read. Each store carries its project_id. Items are ordered by name, then id. - [List memory stores](/zh/api-reference/native/memory-stores/list-memory-stores) - [Create memory store](/zh/api-reference/native/memory-stores/create-memory-store) - [Get memory store](/zh/api-reference/native/memory-stores/get-memory-store) - [Delete memory store](/zh/api-reference/native/memory-stores/delete-memory-store) - [Update memory store](/zh/api-reference/native/memory-stores/update-memory-store) - [List memory files](/zh/api-reference/native/memory-stores/list-memory-files): List a directory's immediate children in name order. Omit path to list the store root. - [Download memory file](/zh/api-reference/native/memory-stores/download-memory-file) - [Write memory file](/zh/api-reference/native/memory-stores/write-memory-file) - [Delete memory file](/zh/api-reference/native/memory-stores/delete-memory-file) - [List secrets visible through ownership authority](/zh/api-reference/native/secrets/list-secrets-visible-through-ownership-authority): Items are ordered by created_at descending, then id descending. Without an owner filter, returns the deduplicated union of organization secrets the caller may list, project secrets the caller may list, and the caller's own user secrets. - [Create secret](/zh/api-reference/native/secrets/create-secret): Creates an encrypted secret holding one credential and returns its metadata; the value is never returned. owner sets whether the organization, a project, or the caller owns it. - [Start MCP OAuth for a new secret](/zh/api-reference/native/secrets/start-mcp-oauth-for-a-new-secret) - [Get secret through ownership authority](/zh/api-reference/native/secrets/get-secret-through-ownership-authority): Returns a secret's owner, kind, name, and current version; the secret value is never returned. - [Delete secret](/zh/api-reference/native/secrets/delete-secret): Deletes the secret and permanently destroys all of its versions and project grants; the ciphertext cannot be recovered. Deletion is blocked while the secret is the credential of a model provider config, machine pool, or integration. - [Update secret metadata](/zh/api-reference/native/secrets/update-secret-metadata): Renames a secret or replaces its metadata, and returns the updated secret without its value. The value, kind, and owner can't be changed here. References use the secret ID, so renaming doesn't break them. - [Create secret version](/zh/api-reference/native/secrets/create-secret-version) - [List secret grants](/zh/api-reference/native/secrets/list-secret-grants): Lists the projects a secret is shared with, one grant per project, most recently shared first by default. - [Create secret grant](/zh/api-reference/native/secrets/create-secret-grant): Shares a secret with another project so that project's resources can use it, and returns the grant; ownership doesn't change. - [Delete secret grant](/zh/api-reference/native/secrets/delete-secret-grant): Deletes only this project grant. The secret, its versions, the target project, and other grants are retained, and there are no dependency blockers. - [List secrets available to project](/zh/api-reference/native/secrets/list-secrets-available-to-project): Includes directly owned and granted secrets, ordered by created_at descending, then id descending. - [Get secret available to project](/zh/api-reference/native/secrets/get-secret-available-to-project) - [Connect an integration through OAuth](/zh/api-reference/native/integrations/connect-an-integration-through-oauth): Starts OAuth for this integration (currently Slack). The callback pins the integration and setup revision, records verified credentials, and returns integration_oauth=success and integration_id to the supplied local return_to route. It requires a browser session for the initiating user and current project management access. Replayed, stale, or deleted-integration callbacks are rejected. - [Create a Slack provider app and connect it to an BMA integration](/zh/api-reference/native/integrations/create-a-slack-provider-app-and-connect-it-to-an-bma-integration): Creates a provider-side Slack app using the supplied configuration token, name and optional icon, then starts OAuth for this saved BMA integration. The callback activates this integration only. It never creates another BMA integration or changes launcher settings. - [Start registration of a customer-owned GitHub App](/zh/api-reference/native/integrations/start-registration-of-a-customer-owned-github-app): Starts guided registration on github.com for a never-connected GitHub integration. Requires a browser session and project management access. Submit manifest as a JSON-encoded form field to registration_url. The callback saves a project credential secret and redirects to the canonical integration page with github_setup=credentials_saved and credential_secret_id (a public secret ID). It does not connect an installation or change launcher settings. - [Inspect installations of a customer-owned GitHub App](/zh/api-reference/native/integrations/inspect-installations-of-a-customer-owned-github-app): Verifies the supplied project-available GitHub credential secret using App authentication and returns one bounded page of installations. Requires a browser session and project management access. Inspection does not connect or change this integration. Explicit confirmation uses ConfigureIntegration with the returned provider_app_id, selected installation ID, credential secret ID and current expected setup revision. A saved secret remains usable while organization approval is pending; there is no expiring continuation. Guided links support github.com only. - [List integrations across projects](/zh/api-reference/native/integrations/list-integrations-across-projects): Lists integrations in every project of the organization the caller can read. Each integration carries its project_id. Items are ordered by created_at descending, then id descending. - [List project integrations](/zh/api-reference/native/integrations/list-project-integrations) - [Create an integration and optional launcher](/zh/api-reference/native/integrations/create-an-integration-and-optional-launcher) - [Get project integration](/zh/api-reference/native/integrations/get-project-integration) - [Update integration settings](/zh/api-reference/native/integrations/update-integration-settings): Replaces integration-owned settings while preserving credentials. The request contains only settings; name and integration_kind are immutable and accepted only on create. Preserve integration-level fields when editing the launcher. Settings follow capabilities.settings.input_schema from the integration catalog. - [Delete integration setup and revoke its capabilities](/zh/api-reference/native/integrations/delete-integration-setup-and-revoke-its-capabilities): Deletes the integration setup and its cron schedules, revokes its capabilities, and releases its credential reference. Existing agents, agent history, and provider messages are preserved. - [List integration conversation subscriptions](/zh/api-reference/native/integrations/list-integration-conversation-subscriptions): Requires project read permission. Disconnected integrations retain their subscriptions and support listing. - [Attach an agent to an integration conversation](/zh/api-reference/native/integrations/attach-an-agent-to-an-integration-conversation): Requires project management permission. Repeating an active attachment returns the same subscription. Subscriptions do not change the agent config or grant sending tools. - [Stop forwarding an integration conversation to an agent](/zh/api-reference/native/integrations/stop-forwarding-an-integration-conversation-to-an-agent): Requires project management permission. Missing subscriptions are a no-op within an existing integration. Disconnected integrations support deletion. Stops future incoming forwarding for this subscription. The agent, sending tools, interaction handlers, and history remain available. Attaching the conversation again through the API resumes forwarding with a new subscription ID. - [Verify and configure integration credentials](/zh/api-reference/native/integrations/verify-and-configure-integration-credentials): Requires a user principal with project management permission. Slack credentials are configured through OAuth. A stale expected_setup_revision or a credential changed during verification returns 409; reload the integration and retry setup. Setup preserves integration settings; verified provider identity scopes incoming events. - [Disconnect this integration without deleting its configuration](/zh/api-reference/native/integrations/disconnect-this-integration-without-deleting-its-configuration) - [List repositories a GitHub integration can access](/zh/api-reference/native/integrations/list-repositories-a-github-integration-can-access): Returns one page of up to 100 repositories the connected installation can access, for use in git_credentials.repository_ids. Requires project management access. - [List installed integration implementations and their capabilities](/zh/api-reference/native/integrations/list-installed-integration-implementations-and-their-capabilities) - [List an agent's pooled machines](/zh/api-reference/native/machines/list-an-agents-pooled-machines): Lists the pooled machines attached to an agent, in binding creation order, with each machine's kind. A persistent machine is kept for a person (for example a purchased BMA computer) and is never deleted for being idle; an ephemeral machine serves turns and is deleted after its idle window. - [Create a persistent machine for an agent](/zh/api-reference/native/machines/create-a-persistent-machine-for-an-agent): Creates one machine for the agent from the requested sold template and disables idle deletion, so the machine stays until it is deleted. The machine is attached to the agent and consumes the project and organization pool-machine quotas like any other pooled machine. The machine pool defaults to the agent's only pool source. - [Delete an agent's persistent machine](/zh/api-reference/native/machines/delete-an-agents-persistent-machine): Deletes one persistent machine attached to the agent through the same pool deletion used for machines that are no longer wanted: the provider machine is deleted, the agent binding is released and the pool quota is freed. Only a persistent machine of this agent can be deleted; an ephemeral machine, or a machine attached to another agent, is refused. The machine is marked for deletion before the response and the provider deletion is retried by maintenance until it succeeds. The call is idempotent: a machine that is already deleting or gone returns 204. - [List visible project machines](/zh/api-reference/native/machines/list-visible-project-machines): Items are ordered by machine created_at descending, then machine id descending. - [Get machine interaction capabilities](/zh/api-reference/native/machines/get-machine-interaction-capabilities): Reports whether the machine can offer a PTY terminal or a desktop and what the caller may do. Seeing a machine never implies shell or desktop access. - [Resume a paused or archived machine](/zh/api-reference/native/machines/resume-a-paused-or-archived-machine): Resumes a paused machine, or restores an archived one, and waits until its daemon is online. Commands, terminal sessions and desktop sessions resume the machine on their own; this endpoint lets a client warm it up ahead of use. Concurrent calls share one resume. Returns 503 when the machine does not come online before the resume timeout; the machine and its disk are kept and a later call retries. - [List a machine's workspace backups](/zh/api-reference/native/machines/list-a-machines-workspace-backups): Workspace backups keep a persistent pool machine's user files (by default /home/user) in BMA storage, independent of the provider host. BMA takes one before the machine pauses and periodically while it runs when files changed, and keeps the newest few. Items are ordered by created_at descending. - [Back up a machine's workspace now](/zh/api-reference/native/machines/back-up-a-machines-workspace-now): Starts a backup of an online pool machine. The returned backup is uploading; list the backups to see it become ready or failed. Backups count against the project's machine backup storage limit. - [Recreate a machine from a workspace backup](/zh/api-reference/native/machines/recreate-a-machine-from-a-workspace-backup): Replaces the machine with a new one created from its template and restores a backup (the newest ready one unless backup_id is given) before the machine comes online again. Only files under the backed-up paths are restored; system-level changes and running processes are not kept. The machine's lifecycle_reason_code reports restoring_from_backup, then restored_from_backup or backup_restore_failed. BMA does the same on its own when the provider loses a machine that has a backup. - [List project machine grants](/zh/api-reference/native/machines/list-project-machine-grants): Lists explicit machine grants that can be deleted directly. Pool-derived machine access is managed through project machine pool grants. - [Create project machine grant](/zh/api-reference/native/machines/create-project-machine-grant): Lets a project's agent configs use one BYO machine by name and returns the grant with the machine's record. Pooled machines can't be granted this way and return 404. - [Delete project machine grant](/zh/api-reference/native/machines/delete-project-machine-grant): Removes the project's access to the machine. Processes that depended on the grant are stopped. The machine itself is retained, and there are no dependency blockers. - [List visible machines](/zh/api-reference/native/machines/list-visible-machines): Lists the machines the caller can see, both BYO and pooled, newest first by default, with each one's connection state. Items are summaries without execution defaults or metadata. - [Create machine](/zh/api-reference/native/machines/create-machine) - [Connect a BYO machine](/zh/api-reference/native/machines/connect-a-byo-machine): Registers a machine you run yourself and returns its daemon token for installing bmad on it; the token is shown only in this response. The machine stays offline until its daemon connects. project_ids grants it to those projects in the same call, and their agent configs reference it by display_name. - [Get machine](/zh/api-reference/native/machines/get-machine): Returns one active machine's full record: connection state, execution defaults (secret IDs only, never values), metadata, and the latest failure report. Machines in other lifecycle states, such as pool machines still provisioning, aren't returned. - [Delete machine](/zh/api-reference/native/machines/delete-machine): Deletes a BYO machine, ends its active daemon runtimes and work, revokes its daemon tokens and project grants, and releases agent bindings. Pooled machines are managed through their machine pool and cannot be deleted through this route. There are no dependency blockers for a BYO machine. - [Update machine execution defaults](/zh/api-reference/native/machines/update-machine-execution-defaults): Updates a machine's execution defaults: working directory, environment variables, and secret environment variables. env and secret_env replace the whole map, and changes apply to processes started afterward. - [List byo machine daemon tokens](/zh/api-reference/native/machines/list-byo-machine-daemon-tokens): Items are ordered by created_at descending, then id descending. - [Create byo machine daemon token](/zh/api-reference/native/machines/create-byo-machine-daemon-token) - [Revoke machine daemon token](/zh/api-reference/native/machines/revoke-machine-daemon-token) - [List agent interactions](/zh/api-reference/native/interactions/list-agent-interactions): Lists an agent's permission prompts and ask_question questions, oldest first, with each one's form and answers. state filters by open, resolved, or canceled. - [Resolve agent interaction](/zh/api-reference/native/interactions/resolve-agent-interaction): Answers an open permission prompt or question so the paused agent resumes, and returns the resolved interaction. Send one answer per question with zero-based option_indices; permission prompts use 0 for Allow and 1 for Deny. - [List files](/zh/api-reference/native/files/list-files): Lists the project's files, newest first. scope_id keeps the files scoped to one session (the files it produced); each metadata filter (key:value) must match a label of the file. Session instances created by mounting a file are never listed; read them through the session's resources. - [Upload a file](/zh/api-reference/native/files/upload-a-file): Streams the request body (1 byte to 1 GiB) into object storage as a project file. A replay with the same Idempotency-Key, filename, content and labels returns the original file with 200; a different request under the key is 409. The project's files may not exceed its storage limit (409). - [Get file metadata](/zh/api-reference/native/files/get-file-metadata) - [Delete a file](/zh/api-reference/native/files/delete-a-file): Deletes the file: it is no longer readable, listable or mountable. Sessions that mounted it keep reading their own session instance until the resource is removed or the session is archived; the stored content is reclaimed after the last of them. Deleting a session instance removes its session resource. Artifacts the file was promoted from are kept. - [Download a file](/zh/api-reference/native/files/download-a-file): Streams the file content with its length and SHA-256 digest. - [List session file resources](/zh/api-reference/native/files/list-session-file-resources): Lists the files mounted into this session, ordered by created_at. - [Mount a file into a session](/zh/api-reference/native/files/mount-a-file-into-a-session): Mounts a project file, read-only, at mount_path below /mnt/session/uploads (default /mnt/session/uploads/). The mount creates a new file_id, a session instance scoped to this session that references the same stored content: no bytes are copied, the instance does not count against the storage limit, and it stays readable after the original file is deleted. The session's storage tools read it at mount_path. Mounting the same file at the same path again returns the existing resource; another file at that path is 409. Only project files can be mounted, not session instances (404). A session holds at most 500 files. - [Unmount a file from a session](/zh/api-reference/native/files/unmount-a-file-from-a-session): Removes the mount and its session instance; the original file, if it still exists, is kept. - [Promote a session artifact to a file](/zh/api-reference/native/files/promote-a-session-artifact-to-a-file): Copies an artifact this session owns into a project file inside BMA, without the caller downloading it. The file is project-wide, or scoped to the session with scope "session" (listed by scope_id). The artifact is kept. An Idempotency-Key replay returns the original file with 200. - [Create a desktop session](/zh/api-reference/native/desktops/create-a-desktop-session): Starts one desktop session for the machine. A caller without desktop control permission can only create a read-only session. A machine has at most one live desktop session per caller. - [Get a desktop session](/zh/api-reference/native/desktops/get-a-desktop-session) - [Close a desktop session](/zh/api-reference/native/desktops/close-a-desktop-session): Closing a session ends its bridge and revokes outstanding watch tickets. - [Get desktop control status](/zh/api-reference/native/desktops/get-desktop-control-status) - [Acquire desktop control](/zh/api-reference/native/desktops/acquire-desktop-control): Pauses the agent and takes the human-control lease. A concurrent holder returns 409 conflict. - [Renew desktop control](/zh/api-reference/native/desktops/renew-desktop-control): Extends the current human-control lease. - [Release desktop control](/zh/api-reference/native/desktops/release-desktop-control): Releases control. The agent stays paused until it re-observes the desktop. - [Hand control back](/zh/api-reference/native/desktops/hand-control-back): Hands control back to the paused desktop. The agent stays paused until it re-observes. - [Capture the desktop](/zh/api-reference/native/desktops/capture-the-desktop): Captures the current framebuffer. The image is returned base64-encoded in JSON. - [Send desktop input](/zh/api-reference/native/desktops/send-desktop-input): Applies one human input action. The caller must hold control; the server rejects stale epochs, read-only sessions, and out-of-order sequences. - [Observe the desktop as the agent](/zh/api-reference/native/desktops/observe-the-desktop-as-the-agent): Returns a real screenshot receipt and the generation that a later agent resume must present. - [Resume the agent after a takeover](/zh/api-reference/native/desktops/resume-the-agent-after-a-takeover): Requires a generation obtained from an observation after the last control change. - [Submit an agent desktop action](/zh/api-reference/native/desktops/submit-an-agent-desktop-action): Fences the action at the supplied generation and returns a pending action that must be confirmed after a fresh observation. - [Confirm a pending agent action](/zh/api-reference/native/desktops/confirm-a-pending-agent-action) - [List terminal sessions](/zh/api-reference/native/terminals/list-terminal-sessions) - [Create a terminal session](/zh/api-reference/native/terminals/create-a-terminal-session): Creates a PTY-backed shell session. The PTY data plane is being wired to the machine daemon; until then this endpoint reports that terminal sessions are unavailable. - [Get a terminal session](/zh/api-reference/native/terminals/get-a-terminal-session) - [Close a terminal session](/zh/api-reference/native/terminals/close-a-terminal-session) - [Mint a terminal connection ticket](/zh/api-reference/native/terminals/mint-a-terminal-connection-ticket): Mints a single-use, Origin-bound ticket for the terminal WebSocket. The ticket is returned once and is never placed in a URL. - [List project actors](/zh/api-reference/native/actors/list-project-actors): Items are ordered by created_at ascending, then id ascending. - [Upsert an external actor](/zh/api-reference/native/actors/upsert-an-external-actor): Upserts by (provider_tenant_id, provider_user_id). Omitted attributes keep their stored values; provided attributes are overwritten, including empty values. An unchanged actor is not rewritten. Actors written through this endpoint always have the external provider. - [Get a project actor](/zh/api-reference/native/actors/get-a-project-actor) - [List model provider configs](/zh/api-reference/native/models/list-model-provider-configs): List model provider configs with server-side filtering, sorting, and cursor pagination. - [Create model provider config](/zh/api-reference/native/models/create-model-provider-config): Create a model provider config, validate the configured credential where the provider exposes a validation endpoint, then probe the provider's /models endpoint. The result is returned as model_catalog; a failed probe does not fail creation. - [Get model provider config](/zh/api-reference/native/models/get-model-provider-config): Returns one model provider config's stored settings; secret values are never returned. The provider isn't contacted, so the response doesn't list its models. - [Update model provider config](/zh/api-reference/native/models/update-model-provider-config): Updates a model provider config's connection settings, such as its credential and headers, and returns the updated config; omitted fields keep their values. The credential secret is checked to exist and match auth_kind, but the provider isn't contacted, so a credential the provider rejects isn't caught here. - [Delete model provider config](/zh/api-reference/native/models/delete-model-provider-config): Deletes only the model provider config. Deletion is blocked while it has configured models. Cluster-managed provider configs cannot be deleted through this route. - [Get model catalog](/zh/api-reference/native/models/get-model-catalog): Fetches the provider's live model catalog by validating the configured credential and probing the provider's /models endpoint. The call waits on the upstream provider, so it is slower than the other model provider config routes and can report failure as data. - [List configured models](/zh/api-reference/native/models/list-configured-models): Lists the models configured under one model provider config, newest first, with each model's slug, token limits, and reasoning support. - [Create configured model](/zh/api-reference/native/models/create-configured-model): Adds a provider model to this provider config under the name agent configs use as model.name, and returns it. The model slug isn't checked against the provider's catalog, and no project can use the model yet. - [Update configured model](/zh/api-reference/native/models/update-configured-model): Updates a configured model's settings and returns the updated model; omitted fields keep their values. Agents already using the model pick up the change on their next model call. The update isn't checked against project grants or agent configs, so lowering a limit below their overrides or turning off tools or reasoning they rely on makes those agents' next model call fail. - [Delete configured model](/zh/api-reference/native/models/delete-configured-model): Deletes only the configured model. Deletion is blocked while it has active project grants. Cluster-managed configured models cannot be deleted through this route. - [List project model grants](/zh/api-reference/native/models/list-project-model-grants): Lists the configured models a project can use, most recently granted first by default, with each grant's overrides and the model's name and provider config. - [Create project model grant](/zh/api-reference/native/models/create-project-model-grant): Lets a project's agent configs use a configured model and returns the new grant. Optional overrides can narrow the model for that project (lower token limits, tools or reasoning turned off, fewer reasoning efforts or modalities) and set its per-request defaults within those limits. - [Delete project model grant](/zh/api-reference/native/models/delete-project-model-grant): Removes the project's access to the configured model. The grant is live policy: new launches can no longer select the model, and agents already using it lose access on their next model call. The model itself is retained, and there are no dependency blockers. - [Update project model grant](/zh/api-reference/native/models/update-project-model-grant): Updates the project's overrides for the configured model. Omitted fields keep their current values; null, or [] for supported_reasoning_efforts, input_modalities, and output_modalities, clears an override so the project inherits from the configured model. Agents already using the model apply the updated overrides on their next model call. Updates are validated against the configured model's current revision but not against agent configs, so narrowing below a config's model settings, such as its context_window_tokens or reasoning effort, makes that agent's next model call fail. - [List machine pools](/zh/api-reference/native/machine-pools/list-machine-pools): List machine pools with server-side filtering, sorting, and cursor pagination. - [Create machine pool](/zh/api-reference/native/machine-pools/create-machine-pool) - [Check machine pool connection](/zh/api-reference/native/machine-pools/check-machine-pool-connection): Checks a tenant-managed pool's provider credential and provider config by making read-only requests to the provider. - [Get machine pool](/zh/api-reference/native/machine-pools/get-machine-pool): Returns one machine pool's configuration and current usage: provider, default machine settings, CPU, memory, and machine-count limits, and idle deletion policy. - [Update machine pool](/zh/api-reference/native/machine-pools/update-machine-pool): Tenant-managed pools support every request field. Cluster-managed pools only allow changes to default CPU and memory, environment and secret environment variables, provider-supported per-machine CPU and memory limits, and the idle deletion policy. Other cluster-managed changes are rejected with 409 Conflict. - [Delete machine pool](/zh/api-reference/native/machine-pools/delete-machine-pool): Deletes the machine pool and its pooled machines, revokes generated machine grants and project machine-pool grants, and stops processes that depended on those grants. Deleting a cluster-managed machine pool is rejected with 409 Conflict; there are no other dependency blockers. - [List project machine pool grants](/zh/api-reference/native/machine-pools/list-project-machine-pool-grants): Lists the machine pools a project can create machines from, one grant per pool, most recently granted first by default. - [Create project machine pool grant](/zh/api-reference/native/machine-pools/create-project-machine-pool-grant): Lets a project create machines from a machine pool, optionally with its own defaults and usage caps within the pool's limits, and returns the grant. No machines are created by this call. - [Get project machine pool grant](/zh/api-reference/native/machine-pools/get-project-machine-pool-grant): Returns one project's grant for a machine pool, with the defaults and limits it sets on top of the pool's own. Null fields set no override, so the pool's value applies. - [Delete project machine pool grant](/zh/api-reference/native/machine-pools/delete-project-machine-pool-grant): Removes the project's access to the machine pool, revokes machine grants generated through it, and stops processes that depended on those grants. The pool itself is retained, and there are no dependency blockers. - [Update project machine pool grant](/zh/api-reference/native/machine-pools/update-project-machine-pool-grant): Updates the grant's overrides and limits. Omitted fields keep their current values; null clears an override so the grant follows the machine pool again. Overlay objects and metadata are replaced whole when present. Existing machines keep their configuration; the updated defaults and limits apply to new launches. - [Mint a desktop watch ticket for a session (BMA extension)](/zh/api-reference/extensions/mint-a-desktop-watch-ticket-for-a-session-bma-extension): Returns a short-lived, single-use, origin-bound watch ticket and the WebSocket endpoint of the desktop session attached to the session's machine. The browser connects to `url` with `subprotocol` and the ticket; the tenant API key never reaches the browser. - [List files uploaded into the session (BMA extension)](/zh/api-reference/extensions/list-files-uploaded-into-the-session-bma-extension) - [Upload one file into the session (BMA extension)](/zh/api-reference/extensions/upload-one-file-into-the-session-bma-extension): Stores one multipart file (at most 8 MiB, non-empty, bare filename) in the session's read_write memory store under the session's own directory. Create-only: an existing filename is a 409 `file_already_exists`. A session without a read_write memory store is a 409 `session_files_unavailable`. - [Download one session file (BMA extension)](/zh/api-reference/extensions/download-one-session-file-bma-extension): Streams one file's bytes. `file_id` is the `id` returned by the upload or list operations. The response carries `Content-Type`, `Content-Length` and `Content-Disposition` when known, and `X-BMA-File-Digest` with the sha256 of the bytes. A file of another session, or an unknown id, is a 404 `not_found_error`. - [List the session's mounted file resources (BMA extension)](/zh/api-reference/extensions/list-the-sessions-mounted-file-resources-bma-extension) - [Mount one project file into the session (BMA extension)](/zh/api-reference/extensions/mount-one-project-file-into-the-session-bma-extension): Mounts an uploaded project file by reference. The Anthropic contract mounts files through `resources` on `POST /v1/sessions`; this extension mounts into an existing session. The file is read-only at `mount_path` (default `/mnt/session/uploads/`), and the response `file_id` is the session instance created for the mount, not the project file's own id. - [Unmount one file resource from the session (BMA extension)](/zh/api-reference/extensions/unmount-one-file-resource-from-the-session-bma-extension): Removes the mount and releases the session instance. The project file itself is kept; other sessions that mounted it keep their instances. - [自托管](/zh/self-hosting/overview): 目前自行运行 BMA 需要什么，以及当前的限制。 - [更新日志](/zh/changelog): 抢先体验部署与各 SDK 的变更。 - [路线图](/zh/roadmap): 计划中的工作。这里的内容都尚不可用，也不承诺日期。