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

# List ideas

> List all ideas in the workspace with pagination and filtering. Archived ideas are excluded from results.



## OpenAPI

````yaml /api/openapi.json get /ideas
openapi: 3.1.0
info:
  title: Ordinal API
  version: 1.0.0
  description: API to create and manage Ordinal workspaces, posts, profiles, and analytics
servers:
  - url: https://app.tryordinal.com/api/v1
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Analytics
    description: Social media analytics data
  - name: Approvals
    description: Post approval workflows
  - name: Comments
    description: >-
      Post comments for team collaboration. Supports @mentions using the format
      @[Display Name](userId).
  - name: Engagements
    description: Auto-engagements for posts (likes, comments, reposts)
  - name: Invites
    description: Workspace invitations for adding new users
  - name: Labels
    description: Labels for organizing posts
  - name: Instagram
    description: Instagram utilities for location search and tagging
  - name: LinkedIn
    description: LinkedIn utilities for profile lookups, tagging, and mentions
  - name: Posts
    description: Create and manage posts
  - name: Profiles
    description: List connected social profiles
  - name: Slack Boosts
    description: >-
      List connected Slack channels (webhooks), then create and manage slack
      boosts so teams get notified in Slack when posts publish. Requires Slack
      connected with marketing boost channels.
  - name: Subscribers
    description: Post subscribers for notifications
  - name: File Uploads
    description: >-
      Upload files from URLs for use in posts. Supports images (JPEG, PNG, GIF,
      WebP) up to 10 MB and videos (MP4, MOV) up to 350 MB.
  - name: Ideas
    description: >-
      Create and manage content ideas. Ideas are draft posts without scheduled
      dates that can be converted to calendar posts.
  - name: Inline Comments
    description: >-
      Text-anchored comments on specific post content. Read-only API for
      retrieving inline comments across channels.
  - name: Users
    description: Workspace users
  - name: Webhooks
    description: >-
      Create, list, get, update, and delete webhooks to receive real-time event
      notifications
  - name: Workspaces
    description: Workspace information
