Kantata Kantata OX Knowledge Base
Release Notes
Kantata OX Release Notes API Breaking Changes
Status Page
Kantata OX API Documentation

Stories

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.

Fetching a list of Stories

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.

Request
query Parameters
active_between
string

Filter for tasks that have a start or due date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in ISO 8601 format. For example, 2013-06-01:2013-08-01.

all_on_account
boolean

If you are a reports viewer or administrator, you can retrieve all stories on an account.

archived
string

Include, filter for, or exclude archived tasks (e.g. GET https://api.mavenlink.com/api/v1/stories?archived=exclude). Valid values: include, only, exclude.

assigned_to_current_user
boolean

If set to true, includes tasks that are assigned to the user making the request.

by_any_tag
string

Include tasks with at least 1 of the specified tags. Give multiple tags in a comma-separated list (e.g. GET /api/v1/stories.json?by_tag_name=design,product management,writing). Tags (and therefore valid values for tags) are defined by users.

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_field
string

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).

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).
by_status
string

Filter for tasks that are in projects with the specified statuses. Valid values are just the names of project statuses. Give multiple statuses in a comma-separated list (e.g. GET /api/v1/stories.json?by_status=Bid Stage,In Planning,In Setup,Not Started.

by_subtask_count
integer <int32>

Filters for parent tasks with the specified number of subtasks.

by_tag_name
string

Include tasks with the exact tags specified. Give multiple tags in a comma-separated list (e.g. GET /api/v1/stories.json?by_tag_name=development,data analysis). Tags (and therefore valid values for tags) are defined by users.

by_workspace_group
string

Filter for tasks in projects that belong to a Project Group (ID). Give multiple project group IDs in a comma-separated list.

completed
boolean

Filter for only completed tasks. If false, no filtering is applied.

completed_between
string

Filter for tasks that were completed within the specified date range. Specify the date range with a pair of colon-separated dates, in ISO 8601 format. For example, 2013-06-01:2013-08-01.

created_after
string <date-time>

Filter for records created after a specified datetime. The datetime must be in ISO 8601 format.

created_before
string <date-time>

Filter for records created before a specified datetime. The datetime must be in ISO 8601 format.

creators
string

Filter for tasks created by the specified user (ID). Give multiple user IDs in a comma-separated list (e.g. GET https://api.mavenlink.com/api/v1/stories?creators=1,2,3).

due_after
string <date>

Filter for tasks that are due after the specified date. The date must be in ISO 8601 format.

due_before
string <date>

Filter for tasks that are due before the specified date. The date must be in ISO 8601 format.

due_between
string

Filter for tasks with a due date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in ISO 8601 format. For example, 2013-06-01:2013-08-01.

due_on
string <date>

Filter for tasks that are due on the specified date. The date must be in ISO 8601 format.

exclude_workspace_title_from_search
boolean

If set to true, excludes tasks in projects with a title that matches searched text.

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 <int32>

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.

has_external_references
boolean

Filter by whether or not the object has external references.

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.

  • 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.
not_assigned_to_resource
integer <int32>

Filter for tasks not assigned to the specified resource (ID).

not_assigned_to_user
integer <int32>

Filter for tasks not assigned to the specified user (ID).

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_archived
boolean

If set to true, filters for archived tasks.

only_deleted
boolean

If set to true, filters for deleted tasks.

only_todos
boolean

If set to true, filters for only To Dos.

optional_fields
Array of strings

Allows you to request one or more optional fields as an array.

Items Enum: "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"
order
string
Default: "updated_at:desc"

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.

page
integer <int32>
Default: 1
parents_only
boolean

Filter for top-level tasks. This does not include subtasks that have other subtasks nested under them.

per_page
integer <int32> <= 200
Default: 20
priority
string

Filter for tasks with the specified priorities. Give multiple priorities in a comma-separated list (GET https://api.mavenlink.com/api/v1/stories?priority=critical,high). Valid values: critical, high, normal, low.

search
string
show_archived
boolean
Default: false

If set to true, includes archived tasks in the response.

show_deleted
boolean
Default: false

If set to true, includes deleted tasks.

show_from_archived_workspaces
boolean
Default: false

If set to true, filters for tasks in archived projects.

show_todos
boolean
Default: false

If set to true, includes To Dos in the response.

starting_between
string

Filter for tasks with a start date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in ISO 8601 format. For example, 2013-06-01:2013-08-01.

story_type
string

Include tasks of the specified type. Valid values: task, milestone, deliverable, issue.

story_types
string

Filter for tasks of the specified type(s). Give multiple task types in a comma-separated list.

time_trackable_on_workspace_id
integer <int32>

Filter for tasks that time can be tracked against in the specified project (ID).

uncompleted
boolean

Filter for only incomplete tasks. If false, no filtering is applied.

updated_after
string <date-time>

Filter for records updated after a specified datetime. The datetime must be in ISO 8601 format.

updated_before
string <date-time>

Filter for records updated before a specified datetime. The datetime must be in ISO 8601 format.

with_ancestry_depth
integer <int32>

Include subtasks that are nested at the specified level from the top-level task (e.g. GET /api/v1/stories.json?with_ancestry_depth=3). 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.

with_assignees
string

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.

with_followers
string

Filter for tasks with the specified followers. Give multiple user IDs in a comma-separated list.

with_parent_id
integer <int32>

Filter for subtasks that are directly nested under the specified task (ID).

with_projects
string

Include tasks in the specified projects. Give multiple project IDs in a comma-separated list.

with_root_id
integer <int32>

Filter for subtasks that are nested at any level under the specified task (ID).

with_start_or_due_date
string

Filter for tasks with start or due dates.

without_external_reference_service_name
string

Exclude by the existence of an external reference with the specified service name.

without_past_completed
boolean

If set to true, filters for tasks that haven't previously been marked as completed.

workspace_id
integer <int32>

Filter for tasks from the specified project (ID).

Responses
200

A list of Stories have been retrieved.

Response Schema: application/json
count
integer <int32>
object
Array of objects
object
object
object
object
object
object
object
object
object
object
object
object
object
object
400

Bad Request

401

Unauthorized request

403

Forbidden request

404

Page Not Found

422

Unprocessable Entity

503

Service is unavailable

get/stories
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "stories": {
    },
  • "external_references": {
    },
  • "workspace_resources": {
    },
  • "workspaces": {
    },
  • "users": {
    },
  • "assignments": {
    },
  • "story_tasks": {
    },
  • "tags": {
    },
  • "story_state_changes": {
    },
  • "posts": {
    },
  • "attachments": {
    },
  • "story_dependencies": {
    },
  • "custom_field_values": {
    },
  • "roles": {
    }
}
Creating a new Story
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.


Request 
query Parameters
include
string
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.
    • 



 
optional_fields
Array of strings
Allows you to request one or more optional fields as an array.


Items Enum: "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"  
Request Body schema: application/json
required
object
 
workspace_id
required
integer <int32> 
The workspace ID where this story should be created.


 
title
required
string
 
story_type
string
Must be one of: 'task', 'deliverable', 'milestone', or 'issue'. Defaults to: 'task'.


 Enum: "task" "deliverable" "milestone" "issue"  
description
string
Must be less than 1000 characters.


 
start_date
string <date> 
Projected start date of the project. Format should look like YYYY-MM-DD. The date must be in ISO 8601 format.


 
due_date
string <date> 
Projected end date of the project. Format should look like YYYY-MM-DD. The date must be in ISO 8601 format.


 
state
string
The status type (category). It is recommended to set the status field instead (which supports custom task statuses).


Possible options depend on the story_type:


    

  • Possible options for task, deliverable, and milestone are not started, started, needs info, and completed.
    • 

  • If a task status set has not been applied to the workspace, possible options for issue are new, reopened, in progress, blocked, fixed, duplicate, can't repro, resolved, and won't fix.
Otherwise, possible options are not started, started, needs info, and completed.
    • 



If both status and state are provided, the provided state value is ignored and the corresponding category of the provided status is applied to the state field instead.


 Enum: "not started" "started" "needs info" "completed" "new" "reopened" "in progress" "blocked" "fixed" "duplicate" "can't repro" "resolved" "won't fix"  
status
string
The status of the story. Possible options depend on whether the workspace has an assigned task status set.


    

  • If the workspace does not have a task status set assigned, possible options are not started, started, needs info, and completed.
    • 

  • If the workspace has a task status set assigned, the possible options are the statuses within the task status set.
You can get a list of statuses within the project’s task status set using the Task Status Set endpoint.
    • 



When status is updated, its category is automatically applied to the state field of the story.


 
checklist
Array of strings
An array of checklist items.


 
parent_id
integer <int32> 
Represents the parent of this story, making this a substory.


 
archived
boolean
Boolean representing whether or not this story is archived.


 
assignee_ids
Array of integers <int32> 
An array of user IDs.


 
budget_estimate_in_cents
integer <int32> 
Can only be set if the workspace is budgeted and the user has budget permissions.


 
time_estimate_in_minutes
integer <int32> 
Can only be set if the workspace is budgeted and the user has budget permissions.


 
tag_list
string
A comma separated.


 
percentage_complete
integer <int32> 
Between 0 and 100. Setting above 0 starts the story and setting to 100 completes the story..


 
fixed_fee
boolean
Representing whether the story is fixed fee or not. Can only be set if the workspace is budgeted and the user has budget permissions.


 
billable
boolean
Representing whether the story is billable or not. Can only be set if the workspace is budgeted and the user has budget permissions.


 
weight
integer <int32> 
Representing the weight of the story. Can only be set on a parent-level milestone by a consultant with at least budget permissions.


 
priority
string
The current priority (importance) of the story (low, normal, high, critical). The default is normal..


 Enum: "low" "normal" "high" "critical"  
time_trackable
boolean
Whether the story can have time logged against it. Whether this field can be updated and by whom depends on the selections in
Time & Expense Settings.
Time & Expense Settings also determine the default value for new tasks. An Account Administrator can explicitly set this field and override the default for new tasks.


 
object
Typically populated programmatically by a third party system via an integration, this is an optional
object that holds data from an external system. It connects objects in an external system with objects in
Kantata OX (for example, to connect a Jira issue to a Kantata OX Project).


 
Array of objects
Determines the custom field values for the task.


 
attachment_ids
Array of integers <int32> 
The attachment ids for the files to be associated with the project after its created.


 
project_plan
boolean
Whether the story is a project task (true) or is a To Do (false).


 
Responses 
200
Story has been created.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


post/stories
Request samples 
application/json
{
  • "story": {
    }
}
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "stories": {
    },
  • "external_references": {
    },
  • "workspace_resources": {
    },
  • "workspaces": {
    },
  • "users": {
    },
  • "assignments": {
    },
  • "story_tasks": {
    },
  • "tags": {
    },
  • "story_state_changes": {
    },
  • "posts": {
    },
  • "attachments": {
    },
  • "story_dependencies": {
    },
  • "custom_field_values": {
    },
  • "roles": {
    }
}
Fetching a single Story
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.


Request 
path Parameters
id
required
integer
The ID of the Model.


 
query Parameters
include
string
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.
    • 



 
optional_fields
Array of strings
Allows you to request one or more optional fields as an array.


Items Enum: "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"  
show_deleted
boolean
 Default:  false
Returns a deleted story when set to true.


 
Responses 
200
The Story has been retrieved.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


get/stories/{id}
Request samples 
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "stories": {
    },
  • "external_references": {
    },
  • "workspace_resources": {
    },
  • "workspaces": {
    },
  • "users": {
    },
  • "assignments": {
    },
  • "story_tasks": {
    },
  • "tags": {
    },
  • "story_state_changes": {
    },
  • "posts": {
    },
  • "attachments": {
    },
  • "story_dependencies": {
    },
  • "custom_field_values": {
    },
  • "roles": {
    }
}
Updating an existing Story
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.


