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

# List ideas

> Lists the workspace's ideas, newest first, with their media and labels. Stage filters (`stages[]`, `unassigned`) match ideas in any of them; label filters (`labels[]`, `untagged`) work the same way; the two groups combine with AND. Page size is set by the server: read `meta.per_page`.



## OpenAPI

````yaml /openapi.json get /ideas
openapi: 3.1.0
info:
  title: TryPost API
  version: 2.0.0
  description: >-
    REST API for TryPost. Authenticate with a workspace API key as a Bearer
    token.
servers:
  - url: https://app.trypost.it/api
    description: TryPost Cloud
security:
  - bearerAuth: []
tags:
  - name: Posts
    description: Create, read, update, delete and preview posts.
  - name: Post notes
    description: Internal notes on a post, visible to workspace members.
  - name: Approvals
    description: Approve or reject posts waiting for approval.
  - name: Recurrence
    description: Make a post repeat on a schedule.
  - name: Media and uploads
    description: Upload files and attach media to posts.
  - name: Social accounts
    description: Connected social accounts and their network-specific options.
  - name: Channels
    description: A channel's posting schedule and queue.
  - name: Ideas
    description: Ideas on the Create board.
  - name: Idea stages
    description: The groups (columns) of the ideas board.
  - name: Analytics
    description: Workspace and channel insights.
  - name: Labels
    description: Labels to organize posts and ideas.
  - name: Signatures
    description: Reusable text to append to posts.
  - name: Workspace
    description: The workspace the API key belongs to.
  - name: API keys
    description: Personal API keys for this workspace.
  - name: Webhooks
    description: Outgoing webhooks and their delivery logs.
  - name: Repurposes
    description: Automations that republish videos posted outside TryPost.
  - name: Platform
    description: Platform capabilities and content types.
