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.
回包
200OK —application/json·DataResponsePrivateWorkspaceStatusBodydefaultError —application/problem+json·D8Error
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" |
回包
200OK —application/json·DataResponsePrivateWorkspaceResultBodydefaultError —application/problem+json·D8Error
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. |
回包
200OK —application/json·PageListResponseProjectItemBodydefaultError —application/problem+json·D8Error
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. |
回包
200OK —application/json·DataResponseProjectItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseProjectItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseProjectItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseProjectItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·PageListResponseProjectMemberItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseProjectMemberItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseProjectItemBodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
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 |
回包
200OK —application/json·DataResponseStruct {}BodydefaultError —application/problem+json·D8Error
