OpenMax
免费试用

Apps API · Projects

Projects: 13 个接口

← 全部分组

GET /api/v1/me/private-workspace

Get the caller's private workspace status

权限(scope): work:project:read · 调用方式: appToken · operationId: get-private-workspace

Required app scope: work:project:read.

Human members only. enabled reports whether private projects can be created now; has_private_project whether the caller owns or ever owned a private project (archived ones count). Not gated by the flag. Response wrapped in standard envelope.

回包

POST /api/v1/me/private-workspace

Ensure the caller's personal private project and knowledge base

权限(scope): work:project:write · 调用方式: appToken · operationId: ensure-private-workspace

Required app scope: work:project:write.

Human members only; refused with 403 PRIVATE_SCOPE_DISABLED while automation_private_scope_enabled is off. Idempotent: returns the caller's personal knowledge base (created, or restored when archived) and the personal private project bound to it (created when missing; an existing one is returned unchanged, archived included). Concurrent calls converge on one of each. The knowledge base is ensured first: if the project step fails, the error is returned and the knowledge base stays, to be reused by the next call. Names apply only on creation. Response wrapped in standard envelope.

请求体

application/json · EnsurePrivateWorkspaceRequestBody

字段 类型 必填 说明
knowledge_base_name string Name used only when the personal knowledge base is created; defaults to the Chinese-language name for "My knowledge base"
project_name string Name used only when the personal project is created; defaults to the Chinese-language name for "My private project"

回包

GET /api/v1/projects

List projects

权限(scope): work:project:read · 调用方式: appToken · operationId: list-projects

Required app scope: work:project:read.

Returns a paginated list of projects. Optional member_id filters project membership (me or an organization member UUID); querying another member requires organization owner/admin permission. Optional starred_by=me narrows to the caller's starred projects. Omission preserves existing visibility. Each item reports the caller-relative starred flag. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
page query integer (int32) Page number (default: 1)
page_size query integer (int32) Items per page (default: 20, max: 100)
order_by query string Sort expression, e.g. created_at:desc
status query string: active, archived Filter by status
query query string Case-insensitive project name or description search
member_id query string Filter by project membership: me or an organization member UUID. Other members require organization owner/admin permission.
starred_by query string Narrow to projects the caller has starred. Only me is accepted (stars are private); any other value, including empty, is rejected with 400. Combines with the other filters and never widens visibility.
scope query string: org, private Narrow to organization or private projects; omitted lists every project the caller can see. Others' private projects never appear.

回包

POST /api/v1/projects

Create a project

权限(scope): work:project:write · 调用方式: appToken · operationId: create-project

Required app scope: work:project:write.

Creates a new project. scope=private creates a project visible only to the caller and the caller's Agents that are members: human callers only (400 PROJECT_SCOPE_INVALID), refused with 403 PRIVATE_SCOPE_DISABLED while automation_private_scope_enabled is off; the caller is owner and fixed lead (any other lead_member_id: 400 PROJECT_SCOPE_INVALID); member_ids may list only the caller's own active Agents (400 PROJECT_PRIVATE_MEMBER_INVALID); knowledge_base_id must be the caller's private knowledge base (400 PROJECT_KB_SCOPE_MISMATCH) and defaults to the caller's personal knowledge base, created when missing; slug is assigned by the platform. Response wrapped in standard envelope.

请求体

application/json · CreateProjectRequestBody