Request 
path Parameters
id
required
integer
The ID of the Model.


 
query Parameters
include
string
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.
    • 



 
optional_fields
Array of strings
Allows you to request one or more optional fields as an array.


Items Enum: "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"  
Request Body schema: application/json
required
object
 
title
string
The title cannot be made blank.


 
story_type
string
Must be 'task', 'deliverable', 'milestone', or 'issue'.


 
description
string
Must be less than 1000 characters.


 
start_date
string <date> 
Projected start date of the project. Format should look like YYYY-MM-DD. The date must be in ISO 8601 format.


 
due_date
string <date> 
Projected end date of the project. Format should look like YYYY-MM-DD. The date must be in ISO 8601 format.


 
state
string
The status type (category). It is recommended to set the status field instead (which supports custom task statuses).


Possible options depend on the story_type:


    

  • Possible options for task, deliverable, and milestone are not started, started, needs info, and completed.
    • 

  • If a task status set has not been applied to the workspace, possible options for issue are new, reopened, in progress, blocked, fixed, duplicate, can't repro, resolved, and won't fix.
Otherwise, possible options are not started, started, needs info, and completed.
    • 



If both status and state are provided, the provided state value is ignored and the corresponding category of the provided status is applied to the state field instead.


 
status
string
The status of the story. Possible options depend on whether the workspace has an assigned task status set.


    

  • If the workspace does not have a task status set assigned, possible options are not started, started, needs info, and completed.
    • 

  • If the workspace has a task status set assigned, the possible options are the statuses within the task status set.