paths:
  /ideas:
    get:
      tags:
        - Ideas
      summary: List ideas
      description: >-
        List all ideas in the workspace with pagination and filtering. Archived
        ideas are excluded from results.
      operationId: ideas-list
      parameters:
        - name: limit
          in: query
          description: Maximum number of ideas to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          description: Cursor for pagination (idea ID from the last item of previous page)
          schema:
            type: string
            format: uuid
        - name: ids
          in: query
          description: Fetch specific ideas by IDs
          schema:
            oneOf:
              - type: array
                items:
                  type: string
                  format: uuid
              - type: string
                format: uuid
        - name: channel
          in: query
          description: Filter by channel
          schema:
            type: string
            enum:
              - LinkedIn
              - Twitter
              - TikTok
              - YouTubeShorts
        - name: linkedInProfileId
          in: query
          description: Filter by LinkedIn profile ID
          schema:
            type: string
            format: uuid
        - name: xProfileId
          in: query
          description: Filter by X/Twitter profile ID
          schema:
            type: string
            format: uuid
        - name: tikTokProfileId
          in: query
          description: Filter by TikTok profile ID
          schema:
            type: string
            format: uuid
        - name: youTubeProfileId
          in: query
          description: Filter by YouTube channel profile ID
          schema:
            type: string
            format: uuid
        - name: labelIds
          in: query
          description: Filter by label IDs (ideas with any of these labels)
          schema:
            oneOf:
              - type: array
                items:
                  type: string
                  format: uuid
              - type: string
                format: uuid
        - name: createdAtMin
          in: query
          description: Filter ideas created on or after this date
          schema:
            type: string
            format: date-time
        - name: createdAtMax
          in: query
          description: Filter ideas created on or before this date
          schema:
            type: string
            format: date-time
        - name: sortBy
          in: query
          description: Field to sort by
          schema:
            type: string
            enum:
              - createdAt
            default: createdAt
        - name: sortOrder
          in: query
          description: Sort order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
      responses:
        '200':
          description: List of ideas
          content:
            application/json:
              schema:
                type: object
                properties:
                  ideas:
                    type: array
                    items:
                      $ref: '#/components/schemas/Idea'
                  nextCursor:
                    type: string
                    nullable: true
                    description: Cursor for the next page of results
                  hasMore:
                    type: boolean
                    description: Whether there are more results
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Idea:
      type: object
      description: Content idea that can be converted to a calendar post
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        title:
          type: string
        channels:
          type: array
          items:
            type: string
        status:
          type: string
          description: Always 'Idea' for ideas
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        linkedIn:
          type: object
          nullable: true
          properties:
            profile:
              allOf:
                - $ref: '#/components/schemas/ChannelProfile'
              nullable: true
            copy:
              type: string
            assets:
              type: array
              description: Assets attached to the LinkedIn content
              items:
                $ref: '#/components/schemas/Asset'
        x:
          type: object
          nullable: true
          description: X (Twitter) content
          properties:
            profile:
              allOf:
                - $ref: '#/components/schemas/ChannelProfile'
              nullable: true
            tweets:
              type: array
              items:
                type: object
                properties:
                  copy:
                    type: string
                  assets:
                    type: array
                    description: Assets attached to this tweet
                    items:
                      $ref: '#/components/schemas/Asset'
        tikTok:
          $ref: '#/components/schemas/TikTokContent'
        youTubeShorts:
          $ref: '#/components/schemas/YouTubeShortsContent'
    ChannelProfile:
      type: object
      description: Profile information for a channel (LinkedIn, X, or Instagram)
      properties:
        id:
          type: string
          format: uuid
          description: Profile ID
        name:
          type: string
          nullable: true
          description: Profile name
        detail:
          type: string
          nullable: true
          description: Profile detail (vanity name for LinkedIn, @username for X)
    Asset:
      type: object
      description: Asset metadata for files attached to posts
      properties:
        id:
          type: string
          format: uuid
          description: Asset ID
        name:
          type: string
          description: Original filename
        url:
          type: string
          format: uri
          description: URL to access the asset
        mimetype:
          type: string
          description: MIME type of the file (e.g., image/jpeg, video/mp4)
        size:
          type: integer
          description: File size in bytes
        width:
          type: integer
          nullable: true
          description: Width in pixels for images and videos
        height:
          type: integer
          nullable: true
          description: Height in pixels for images and videos
        duration:
          type: number
          nullable: true
          description: Duration in seconds for videos
    TikTokContent:
      type: object
      nullable: true
      description: TikTok content. Present when the post targets the TikTok channel.
      properties:
        profile:
          allOf:
            - $ref: '#/components/schemas/ChannelProfile'
          nullable: true
        copy:
          type: string
          description: Caption text
        assets:
          type: array
          description: Assets attached to the TikTok post (one video).
          items:
            $ref: '#/components/schemas/Asset'
        privacyLevel:
          $ref: '#/components/schemas/TikTokPrivacyLevel'
        isCommentDisabled:
          type: boolean
        isDuetDisabled:
          type: boolean
        isStitchDisabled:
          type: boolean
        isPromotingBusiness:
          type: boolean
        isPaidPartnership:
          type: boolean
        videoCoverTimestampMs:
          type: integer
          format: int32
          nullable: true
          description: >-
            Timestamp (in milliseconds) of the video frame used as the cover
            thumbnail. Null when not set.
    YouTubeShortsContent:
      type: object
      nullable: true
      description: >-
        YouTube Shorts content. Present when the post targets the YouTube Shorts
        channel.
      properties:
        profile:
          allOf:
            - $ref: '#/components/schemas/ChannelProfile'
          nullable: true
        title:
          type: string
          nullable: true
          description: Video title
        description:
          type: string
          nullable: true
          description: Video description
        assets:
          type: array
          description: Assets attached to the YouTube Shorts post (one video).
          items:
            $ref: '#/components/schemas/Asset'
        privacyStatus:
          $ref: '#/components/schemas/YouTubePrivacyStatus'
        categoryId:
          type: string
          nullable: true
        notifySubscribers:
          type: boolean
        isEmbeddable:
          type: boolean
        isSelfDeclaredMadeForKids:
          type: boolean
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
    TikTokPrivacyLevel:
      type: string
      description: Audience visibility for the TikTok video.
      enum:
        - PUBLIC_TO_EVERYONE
        - FOLLOWER_OF_CREATOR
        - MUTUAL_FOLLOW_FRIENDS
        - SELF_ONLY
    YouTubePrivacyStatus:
      type: string
      description: Audience visibility for the YouTube Shorts video.
      enum:
        - public
        - private
        - unlisted
  responses:
    Unauthorized:
      description: Unauthorized - Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: UNAUTHORIZED
            message: Invalid or unauthorized API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authentication. Generate an API key from your workspace
        settings.

````