paths:
  /ideas:
    get:
      tags:
        - Ideas
      summary: List ideas
      description: >-
        Lists the workspace's ideas, newest first, with their media and labels.
        Stage filters (`stages[]`, `unassigned`) match ideas in any of them;
        label filters (`labels[]`, `untagged`) work the same way; the two groups
        combine with AND. Page size is set by the server: read `meta.per_page`.
      operationId: listIdeas
      parameters:
        - name: stages[]
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Only ideas in these stages. Values that are not UUIDs are ignored.
            Must be sent as a list (`stages[]=…`); a single value without `[]`
            returns `422`.
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: unassigned
          in: query
          required: false
          description: >-
            Also (or only) ideas without a stage. `true`, `1`, `yes` or `on`
            turn it on; any other value is off.
          schema:
            type: boolean
        - name: labels[]
          in: query
          required: false
          style: form
          explode: true
          description: >-
            Only ideas with any of these labels. Values that are not UUIDs are
            ignored. Must be sent as a list (`stages[]=…`); a single value
            without `[]` returns `422`.
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: untagged
          in: query
          required: false
          description: >-
            Also (or only) ideas without labels. `true`, `1`, `yes` or `on` turn
            it on; any other value is off.
          schema:
            type: boolean
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: A page of ideas.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Idea'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
              example:
                data:
                  - id: 9e2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                    idea_stage_id: 9e1a2b3c-4d5e-4f6a-8b7c-9d0e1f2a3b4c
                    title: Behind the scenes of the 2.0 launch
                    body: >-
                      Show the team, the whiteboard and the first sketch of the
                      new composer.
                    position: 0
                    media:
                      - id: 9e2b3c50-7a8b-4c9d-8e0f-1a2b3c4d5e6f
                        path: medias/9e2b3c50-7a8b-4c9d-8e0f-1a2b3c4d5e6f.jpg
                        url: >-
                          https://media.trypost.it/medias/9e2b3c50-7a8b-4c9d-8e0f-1a2b3c4d5e6f.jpg
                        type: image
                        mime_type: image/jpeg
                        original_filename: whiteboard.jpg
                        size: 351204
                        meta:
                          width: 1600
                          height: 1200
                    labels:
                      - id: 9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f
                        name: Launch
                        color: '#2563EB'
                        created_at: '2026-09-01 10:00:00'
                        updated_at: '2026-09-01 10:00:00'
                    created_at: '2026-10-07 18:20:00'
                    updated_at: '2026-10-07 18:20:00'
                links:
                  first: https://app.trypost.it/api/ideas?page=1
                  last: https://app.trypost.it/api/ideas?page=1
                  prev: null
                  next: null
                meta:
                  current_page: 1
                  from: 1
                  last_page: 1
                  links:
                    - url: null
                      label: '« Previous'
                      page: null
                      active: false
                    - url: https://app.trypost.it/api/ideas?page=1
                      label: '1'
                      page: 1
                      active: true
                    - url: null
                      label: Next »
                      page: null
                      active: false
                  path: https://app.trypost.it/api/ideas
                  per_page: 25
                  to: 1
                  total: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Idea:
      type: object
      properties:
        id:
          type: string
          format: uuid
        idea_stage_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Stage (board column) of the idea. `null` is Unassigned.
        title:
          type:
            - string
            - 'null'
        body:
          type:
            - string
            - 'null'
        position:
          type: integer
          description: Order within its stage, starting at 0.
        media:
          type: array
          items:
            $ref: '#/components/schemas/MediaItem'
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
        created_at:
          type: string
          description: UTC, format `Y-m-d H:i:s`.
          examples:
            - '2026-10-07 18:20:00'
        updated_at:
          type: string
          description: UTC, format `Y-m-d H:i:s`.
          examples:
            - '2026-10-07 18:20:00'
    PaginationLinks:
      type: object
      properties:
        first:
          type:
            - string
            - 'null'
        last:
          type:
            - string
            - 'null'
        prev:
          type:
            - string
            - 'null'
        next:
          type:
            - string
            - 'null'
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
        from:
          type:
            - integer
            - 'null'
        last_page:
          type: integer
        links:
          type: array
          items:
            type: object
            properties:
              url:
                type:
                  - string
                  - 'null'
              label:
                type: string
              page:
                type:
                  - integer
                  - 'null'
              active:
                type: boolean
        path:
          type: string
        per_page:
          type: integer
          description: Page size set by the server. Read it; do not assume a value.
        to:
          type:
            - integer
            - 'null'
        total:
          type: integer
    MediaItem:
      type: object
      description: A media item as stored on a post.
      properties:
        id:
          type: string
          format: uuid
          description: Media id. Pass it as `media[].id` to reuse the file on another post.
        path:
          type: string
          description: Storage path, `medias/{uuid}.{ext}`.
        url:
          type: string
          format: uri
          description: Public URL of the file.
        type:
          type:
            - string
            - 'null'
          enum:
            - image
            - video
            - document
            - null
          description: '`null` on older items stored without a type.'
        mime_type:
          type:
            - string
            - 'null'
        original_filename:
          type:
            - string
            - 'null'
        size:
          type:
            - integer
            - 'null'
          description: Size in bytes.
        meta:
          $ref: '#/components/schemas/MediaItemMeta'
        source:
          type:
            - string
            - 'null'
          enum:
            - ai
            - unsplash
            - google_drive
            - google_photos
            - canva
            - null
          description: >-
            Where the file came from in the app. Present only on items added
            from one of these sources.
        source_meta:
          type:
            - object
            - 'null'
          description: Details from that source. Present only when the source gave any.
      examples:
        - id: 9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f
          path: medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg
          url: >-
            https://media.trypost.it/medias/9d3c1f30-8a9b-4c0d-9e1f-2a3b4c5d6e7f.jpg
          type: image
          mime_type: image/jpeg
          original_filename: launch.jpg
          size: 482113
          meta:
            width: 1080
            height: 1350
            alt_text: Product launch banner
    Label:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        color:
          type: string
          description: Hex color, `#RRGGBB`.
          examples:
            - '#2563EB'
        created_at:
          type: string
          description: UTC, format `Y-m-d H:i:s`.
          examples:
            - '2026-09-01 10:00:00'
        updated_at:
          type: string
          description: UTC, format `Y-m-d H:i:s`.
          examples:
            - '2026-09-01 10:00:00'
    ErrorBody:
      type: object
      properties:
        message:
          type: string
    ValidationErrorBody:
      type: object
      properties:
        message:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    RateLimitErrorBody:
      type: object
      properties:
        name:
          type: string
          const: rate_limit_exceeded
        message:
          type: string
          examples:
            - Rate limit exceeded. Please retry after 30 seconds.
    MediaItemMeta:
      type: object
      description: >-
        Editable settings of one media item. Other keys the server measured (for
        example `width`, `height`, `duration`) may also appear in responses.
      properties:
        alt_text:
          type: string
          maxLength: 2000
          description: >-
            Accessibility description. Applies to images; each network truncates
            it to its own cap.
        user_tags:
          type: array
          maxItems: 20
          description: People tagged on an Instagram image.
          items:
            type: object
            required:
              - username
              - x
              - 'y'
            properties:
              username:
                type: string
                pattern: ^@?[A-Za-z0-9._]{1,30}$
                description: Public Instagram username. A leading `@` is dropped.
              x:
                type: number
                minimum: 0
                maximum: 1
                description: Offset from the left edge, 0 to 1.
              'y':
                type: number
                minimum: 0
                maximum: 1
                description: Offset from the top edge, 0 to 1.
        cover_offset_ms:
          type: integer
          minimum: 0
          description: >-
            Video frame used as the cover, in milliseconds from the start.
            Cannot pass the end of the video.
  responses:
    Unauthorized:
      description: >-
        Missing, invalid, revoked or expired API key. Bodies: `Unauthenticated.`
        (no key, or a key that is invalid or revoked), `Token expired.` (past
        its `expires_at`), `Token not found.` and `No workspace selected.` (the
        key is no longer bound to a workspace).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            message: Unauthenticated.
    PaymentRequired:
      description: >-
        TryPost Cloud only: the workspace's account has no active subscription
        or trial. Body: `{"message": "Active subscription required."}`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
          example:
            message: Active subscription required.
    Forbidden:
      description: >-
        The request is not allowed. API keys work only for workspace admins (the
        account owner or a member marked as admin): otherwise every request
        returns `Insufficient workspace permissions.`. Other bodies: `Workspace
        access denied.` (the key's user left the workspace) and `Personal access
        token required.` (an MCP OAuth token was sent) and `This action is
        unauthorized.` (the note belongs to another member).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
    ValidationError:
      description: Validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorBody'
    TooManyRequests:
      description: 'Rate limit exceeded. Limits: 60 requests per minute per workspace.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitErrorBody'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Workspace API key from Settings → API Keys.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.