You can get a list of statuses within the project’s task status set using the Task Status Set endpoint.
    • 



When status is updated, its category is automatically applied to the state field of the story.


 
follower_ids
Array of integers <int32> 
Array of user IDs who are following the story.


 
parent_id
integer <int32> 
Represents the parent of this story, making this a substory.


 
archived
boolean
Boolean representing whether or not this story is archived.


 
assignee_ids
Array of integers <int32> 
An array of user IDs.


 
budget_estimate_in_cents
integer <int32> 
Can only be set if the workspace is budgeted and the user has budget permissions.


 
time_estimate_in_minutes
integer <int32> 
Can only be set if the workspace is budgeted and the user has budget permissions.


 
tag_list
string
A comma separated.


 
percentage_complete
integer <int32> 
Between 0 and 100. Setting above 0 starts the story and setting to 100 completes the story..


 
fixed_fee
boolean
Representing whether the story is fixed fee or not. Can only be set if the workspace is budgeted and the user has budget permissions.


 
billable
boolean
Representing whether the story is billable or not. Can only be set if the workspace is budgeted and the user has budget permissions.


 
weight
integer <int32> 
Representing the weight of the story. Can only be set on a parent-level milestone by a consultant with at least budget permissions.


 
priority
string
The current priority (importance) of the story (low, normal, high, critical). The default is normal..


 
time_trackable
boolean
Whether the story can have time logged against it. Whether this field can be updated and by whom depends on the selections in
Time & Expense Settings.
Time & Expense Settings also determine the default value for new tasks. An Account Administrator can explicitly set this field and override the default for new tasks.


 
object
Typically populated programmatically by a third party system via an integration, this is an optional
object that holds data from an external system. It connects objects in an external system with objects in
Kantata OX (for example, to connect a Jira issue to a Kantata OX Project).


 
Array of objects
Determines the custom field values for the task.


 
Responses 
200
Story has been updated.


