---
updatedAt: 2026-06-11T21:38:37.000Z
agentTools:
  projectIndex: https://docs.atono.io/llms.txt
---

# Get stories

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Atono API",
    "version": "0.1"
  },
  "servers": [
    {
      "url": "https://api.atono.io",
      "description": "Atono API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/stories": {
      "get": {
        "tags": [
          "Stories"
        ],
        "summary": "Get stories",
        "operationId": "listStories",
        "parameters": [
          {
            "name": "filter[assigneeIds]",
            "in": "query",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "description": "Finds stories assigned to any of the specified users, or unassigned. Provide a pipe-separated list of user UUIDs. Use `NONE` to find unassigned stories.",
              "name": "filter[assigneeIds]"
            }
          },
          {
            "name": "filter[teamIds]",
            "in": "query",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "description": "Finds stories assigned to any of the specified team backlogs, or in Story refinement (not assigned to a team). Provide a pipe-separated list of team UUIDs. Use `NONE` to find stories not assigned to a team. ",
              "name": "filter[teamIds]"
            }
          },
          {
            "name": "filter[createdAt]",
            "in": "query",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "description": "Finds stories created within a specific date range. Provide two pipe-separated ISO 8601 timestamps (e.g., `start|end`).",
              "example": "2021-01-01T00:00:00Z|2021-01-31T23:59:59Z",
              "name": "filter[createdAt]",
              "exampleSetFlag": true
            }
          },
          {
            "name": "filter[updatedAt]",
            "in": "query",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "description": "Finds stories last updated within a specific date range. Provide two pipe-separated ISO 8601 timestamps (e.g., `start|end`).",
              "example": "2021-01-01T00:00:00Z|2021-01-31T23:59:59Z",
              "name": "filter[updatedAt]",
              "exampleSetFlag": true
            }
          },
          {
            "name": "filter[doneAt]",
            "in": "query",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "description": "Finds stories completed within a specific date range. Provide two pipe-separated ISO 8601 timestamps (e.g., `start|end`).",
              "example": "2021-01-01T00:00:00Z|2021-01-31T23:59:59Z",
              "name": "filter[doneAt]",
              "exampleSetFlag": true
            }
          },
          {
            "name": "filter[timeboxIds]",
            "in": "query",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "description": "Finds stories assigned to any of the specified timeboxes. Provide a pipe-separated list of timebox UUIDs. Use `NONE` to find stories not assigned to a timebox.",
              "name": "filter[timeboxIds]"
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "Includes additional related data for each story. Repeat the parameter to include multiple relationships.\n* `ASSIGNEE` - The user assigned to the story.\n* `CREATOR` - The user who created the story.\n* `FEATURE_FLAG` - The feature flag associated with the story.\n* `TEAM` - The team backlog the story is assigned to.\n* `FULL_TEXT` - Returns the story’s main content and all acceptance criteria as a single formatted text block (may include minimal HTML).\n",
            "schema": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "$ref": "#/components/schemas/StoryController.ListInclusionType"
              }
            }
          },
          {
            "name": "page[number]",
            "in": "query",
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int32",
              "description": "Returns a specific page of results, starting from page `0`. Use with `page[size]` to control how many items are returned per page. For example, if `page[size]` is `20`, then `page[number]=2` returns items 21-40.",
              "minimum": 0,
              "name": "page[number]"
            }
          },
          {
            "name": "page[size]",
            "in": "query",
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int32",
              "description": "Controls how many items are returned in each response page.",
              "minimum": 0,
              "name": "page[size]"
            }
          },
          {
            "name": "page[offset]",
            "in": "query",
            "schema": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int32",
              "description": "Skips the specified number of items before starting the result set. For example, if `page[offset]` is `30` and `page[size]` is `10`, the response returns items 31-40.",
              "minimum": 0,
              "name": "page[offset]"
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorts the list of stories by one or more fields. Prefix a field name with a minus sign (`-`) to sort in descending order. Repeat the parameter to sort by multiple fields. Supported fields include:\n* `assignee.fullName`\n* `handle`\n* `position`\n* `team.name`\n* `title`\n* `createdAt`\n* `updatedAt`\n* `doneAt`",
            "schema": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "string"
              }
            },
            "example": "-createdAt"
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved the list of stories and their included relationships.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MultiResourceBody_StoryResource_"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BacklogItem.CycleTimeMode": {
        "enum": [
          "NORMAL",
          "OUTLIER"
        ]
      },
      "ContentChunk_25": {
        "description": "A segment of content in the description of a story or a bug.",
        "properties": {
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/StoryContentChunk.ContentChunkType"
              }
            ],
            "description": "    The type of content chunk.\n    - `DISPLAY_HTML`: HTML-formatted content.\n    - `TEXT`: Plain text content.\n    - `PERSONA`: The \"As a...\" persona from the user story.\n"
          },
          "value": {
            "type": "string",
            "description": "The content in this chunk.",
            "minLength": 1
          }
        },
        "required": [
          "type",
          "value"
        ]
      },
      "ContentChunk_27": {
        "description": "A segment of content in the description of a story or a bug.",
        "properties": {
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GenericContentChunk.ContentChunkType"
              }
            ],
            "description": "    The type of content chunk.\n    - `DISPLAY_HTML`: HTML-formatted content.\n    - `TEXT`: Plain text content.\n"
          },
          "value": {
            "type": "string",
            "description": "The content in this chunk.",
            "minLength": 1
          }
        },
        "required": [
          "type",
          "value"
        ]
      },
      "GenericContentChunk.ContentChunkType": {
        "description": "    The type of content chunk.\n    - `DISPLAY_HTML`: HTML-formatted content.\n    - `TEXT`: Plain text content.\n",
        "enum": [
          "DISPLAY_HTML",
          "TEXT"
        ]
      },
      "MultiResourceBody_StoryResource_": {
        "properties": {
          "data": {
            "type": "array",
            "description": "A list of returned resources, based on the request.",
            "items": {
              "$ref": "#/components/schemas/StoryResource",
              "description": "A story represents a piece of planned work in Atono, typically written from the user's perspective. It includes a user story statement, acceptance criteria, and optional context to guide implementation or review."
            }
          },
          "errors": {
            "type": "array",
            "description": "A list of errors returned with the response, if the request could not be completed. Each object includes details about a specific issue.",
            "items": {
              "$ref": "#/components/schemas/ProblemDetail",
              "description": "A problem detail object is a way to convey information about an error that occurred while processing a request."
            }
          },
          "meta": {
            "additionalProperties": true,
            "description": "Additional contextual information about the response. May include summary data such as item counts, timestamps, or other calculated values."
          },
          "included": {
            "type": "array",
            "description": "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).",
            "items": {}
          },
          "links": {
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            },
            "description": "Pagination or navigation links related to the response. May include keys such as `self`, `next`, `prev`, `first`, or `last`."
          }
        },
        "readOnly": true
      },
      "MultipleRelationships": {
        "properties": {
          "links": {
            "$ref": "#/components/schemas/RelationshipLinks"
          },
          "data": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/ResourceIdentifier"
            }
          },
          "meta": {
            "additionalProperties": true
          }
        },
        "required": [
          "data",
          "links",
          "meta"
        ]
      },
      "ProblemDetail": {
        "description": "A problem detail object is a way to convey information about an error that occurred while processing a request.",
        "properties": {
          "id": {
            "type": "string",
            "description": "A unique identifier for this specific error occurrence. Useful for debugging and support."
          },
          "links": {
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            },
            "allOf": [
              {
                "type": [
                  "null",
                  "object"
                ]
              }
            ],
            "description": "Links related to the error. May include a URL to relevant documentation or support resources."
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "description": "The HTTP status code associated with the error (e.g., 400, 404, 422)."
          },
          "code": {
            "type": "string",
            "description": "An internal code that identifies the type or category of the error."
          },
          "title": {
            "type": "string",
            "description": "A short summary of the problem."
          },
          "source": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/ProblemSource"
              }
            ],
            "readOnly": true
          },
          "detail": {
            "type": "string",
            "description": "Additional information about the error, intended to provide more context than the title."
          },
          "meta": {
            "additionalProperties": true,
            "description": "Additional information about the error, which may be useful for debugging. The contents vary depending on the error type."
          }
        },
        "readOnly": true
      },
      "ProblemSource": {
        "description": "Identifies the part of the request that caused the error. Only one source is present per error.",
        "properties": {
          "pointer": {
            "type": [
              "string",
              "null"
            ],
            "description": "Specifies the path to the field in the request body that caused the error."
          },
          "parameter": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identifies a query parameter in the request URL that caused the error."
          },
          "header": {
            "type": [
              "string",
              "null"
            ],
            "description": "Identifies the request header that caused the error."
          }
        },
        "readOnly": true
      },
      "RelationshipLinks": {
        "properties": {
          "self": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "related": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          }
        },
        "required": [
          "related",
          "self"
        ]
      },
      "ResourceIdentifier": {
        "properties": {
          "type": {
            "type": "string",
            "description": "Identifies the type of the linked resource."
          },
          "id": {
            "type": "string",
            "description": "The unique identifier of the linked resource."
          }
        },
        "required": [
          "id",
          "type"
        ]
      },
      "SingleRelationship": {
        "properties": {
          "links": {
            "$ref": "#/components/schemas/RelationshipLinks"
          },
          "data": {
            "$ref": "#/components/schemas/ResourceIdentifier"
          },
          "meta": {
            "additionalProperties": true
          }
        },
        "required": [
          "data",
          "links",
          "meta"
        ]
      },
      "StoryContentChunk.ContentChunkType": {
        "description": "    The type of content chunk.\n    - `DISPLAY_HTML`: HTML-formatted content.\n    - `TEXT`: Plain text content.\n    - `PERSONA`: The \"As a...\" persona from the user story.\n",
        "enum": [
          "DISPLAY_HTML",
          "TEXT",
          "PERSONA"
        ]
      },
      "StoryController.ListInclusionType": {
        "enum": [
          "ASSIGNEE",
          "CREATOR",
          "FEATURE_FLAG",
          "TEAM",
          "WORKFLOW_STEP",
          "FULL_TEXT"
        ]
      },
      "StoryResource": {
        "description": "A story represents a piece of planned work in Atono, typically written from the user's perspective. It includes a user story statement, acceptance criteria, and optional context to guide implementation or review.",
        "properties": {
          "type": {
            "type": "string",
            "default": "story",
            "description": "Identifies the type of resource.",
            "pattern": "story",
            "defaultValue": "story"
          },
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The unique identifier for the resource, typically a UUID."
          },
          "attributes": {
            "allOf": [
              {
                "$ref": "#/components/schemas/StoryResource.Attributes"
              }
            ],
            "description": "Contains the structured data fields that describe the resource, such as properties, settings, and timestamps."
          },
          "relationships": {
            "allOf": [
              {
                "$ref": "#/components/schemas/StoryResource.Relationships"
              }
            ],
            "description": "Contains references to other related resources."
          }
        },
        "readOnly": true
      },
      "StoryResource.Attributes": {
        "description": "Contains the structured data fields that describe the resource, such as properties, settings, and timestamps.",
        "properties": {
          "title": {
            "type": "string",
            "description": "The title of the story."
          },
          "handle": {
            "type": "string",
            "description": "A unique identifier for the story, shown in the Atono application as the item ID (e.g., `STORY-123`)."
          },
          "position": {
            "type": "integer",
            "format": "int32",
            "description": "Indicates the story's position within its current workflow step, where `0` is the topmost item. Position is relative to the step and team backlog."
          },
          "content": {
            "type": [
              "array",
              "null"
            ],
            "description": "The user story statement shown at the top of the story (e.g., \"As a… I want to… so that…\").",
            "example": "As a user, I want to be able to log in so that I can access my account.",
            "items": {
              "$ref": "#/components/schemas/ContentChunk_25",
              "description": "A segment of content in the description of a story or a bug."
            },
            "readOnly": true,
            "exampleSetFlag": true
          },
          "additionalContent": {
            "type": [
              "array",
              "null"
            ],
            "description": "Optional notes added below the acceptance criteria, often used for background info, technical notes, decisions, or context for the team.",
            "items": {
              "$ref": "#/components/schemas/ContentChunk_27",
              "description": "A segment of content in the description of a story or a bug."
            },
            "readOnly": true
          },
          "cycleTimeMode": {
            "allOf": [
              {
                "$ref": "#/components/schemas/BacklogItem.CycleTimeMode"
              }
            ],
            "description": "Indicates whether the story is marked as an `OUTLIER` (excluded) or remains `NORMAL` (included) in average cycle time calculations, reports, and staleness indicators."
          },
          "stalenessIndicatorSnoozeUntil": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time until which the staleness indicator is hidden for this story in its current step and team backlog. Once the date passes, the indicator is shown again if the story is still stale."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time the story was created."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time the story was last updated."
          },
          "doneAt": {
            "type": "string",
            "format": "date-time",
            "description": "The date and time when the story was completed."
          },
          "deleted": {
            "type": "boolean",
            "description": "Indicates whether the story has been deleted."
          }
        }
      },
      "StoryResource.Relationships": {
        "description": "Contains references to other related resources.",
        "properties": {
          "acceptanceCriteria": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/MultipleRelationships"
              }
            ],
            "description": "A relationship object linking to the story's acceptance criteria. The object includes resource identifiers, related links, and metadata."
          },
          "assignee": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/SingleRelationship"
              }
            ],
            "description": "A relationship object linking to the user assigned to the story. If `null`, the story is currently unassigned. Includes a reference to the user and optional related links and metadata."
          },
          "team": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/SingleRelationship"
              }
            ],
            "description": "A relationship object linking to the team backlog the story is currently assigned to. Includes a reference to the team, along with related links and metadata. If `null`, the story is in Story refinement (not assigned to a team)."
          },
          "workflowStep": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/SingleRelationship"
              }
            ],
            "description": "A relationship object linking to the workflow step that the story is currently assigned to. Includes a reference to the workflow step, along with related links and metadata."
          },
          "featureFlag": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/SingleRelationship"
              }
            ],
            "description": "A relationship object linking to the feature flag associated with the story. Includes a reference to the flag along with related links and metadata. If `null`, no feature flag is associated with the story."
          },
          "creator": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/SingleRelationship"
              }
            ],
            "description": "A relationship object linking to the user who created the story. Includes a reference to the user, along with related links and metadata."
          },
          "attachments": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/MultipleRelationships"
              }
            ],
            "description": "A relationship object linking to the story's attachments. The object includes resource identifiers, related links, and metadata."
          },
          "epic": {
            "type": [
              "null",
              "object"
            ],
            "allOf": [
              {
                "$ref": "#/components/schemas/SingleRelationship"
              }
            ],
            "description": "A relationship object linking to the epic that the story is associated with. Includes a reference to the epic, along with related links and metadata. If `null`, the story is not associated with any epic."
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "name": "X-API-KEY",
        "in": "header"
      }
    }
  }
}
```