---
title: "Add stories to an epic"
method: POST
path: "/api/backlog_items/{id}/relationships/epicStories"
tags: ["Backlog Items"]
---

# Add stories to an epic

`POST /api/backlog_items/{id}/relationships/epicStories`

## Request

- Base URL: `https://api.atono.io`
- URL: `https://api.atono.io/api/backlog_items/{id}/relationships/epicStories`
- Auth: API key in header `X-API-KEY`

Bulk-adds backlog items of type STORY to the epic identified by `id`, up to a maximum of 100 stories per epic. To see the current count, fetch the epic with `include=EPIC_STORIES` and check `relationships.epicStories.meta.count`.

Note that `id` in the path is the **epic's** id, while each `id` inside the request body's `data` array is a **story's** id.

A story that already belongs to a different epic is moved rather than duplicated, since a story can only belong to one epic at a time. Stories that are already on this epic are left as-is and are not duplicated.

This endpoint applies a best-effort, partial-success model for invalid items: any story in `data` that is not found, is not of type STORY (e.g. it's a bug or another epic - no nested epics), or belongs to a private team the caller cannot access, is reported in the `errors` array along with its id and the reason, without blocking the rest of the request. Stories already on this epic are left as-is and don't count as new additions.

Capacity is enforced as all-or-nothing: if adding every valid, not-yet-associated story in `data` would exceed the 100-story limit, none of them are added, and a single error in `errors` reports how many stories were requested versus how many could actually fit. (Invalid items such as bugs or non-existent ids don't count toward this limit either way.)

## Path parameters

- `id` string, uuid, required

## Request body

- MultiResourceRequestResourceIdentifier
  - `data` ResourceIdentifier[], required
    - `type` string, required: Identifies the type of the linked resource.
    - `id` string, required: The unique identifier of the linked resource.

## Response `200`

At least one story ended up associated with the epic. Returns the full, current list of story ids on the epic (not just the ones just added) in `data`, plus any failures in `errors`. `meta.addedCount` is the number of stories newly associated by this call. `meta.errorCount` is the number of entries in the `errors` array (e.g. the 100-story-limit violation is always reported as a single aggregate entry, even though it can reject many stories at once). `meta.failedCount` is the total number of individual story ids that were rejected across all errors - for the limit-violation error, check that error's `meta.ids` for the full list of rejected ids.

- MultiResourceBodyResourceIdentifier
  - `data` ResourceIdentifier[]: A list of returned resources, based on the request.
    - `type` string, required: Identifies the type of the linked resource.
    - `id` string, required: The unique identifier of the linked resource.
  - `errors` ProblemDetail[]: A list of errors returned with the response, if the request could not be completed. Each object includes details about a specific issue.
    - `id` string: A unique identifier for this specific error occurrence. Useful for debugging and support.
    - `links` object, nullable: Links related to the error. May include a URL to relevant documentation or support resources.
    - `status` integer: The HTTP status code associated with the error (e.g., 400, 404, 422).
    - `code` string: An internal code that identifies the type or category of the error.
    - `title` string: A short summary of the problem.
    - `source` ProblemSource: Identifies the part of the request that caused the error. Only one source is present per error.
      - `pointer` string, nullable: Specifies the path to the field in the request body that caused the error.
      - `parameter` string, nullable: Identifies a query parameter in the request URL that caused the error.
      - `header` string, nullable: Identifies the request header that caused the error.
    - `detail` string: Additional information about the error, intended to provide more context than the title.
    - `meta` unknown
  - `meta` unknown
  - `included` unknown[]: A list of related resources included in the response, either automatically by the API or in response to an `include` parameter in the request. Each item contains a full resource object (e.g., users, teams, acceptance criteria).
    - unknown
  - `links` unknown

## Other responses

- `400`: `data` was missing, `data` had more than 100 entries, every story in `data` failed to be added (not found or not of type STORY), or the valid stories alone would exceed the epic's 100-story limit. See `errors` for details.
- `404`: The epic identified by `id` could not be found.

---

[API](https://skmtc.dev/atono/apis/backend-api.md) · [All operations](https://skmtc.dev/atono/apis/backend-api/llms.txt) · [OpenAPI document](https://skmtc.dev/atono/apis/backend-api/revisions/78a57b1d8c3d?raw)