Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: 1.0.0
title: Kantata OX API Documentation Workspaces API
description: Kantata OX's API provides access to the majority of Kantata OX's data model.
termsOfService: https://www.kantata.com/terms-of-use
contact:
name: Kantata OX Support
url: https://knowledge.kantata.com/hc/en-us
license:
name: COPYRIGHT © 2026 Kantata, Inc.
url: https://www.kantata.com/terms-of-use
x-logo:
url: https://theme.zdassets.com/theme_assets/56104/04e93064d309f75d054b8cee885d1ea51e9be8f7.png
backgroundColor: '#FFFFFF'
altText: Kantata OX API Documentation
href: https://developer.kantata.com
servers:
- url: https://api.mavenlink.com/api/v1
tags:
- name: Workspaces
description: Workspaces (also called projects) represent the space in which Kantata OX users plan, communicate, and collaborate.
paths:
/workspaces:
get:
summary: Fetching a list of Workspaces
description: '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.'
operationId: Get Workspaces
tags:
- Workspaces
parameters:
- in: query
name: account_color_ids
description: Filter by color ID. Provide a comma-separated list of color IDs.
schema:
type: string
- in: query
name: archived
description: Filter for only archived projects, or include or exclude archived projects from the results. Options are `only`, `exclude`, and `include`.
schema:
type: string
- in: query
name: budgeted
description: Return only budgeted projects (`true`) or only non-budgeted projects (`false`).
schema:
type: boolean
- in: query
name: by_custom_choice_value
description: '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)`.'
schema:
type: string
- in: query
name: by_custom_currency_value
description: '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](https://mavenlink.zendesk.com/hc/en-us/articles/360041576473) 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)`.'
schema:
type: string
- in: query
name: by_custom_date_value
description: '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)`.'
schema:
type: string
- in: query
name: by_custom_number_value
description: '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)`.'
schema:
type: string
- in: query
name: by_custom_text_value
description: '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)`
- `(1:something):(1:else)` (multiple values for the same field, returns objects matching any value)
- `1` (bare field ID with no value, returns all objects that have any value for that field).'
schema:
type: string
- in: query
name: can_create_line_items
description: Return only projects where the authenticated user can create expenses or time entries (`true`) or only projects where the user can't (`false`).
schema:
type: boolean
- in: query
name: created_after
description: Filter for records created after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: created_at
description: '(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](https://www.w3.org/TR/NOTE-datetime) format. For example, `2014-12-05;2014-12-25`.'
schema:
type: string
- in: query
name: created_before
description: Filter for records created before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: creator
description: Filter for projects created by a specific user(s). Provide a comma-separated list of user IDs. For example, `10,20`.
schema:
type: string
- in: query
name: current_user_is_maven_participant
description: 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.
schema:
type: boolean
- in: query
name: custom_date_range
description: 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](https://www.w3.org/TR/NOTE-datetime) format. For example, `1:2014-12-05:2014-12-25;2:2015-12-05:2015-12-25`.
schema:
type: string
- in: query
name: custom_integer_ranges
description: 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`.
schema:
type: string
- in: query
name: due_date_after
description: 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](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date
- in: query
name: due_date_before
description: 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](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date
- in: query
name: except
description: Filter out specific projects from the results. Provide a comma-separated list of workspace IDs.
schema:
type: string
- in: query
name: external_reference_external_message
description: Filter the objects based on the external message of their associated external references. This is an exact match.
schema:
type: string
- in: query
name: external_reference_external_status
description: Filter by the status of the external object in the external system.
schema:
type: string
- in: query
name: external_reference_service_model
description: Filter by the type of the external object this external reference belongs to.
schema:
type: string
- in: query
name: external_reference_service_model_ref
description: Filter by the id of the external object this external reference belongs to.
schema:
type: integer
format: int32
- in: query
name: external_reference_service_model_refs
description: Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs.
schema:
type: string
- in: query
name: external_reference_service_name
description: Filter by the name of the provider for integration.
schema:
type: string
- in: query
name: external_reference_status
description: Filter by the status of the integration, this can be successful or fail.
schema:
type: string
- in: query
name: financials_viewable_by_user
description: 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.
schema:
type: boolean
- in: query
name: for_approver
description: Filter for projects where the user with the specified user ID can approve time.
schema:
type: integer
format: int32
- in: query
name: has_approvers
description: Return only projects that have an approver (`true`) or only projects that don't (`false`).
schema:
type: boolean
- in: query
name: has_external_references
description: Filter by whether or not the object has external references.
schema:
type: boolean
- in: query
name: has_maven_participant
description: Filter for projects where the user with the specified user ID is on the provider team.
schema:
type: integer
format: int32
- in: query
name: has_participant
description: Filter for projects where the user with the specified user ID is a participant.
schema:
type: integer
format: int32
- in: query
name: has_participation
description: Filter for projects where the authenticated user is a participant.
schema:
type: boolean
- in: query
name: has_value_for_custom_field_ids
description: Filter by the presence of a custom field value for the specified comma-separated custom field ID(s).
schema:
type: string
- in: query
name: include
description: '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](/tag/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.'
schema:
type: string
- in: query
name: include_archived
description: Include (`true`) or exclude (`false`) archived projects from the results.
schema:
type: boolean
default: false
- in: query
name: matching
description: '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`.'
schema:
type: string
- in: query
name: milestone_weight_percentage_complete
description: Filter for projects which have a milestone percent completion within the specified range. Provide two comma-separated numbers. For example, `15,30`.
schema:
type: string
- in: query
name: on_account_by_orgs
required: false
description: 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.
schema:
type: boolean
- in: query
name: on_my_account
description: Filter for projects that are on the same account as the authenticated user.
schema:
type: boolean
- in: query
name: only
description: '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`.'
schema:
type: string
- in: query
name: only_joinable
required: false
description: Filter for projects which the authenticated user can join and are within the organization hierarchy the user is a part of.
schema:
type: boolean
- in: query
name: only_participating_or_joinable
required: false
description: Filter for projects which the authenticated user is participating in or can join.
schema:
type: boolean
- in: query
name: only_project_manager_in
required: false
description: 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.
schema:
type: boolean
- in: query
name: optional_fields
description: Allows you to request one or more optional fields as an array.
schema:
type: array
items:
type: string
enum:
- revenue_recognition_method_id
- revenue_recognition_method_name
- 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
- in: query
name: order
description: '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:<custom_field_id>:asc`, `custom_field:<custom_field_id>: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:<custom_field_id>:asc` and `custom_field:<custom_field_id>:desc` options do not support multi-choice custom fields.'
schema:
type: string
default: updated_at:desc
- in: query
name: page
schema:
type: integer
format: int32
default: 1
- in: query
name: participant_or_org_member_in
required: false
description: 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.
schema:
type: boolean
- in: query
name: pending_timesheet_submissions
description: 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](https://www.w3.org/TR/NOTE-datetime) format. For example, `2014-12-05;2014-12-25`.
schema:
type: string
- in: query
name: per_page
schema:
type: integer
format: int32
default: 20
maximum: 200
- in: query
name: provider_lead
description: Filter for projects with the specified provider team leads. Provide a comma-separated list of user IDs. For example, `10,20`.
schema:
type: string
- in: query
name: require_time_approvals
description: Return only projects that require time approvals (`true`) or only projects that don't (`false`).
schema:
type: boolean
- in: query
name: requiring_expense_approval
description: Return only projects that require expense approvals (`true`) or only projects that don't (`false`).
schema:
type: boolean
- in: query
name: search
description: "The `search` parameter filters for projects that match one or more keywords. By default, the following fields are searched:\n - `workspace_id`\n - `title`\n - `description`\n - `full_name` of the `primary_maven` (i.e. the Provider team lead)\n - `full_name` of the `primary_counterpart` (i.e. the Client team lead)\n - `name` of `workspace_groups`, including the `primary_workspace_group`\n - `display_value` of `custom_field_values` (Excluding `currency` and `date` custom fields)\n\n 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:\n - `title`\n - `description`\n - `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).\n - `custom_field_value` - Searches the `display_value` of `custom_field_values`. (Excluding `currency` and `date` custom fields.)\n - `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).\n\n To combine multiple field-specific search terms, separate them by a space. For example, `search=title:'acme' description:'website'`.\n\n You can combine a field-specific search term with general search terms. For example, `search=description:'acme' design`."
schema:
type: string
- in: query
name: selected_choices
description: '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`.'
schema:
type: string
- in: query
name: stage
description: Return only projects in the estimate stage or project stage. Options are `estimate` and `project`.
schema:
type: string
- in: query
name: start_date_after
description: 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](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date
- in: query
name: start_date_before
description: 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](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date
- in: query
name: updated_after
description: Filter for records updated after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: updated_before
description: Filter for records updated before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date-time
- in: query
name: user_not_participating
description: Filter for projects where the user with the specified ID is not participating.
schema:
type: integer
format: int32
- in: query
name: viewable_for_time_administration
description: Return only projects where the authenticated user can approve time. Can be used in combination with the `include_archived` filter.
schema:
type: boolean
- in: query
name: with_organizations
description: Only includes projects that have an organization (true) or only includes projects that do not have an organization (false).
schema:
type: boolean
- in: query
name: without_external_reference_service_name
description: Exclude by the existence of an external reference with the specified service name.
schema:
type: string
- in: query
name: workspace_groups
description: Filter for projects that are associated with the specified [project groups](https://developer.kantata.com/tag/Workspace-Groups). Provide a comma-separated list of group IDs. For example, `10,20`.
schema:
type: string
responses:
'200':
description: A list of Workspaces have been retrieved.
content:
application/json:
schema:
type: object
properties:
count:
type: integer
format: int32
meta:
type: object
properties:
count:
type: integer
format: int32
page_count:
type: integer
format: int32
page_number:
type: integer
format: int32
page_size:
type: integer
format: int32
results:
type: array
items:
type: object
properties:
key:
type: string
id:
type: string
workspaces:
type: object
additionalProperties:
$ref: '#/components/schemas/Workspace'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
stories:
type: object
additionalProperties:
$ref: '#/components/schemas/Story'
users:
type: object
additionalProperties:
$ref: '#/components/schemas/User'
participations:
type: object
additionalProperties:
$ref: '#/components/schemas/Participation'
timesheet_submissions:
type: object
additionalProperties:
$ref: '#/components/schemas/TimesheetSubmission'
workspace_groups:
type: object
additionalProperties:
$ref: '#/components/schemas/WorkspaceGroup'
custom_field_values:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldValue'
workspace_resources:
type: object
additionalProperties:
$ref: '#/components/schemas/WorkspaceResource'
status_reports:
type: object
additionalProperties:
$ref: '#/components/schemas/StatusReport'
account_colors:
type: object
additionalProperties:
$ref: '#/components/schemas/AccountColor'
account_insights_mappings:
type: object
additionalProperties:
$ref: '#/components/schemas/AccountInsightsMapping'
billing_milestones:
type: object
additionalProperties:
$ref: '#/components/schemas/BillingMilestone'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'401':
description: Unauthorized request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'403':
description: Forbidden request
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
'503':
description: Service is unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
post:
summary: Creating a new Workspace
description: 'Creates a new workspace (project).
This endpoint has its own rate limit. See the Knowledge Base for more information.
**Bulk Create**
This endpoint supports bulk creating up to 100 objects. In the request body, set the top-level key to its plural form and place the objects in an array. Example:
```
{
"workspaces": [
{
"title": "Acme Inc - Website Redesign"
},
{
# --- truncated at 32 KB (253 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mavenlink/refs/heads/main/openapi/mavenlink-workspaces-api-openapi.yml