# 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. Endpoint: POST /stories Version: 1.0.0 ## 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) Allows you to request one or more optional fields as an array. 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 fields (application/json): - `story` (object) - `story.workspace_id` (integer, required) The workspace ID where this story should be created. - `story.title` (string, required) - `story.story_type` (string) Must be one of: 'task', 'deliverable', 'milestone', or 'issue'. Defaults to: 'task'. Enum: "task", "deliverable", "milestone", "issue" - `story.description` (string) Must be less than 1000 characters. - `story.start_date` (string) Projected start date of the project. Format should look like YYYY-MM-DD. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `story.due_date` (string) Projected end date of the project. Format should look like YYYY-MM-DD. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `story.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" - `story.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. - `story.checklist` (array) An array of checklist items. - `story.parent_id` (integer) Represents the parent of this story, making this a substory. - `story.archived` (boolean) Boolean representing whether or not this story is archived. - `story.assignee_ids` (array) An array of user IDs. - `story.budget_estimate_in_cents` (integer) Can only be set if the workspace is budgeted and the user has budget permissions. - `story.time_estimate_in_minutes` (integer) Can only be set if the workspace is budgeted and the user has budget permissions. - `story.tag_list` (string) A comma separated. - `story.percentage_complete` (integer) Between 0 and 100. Setting above 0 starts the story and setting to 100 completes the story.. - `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. - `story.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. - `story.weight` (integer) Representing the weight of the story. Can only be set on a parent-level milestone by a consultant with at least budget permissions. - `story.priority` (string) The current priority (importance) of the story (low, normal, high, critical). The default is normal.. Enum: "low", "normal", "high", "critical" - `story.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](https://knowledge.kantata.com/hc/en-us/articles/360000317994-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. - `story.external_reference` (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). - `story.external_reference.service_name` (string, required) The provider name of the integration. If you are adding multiple external references to the same object, the service_name must be unique. - `story.external_reference.service_model` (string, required) The object type of the external object this external reference belongs to. - `story.external_reference.service_model_ref` (string, required) The object ID of the external object this external reference belongs to. - `story.external_reference.status` (string) The status of the integration. Options are successful, pending, or failed. - `story.external_reference.external_message` (string) The message on the external object. - `story.external_reference.external_link` (string) The link to the external object. - `story.external_reference.external_status` (string) The status of the external object in the external system. - `story.external_reference.locked` (boolean) Whether the subject is locked. - `story.custom_fields` (array) Determines the custom field values for the task. - `story.custom_fields.custom_field_id` (integer) The ID of the custom field. - `story.custom_fields.value` (string) The value for the corresponding custom field. The value formats for different types are: * string - `, eg. 'foo' * date - eg. '2014-02-25' (accepted range: '1900-01-01' to '2015-12-31') * number - eg. '13' * currency - [, ] eg. '[998, USD]' * single and multi - [] eg. '[1, 2, 4]'`. - `story.attachment_ids` (array) The attachment ids for the files to be associated with the project after its created. - `story.project_plan` (boolean) Whether the story is a project task (true) or is a To Do (false). ## Response 200 fields (application/json): - `count` (integer) - `meta` (object) - `meta.count` (integer) - `meta.page_count` (integer) - `meta.page_number` (integer) - `meta.page_size` (integer) - `results` (array) - `results.key` (string) - `results.id` (string) - `stories` (object) - `external_references` (object) - `workspace_resources` (object) - `workspaces` (object) - `users` (object) - `assignments` (object) - `story_tasks` (object) - `tags` (object) - `story_state_changes` (object) - `posts` (object) - `attachments` (object) - `story_dependencies` (object) - `custom_field_values` (object) - `roles` (object) ## Response 400 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 401 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 403 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 404 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 422 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 503 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string)