​

projects

orc projects creates Projects in a Workspace, updates plans such as owners, dates, and priorities, and retrieves progress rollups. Archive unused Projects and restore them later.

Authentication and a selected Workspace are required. The project_key supplied on creation is a lookup key unique within the Workspace and cannot be changed through updates. Pass this key to get, update, archive, and restore.

List Projects in the Workspace.

Lists Projects. Include archived Projects with --include-archived, and paginate with --limit and --cursor.

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: string. Optional.

Include archived projects in the response.; enum: true|false

Type: string. Optional.

Creates a Project using project_key and name. If status is omitted on creation, it defaults to planned. You can also specify an initiative_id in the same Workspace or milestone JSON.

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) Project lookup key, unique within the workspace. Must not contain slash, backslash or two consecutive dots. This key cannot be changed through the update endpoint.

Type: string. Optional.

(required) Display name.

Type: string. Optional.

Project lifecycle status. Omitted on creation, it defaults to planned.; enum: planned|in_progress|paused|completed|canceled

Type: string. Optional.

Project priority; null means unassigned.; enum: urgent|high|medium|low; (use "null" or "reset" to clear)

Type: string. Optional.

Active workspace member id of the project lead. null means no lead is assigned.; (use "null" or "reset" to clear)

Type: string. Optional.

Planned start as YYYY, YYYY-MM or YYYY-MM-DD. This is a calendar value, not a timestamp. null clears it.; (use "null" or "reset" to clear)

Type: string. Optional.

Target completion as YYYY, YYYY-MM or YYYY-MM-DD. This is a calendar value, not a timestamp. null clears it.; (use "null" or "reset" to clear)

Type: string. Optional.

Active workspace member ids assigned to this project. The array replaces the current assignment on update; an empty array clears it. These assignments do not define the workspace access boundary.; csv

Type: string. Optional.

Project label values. The array replaces current labels on update; an empty array clears them. At most one label from each configured label group may be selected.; csv

Type: string. Optional.

Presentation precision for the planned start date. null leaves the precision unspecified.; enum: day|month|quarter|half_year|year; (use "null" or "reset" to clear)

Type: string. Optional.

Presentation precision for the target date. null leaves the precision unspecified.; enum: day|month|quarter|half_year|year; (use "null" or "reset" to clear)

Type: string. Optional.

Short project summary, separate from the detailed description. Null or empty clears it.; (use "null" or "reset" to clear); max 1000 chars

Type: string. Optional.

Optional description.

Type: string. Optional.

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: string. Optional.

Optional parent Initiative ID in the same Workspace.; (use "null" or "reset" to clear)

Type: string. Optional.

Optional embedded project milestone. Supply both name and date; omission or null stores no milestone. This does not create a record in the project milestones collection.

Type: string. Optional.

Project list ordering value; smaller values come first and equal values are ordered by projectKey. Creation appends after the current largest value when omitted.

Type: number. Optional.

Visual identity color token. Creation defaults to default when omitted.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red

Type: string. Optional.

Visual identity mode. Creation defaults to initial when omitted.; enum: color|initial|icon|emoji|image

Type: string. Optional.

Icon token used with identity_kind=icon. null clears the stored token.; (use "null" or "reset" to clear); max 64 chars

Type: string. Optional.

Emoji used with identity_kind=emoji. null clears the stored emoji.; (use "null" or "reset" to clear); max 32 chars

Type: string. Optional.

Uploaded image file id used with identity_kind=image. null clears the reference.; (use "null" or "reset" to clear)

Type: string. Optional.

Retrieves details by the Project lookup key. For organization-scoped credentials, specify the target Workspace with --workspace-id when needed.

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: string. Optional.

Updates the name, status, priority, lead, dates, display order, appearance, or Initiative association. visibility stores workspace or private metadata, but reads in this API are authorized at Workspace level; private does not create a separate member access boundary.

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: string. Optional.

Project display name.

Type: string. Optional.

Project lifecycle status. Omitted on creation, it defaults to planned.; enum: planned|in_progress|paused|completed|canceled

Type: string. Optional.

Project priority; null means unassigned.; enum: urgent|high|medium|low; (use "null" or "reset" to clear)

Type: string. Optional.

Active workspace member id of the project lead. null means no lead is assigned.; (use "null" or "reset" to clear)

Type: string. Optional.

Planned start as YYYY, YYYY-MM or YYYY-MM-DD. This is a calendar value, not a timestamp. null clears it.; (use "null" or "reset" to clear)

Type: string. Optional.

Target completion as YYYY, YYYY-MM or YYYY-MM-DD. This is a calendar value, not a timestamp. null clears it.; (use "null" or "reset" to clear)

Type: string. Optional.

Active workspace member ids assigned to this project. The array replaces the current assignment on update; an empty array clears it. These assignments do not define the workspace access boundary.; csv

Type: string. Optional.

Project label values. The array replaces current labels on update; an empty array clears them. At most one label from each configured label group may be selected.; csv

Type: string. Optional.

Presentation precision for the planned start date. null leaves the precision unspecified.; enum: day|month|quarter|half_year|year; (use "null" or "reset" to clear)

Type: string. Optional.

Presentation precision for the target date. null leaves the precision unspecified.; enum: day|month|quarter|half_year|year; (use "null" or "reset" to clear)

Type: string. Optional.

Short project summary, separate from the detailed description. Null or empty clears it.; (use "null" or "reset" to clear); max 1000 chars

Type: string. Optional.

Project description.

Type: string. Optional.

Project list ordering value; smaller values come first and equal values are ordered by projectKey. Creation appends after the current largest value when omitted.

Type: number. Optional.

Stored project visibility metadata. Project reads in this API are authorized at workspace level; private does not create a separate member access boundary.; enum: workspace|private

Type: string. Optional.

Visual identity color token. Creation defaults to default when omitted.; enum: default|gray|brown|orange|yellow|green|blue|purple|pink|red

Type: string. Optional.

Visual identity mode. Creation defaults to initial when omitted.; enum: color|initial|icon|emoji|image

Type: string. Optional.

Icon token used with identity_kind=icon. null clears the stored token.; (use "null" or "reset" to clear); max 64 chars

Type: string. Optional.

Emoji used with identity_kind=emoji. null clears the stored emoji.; (use "null" or "reset" to clear); max 32 chars

Type: string. Optional.

Uploaded image file id used with identity_kind=image. null clears the reference.; (use "null" or "reset" to clear)

Type: string. Optional.

Optional parent Initiative ID in the same Workspace.; (use "null" or "reset" to clear)

Type: string. Optional.

Embedded project milestone. Omit to preserve it, send null to clear it, or send both name and date to replace it. This does not update records managed by the project milestones collection.

Type: string. Optional.

Restores an archived Project by its lookup key.

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.

Archives a Project by its lookup key. For organization-scoped credentials, specify the containing Workspace with --workspace-id.

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.

Workspace context. Organization-scoped credentials must supply a workspace in their organization. Workspace-scoped API keys remain bound to their authenticated workspace; this value cannot redirect them to another workspace.

Type: string. Optional.

Retrieves a progress rollup using a Project ID or an existing Project key. This is separate from retrieving individual Project settings.

Create a Project with a lookup key and name.

Mark the Project as in progress.

Retrieve the progress rollup.

Restore an archived Project.

project_key cannot contain /, \, or consecutive ... The project_id used to associate an Issue with a Project is a UUID and differs from this lookup key. Initiative associations must remain within the same Workspace; clear one by sending null for initiative_id in an update body. Use orc projects milestones for milestone management.

The following global options can be used with orc projects:

For details and examples, see global options.