Skip to main content
PATCH
Update a project

Authorizations

Authorization
string
header
required

Your Reason API key from Settings › API keys. New keys use reason_; legacy ara_ keys remain accepted. Keys are capability-scoped: run, mcp:read, mcp:write, secrets:read, secrets:write, sessions:read, sessions:debug, devices:read, devices:write, devices:use, computers:read, computers:write, ssh:write, knowledge:read, memory:read, memory:write, skills:read, skills:write, pages:read, pages:write, repos:read, repos:write, reviews:read, reviews:write, deployment:read, analytics:read, org:read, org:write, attachments:read, attachments:write, guardrails:read, guardrails:write, network:read, network:write, automations:read, automations:write, agent_auth:read. devices:write, devices:use, computers:read, computers:write, ssh:write, network:read and network:write are opt-in, excluded from default keys. computers:read lists visible cloud and connected computers without waking them or granting execution access. devices:read discovers local Device targets; devices:use separately consents to local execution, so a discover-and-run local workflow needs both. devices:write manages enrollment and device grants; computers:write creates or deletes cloud computers; ssh:write manages retained SSH access. network:read reads the saved workspace network policy; network:write replaces custom allowed hosts and requires a current organization owner/admin. Legacy project PATCH requests containing network_allowed_hosts also require network:write plus their existing run scope and project management permission; saved project hosts do not affect current session egress. Only owners/admins can mint or manage keys with network:write; keys cannot grant themselves more authority. See /docs/network-policies for replacement semantics and runtime applicability. mcp:write manages MCP server configuration only; it does not authorize remote MCP-tool execution. sessions:read reads sessions, including the assistant, reasoning and tool activity in their events. sessions:debug is privileged: only for organization owners/admins, it expands session events to the full diagnostic projection (diagnostic event kinds, status text and raw event metadata).

Scopes

run

Path Parameters

orgId
string
required

Organization id or slug. Resolve it with GET /v3/self.

projectId
string<uuid>
required

The project id, returned as id by listProjects and createProject: the id of the Reason it is.

Body

application/json

Update a project, which is a Reason: name, description (the Reason's instructions) and visibility apply; the other fields are accepted and ignored.

name
string
Required string length: 1 - 120
description
string | null
Maximum string length: 2000
visibility
enum<string>
Available options:
workspace,
private
kind
enum<string>
Available options:
local,
remote
cloud_enabled
boolean
network_allowed_hosts
string[]
Maximum array length: 50
default_machine
enum<string> | null
Available options:
namespace-linux-s,
namespace-linux-m,
namespace-linux-l,
namespace-linux-xl,
namespace-macos-m,
namespace-macos-l,
blaxel-linux-s,
blaxel-linux-m,
blaxel-linux-l,
blaxel-linux-xl,
compute-linux-s,
compute-linux-l,
compute-linux-xl
resources
object[]
Maximum array length: 100
source_folders
(string | object)[]
Maximum array length: 100
Required string length: 1 - 4096
preferred_dir
string | null
Maximum string length: 4096

Response

Updated project.

A named Reason the caller can see, in the retired Project shape. resources is always empty: a session names its own repositories and target.

id
string<uuid>
required

The Reason's id. Pass it as project_id when creating or listing sessions, or as reasonId to the Reasons operations.

name
string
required
slug
string
required
description
string | null
required
kind
enum<string>
required
Available options:
local,
remote
cloud_enabled
boolean
required

Always true: a project no longer restricts where its sessions run.

visibility
enum<string>
required
Available options:
workspace,
private
archived_at
string | null
required
revision
integer
required
can_edit
boolean
required
resources
object[]
required