OpenMax
Free Trial

Apps API · Projects

Projects: 13 endpoints

← All groups

GET /api/v1/me/private-workspace

Get the caller's private workspace status

Scope: work:project:read · Called with: 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.

Responses

POST /api/v1/me/private-workspace

Ensure the caller's personal private project and knowledge base

Scope: work:project:write · Called with: 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.

Request body

application/json · EnsurePrivateWorkspaceRequestBody

Field Type Required Description
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"

Responses

GET /api/v1/projects

List projects

Scope: work:project:read · Called with: 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.

Parameters

Name In Type Required Description
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.

Responses

POST /api/v1/projects

Create a project

Scope: work:project:write · Called with: 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.

Request body

application/json · CreateProjectRequestBody

Field Type Required Description
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 yes 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.

Responses

GET /api/v1/projects/{project_id}

Get project details

Scope: work:project:read · Called with: appToken · operationId: get-project

Required app scope: work:project:read.

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

Parameters

Name In Type Required Description
project_id path string (uuid) yes Project UUID

Responses

PATCH /api/v1/projects/{project_id}

Update a project

Scope: work:project:write · Called with: 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.

Parameters

Name In Type Required Description
project_id path string (uuid) yes Project UUID

Request body

application/json · UpdateProjectRequestBody

Field Type Required Description
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

Responses

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

Archive a project

Scope: work:project:write · Called with: 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.

Parameters

Name In Type Required Description
project_id path string (uuid) yes Project UUID

Responses

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

List project members

Scope: work:project:read · Called with: appToken · operationId: list-project-members

Required app scope: work:project:read.

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

Parameters

Name In Type Required Description
project_id path string (uuid) yes 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

Responses

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

Add project member

Scope: work:project:write · Called with: 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.

Parameters

Name In Type Required Description
project_id path string (uuid) yes Project UUID

Request body

application/json · AddProjectMemberRequestBody

Field Type Required Description
member_id string (uuid) yes Member UUID
role string: member, lead yes Project member role

Responses

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

Remove project member

Scope: work:project:write · Called with: 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.

Parameters

Name In Type Required Description
project_id path string (uuid) yes Project UUID
member_id path string (uuid) yes Member UUID

Responses

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

Restore an archived project

Scope: work:project:write · Called with: appToken · operationId: restore-project

Required app scope: work:project:write.

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

Parameters

Name In Type Required Description
project_id path string (uuid) yes Project UUID

Responses

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

Star project

Scope: work:project:write · Called with: 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.

Parameters

Name In Type Required Description
project_id path string (uuid) yes Project UUID

Responses

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

Unstar project

Scope: work:project:write · Called with: 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.

Parameters

Name In Type Required Description
project_id path string (uuid) yes Project UUID

Responses