Kantata Kantata OX Knowledge Base Release Notes 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 YYYY-MM-DD 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 0 to many comma separated custom field choice values IDs. The custom field choice value can also be the word 'blank'. Multiple custom field choice values IDs can be provided by separating them with a semi-colon.

The filter supports the following formats:

  • 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_2_ID;custom_field_3_ID:blank.
by_custom_currency_value
string

Filter by a custom field currency value, represented as a string with the custom field id and the currency value, separated by a colon. Optionally, the currency can be supplied, separted from the currency value with another colon. Multiple custom field currency values an be provided by separating them with a semi-colon. For example, "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, starting date, and ending date, seperated by colons. Both a starting date and ending date can be supplied, or just one can be provided. Multiple custom field date values an be provided by separating them with a semi-colon. For example, "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 and the number value, separated by a colon. Multiple custom field number values an be provided by separating them with a semi-colon. For example, "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 and the text value, separated by a colon. Multiple custom field text values an be provided by separating them with a semi-colon. For example, "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.

created_after
string

Filter for records created after a specified datetime.

created_before
string

Filter for records created before a specified datetime.

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

Filter for tasks that are due after the specified date, in YYYY-MM-DD format.

due_before
string

Filter for tasks that are due before the specified date, in YYYY-MM-DD 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 YYYY-MM-DD format. For example, 2013-06-01:2013-08-01.

due_on
string

Filter for tasks that are due on the specified date, in YYYY-MM-DD 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_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) - All of the tasks that the task is nested under (parents and top-level).
  • assigned_role (Role) - The requester's assigned role for the task.
  • assignees (User) - All users assigned to the task.
  • attachments (Attachments::PostAttachment) - All attachments in the task's posts. Restricted to queries using the only parameter.
  • creator (User) - The user who created the task.
  • current_assignments (Assignment) - All assignments for the task.
  • custom_field_values (CustomFieldValue) - All custom field values set on the task.
  • descendants (Story) - All of the subtasks nested under this top-level task.
  • external_references (ExternalReference) - Includes references to external integrations for this object.
  • followers (User) - All users following the task.
  • google_documents (GoogleDocument) - All google documents for the task. Restricted to queries using the only parameter.
  • parent (Story) - The parent task that this subtask is nested directly under.
  • potential_workspace_resources (WorkspaceResource) - The project's named resources who are not assigned to the task. Restricted to queries using the only parameter.
  • potential_workspace_resources_with_unnamed (WorkspaceResource) - All of the project's resources (named and unnamed) who are not assigned to the task. Restricted to queries using the only parameter.
  • proofs (Proof) - All proofs for the task.
  • replies (Post) - All task posts, except for the first one. Restricted to queries using the only parameter.
  • root (Story) - The top-level task that this subtask is nested under.
  • source_dependencies (StoryDependency) - All tasks that this task is dependent on.
  • story_state_changes (StoryStateChange) - All status changes the task has gone through. Restricted to queries using the only parameter.
  • story_tasks (StoryTask) - All checklist items for the task.
  • sub_stories (Story) - All direct subtasks of the task. This does not include subtasks of its direct subtasks.
  • tags (ActsAsTaggableOn::Tag) - All tags for the task.
  • target_dependencies (StoryDependency) - All tasks that are dependent on this task.
  • workspace (Workspace) - The project the task is in.
  • workspace_resources (WorkspaceResource) - The named resources who are assigned to the task.
  • workspace_resources_with_unnamed (WorkspaceResource) - All of the resources (named and unnamed) assigned to the task.
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.

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.

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 YYYY-MM-DD 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

If set to true, filters for incomplete tasks.

updated_after
string

Filter for records updated after a specified datetime.

updated_before
string

