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

> ## Agent Instructions
> PostQueen's hosted API is https://api.postqueen.ai. The public API base is https://api.postqueen.ai/public/v1 and takes the raw API key in the Authorization header, with no Bearer prefix.
> The MCP server for posting is https://api.postqueen.ai/mcp/YOUR_API_KEY (or /mcp with Authorization: Bearer YOUR_API_KEY). docs.postqueen.ai/mcp only searches these docs and cannot post.
> The API key is under Connections > API Keys in the app, and only workspace admins can see it.

# List clippings

> Your workspace's clippings, newest first, 20 to a page, with the state of each.

export const ChannelStatus = ({status, children}) => {
  const look = ({
    available: {
      color: 'green',
      label: 'Available'
    },
    'in-review': {
      color: 'yellow',
      label: 'In review'
    },
    soon: {
      color: 'gray',
      label: 'Soon'
    }
  })[status] || ({
    color: 'gray',
    label: status
  });
  return <div className="pq-status not-prose" data-status={status}>
      <Badge color={look.color} shape="pill" size="md">{look.label}</Badge>
      {children ? <span className="pq-status-note">{children}</span> : null}
    </div>;
};

<ChannelStatus status="soon">Not available on PostQueen yet.</ChannelStatus>

Each entry is one clipping: its `id`, the video `url`, its `status` and `error`, the video's `title` and `thumbnail`, its `duration` in seconds and when it was started (`createdAt`). The clips themselves are on [Get a clipping](/public-api/clipping/get).

* `page` starts at `1`. Leave it out for the first page.
* `pages` is the number of pages there are.
* `title`, `thumbnail` and `duration` are `null` until the video has been analysed.


## OpenAPI

````yaml GET /clipping
openapi: 3.1.0
info:
  title: PostQueen Public API
  version: 1.0.0
  license:
    name: MIT
    identifier: MIT
  description: >-
    Schedule posts, upload media, read analytics and manage the channels of your
    PostQueen workspace.


    ## Authentication


    Send your API key in the `Authorization` header exactly as it is, with no
    prefix:


    ```

    Authorization: YOUR_API_KEY

    ```


    The key is under **Connections > API Keys** in the app. Only a workspace
    Admin or Super Admin can reveal or rotate it. An app your users sign in to
    with OAuth sends its `pos_` access token in the same header, also with no
    prefix. The workspace needs a subscription, and the free trial counts.


    ## Rate limits


    A workspace can send 30 `POST /posts` requests an hour, and a request
    refused with `400` counts too. `POST /upload` and `POST /upload-from-url`
    allow 300 requests an hour each, per workspace. Nothing else is limited. A
    limited endpoint answers with `X-RateLimit-Limit`, `X-RateLimit-Remaining`
    and `X-RateLimit-Reset` headers, and over the limit with `429` and
    `Retry-After` (seconds).


    ## Terminology


    The app says channel, the API says integration. They are the same thing: a
    connected account on a network.
servers:
  - url: https://api.postqueen.ai/public/v1
    description: PostQueen
security:
  - ApiKeyAuth: []
tags:
  - name: Channels
    description: Connected channels. The API calls them integrations.
  - name: Posts
    description: Create, list, change and delete posts
  - name: Media
    description: Upload files to the media library
  - name: Clipping
    description: >-
      Turn a YouTube video into short vertical clips. Not available on PostQueen
      yet
  - name: AI video
    description: Generate a video with AI into the media library
  - name: Analytics
    description: Channel and post metrics
  - name: Notifications
    description: The workspace's notifications
  - name: OAuth
    description: Sign-in for apps that act for other PostQueen workspaces
paths:
  /clipping:
    get:
      tags:
        - Clipping
      summary: List clippings
      description: >-
        Not available on PostQueen yet.


        The workspace's clippings, newest first, 20 per page. The clips of one
        clipping are on `GET /clipping/{id}`.
      operationId: listClippings
      parameters:
        - name: page
          in: query
          required: false
          description: Page number, starting at 1
          schema:
            type: integer
            minimum: 1
            default: 1
          example: 1
      responses:
        '200':
          description: One page of clippings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClippingsResponse'
              example:
                pages: 1
                results:
                  - id: 3f0c2a4e-8b1d-4c6e-9f2a-7d5b1e0c4a93
                    url: https://www.youtube.com/watch?v=VIDEO_ID
                    status: completed
                    error: null
                    title: How we plan a month of posts
                    thumbnail: https://example.com/video-thumbnail.jpg
                    duration: 1524
                    createdAt: '2026-10-01T09:00:12.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    ClippingsResponse:
      type: object
      properties:
        pages:
          type: integer
          description: The number of pages
        results:
          type: array
          items:
            $ref: '#/components/schemas/ClippingSummary'
    ClippingSummary:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          description: The video's link, as it was sent
        status:
          type: string
          enum:
            - analysing
            - transcribing
            - picking
            - rendering
            - completed
            - failed
        error:
          type:
            - string
            - 'null'
          description: >-
            Why the clipping failed, or what went wrong after its clips were
            made
        title:
          type:
            - string
            - 'null'
          description: The video's title, once it is analysed
        thumbnail:
          type:
            - string
            - 'null'
          description: The video's thumbnail, once it is analysed
        duration:
          type:
            - integer
            - 'null'
          description: The video's length in seconds, rounded up, once it is analysed
        createdAt:
          type: string
          format: date-time
    MessageError:
      type: object
      description: The error shape of most checks written into the public API itself
      properties:
        msg:
          type: string
  responses:
    Unauthorized:
      description: >-
        `No API Key found`, `Invalid API key`, `Invalid OAuth token`, or `No
        subscription found` when the workspace has no subscription
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageError'
          example:
            msg: Invalid API key
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Your API key from Connections > API Keys, or an OAuth access token
        (`pos_...`). Send it as it is, with no `Bearer` prefix.

````