Response Schema: application/json
count
integer <int32> 
 
object
 
Array of objects
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
object
 
400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


put/stories/{id}
Request samples 
application/json
{
  • "story": {
    }
}
Response samples 
application/json
{
  • "count": 0,
  • "meta": {
    },
  • "results": [
    ],
  • "stories": {
    },
  • "external_references": {
    },
  • "workspace_resources": {
    },
  • "workspaces": {
    },
  • "users": {
    },
  • "assignments": {
    },
  • "story_tasks": {
    },
  • "tags": {
    },
  • "story_state_changes": {
    },
  • "posts": {
    },
  • "attachments": {
    },
  • "story_dependencies": {
    },
  • "custom_field_values": {
    },
  • "roles": {
    }
}
Deleting an existing Story
Soft deletes a task (by setting a value for deleted_at). You can view soft deleted tasks by fetching a
list of tasks with the only_deleted filter set to true.


Note: Tasks are only permanently deleted when the project is deleted.


The response will contain no content and an HTTP 204 status code if the request was
successful, or a standard Kantata OX error message explaining why the object could not be deleted.


Request 
path Parameters
id
required
integer
The ID of the Model.


 
Responses 
204
Story has been deleted.


400
Bad Request


401
Unauthorized request


403
Forbidden request


404
Page Not Found


422
Unprocessable Entity


503
Service is unavailable


delete/stories/{id}
Request samples 
Response samples 
application/json
{
  • "errors": [
    ]
}
➔ Next to Story Dependencies