---
title: "Create user story"
description: "Create a new user story with optional initial steps"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.testandaccept.com/llms.txt
> Use this file to discover all available pages before exploring further.

Path: Test And Accept API › UserStories

`POST /user-stories`

Create a new user story with optional initial steps

## Authentication

- `bearerAuth`, http, header `Authorization`, format `tnda_ token`

## Request body

_Required._

- `projectId` (`userStories-create.projectId`; string, required)
  - format `uuid`; pattern `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$`
- `title` (`userStories-create.title`; string, required)
  - minLength 1; maxLength 200
- `description` (`userStories-create.description`; string, required)
  - minLength 1
- `orderIndex` (`userStories-create.orderIndex`; integer, optional)
  - min 0; max 9007199254740991
- `steps` (`userStories-create.steps`; array<object>, optional)
  - `title` (`userStories-create.steps.title`; string, required)
    - minLength 1; maxLength 200
  - `description` (`userStories-create.steps.description`; string, optional)
  - `acceptanceCriteria` (`userStories-create.steps.acceptanceCriteria`; string, optional)

## Example request

```json
{
  "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  "title": "string",
  "description": "string",
  "orderIndex": 0,
  "steps": [
    {
      "title": "string",
      "description": "string",
      "acceptanceCriteria": "string"
    }
  ]
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url https://api.testandaccept.com/api/rest/user-stories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  "title": "string",
  "description": "string",
  "orderIndex": 0,
  "steps": [
    {
      "title": "string",
      "description": "string",
      "acceptanceCriteria": "string"
    }
  ]
}
'
```

### TypeScript

```typescript
const url = 'https://api.testandaccept.com/api/rest/user-stories';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({
    projectId: '5a8591dd-4039-49df-9202-96385ba3eff8',
    title: 'string',
    description: 'string',
    orderIndex: 0,
    steps: [{title: 'string', description: 'string', acceptanceCriteria: 'string'}]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.testandaccept.com/api/rest/user-stories"

payload = {
    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
    "title": "string",
    "description": "string",
    "orderIndex": 0,
    "steps": [
        {
            "title": "string",
            "description": "string",
            "acceptanceCriteria": "string"
        }
    ]
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
```

## Responses

### 200

Successful response

#### Example

```json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  "title": "string",
  "description": "string",
  "ownerUserId": "string",
  "status": "draft",
  "orderIndex": 0,
  "createdAt": "string",
  "updatedAt": "string"
}
```

- `id` (`userStories-create.response.200.id`; string, required)
  - format `uuid`; pattern `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$`
- `projectId` (`userStories-create.response.200.projectId`; string, required)
  - format `uuid`; pattern `^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$`
- `title` (`userStories-create.response.200.title`; string, required)
- `description` (`userStories-create.response.200.description`; any of, required)
  - any of: `string`, `null`
- `ownerUserId` (`userStories-create.response.200.ownerUserId`; string, required)
- `status` (`userStories-create.response.200.status`; string, required)
  - one of `"draft"`, `"refined"`, `"assessed"`
- `orderIndex` (`userStories-create.response.200.orderIndex`; number, required)
- `createdAt` (`userStories-create.response.200.createdAt`; string, required)
- `updatedAt` (`userStories-create.response.200.updatedAt`; string, required)

### 400

Invalid input data

#### Example

```json
{
  "code": "BAD_REQUEST",
  "message": "Invalid input data",
  "issues": []
}
```

- `message` (`userStories-create.response.400.message`; string, required) — The error message
  - example `"Invalid input data"`
- `code` (`userStories-create.response.400.code`; string, required) — The error code
  - example `"BAD_REQUEST"`
- `issues` (`userStories-create.response.400.issues`; array<object>, optional) — An array of issues that were responsible for the error
  - example `[]`
  - `message` (`userStories-create.response.400.issues.message`; string, required)

### 401

Authorization not provided

#### Example

```json
{
  "code": "UNAUTHORIZED",
  "message": "Authorization not provided",
  "issues": []
}
```

- `message` (`userStories-create.response.401.message`; string, required) — The error message
  - example `"Authorization not provided"`
- `code` (`userStories-create.response.401.code`; string, required) — The error code
  - example `"UNAUTHORIZED"`
- `issues` (`userStories-create.response.401.issues`; array<object>, optional) — An array of issues that were responsible for the error
  - example `[]`
  - `message` (`userStories-create.response.401.issues.message`; string, required)

### 403

Insufficient access

#### Example

```json
{
  "code": "FORBIDDEN",
  "message": "Insufficient access",
  "issues": []
}
```

- `message` (`userStories-create.response.403.message`; string, required) — The error message
  - example `"Insufficient access"`
- `code` (`userStories-create.response.403.code`; string, required) — The error code
  - example `"FORBIDDEN"`
- `issues` (`userStories-create.response.403.issues`; array<object>, optional) — An array of issues that were responsible for the error
  - example `[]`
  - `message` (`userStories-create.response.403.issues.message`; string, required)

### 500

Internal server error

#### Example

```json
{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "issues": []
}
```

- `message` (`userStories-create.response.500.message`; string, required) — The error message
  - example `"Internal server error"`
- `code` (`userStories-create.response.500.code`; string, required) — The error code
  - example `"INTERNAL_SERVER_ERROR"`
- `issues` (`userStories-create.response.500.issues`; array<object>, optional) — An array of issues that were responsible for the error
  - example `[]`
  - `message` (`userStories-create.response.500.issues.message`; string, required)


Source: https://docs.testandaccept.com/reference/user-stories/create/index.md