Projects

This endpoint manages workflow projects within the organization.

Overview

The Projects API allows you to create, update, and manage workflow projects. Projects serve as containers for work activities, providing structure and organization for tasks, deliverables, and team collaboration.

Key Features

• Create and configure workflow projects
• Manage project membership and team assignments
• Track project status and progress
• Organize work into structured activities and work units
• Support for project templates and duplication

Project Organization

Projects can be organized by:

• Customer’s organization
• Organizational unit
• Project type and category
• Custom attributes and tags

Related Endpoints

• Members API: Manage project team members and their roles
• Activities API: Organize work within projects
• Work Units API: Track individual tasks and deliverables
• Work Periods API: Manage time tracking for project activities

Endpoints

• get /api/v3/workflow/projects
• post /api/v3/workflow/projects
• post /api/v3/workflow/projects/:id/autoselect
• post /api/v3/workflow/projects/:id/duplicate
• get /api/v3/workflow/projects/:resource_id
• patch /api/v3/workflow/projects/:resource_id

get/api/v3/workflow/projects

Return a paginated list of workflow/projects

type InputSchema = {
  page?: {
    // The page number, default to 1
    number?: number;
    // The number of items per page, default to 1000
    size?: number;
  };
  // The sort order, comma separated list of fields. See sorting section for more details
  sort?: string;
  // Set to true to return the total number of items in the collection
  count?: boolean;
  filter?: {
    id?: any;
    name?: any;
    enabled?: any;
    readonly?: any;
    organization_id?: any;
    organizational_unit?: any;
    created_at?: any;
    updated_at?: any;
    definition?: any;
    name__match?: any;
    organization?: any;
    organizational_unit?: any;
    enabled?: any;
  };
  // The related resources to include in the response. Allowed resources are:
  // - `members`
  included?: Array<string>;
  // The fields to include in the response.
  // The key is the resource type and the value is an array of fields.
  fields?: { [key: string]: Array<any> };
};

type OutputSchema = {
  data: Array<{
    type: string;
    id?: string;
    attributes?: {
      id?: number;
      name?: string;
      enabled?: boolean;
      readonly?: boolean;
      organization_id?: number;
      organizational_unit?: string;
      created_at?: Date;
      updated_at?: Date;
      definition?: Record<string, any>;
    };
    relationships?: Record<string, any>;
  }>;
  included?: Array<Record<string, any>>;
};

post/api/v3/workflow/projects

Create a new project within the organization.

This endpoint allows you to create a new project within the organization. Projects serve as containers for work activities, providing structure and organization for tasks, deliverables, and team collaboration.

Behavior

• Creates a new project record with the specified properties
• Optionally enables or disables the project
• Optionally sets the project as read-only
• Supports defining project with a JSON (object or string) or YAML (string) formats

Response

Returns the newly created project record with complete project data.

type InputSchema = {
  data: {
    type: string;
    attributes: {
      name: string;
      organization_id: number;
      organizational_unit: string;
      definition: Record<string, any> | string;
      enabled?: boolean;
      readonly?: boolean;
    };
  };
};

post/api/v3/workflow/projects/:id/autoselect

Automatically select and assign an activity to the current user.

This endpoint finds the best available activity for the current user in the specified project and assigns it to them. Activities are selected based on priority criteria including:

• Priority value (higher values are selected first)
• Creation date (older activities are selected first)
• Assignment status (activities already assigned to the user are prioritized)

The endpoint uses a locking mechanism to prevent race conditions when multiple users request activities simultaneously.

Behavior

• Checks if the user is a member of the project
• Finds activities matching the user’s roles that are not blacklisted
• Prioritizes activities based on priority value, creation date, and assignment status
• Uses Redis locks to prevent race conditions
• Assigns and starts the selected activity for the user

Response

Returns the assigned activity record with node information included.

Errors

• 404 Not Found: No suitable activity is available
• 422 Unprocessable Entity: User is not a member of the project

type InputSchema = { id: any };

post/api/v3/workflow/projects/:id/duplicate

Create a duplicate copy of an existing project.

This endpoint allows you to create a complete copy of an existing project, including its structure, settings, and configurations. This is useful for creating new projects based on established templates or for creating similar projects without starting from scratch.

Behavior

• Creates a new project record with the same properties as the source project
• Duplicates the project structure (activities, work units, etc.)
• Optionally copies team membership assignments
• Appends “(Copy)” to the name of the duplicated project

Response

Returns the newly created project record with complete project data.

type InputSchema = { id: any };

get/api/v3/workflow/projects/:resource_id

Show a specific workflow/projects

type InputSchema = {
  resource_id: number;
  included?: Array<string>;
  fields?: { [key: string]: Array<any> };
};

type OutputSchema = {
  data: {
    type: string;
    id?: string;
    attributes?: {
      id?: number;
      name?: string;
      enabled?: boolean;
      readonly?: boolean;
      organization_id?: number;
      organizational_unit?: string;
      created_at?: Date;
      updated_at?: Date;
      definition?: Record<string, any>;
    };
    relationships?: Record<string, any>;
  };
  included?: Array<Record<string, any>>;
};

patch/api/v3/workflow/projects/:resource_id

Update a workflow/projects

type InputSchema = {
  resource_id: number;
  data: {
    type: string;
    attributes: {
      id?: number;
      name?: string;
      enabled?: boolean;
      readonly?: boolean;
      organization_id?: number;
      organizational_unit?: string;
      created_at?: Date;
      updated_at?: Date;
      definition?: Record<string, any>;
    };
  };
};