# Fetching a list of Workspaces Gets a list of projects. This endpoint has its own rate limit. See the Knowledge Base for more information. #### Archived Projects By default, archived projects are not returned in the response. Use the include_archived=true filter to retrieve archived projects. This endpoint returns structured Workspace objects. As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the results array and will be indexed by ID in the workspaces top-level JSON key. Please see our Response Format section for more information. Endpoint: GET /workspaces Version: 1.0.0 ## Query parameters: - `account_color_ids` (string) Filter by color ID. Provide a comma-separated list of color IDs. - `archived` (string) Filter for only archived projects, or include or exclude archived projects from the results. Options are only, exclude, and include. - `budgeted` (boolean) Return only budgeted projects (true) or only non-budgeted projects (false). - `by_custom_choice_value` (string) Filter by a custom field choice value, represented as a string with the custom field ID, followed by a colon, and then comma-separated custom field choice value IDs. The custom field choice value can also be the word blank. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - custom_field_ID:choice_value_ID - custom_field_ID:choice_value_1_ID,choice_value_2_ID - custom_field_ID:blank - (custom_field_1_ID:choice_value_1_ID,choice_value_2_ID):(custom_field_2_ID:choice_value_3_ID). - `by_custom_currency_value` (string) Filter by a custom field currency value, represented as a string with the custom field ID, followed by a colon, and then the currency value. Optionally, the currency ISO code can be supplied as well, separated from the currency value by another colon. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - (1:200.2:USD):(2:100). - `by_custom_date_value` (string) Filter by a custom field date value, represented as a string with the custom field ID, followed by a colon, the starting date, another colon, and then the ending date. You can provide both a starting date and ending date, or provide just one. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - (1:2014-12-05:2014-12-25):(2:2014-12-05). - `by_custom_number_value` (string) Filter by a custom field number value, represented as a string with the custom field ID, followed by a colon, and then the number value. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - (1:200):(2:101). - `by_custom_text_value` (string) Filter by a custom field text value, represented as a string with the custom field ID, followed by a colon, and then the text value. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - (1:something):(2:else). - `can_create_line_items` (boolean) Return only projects where the authenticated user can create expenses or time entries (true) or only projects where the user can't (false). - `created_after` (string) Filter for records created after a specified datetime. The datetime must be in ISO 8601 format. - `created_at` (string) (Deprecated) Use the created_before and created_after filters instead. Filter for projects created between a specified date range. Format as from_date;to_date. Dates must be in ISO 8601 format. For example, 2014-12-05;2014-12-25. - `created_before` (string) Filter for records created before a specified datetime. The datetime must be in ISO 8601 format. - `creator` (string) Filter for projects created by a specific user(s). Provide a comma-separated list of user IDs. For example, 10,20. - `current_user_is_maven_participant` (boolean) Filter for projects where the authenticated user is on the provider team. When included in your request, this filter is always processed as true; the actual value you provide is ignored. - `custom_date_range` (string) Filter for projects with date custom field value(s) within a specified range. Format as custom_field_id:from_date:to_date;custom_field_id:from_date:to_date. Multiple custom fields can be delimited by semicolons. Dates must be in ISO 8601 format. For example, 1:2014-12-05:2014-12-25;2:2015-12-05:2015-12-25. - `custom_integer_ranges` (string) Filter for projects with number custom field value(s) within a specified range. Format as custom_field_id:min:max;custom_field_id:min:max. Multiple custom fields can be delimited by semicolons. For example, 42:20:10;43:50:100. - `due_date_after` (string) Filter for projects that are due after the specified date. Can be used with due_date_before to filter by a date range. The date must be in ISO 8601 format. - `due_date_before` (string) Filter for projects that are due before the specified date. Can be used with due_date_after to filter by a date range. The date must be in ISO 8601 format. - `except` (string) Filter out specific projects from the results. Provide a comma-separated list of workspace IDs. - `external_reference_external_message` (string) Filter the objects based on the external message of their associated external references. This is an exact match. - `external_reference_external_status` (string) Filter by the status of the external object in the external system. - `external_reference_service_model` (string) Filter by the type of the external object this external reference belongs to. - `external_reference_service_model_ref` (integer) Filter by the id of the external object this external reference belongs to. - `external_reference_service_model_refs` (string) Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs. - `external_reference_service_name` (string) Filter by the name of the provider for integration. - `external_reference_status` (string) Filter by the status of the integration, this can be successful or fail. - `financials_viewable_by_user` (boolean) Return only projects that the authenticated user can view, has financial access in, and is on the provider team. If false, no filtering is applied. - `for_approver` (integer) Filter for projects where the user with the specified user ID can approve time. - `has_approvers` (boolean) Return only projects that have an approver (true) or only projects that don't (false). - `has_external_references` (boolean) Filter by whether or not the object has external references. - `has_maven_participant` (integer) Filter for projects where the user with the specified user ID is on the provider team. - `has_participant` (integer) Filter for projects where the user with the specified user ID is a participant. - `has_participation` (boolean) Filter for projects where the authenticated user is a participant. - `has_value_for_custom_field_ids` (string) Filter by the presence of a custom field value for the specified comma-separated custom field ID(s). - `include` (string) Any of the below associations can be included in your request by providing the include param, e.g. include=association1,association2. - account_color (AccountColor) - Retrieves the color of the workspace. The response will include account_color_id, which references the data in the account_colors top-level key. - account_insights_mappings (AccountInsightsMapping) - Retrieves the Insights dynamic dashboards in the workspace. The response will include account_insights_mapping_ids, which references the data in the account_insights_mappings top-level key. - approver (User) - Retrieves the first approver (as determined by user ID) on the workspace who is viewable to the current user. The response will include approver_id, which references the data in the users top-level key. - approvers (User) - Retrieves all time approvers on the workspace who are viewable to the current user. The response will include approver_ids, which references the data in the users top-level key. - billing_milestones (BillingMilestone) - Retrieves the billing milestones for the workspace. The response will include billing_milestone_ids, which references the data in the billing_milestones top-level key. - creator (User) - Retrieves the user who created the project. The response will include creator_id, which references the data in the users top-level key. If the creator has left the project, you can use primary_counterpart to get the provider-side team lead. - current_status_report (StatusReport) - Retrieves the most recent project status report from today. The response will include current_status_report_id, which references the data in the status_reports top-level key. - current_user_participation (Participation) - Retrieves the workspace participation of the current user. The response will include current_user_participation_ids, which references the data in the participations top-level key. - custom_field_values (CustomFieldValue) - Retrieves custom field values for the workspace. The response will include custom_field_value_ids, which references the data in the custom_field_values top-level key. - external_references (ExternalReference) - Includes references to external integrations for this object. - financial_viewers (User) - Retrieves the users on the project who have financial access. The response will include financial_viewer_ids, which references the data in the users top-level key. - next_uncompleted_milestone (Story) - Retrieves the next project milestone that is not complete. The response will include next_uncompleted_milestone_id, which references the data in the stories top-level key. - participants (User) - Retrieves users that are participating in the project. The response will include participant_ids, which references the data in the users top-level key. - participations (Participation) - Retrieves the participations of each participant in the project. The response will include participation_ids, which references the data in the participations top-level key. - possible_approvers (User) - Retrieves the users that can be made time approvers on the workspace. The response will include possible_approver_ids, which references the data in the users top-level key. - primary_counterpart (User) - Retrieves the lead of the Clients team. The response will include primary_counterpart_id, which references the data in the users top-level key. - primary_maven (User) - Retrieves the lead of the Providers team. The response will include primary_maven_id, which references the data in the users top-level key. - primary_workspace_group (WorkspaceGroup) - Retrieves the primary group associated with the project. The response will include primary_workspace_group_id, which references the data in the workspace_groups top-level key. - status_reports (StatusReport) - Retrieves the status reports for the workspace. The response will include status_report_ids, which references the data in the status_reports top-level key. - timesheet_submissions (TimesheetSubmission) - Retrieves the list of all submitted timesheets which the user can approve on the project. The response will include timesheet_submission_ids, which references the data in the timesheet_submissions top-level key. - workspace_groups (WorkspaceGroup) - Retrieves groups associated with the project that is visible to the current user. The response will include workspace_group_ids, which references the data in the workspace_groups top-level key. - workspace_resources (WorkspaceResource) - Retrieves the named resources for the workspace. The response will include workspace_resource_ids, which references the data in the workspace_resources top-level key. - workspace_resources_with_unnamed (WorkspaceResource) - Retrieves the named and unnamed resources for the workspace. The response will include workspace_resources_with_unnamed_ids, which references the data in the workspace_resources top-level key. - `include_archived` (boolean) Include (true) or exclude (false) archived projects from the results. - `matching` (string) Filter for projects with a title that match the specified string. This filter is not case sensitive. This filter functions as a "starts with" filter for each word in project titles. Additionally, the following common words (known as stop words) are ignored: a, an, and, are, as, at, be, but, by, for, if, in, into, is, it, no, not, of, on, or, such, that, the, their, then, there, these, they, this, to, was, with. - `milestone_weight_percentage_complete` (string) Filter for projects which have a milestone percent completion within the specified range. Provide two comma-separated numbers. For example, 15,30. - `on_account_by_orgs` (boolean) Filter for projects that are on the authenticated user’s account and within the organization hierarchy the authenticated user is a part of. Requires the Report Viewer account permission or above. - `on_my_account` (boolean) Filter for projects that are on the same account as the authenticated user. - `only` (string) Allows you to request one or more resources directly by ID. Multiple IDs can be supplied in a comma separated list, like GET /api/v1/workspaces.json?only=5,6,7. - `only_joinable` (boolean) Filter for projects which the authenticated user can join and are within the organization hierarchy the user is a part of. - `only_participating_or_joinable` (boolean) Filter for projects which the authenticated user is participating in or can join. - `only_project_manager_in` (boolean) Filter for projects that are on the same account as the authenticated user, where the user is on the provider team, and where they have financial access or higher. - `optional_fields` (array) Allows you to request one or more optional fields as an array. Enum: "client_lead_name", "provider_lead_name", "stage", "estimated_minutes", "total_invoiced", "total_minutes_approved", "billable_minutes", "non_billable_minutes", "minutes_logged", "incoming_email_address", "lock_date" - `order` (string) Supply order with the name of a valid sort field for the endpoint and a direction. Valid values: amount_paid:asc, amount_paid:desc, color_name:asc, color_name:desc, created_at:asc, created_at:desc, custom_field::asc, custom_field::desc, due_date:asc, due_date:desc, last_viewed:asc, last_viewed:desc, percentage_complete:asc, percentage_complete:desc, price:asc, price:desc, provider_lead_name:asc, provider_lead_name:desc, search, start_date:asc, start_date:desc, status:asc, status:desc, task_status_set:asc, task_status_set:desc, title:asc, title:desc, updated_at:asc, and updated_at:desc. Note: The custom_field::asc and custom_field::desc options do not support multi-choice custom fields. - `page` (integer) - `participant_or_org_member_in` (boolean) Filter for projects that are on the same account as the authenticated user, that the user is participating in, and that are within the organization hierarchy the user is a part of. - `pending_timesheet_submissions` (string) Filter for projects that have pending timesheet submissions within a specified date range. Format as from_date;to_date. Dates must be in ISO 8601 format. For example, 2014-12-05;2014-12-25. - `per_page` (integer) - `provider_lead` (string) Filter for projects with the specified provider team leads. Provide a comma-separated list of user IDs. For example, 10,20. - `require_time_approvals` (boolean) Return only projects that require time approvals (true) or only projects that don't (false). - `requiring_expense_approval` (boolean) Return only projects that require expense approvals (true) or only projects that don't (false). - `search` (string) The search parameter filters for projects that match one or more keywords. By default, the following fields are searched: - workspace_id - title - description - full_name of the primary_maven (i.e. the Provider team lead) - full_name of the primary_counterpart (i.e. the Client team lead) - name of workspace_groups, including the primary_workspace_group - display_value of custom_field_values (Excluding currency and date custom fields) You can search on specific fields using the format search=field_name:'keyword'. For example, search=description:'acme'. This is supported for the following fields: - title - description - group - Searches only the name field of workspace_groups. The keyword must match the entire name of the group (i.e. not a partial match). - custom_field_value - Searches the display_value of custom_field_values. (Excluding currency and date custom fields.) - status - Searches only the message field of the project status. The keyword must match the entire name of the project status (i.e. not a partial match). To combine multiple field-specific search terms, separate them by a space. For example, search=title:'acme' description:'website'. You can combine a field-specific search term with general search terms. For example, search=description:'acme' design. - `selected_choices` (string) Filter for projects that have a specific choice selected for a choice custom field. Format as custom_field_id:choice_ids;custom_field_id:choice_ids. Pass none to indicate no selection. Multiple custom fields can be delimited by semicolons. For example: 1:3,2;4:2,none. - `stage` (string) Return only projects in the estimate stage or project stage. Options are estimate and project. - `start_date_after` (string) Filter for projects that start after the specified date. Can be used with start_date_before to filter by a date range. The date must be in ISO 8601 format. - `start_date_before` (string) Filter for projects that start before the specified date. Can be used with start_date_after to filter by a date range. The date must be in ISO 8601 format. - `updated_after` (string) Filter for records updated after a specified datetime. The datetime must be in ISO 8601 format. - `updated_before` (string) Filter for records updated before a specified datetime. The datetime must be in ISO 8601 format. - `user_not_participating` (integer) Filter for projects where the user with the specified ID is not participating. - `viewable_for_time_administration` (boolean) Return only projects where the authenticated user can approve time. Can be used in combination with the include_archived filter. - `with_organizations` (boolean) Only includes projects that have an organization (true) or only includes projects that do not have an organization (false). - `without_external_reference_service_name` (string) Exclude by the existence of an external reference with the specified service name. - `workspace_groups` (string) Filter for projects that are associated with the specified project groups. Provide a comma-separated list of group IDs. For example, 10,20. ## Response 200 fields (application/json): - `count` (integer) - `meta` (object) - `meta.count` (integer) - `meta.page_count` (integer) - `meta.page_number` (integer) - `meta.page_size` (integer) - `results` (array) - `results.key` (string) - `results.id` (string) - `workspaces` (object) - `external_references` (object) - `stories` (object) - `users` (object) - `participations` (object) - `timesheet_submissions` (object) - `workspace_groups` (object) - `custom_field_values` (object) - `workspace_resources` (object) - `status_reports` (object) - `account_colors` (object) - `account_insights_mappings` (object) - `billing_milestones` (object) ## Response 400 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 401 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 403 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 404 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 422 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 503 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string)