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 Stories 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: Stories
description: 'Stories are tasks, milestones, deliverables, or issues in
Kantata OX. They belong to Workspaces, show up in the local and
global task trackers, can be linked to Posts, can have sub-Stories
and TaskLists, and have many attributes for planning, tasking, and
financials.'
paths:
/stories:
get:
summary: Fetching a list of Stories
description: 'This endpoint returns structured Story 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 `stories` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Get Stories
tags:
- Stories
parameters:
- in: query
name: active_between
description: "Filter for tasks that have a start or due date that is within a specified date range. Specify the date range with\n a pair of colon-separated dates, in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, `2013-06-01:2013-08-01`."
schema:
type: string
- in: query
name: all_on_account
required: false
description: If you are a reports viewer or administrator, you can retrieve all stories on an account.
schema:
type: boolean
- in: query
name: archived
description: "Include, filter for, _or_ exclude archived tasks (e.g. `GET https://api.mavenlink.com/api/v1/stories?archived=exclude`).\n Valid values: `include`, `only`, `exclude`."
schema:
type: string
- in: query
name: assigned_to_current_user
description: If set to `true`, includes tasks that are assigned to the user making the request.
schema:
type: boolean
- in: query
name: by_any_tag
description: "Include tasks with at least 1 of the specified [tags](https://mavenlink.zendesk.com/hc/en-us/articles/360052128794-New-Task-Tracker#Task-Rows).\n Give multiple tags in a comma-separated list (e.g. `GET /api/v1/stories.json?by_tag_name=design,product management,writing`).\n Tags (and therefore valid values for tags) are defined by users."
schema:
type: string
- 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_field
description: 'Filter for tasks with custom fields that have a date value within a specified range.
Specify the custom field ID and date range in a colon-separated string, with dates in a YYYY-MM-DD format.
For example, `GET /api/v1/stories.json?by_custom_date_field=18290:2018-05-02:2018-06-01`.
Give multiple custom fields with date values in a semicolon-separated list
(e.g. `GET /api/v1/stories.json?by_custom_date_field=18290:2018-05-02:2018-06-01;18291:2018-06-15:2018-08-15`).'
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: by_status
description: Filter by task status. Provide a comma-separated list of task status names.
schema:
type: string
- in: query
name: by_subtask_count
description: Filters for parent tasks with the specified number of subtasks.
schema:
type: integer
format: int32
- in: query
name: by_tag_name
description: "Include tasks with the exact [tags](https://mavenlink.zendesk.com/hc/en-us/articles/360052128794-New-Task-Tracker#Task-Rows) specified.\n Give multiple tags in a comma-separated list (e.g. `GET /api/v1/stories.json?by_tag_name=development,data analysis`).\n Tags (and therefore valid values for tags) are defined by users."
schema:
type: string
- in: query
name: by_workspace_group
description: "Filter for tasks in projects that belong to a [Project Group](/tag/Workspace-Groups) (ID).\n Give multiple project group IDs in a comma-separated list."
schema:
type: string
- in: query
name: completed
description: Filter for only completed tasks. If `false`, no filtering is applied.
schema:
type: boolean
- in: query
name: completed_between
description: "Filter for tasks that were completed within the specified date range. Specify the date range with\n a pair of colon-separated dates, in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, `2013-06-01:2013-08-01`."
schema:
type: string
- 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_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: creators
description: "Filter for tasks created by the specified user (ID).\n Give multiple user IDs in a comma-separated list (e.g. `GET https://api.mavenlink.com/api/v1/stories?creators=1,2,3`)."
schema:
type: string
- in: query
name: due_after
description: Filter for tasks that are due after the specified date. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date
- in: query
name: due_before
description: Filter for tasks that are due before the specified date. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date
- in: query
name: due_between
description: "Filter for tasks with a due date that is within a specified date range. Specify the date range with\n a pair of colon-separated dates, in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, `2013-06-01:2013-08-01`."
schema:
type: string
- in: query
name: due_on
description: Filter for tasks that are due on the specified date. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format.
schema:
type: string
format: date
- in: query
name: exclude_workspace_title_from_search
description: If set to `true`, excludes tasks in projects with a title that matches searched text.
schema:
type: boolean
- 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: has_external_references
description: Filter by whether or not the object has external references.
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`.
- `ancestors` (Story) - Retrieves all of the tasks that the task is nested under (parents and top-level tasks). The response will include `ancestor_ids`, which references the data in the `stories` top-level key.
- `assigned_role` (Role) - Retrieves the authenticated user’s assigned role for the task. The response will include `assigned_role_id`, which references the data in the `roles` top-level key.
- `assignees` (User) - Retrieves all users assigned to the task, excluding unnamed resources. The response will include `assignee_ids`, which references the data in the `users` top-level key.
- `attachments` (Attachments::PostAttachment) - Retrieves all attachments in the task''s posts. The response will include `attachment_ids`, which references the data in the `attachments` top-level key. Must be used with the `only` parameter.
- `creator` (User) - Retrieves the user who created the task. The response will include `creator_id`, which references the data in the `users` top-level key.
- `current_assignments` (Assignment) - Retrieves all assignments for the task. The response will include `current_assignment_ids`, which references the data in the `assignments` top-level key.
- `custom_field_values` (CustomFieldValue) - Retrieves the task’s custom field values. The response will include `custom_field_value_ids`, which references the data in the `custom_field_values` top-level key.
- `descendants` (Story) - Retrieves all of the subtasks nested under this top-level task. The response will include `descendant_ids`, which references the data in the `stories` top-level key.
- `external_references` (ExternalReference) - Includes references to external integrations for this object.
- `followers` (User) - Retrieves all users following the task. The response will include `follower_ids`, which references the data in the `users` top-level key.
- `google_documents` (GoogleDocument) - Retrieves all Google documents for the task. The response will include `google_document_ids`, which references the data in the `google_documents` top-level key. Must be used with the `only` parameter.
- `parent` (Story) - Retrieves the parent task that this subtask is nested directly under. The response will include `parent_id`, which references the data in the `stories` top-level key.
- `potential_workspace_resources` (WorkspaceResource) - Retrieves the project''s named resources who are not assigned to the task. The response will include `potential_workspace_resource_ids`, which references the data in the `workspace_resources` top-level key. Must be used with the `only` parameter.
- `potential_workspace_resources_with_unnamed` (WorkspaceResource) - Retrieves all of the project''s resources (named and unnamed) who are not assigned to the task. The response will include `potential_workspace_resources_with_unnamed_ids`, which references the data in the `workspace_resources` top-level key. Must be used with the `only` parameter.
- `replies` (Post) - Retrieves all task posts, except for the first one. The response will include `reply_ids`, which references the data in the `posts` top-level key. Must be used with the `only` parameter.
- `root` (Story) - Retrieves the top-level task that this subtask is nested under. The response will include `root_id`, which references the data in the `stories` top-level key.
- `source_dependencies` (StoryDependency) - Retrieves all tasks that this task is dependent on. The response will include `source_dependency_ids`, which references the data in the `story_dependencies` top-level key.
- `story_state_changes` (StoryStateChange) - Retrieves all status changes the task has gone through. The response will include `story_state_change_ids`, which references the data in the `story_state_changes` top-level key. Must be used with the `only` parameter.
- `story_tasks` (StoryTask) - Retrieves all checklist items for the task. The response will include `story_task_ids`, which references the data in the `story_tasks` top-level key.
- `sub_stories` (Story) - Retrieves all direct subtasks of the task. This does not include the subtasks of its direct subtasks. The response will include `sub_story_ids`, which references the data in the `stories` top-level key.
- `tags` (ActsAsTaggableOn::Tag) - Retrieves all tags for the task. The response will include `tag_ids`, which references the data in the `tags` top-level key.
- `target_dependencies` (StoryDependency) - Retrieves all tasks that are dependent on this task. The response will include `target_dependency_ids`, which references the data in the `story_dependencies` top-level key.
- `workspace` (Workspace) - Retrieves the project the task is in. The response will include `workspace_id`, which references the data in the `workspaces` top-level key.
- `workspace_resources` (WorkspaceResource) - Retrieves the named resources who are assigned to the task. The response will include `workspace_resource_ids`, which references the data in the `workspace_resources` top-level key.
- `workspace_resources_with_unnamed` (WorkspaceResource) - Retrieves all of the resources (named and unnamed) assigned to the task. 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: not_assigned_to_resource
description: Filter for tasks not assigned to the specified resource (ID).
schema:
type: integer
format: int32
- in: query
name: not_assigned_to_user
description: Filter for tasks not assigned to the specified user (ID).
schema:
type: integer
format: int32
- 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_archived
description: If set to `true`, filters for archived tasks.
schema:
type: boolean
- in: query
name: only_deleted
description: If set to `true`, filters for deleted tasks.
schema:
type: boolean
- in: query
name: only_todos
description: If set to `true`, filters for only To Dos.
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:
- custom_task_status_id
- read_only
- can_edit
- can_post
- archived_editable
- is_time_trackable_type
- has_out_of_bounds_sads
- can_align_time
- formatted_description
- parsed_description
- render_description_markdown
- in: query
name: order
description: 'Supply `order` with the name of a valid sort field for the endpoint and a direction.
Valid values: `created_at:asc`, `created_at:desc`, `due_date:asc`, `due_date:desc`, `importance`, `parent_and_position`, `position`, `priority_level:asc`, `priority_level:desc`, `start_date:asc`, `start_date:desc`, `updated_at:asc`, and `updated_at:desc`.'
schema:
type: string
default: updated_at:desc
- in: query
name: page
schema:
type: integer
format: int32
default: 1
- in: query
name: parents_only
description: Filter for top-level tasks. This does not include subtasks that have other subtasks nested under them.
schema:
type: boolean
- in: query
name: per_page
schema:
type: integer
format: int32
default: 20
maximum: 200
- in: query
name: priority
description: "Filter for tasks with the specified priorities. Give multiple priorities in a comma-separated list\n (`GET https://api.mavenlink.com/api/v1/stories?priority=critical,high`).\n Valid values: `critical`, `high`, `normal`, `low`."
schema:
type: string
- in: query
name: search
schema:
type: string
- in: query
name: show_archived
description: If set to `true`, includes archived tasks in the response.
schema:
type: boolean
default: false
- in: query
name: show_deleted
description: If set to `true`, includes deleted tasks.
schema:
type: boolean
default: false
- in: query
name: show_from_archived_workspaces
description: If set to `true`, filters for tasks in archived projects.
schema:
type: boolean
default: false
- in: query
name: show_todos
description: If set to `true`, includes To Dos in the response.
schema:
type: boolean
default: false
- in: query
name: starting_between
description: "Filter for tasks with a start date that is within a specified date range. Specify the date range with\n a pair of colon-separated dates, in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, `2013-06-01:2013-08-01`."
schema:
type: string
- in: query
name: story_type
description: 'Include tasks of the specified type. Valid values: `task`, `milestone`, `deliverable`, `issue`.'
schema:
type: string
- in: query
name: story_types
description: Filter for tasks of the specified type(s). Give multiple task types in a comma-separated list.
schema:
type: string
- in: query
name: time_trackable_on_workspace_id
description: "Filter for tasks that [time can be tracked against](https://mavenlink.zendesk.com/hc/en-us/articles/360008143214)\n in the specified project (ID)."
schema:
type: integer
format: int32
- in: query
name: uncompleted
description: Filter for only incomplete tasks. If `false`, no filtering is applied.
schema:
type: boolean
- 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: with_ancestry_depth
description: "Include [subtasks](https://mavenlink.zendesk.com/hc/en-us/articles/205221350)\n that are nested at the specified level from the top-level task (e.g. `GET /api/v1/stories.json?with_ancestry_depth=3`).\n The top-level task is considered to be at the 0 level. Subtasks can be nested up to 4 levels from the top-level task."
schema:
type: integer
format: int32
- in: query
name: with_assignees
description: 'Filter for tasks assigned to the specified users. Give multiple user IDs in a comma-separated list
(e.g. `GET https://api.mavenlink.com/api/v1/stories?with_assignees=1,2,3`).
In addition to user IDs, you can also pass `unassigned` and `unnamed`.
These can be included in a comma-separated list
(e.g. `GET https://api.mavenlink.com/api/v1/stories?with_assignees=1,2,3,unassigned,unnamed`).
`unassigned` returns tasks that are not assigned to any users.
`unnamed` returns tasks assigned to unnamed resources.'
schema:
type: string
- in: query
name: with_followers
description: Filter for tasks with the specified followers. Give multiple user IDs in a comma-separated list.
schema:
type: string
- in: query
name: with_parent_id
description: "Filter for [subtasks](https://mavenlink.zendesk.com/hc/en-us/articles/205221350) that are directly nested under\n the specified task (ID)."
schema:
type: integer
format: int32
- in: query
name: with_projects
description: Include tasks in the specified projects. Give multiple project IDs in a comma-separated list.
schema:
type: string
- in: query
name: with_root_id
description: "Filter for [subtasks](https://mavenlink.zendesk.com/hc/en-us/articles/205221350)\n that are nested at any level under the specified task (ID)."
schema:
type: integer
format: int32
- in: query
name: with_start_or_due_date
description: Filter for tasks with start or due dates.
schema:
type: string
- 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: without_past_completed
description: If set to `true`, filters for tasks that haven't previously been marked as completed.
schema:
type: boolean
- in: query
name: workspace_id
description: Filter for tasks from the specified project (ID).
schema:
type: integer
format: int32
responses:
'200':
description: A list of Stories 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
stories:
type: object
additionalProperties:
$ref: '#/components/schemas/Story'
external_references:
type: object
additionalProperties:
$ref: '#/components/schemas/ExternalReference'
workspace_resources:
type: object
additionalProperties:
$ref: '#/components/schemas/WorkspaceResource'
workspaces:
type: object
additionalProperties:
$ref: '#/components/schemas/Workspace'
users:
type: object
additionalProperties:
$ref: '#/components/schemas/User'
assignments:
type: object
additionalProperties:
$ref: '#/components/schemas/Assignment'
story_tasks:
type: object
additionalProperties:
$ref: '#/components/schemas/StoryTask'
tags:
type: object
additionalProperties:
$ref: '#/components/schemas/ActsAsTaggableOn__Tag'
story_state_changes:
type: object
additionalProperties:
$ref: '#/components/schemas/StoryStateChange'
posts:
type: object
additionalProperties:
$ref: '#/components/schemas/Post'
attachments:
type: object
additionalProperties:
$ref: '#/components/schemas/Attachments__PostAttachment'
story_dependencies:
type: object
additionalProperties:
$ref: '#/components/schemas/StoryDependency'
custom_field_values:
type: object
additionalProperties:
$ref: '#/components/schemas/CustomFieldValue'
roles:
type: object
additionalProperties:
$ref: '#/components/schemas/Role'
'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 Story
description: 'Creates a task (story) in a project (workspace).
**Bulk Create**
This endpoint supports bulk creating up to 300 objects. In the request body, set the top-level key to its plural form and place the objects in an array. Example:
```
{
"stories": [
{
"workspace_id": 123,
"title": "Task"
},
{
"workspace_id": 456,
"title": "Task 2"
}
]
}
```
This endpoint returns structured Story 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 `stories` top-level JSON key.
Please see our Response Format section for more information.'
operationId: Create Story
tags:
- Stories
parameters:
- 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`.
- `ancestors` (Story) - Retrieves all of the tasks that the task is nested under (parents and top-level tasks). The response will include `ancestor_ids`, which references the data in the `stories` top-level key.
- `assigned_role` (Role) - Retrieves the authenticated user’s assigned role for the task. The response will include `assigned_role_id`, which references
# --- truncated at 32 KB (163 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mavenlink/refs/heads/main/openapi/mavenlink-stories-api-openapi.yml