Docs
Contents

Organization project governance (inactive queries / batch deletion / restore)

Overview and use cases

A set of project lifecycle governance capabilities for organization Owner: query inactive projects in the organization, initiate delayed batch deletion after a dry run precheck, query projects in the deletion lifecycle, and restore projects still in the pending_purge state. Both 2.6.0's agentbase-web-sdk@2.8.0 and agentbase-node-sdk@2.8.0 include the corresponding methods (the Projects service for Web/Node); controlled integrations without an SDK can use the equivalent REST API.

Prerequisites

ItemDescription
RoleThe current account must be an Owner of the target organization; ordinary organization members have no permission
AuthenticationOwner Session (preferred for interactive use), short-term Owner JWT (preferred for automation, account.createJWT issuance, default 15 minutes); an Organization API Key is only an option when the target environment has been delivered and provides projects.read/projects.write
ClientManagement-plane requests point to the Console project (setProject('console') or the environment's actual Console project ID) and setOrganization(teamId) declare the organization (X-Appwrite-Organization header)
ScopeQuery-type operations (inactive list, deletion list) require projects.read; batch deletion and restore require projects.write

An ordinary project API Key cannot substitute for organization-level credentials; the existence of an organization Key method in the SDK does not mean the target instance exposes the corresponding creation entry point. When a Key is unavailable, governance is not blocked—use Session / JWT instead.

Usage workflow

Fixed workflow (deletion is a high-risk operation; do not automate it into “query results deleted directly”):

  1. Query candidates: use Projects.listInactiveByOrganization to page through inactive projects and verify them manually.

  2. Fixed list: the Owner explicitly selects 1–50 project IDs and the audit reason.

  3. Dry run precheck: batchReleaseByOrganization({ dryRun: true }), then verify each project's results and summary (accepted / rejected / skipped).

  4. Formal submission after second confirmation: dryRun: false, with the same list and the same reason.

  5. Track the deletion lifecycle: use listDeletionsByOrganization to view pending_purge / purging / purge_failed sorted by deletedAt descending.

  6. Restore (optional): re-read the latest state, confirm the target project is still pending_purge, then have the Owner specify a single projectId and call restoreDeletionByOrganization; a successful restore clears deletion metadata.

Console equivalent entry point: the organization “Project Cleanup” page <console-origin>/console/organization-{organizationId}/project-cleanup; the Console directly submits formal deletion (showing all accepted / partially accepted / rejected with a failure summary). Use the SDK / REST when per-project precheck results are needed.

Key parameters and returns

Method and REST mapping

OperationRESTScope
Query inactive projectsGET /v1/teams/{teamId}/projects/inactiveprojects.read
Precheck / batch deletePOST /v1/teams/{teamId}/projects/batch-releaseprojects.write
Query deletion lifecycleGET /v1/teams/{teamId}/projects/deletionsprojects.read
Restore pending-deletion projectDELETE /v1/teams/{teamId}/projects/{projectId}/deletionprojects.write

The corresponding SDK methods are described in the operation sections below; they all belong to the Projects service of the Web/Node SDK.

Parameter essentials

All methods must pass teamId, whose value is the canonical Team ID corresponding to the organization; the Console-exposed organizationId cannot be used directly. The table below lists only the other parameters of each method, with each marked individually as required or not.

Inactive project query parameters

Method to call: Projects.listInactiveByOrganization.

ParameterRequiredDescription
inactiveDaysYesInactivity time threshold, range 1–365 days.
graceDaysNoGrace period after project creation, default 7 days.
limitNoItems per page, range 1–500, default 100.
cursorNoWhen continuing to the next page, pass back the previous page's nextCursor as-is.

Only configure the parameters above; do not pass filters such as criteria, signals, or preset. The response returns candidate projects and pagination info; for activity determination and the meaning of total, see “Response and activity semantics” below.

Precheck and batch deletion parameters

Method to call: Projects.batchReleaseByOrganization.

ParameterRequiredDescription
projectIdsYesArray of project IDs, 1–50 per call, using the Owner-confirmed fixed list.
dryRunNoPass true for precheck, false for formal submission. This page's workflow requires explicitly passing the value each time—precheck first, then submit after confirmation.
reasonNoAudit reason, filled in per the workflow above; use the same reason for both precheck and formal submission.

The response contains the request ID requestId, per-project results results, and a summary summary. The summary distinguishes accepted, rejected, and skipped; do not assume all projects were accepted just because the request succeeded.

Deletion lifecycle query parameters

Method to call: Projects.listDeletionsByOrganization.

ParameterRequiredDescription
limitNoItems per page, range 1–100, default 25.
offsetNoPagination offset.

Returns the list of projects in the deletion lifecycle. Projects in the list are not necessarily restorable; their deletionStatus must be checked.

Pending-deletion project restore parameters

Method to call: Projects.restoreDeletionByOrganization.

ParameterRequiredDescription
projectIdYesA single project explicitly specified by the Owner; its current state must be pending_purge.

On success, status is restored and includes projectId and requestId.

Response and activity semantics

Errors and boundaries

SDK Category Differences

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Query inactive projects

listInactiveByOrganization Page through candidates, verify manually, then fix the list.

const { Account, Client, Projects } = require('agentbase-node-sdk');

const teamId = process.env.APPBASE_ORGANIZATION_TEAM_ID;   // canonical Team ID
const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT)
    .setProject(process.env.APPWRITE_CONSOLE_PROJECT_ID || 'console');  // Management plane points to a Console project