字段 类型 必填 说明
description string Project description
is_default boolean Whether this is the organization default project
knowledge_base_id string (uuid) Knowledge base UUID; if omitted the org default KB is used (a private project uses the caller's personal knowledge base)
lead_member_id string (uuid) Lead member UUID. Required for an organization project; for a private project omit it or pass the caller (the owner is always the lead).
member_ids array of string Initial project member UUIDs created atomically with the project; for a private project only the caller's own active Agents
name string 是 Project name
scope string: org, private org (default) or private. A private project is visible only to its owner (the caller) and the owner's Agents that are members; creating one needs automation_private_scope_enabled.
slug string Optional project slug. Auto-generated from name when omitted.

回包

GET /api/v1/projects/{project_id}

Get project details

权限(scope): work:project:read · 调用方式: appToken · operationId: get-project

Required app scope: work:project:read.

Returns detailed information about a specific project. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID

回包

PATCH /api/v1/projects/{project_id}

Update a project

权限(scope): work:project:write · 调用方式: appToken · operationId: update-project

Required app scope: work:project:write.

Updates project metadata. The Owner's hidden project of automations attached to no project cannot be changed (409 WORK_PROJECT_SYSTEM_MANAGED). Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID

请求体

application/json · UpdateProjectRequestBody

字段 类型 必填 说明
description string Update project description
knowledge_base_id string (uuid) Update default knowledge base for new issues; existing issues retain their knowledge base
lead_member_id string (uuid) Update lead member UUID
name string Update project name

回包

POST /api/v1/projects/{project_id}/archive

Archive a project

权限(scope): work:project:write · 调用方式: appToken · operationId: archive-project

Required app scope: work:project:write.

Archives a project. There is no hard delete: archiving is how a project is removed. The Owner's hidden project of automations attached to no project cannot be archived (409 WORK_PROJECT_SYSTEM_MANAGED). Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID

回包

GET /api/v1/projects/{project_id}/members

List project members

权限(scope): work:project:read · 调用方式: appToken · operationId: list-project-members

Required app scope: work:project:read.

Returns the project's members. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID
page query integer (int32) Page number (default: 1)
page_size query integer (int32) Items per page (default: 20, max: 100)
order_by query string Sort expression, e.g. created_at:desc

回包

POST /api/v1/projects/{project_id}/members

Add project member

权限(scope): work:project:write · 调用方式: appToken · operationId: add-project-member

Required app scope: work:project:write.

Adds a member to a project. The Owner's hidden project of automations attached to no project takes members only through an automation write's project_member_additions (409 WORK_PROJECT_SYSTEM_MANAGED here). Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID

请求体

application/json · AddProjectMemberRequestBody

字段 类型 必填 说明
member_id string (uuid) 是 Member UUID
role string: member, lead 是 Project member role

回包

DELETE /api/v1/projects/{project_id}/members/{member_id}

Remove project member

权限(scope): work:project:write · 调用方式: appToken · operationId: remove-project-member

Required app scope: work:project:write.

Removes a member from a project. The project's current lead (a private project's owner included) cannot be removed, by anyone, the lead included: 409 WORK_PROJECT_LEAD_NOT_REMOVABLE, nothing changes; change the lead first. On the Owner's hidden project of automations attached to no project, only a member that leads no automation (enabled or paused) targeting it can be removed, such as a former Lead Agent; the Owner and a current Lead answer 409 WORK_PROJECT_SYSTEM_MANAGED. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID
member_id path string (uuid) 是 Member UUID

回包

POST /api/v1/projects/{project_id}/restore

Restore an archived project

权限(scope): work:project:write · 调用方式: appToken · operationId: restore-project

Required app scope: work:project:write.

Disabled in v0.7. The route is kept for compatibility and returns 412.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID

回包

POST /api/v1/projects/{project_id}/star

Star project

权限(scope): work:project:write · 调用方式: appToken · operationId: star-project

Required app scope: work:project:write.

Stars a project for the current user. Stars are private to the caller; there is no way to star on behalf of another member. Idempotent. The caller must be able to see the project (403 / 404 otherwise, same as get-project). Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID

回包

POST /api/v1/projects/{project_id}/unstar

Unstar project

权限(scope): work:project:write · 调用方式: appToken · operationId: unstar-project

Required app scope: work:project:write.

Removes the current user's star from a project. Idempotent: unstarring a project that is not starred succeeds. No visibility check, so a star can be cleared after losing access to the project. Response wrapped in standard envelope.

参数

名字 位置 类型 必填 说明
project_id path string (uuid) 是 Project UUID

回包