---
title: "Creating a new Story"
method: POST
path: "/stories"
tags: ["Stories"]
---

# Creating a new Story

`POST /stories`

## Request

- Base URL: `https://api.mavenlink.com/api/v1`
- URL: `https://api.mavenlink.com/api/v1/stories`
- Auth: none declared

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.

## Query parameters

- `include` string
- `optional_fields` string[]

## Request body

- object
  - `story` object
    - `workspace_id` integer, required: The workspace ID where this story should be created.
    - `title` string, required
    - `story_type` 'task' | 'deliverable' | 'milestone' | 'issue': Must be one of: 'task', 'deliverable', 'milestone', or 'issue'. Defaults to: 'task'.
    - `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](https://www.w3.org/TR/NOTE-datetime) 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](https://www.w3.org/TR/NOTE-datetime) format.
    - `state` 'not started' | 'started' | 'needs info' | 'completed' | 'new' | 'reopened' | 'in progress' | 'blocked' | 'fixed' | 'duplicate' | 'can't repro' | 'resolved' | 'won't fix': 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.
    - `checklist` string[]: An array of checklist items.
    - `parent_id` integer: Represents the parent of this story, making this a substory.
    - `archived` boolean: Boolean representing whether or not this story is archived.
    - `assignee_ids` integer[]: An array of user IDs.
    - `budget_estimate_in_cents` integer: Can only be set if the workspace is budgeted and the user has budget permissions.
    - `time_estimate_in_minutes` integer: Can only be set if the workspace is budgeted and the user has budget permissions.
    - `tag_list` string: A comma separated.
    - `percentage_complete` integer: 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: Representing the weight of the story. Can only be set on a parent-level milestone by a consultant with at least budget permissions.
    - `priority` 'low' | 'normal' | 'high' | 'critical': 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](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.
    - `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).
      - `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.
      - `service_model` string, required: The object type of the external object this external reference belongs to.
      - `service_model_ref` string, required: The object ID of the external object this external reference belongs to.
      - `status` string: The status of the integration. Options are `successful`, `pending`, or `failed`.
      - `external_message` string: The message on the external object.
      - `external_link` string: The link to the external object.
      - `external_status` string: The status of the external object in the external system.
      - `locked` boolean: Whether the subject is locked.
    - `custom_fields` object[]: Determines the custom field values for the task.
      - `custom_field_id` integer: The ID of the custom field.
      - `value` string: The value for the corresponding custom field. The value formats for different types are: * `string` - `<text_string>`, eg. `'foo'` * `date` - `<ISO_8601 Date Format>` eg. `'2014-02-25'` `(accepted range: '1900-01-01' to '2015-12-31')` * `number` - `<integer_value>` eg. `'13'` * `currency` - `[<int_value_in_cents>, <currency_code>]` eg. `'[998, USD]'` * `single` and `multi` - `[<choice_ids>]` eg. `'[1, 2, 4]'`.
    - `attachment_ids` integer[]: 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`).

## Response `200`

Story has been created.

- object
  - `count` integer
  - `meta` object
    - `count` integer
    - `page_count` integer
    - `page_number` integer
    - `page_size` integer
  - `results` object[]
    - `key` string
    - `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

## Other responses

- `400`: Bad Request
- `401`: Unauthorized request
- `403`: Forbidden request
- `404`: Page Not Found
- `422`: Unprocessable Entity
- `503`: Service is unavailable

---

[API](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation.md) - [All operations](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/kantata/apis/kantata-ox-api-documentation/revisions/9d4ebed2fa98?raw)