const account = new Account(client);
const session = await account.createEmailPasswordSession({  // The current account must be the organization Owner
    email: process.env.APPBASE_OWNER_EMAIL,
    password: process.env.APPBASE_OWNER_PASSWORD
});
client.setSession(session.secret).setOrganization(teamId);  // or setJWT(shortLivedOwnerJwt)
const projects = new Projects(client);

const page = await projects.listInactiveByOrganization({
    teamId,
    inactiveDays: 90,      // Required, 1-365
    graceDays: 7,          // Optional, default 7
    limit: 50              // Optional, 1-500, default 100
    // cursor: pass back the previous page's nextCursor as-is
});
// page: { inactiveDays, projects[], total, scanned, nextCursor? }
// total is the match count of this bounded scan (at most 50 projects scanned per request), not the organization-level exact total

Dry run precheck and batch deletion

batchReleaseByOrganization: the Owner fixes 1–50 project IDs and an audit reason, first dryRun: true, then after second confirmation dryRun: false.

// For client / projects initialization, see the previous card; projectIds is a fixed list scoped by the Owner (1-50 items), not selected directly in full from query results
const fixedProjectIds = ['project-a', 'project-b'];
const reason = '长期无资源活动,业务负责人已确认';

const preview = await projects.batchReleaseByOrganization({
    teamId, projectIds: fixedProjectIds, dryRun: true, reason
});
// preview: { requestId, results[], summary: { accepted, rejected, skipped } }
if (preview.summary.rejected > 0 || preview.summary.skipped > 0) {
    throw new Error('预检未全部通过,重新核对固定清单');
}

const submitted = await projects.batchReleaseByOrganization({
    teamId, projectIds: fixedProjectIds, dryRun: false, reason   // After secondary confirmation, formally submit the same checklist
});

Deletion lifecycle and restore

listDeletionsByOrganization View pending_purge / purging / purge_failed sorted by deletedAt descending; only pending_purge items can be restored by the Owner specifying a single project.

// For client / projects initialization, see the first card
const deletions = await projects.listDeletionsByOrganization({ teamId, limit: 25, offset: 0 });
// deletions.projects[]: { projectId, name, teamId, deletionStatus, deletedAt, purgeAt, ... }

const selectedProjectId = 'project-id-confirmed-by-owner';   // Owner must be specified explicitly; do not auto-select the first in the list
const selected = deletions.projects.find((p) => p.projectId === selectedProjectId);
if (!selected || selected.deletionStatus !== 'pending_purge') {
    throw new Error('指定项目不在当前页,或已不可恢复');
}

const restored = await projects.restoreDeletionByOrganization({ teamId, projectId: selectedProjectId });
// On success returns { status: 'restored', projectId, requestId }; 409 means the status has changed — re-query instead of retrying

Example Guide