Filter for records updated before a specified datetime.

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
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": {
    },
  • "proofs": {
    },
  • "story_dependencies": {
    },
  • "custom_field_values": {
    },
  • "roles": {
    }
}
Creating a new Story
The maximum number of stories that can be created in a single request is 300.


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) - All of the tasks that the task is nested under (parents and top-level).
    • 

  • assigned_role (Role) - The requester's assigned role for the task.
    • 

  • assignees (User) - All users assigned to the task.
    • 

  • attachments (Attachments::PostAttachment) - All attachments in the task's posts.  Restricted to queries using the only parameter.
    • 

  • creator (User) - The user who created the task.
    • 

  • current_assignments (Assignment) - All assignments for the task.
    • 

  • custom_field_values (CustomFieldValue) - All custom field values set on the task.
    • 

  • descendants (Story) - All of the subtasks nested under this top-level task.
    • 

  • external_references (ExternalReference) - Includes references to external integrations for this object.
    • 

  • followers (User) - All users following the task.
    • 

  • google_documents (GoogleDocument) - All google documents for the task.  Restricted to queries using the only parameter.
    • 

  • parent (Story) - The parent task that this subtask is nested directly under.
    • 

  • potential_workspace_resources (WorkspaceResource) - The project's named resources who are not assigned to the task.  Restricted to queries using the only parameter.
    • 

  • potential_workspace_resources_with_unnamed (WorkspaceResource) - All of the project's resources (named and unnamed) who are not assigned to the task.  Restricted to queries using the only parameter.
    • 

  • proofs (Proof) - All proofs for the task.
    • 

  • replies (Post) - All task posts, except for the first one.  Restricted to queries using the only parameter.
    • 

  • root (Story) - The top-level task that this subtask is nested under.
    • 

  • source_dependencies (StoryDependency) - All tasks that this task is dependent on.
    • 

  • story_state_changes (StoryStateChange) - All status changes the task has gone through.  Restricted to queries using the only parameter.
    • 

  • story_tasks (StoryTask) - All checklist items for the task.
    • 

  • sub_stories (Story) - All direct subtasks of the task. This does not include subtasks of its direct subtasks.
    • 

  • tags (ActsAsTaggableOn::Tag) - All tags for the task.
    • 

  • target_dependencies (StoryDependency) - All tasks that are dependent on this task.
    • 

  • workspace (Workspace) - The project the task is in.
    • 

  • workspace_resources (WorkspaceResource) - The named resources who are assigned to the task.
    • 

  • workspace_resources_with_unnamed (WorkspaceResource) - All of the resources (named and unnamed) assigned to the task.
    • 



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


 
due_date
string <date> 
Projected end date of the project. Format should look like YYYY-MM-DD.


 
state
string
The current state of the story, state options are based on the story_type:


    

  • States for task, deliverable and milestones are not started, started, and completed.
    • 

  • States for issues are new, reopened, in progress, blocked, fixed, duplicate, can't repro,
resolved, and won't fix.
    • 



 Enum: "not started" "started" "completed" "new" "reopened" "in progress" "blocked" "fixed" "duplicate" "can't repro"  
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.


 
object
 
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
Representing whether the story can have time logged against it.


 
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.


 
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
 
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": {
    },
  • "proofs": {
    },
  • "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) - All of the tasks that the task is nested under (parents and top-level).
    • 

  • assigned_role (Role) - The requester's assigned role for the task.
    • 

  • assignees (User) - All users assigned to the task.
    • 

  • attachments (Attachments::PostAttachment) - All attachments in the task's posts.  Restricted to queries using the only parameter.
    • 

  • creator (User) - The user who created the task.
    • 

  • current_assignments (Assignment) - All assignments for the task.
    • 

  • custom_field_values (CustomFieldValue) - All custom field values set on the task.
    • 

  • descendants (Story) - All of the subtasks nested under this top-level task.
    • 

  • external_references (ExternalReference) - Includes references to external integrations for this object.
    • 

  • followers (User) - All users following the task.
    • 

  • google_documents (GoogleDocument) - All google documents for the task.  Restricted to queries using the only parameter.
    • 

  • parent (Story) - The parent task that this subtask is nested directly under.
    • 

  • potential_workspace_resources (WorkspaceResource) - The project's named resources who are not assigned to the task.  Restricted to queries using the only parameter.
    • 

  • potential_workspace_resources_with_unnamed (WorkspaceResource) - All of the project's resources (named and unnamed) who are not assigned to the task.  Restricted to queries using the only parameter.
    • 

  • proofs (Proof) - All proofs for the task.
    • 

  • replies (Post) - All task posts, except for the first one.  Restricted to queries using the only parameter.
    • 

  • root (Story) - The top-level task that this subtask is nested under.
    • 

  • source_dependencies (StoryDependency) - All tasks that this task is dependent on.
    • 

  • story_state_changes (StoryStateChange) - All status changes the task has gone through.  Restricted to queries using the only parameter.
    • 

  • story_tasks (StoryTask) - All checklist items for the task.
    • 

  • sub_stories (Story) - All direct subtasks of the task. This does not include subtasks of its direct subtasks.
    • 

  • tags (ActsAsTaggableOn::Tag) - All tags for the task.
    • 

  • target_dependencies (StoryDependency) - All tasks that are dependent on this task.
    • 

  • workspace (Workspace) - The project the task is in.
    • 

  • workspace_resources (WorkspaceResource) - The named resources who are assigned to the task.
    • 

  • workspace_resources_with_unnamed (WorkspaceResource) - All of the resources (named and unnamed) assigned to the task.
    • 



 
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
 
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": {