---
title: "List all stars"
method: POST
path: "/stars.list"
tags: ["Stars"]
---

# List all stars

`POST /stars.list`

## Request

- Base URL: `https://app.getoutline.com/api`
- URL: `https://app.getoutline.com/api/stars.list`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://app.getoutline.com/oauth/authorize`
    - Token URL: `https://app.getoutline.com/oauth/token` scopes: `read`, `write`

List all starred documents for the authenticated user. Stars allow users to bookmark important documents for quick access in the sidebar.

## Request body

- Pagination
  - `offset` number
  - `limit` number

## Response `200`

OK

- object
  - `data` object
    - `stars` Star[]
      - `id` string, uuid: Unique identifier for the object.
      - `index` string: Index of the star in the list of stars.
      - `documentId` string, uuid, nullable: Unique identifier for the starred document.
      - `collectionId` string, uuid, nullable: Unique identifier for the starred collection.
      - `createdAt` string, date-time: Date and time when this star was created
      - `updatedAt` string, date-time: Date and time when this star was last changed
    - `documents` Document[]
      - `id` string, uuid: Unique identifier for the object.
      - `collectionId` string, uuid, nullable: Identifier for the associated collection.
      - `parentDocumentId` string, uuid, nullable: Identifier for the document this is a child of, if any.
      - `title` string: The title of the document.
      - `fullWidth` boolean: Whether this document should be displayed in a full-width view.
      - `icon` string, nullable: An emoji or icon associated with the document.
      - `color` string, nullable: The color of the document icon in hex format.
      - `text` string: The text content of the document, contains markdown formatting
      - `data` object, nullable: The body of the document as a Prosemirror document, returned in place of text when requested.
      - `url` string: A URL path to access the document. Deprecated – prefer the `path` field.
      - `path` string: A URL path to access the document.
      - `urlId` string: A short unique ID that can be used to identify the document as an alternative to the UUID
      - `collaboratorIds` string[]: Identifiers of users who have edited the document.
      - `tasks` object: Task completion counts for the document.
        - `completed` number
        - `total` number
      - `templateId` string, uuid: Unique identifier for the template this document was created from, if any
      - `revision` number: A number that is auto incrementing with every revision of the document that is saved
      - `createdAt` string, date-time: The date and time that this object was created
      - `createdBy` User
        - `id` string, uuid: Unique identifier for the object.
        - `name` string: The name of this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if necessary.
        - `avatarUrl` string, uri: The URL for the image associated with this user, it will be displayed in the application UI and email notifications.
        - `color` string: A color representing the user, used in the UI for avatars without an image.
        - `email` string, email: The email associated with this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if necessary.
        - `role` 'admin' | 'member' | 'viewer' | 'guest'
        - `isSuspended` boolean: Whether this user has been suspended.
        - `lastActiveAt` string, date-time, nullable: The last time this user made an API request, this value is updated at most every 5 minutes.
        - `timezone` string, nullable: The timezone this user has registered.
        - `createdAt` string, date-time: The date and time that this user first signed in or was invited as a guest.
        - `updatedAt` string, date-time: The date and time that this user was last updated.
        - `deletedAt` string, date-time, nullable: The date and time that this user was deleted, if applicable.
        - `invitedBy` User (recursive)
      - `updatedAt` string, date-time: The date and time that this object was last changed
      - `updatedBy` User
        - `id` string, uuid: Unique identifier for the object.
        - `name` string: The name of this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if necessary.
        - `avatarUrl` string, uri: The URL for the image associated with this user, it will be displayed in the application UI and email notifications.
        - `color` string: A color representing the user, used in the UI for avatars without an image.
        - `email` string, email: The email associated with this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if necessary.
        - `role` 'admin' | 'member' | 'viewer' | 'guest'
        - `isSuspended` boolean: Whether this user has been suspended.
        - `lastActiveAt` string, date-time, nullable: The last time this user made an API request, this value is updated at most every 5 minutes.
        - `timezone` string, nullable: The timezone this user has registered.
        - `createdAt` string, date-time: The date and time that this user first signed in or was invited as a guest.
        - `updatedAt` string, date-time: The date and time that this user was last updated.
        - `deletedAt` string, date-time, nullable: The date and time that this user was deleted, if applicable.
        - `invitedBy` User (recursive)
      - `publishedAt` string, date-time, nullable: The date and time that this object was published
      - `dataAttributes` DocumentDataAttribute[], nullable
        - `dataAttributeId` string, uuid: Unique identifier for the associated data attribute.
        - `value` union: The value of the data attribute for this document.
          - string
          - boolean
          - number
        - `updatedAt` string, date-time: The date and time that this object attribute was last changed
      - `archivedAt` string, date-time, nullable: The date and time that this object was archived
      - `deletedAt` string, date-time, nullable: The date and time that this object was deleted
      - `deletedBy` User
        - `id` string, uuid: Unique identifier for the object.
        - `name` string: The name of this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if necessary.
        - `avatarUrl` string, uri: The URL for the image associated with this user, it will be displayed in the application UI and email notifications.
        - `color` string: A color representing the user, used in the UI for avatars without an image.
        - `email` string, email: The email associated with this user, it is migrated from Slack or Google Workspace when the SSO connection is made but can be changed if necessary.
        - `role` 'admin' | 'member' | 'viewer' | 'guest'
        - `isSuspended` boolean: Whether this user has been suspended.
        - `lastActiveAt` string, date-time, nullable: The last time this user made an API request, this value is updated at most every 5 minutes.
        - `timezone` string, nullable: The timezone this user has registered.
        - `createdAt` string, date-time: The date and time that this user first signed in or was invited as a guest.
        - `updatedAt` string, date-time: The date and time that this user was last updated.
        - `deletedAt` string, date-time, nullable: The date and time that this user was deleted, if applicable.
        - `invitedBy` User (recursive)
      - `deprecatedReason` string, nullable: The reason the document was archived or deleted, if one was provided.
      - `preferences` object, nullable: Document-level display preferences.
        - `headingPrefix` 'none' | 'numeric' | 'alphanumeric' | 'outline': Numbering style applied to the document's headings when rendered.
  - `pagination` Pagination
    - `offset` number
    - `limit` number
  - `policies` Policy[]
    - `id` string, uuid: Unique identifier for the object this policy references.
    - `abilities` object: The abilities that are allowed by this policy, if an array is returned then the individual ID's in the array represent the memberships that grant the ability.

