​

initiatives

orc initiatives creates Initiatives in a Workspace and updates their owner, priority, target date, and status. Add and reorder associated Projects, retrieve progress rollups, post comments and updates, and manage favorites and subscriptions. Deleted Initiatives can be restored.

Authentication and a selected Workspace are required. Updates must include version from the current response. Use a Project ID in the same Workspace when adding a Project.

List Initiatives in the Workspace.

Lists Initiatives with tab or status filters, ordering, and pagination. An explicit --status overrides the tab when both are supplied.

Convenience filter: active selects active; planned selects proposed and planned. all or omission applies no tab filter. An explicit status takes precedence.; enum: active|planned|all

Type: string. Optional.

Exact lifecycle-state filter. Overrides tab when both are supplied.

Type: string. Optional.

Sort field. Defaults to created_at; manual uses the shared numeric rank and target_date uses the target calendar date.; enum: created_at|target_date|manual

Type: string. Optional.

Sort direction. Defaults to descending for created_at and ascending for target_date or manual. Keep it unchanged while following a cursor.; enum: asc|desc

Type: string. Optional.

Creates an Initiative with a name. Names are trimmed and limited to 200 characters; blank names are rejected. You can also specify an owner, priority, target date, status, and labels.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

Optional display color token. Null clears it; omission in an update preserves it.; (use "null" or "reset" to clear); max 100 chars

Type: string. Optional.

Description text. Use an empty string to clear it.; max 2000 chars

Type: string. Optional.

Optional display icon token. Null clears it; omission in an update preserves it.; (use "null" or "reset" to clear); max 100 chars

Type: string. Optional.

Complete label set. Labels are trimmed and must be unique. Use [] to clear; omission in an update preserves the set.; csv

Type: string. Optional.

(required) Initiative name. Leading and trailing whitespace is removed; a blank name is rejected.; max 200 chars

Type: string. Optional.

Owner user ID belonging to this workspace. Null clears the owner; omission in an update preserves it.; (use "null" or "reset" to clear)

Type: string. Optional.

Priority label, or null when unset. Omission in an update preserves it.; enum: urgent|high|medium|low|; (use "null" or "reset" to clear)

Type: string. Optional.

Body field: status

Type: string. Optional.

Target calendar date in YYYY-MM-DD form. Supply target_precision with it; set both to null to clear the target.; (use "null" or "reset" to clear)

Type: string. Optional.

Target date granularity. Supply target_date together with this field; both must be non-null or both null.; enum: day|month|quarter|half_year|year|; (use "null" or "reset" to clear)

Type: string. Optional.

Retrieves current information by Initiative ID. Read the update version from this response.

Updates an Initiative using its ID and current version. A stale version causes a conflict. Omitted priority is preserved; null clears it. Use an empty string to clear the description.

Optional display color token. Null clears it; omission in an update preserves it.; (use "null" or "reset" to clear); max 100 chars

Type: string. Optional.

Description text. Use an empty string to clear it.; max 2000 chars

Type: string. Optional.

Optional display icon token. Null clears it; omission in an update preserves it.; (use "null" or "reset" to clear); max 100 chars

Type: string. Optional.

Complete label set. Labels are trimmed and must be unique. Use [] to clear; omission in an update preserves the set.; csv

Type: string. Optional.

Initiative name. Leading and trailing whitespace is removed; a blank name is rejected.; max 200 chars

Type: string. Optional.

Owner user ID belonging to this workspace. Null clears the owner; omission in an update preserves it.; (use "null" or "reset" to clear)

Type: string. Optional.

Priority label, or null when unset. Omission in an update preserves it.; enum: urgent|high|medium|low|; (use "null" or "reset" to clear)

Type: string. Optional.

Workspace-shared manual position as a non-negative decimal string. Lower values appear first for ascending manual order.; max 100 chars

Type: string. Optional.

Body field: status

Type: string. Optional.

Target calendar date in YYYY-MM-DD form. Supply target_precision with it; set both to null to clear the target.; (use "null" or "reset" to clear)

Type: string. Optional.

Target date granularity. Supply target_date together with this field; both must be non-null or both null.; enum: day|month|quarter|half_year|year|; (use "null" or "reset" to clear)

Type: string. Optional.

(required) Latest saved version from the Initiative response. A stale value returns a conflict; read the current resource before retrying.

Type: number. Optional.

Soft-deletes an Initiative by ID.

Retrieves an Initiative progress rollup, separate from retrieving individual settings.

Lists Projects associated with the Initiative. Paginate with --limit and --cursor.

Adds a Project in the same Workspace using project_id. Membership rank is a non-negative integer; when omitted, the Project display order is used.

(required) ID of a project in the same workspace.

Type: string. Optional.

Non-negative integer membership rank. Defaults to the project display order when omitted.

Type: number. Optional.

Reorders an associated Project using the Initiative ID, Project ID, and a new rank. Lower non-negative integer values appear first.

(required) New non-negative integer membership rank. Lower values appear first.

Type: number. Optional.

Removes an association using the Initiative ID and Project ID. This is separate from archiving the Project itself.

Lists Initiative activity.

Lists Initiative comments.

Posts a comment using an Initiative ID and body. Specify parent_id for a reply.

(required) Comment text. Trimmed before validation; must contain 1 to 10000 characters.; max 10000 chars

Type: string. Optional.

Top-level comment ID in this initiative. Omit or pass null to start a thread. Replies to replies are rejected.; (use "null" or "reset" to clear); max 500 chars

Type: string. Optional.

Adds the specified Initiative to favorites.

Removes the specified Initiative from favorites.

Restores a soft-deleted Initiative by ID.

Subscribes to the specified Initiative.

Unsubscribes from the specified Initiative.

Lists Initiative progress updates.

Posts an Initiative update using its ID, body, and health. This is separate from an ordinary comment.

(required) Progress-update text. Trimmed before validation; must contain 1 to 10000 characters.; max 10000 chars

Type: string. Optional.

(required) Body field: health

Type: string. Optional.

Executes multiple actions in JSON items. Items are processed independently in input order; result indices refer to the input array. Individual failures do not roll back successful items.

Retry identity for operations that support idempotency. Use a unique key for each new operation, and reuse it only when retrying the same HTTP method, path, query values and exact request body. JSON whitespace changes can count as a different body. Keys contain 1–255 characters after trimming and expire after 24 hours. A completed JSON response is replayed without repeating the operation. A different request using the same key returns 409 idempotency_error. An in-progress request returns 409 idempotency_in_progress with Retry-After: 2. Whether this header is required depends on the operation.

Type: string. Optional.

(required) Actions processed independently in input order. Each result index refers to this array. A malformed request is rejected before processing; reported item failures do not roll back successful items.; JSON array of objects (use --stdin for large resources)

Type: string. Optional.

Create an Initiative with a name.

Include the retrieved version and fields to change in the JSON.

Read current information and submit an update file.

Add a Project from the same Workspace.

Reorder an associated Project.

Retrieve the Initiative progress rollup.

If an update conflicts, read the current content and version with get, review the changes, and resubmit. Check each batch item’s result. A malformed request is rejected before processing, but individual failures do not undo successful items.

An Initiative’s own manual rank is a non-negative decimal string. In contrast, the rank of a Project’s membership in an Initiative is a non-negative integer. These order different resources; do not confuse their value types.

The following global options can be used with orc initiatives:

For details and examples, see global options.