# 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/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. ## 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: - `200` (unknown) Story has been created. ## 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: - `400` (unknown) Bad Request ## Response 400 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 401: - `401` (unknown) Unauthorized request ## Response 401 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 403: - `403` (unknown) Forbidden request ## Response 403 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 404: - `404` (unknown) Page Not Found ## Response 404 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 422: - `422` (unknown) Unprocessable Entity ## Response 422 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 503: - `503` (unknown) Service is unavailable ## Response 503 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string)