## Other responses

- `401`: The API key is missing or otherwise invalid.
- `403`: The current API key is not authorized to perform this action.
- `429`: The request was rate limited.

## Changes

- **2026-11-02** `5ddf01ffba84`: 2 info
  - added the optional property `data/documents/items/path` to the response with the `200` status
  - response property `data/documents/items/url` deprecated
- **2026-09-20** `a75820943fbb`: 1 info
  - added the optional property `data/documents/items/deprecatedReason` to the response with the `200` status
- **2026-08-24** `dff00215628f`: 2 info
  - added the optional property `data/documents/items/deletedBy` to the response with the `200` status
  - added the optional property `data/documents/items/preferences` to the response with the `200` status
- **2026-08-12** `9a99ee93e11d`: 2 info
  - added the optional property `data/documents/items/createdBy/invitedBy` to the response with the `200` status
  - added the optional property `data/documents/items/updatedBy/invitedBy` to the response with the `200` status
- **2026-05-30** `304cd065561b`: 7 breaking, 4 warning, 15 info
  - the response property `data/documents/items/archivedAt` became nullable for the status `200`
  - the response property `data/documents/items/collectionId` became nullable for the status `200`
  - the response property `data/documents/items/createdBy/lastActiveAt` became nullable for the status `200`
  - the response property `data/documents/items/parentDocumentId` became nullable for the status `200`
  - …22 more

[Operation history](https://skmtc.dev/defaulr/apis/outline-api/changes/stars.list/post.md)

---

[API](https://skmtc.dev/defaulr/apis/outline-api.md) - [All operations](https://skmtc.dev/defaulr/apis/outline-api/llms.txt) - [OpenAPI document](https://skmtc.dev/defaulr/apis/outline-api/revisions/5ddf01ffba84?raw)