> ## 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.
# Get a clipping
> A clipping's progress and its clips, with the video and media id of each finished clip.
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
{look.label}
{children ? {children} : null}
;
};
Not available on PostQueen yet.
Ask again every few seconds with the `id` from [Start a clipping](/public-api/clipping/start) until `status` is `completed` or `failed`:
| Status | What it means |
| -------------- | ------------------------------------------------------------------------------ |
| `analysing` | PostQueen is reading the video and taking the minutes |
| `transcribing` | The video had no captions PostQueen can use, so its audio is being transcribed |
| `picking` | AI is choosing the moments |
| `rendering` | The clips are being made. `clips` is filled from here on |
| `completed` | Done. At least one clip was made |
| `failed` | No clip was made. `error` says why, and the minutes were given back |
A `completed` clipping can still have failed clips, and an `error` when something went wrong after the clips were made, such as the draft posts.
## The clips
`clips` lists them in the order they appear in the video. Each has:
| Field | What it is |
| ----------------- | --------------------------------------------------------------------------------- |
| `id` | The clip's id |
| `title` | A short title, written by AI |
| `content` | The post text written for the clip, without hashtags |
| `start`, `end` | Where the clip sits in the source video, in seconds |
| `status` | `pending`, `completed` or `failed` |
| `error` | Why the clip failed |
| `mediaId`, `path` | The clip in your media library. Put them on a post as the media's `id` and `path` |
| `thumbnail` | A JPEG of the clip's first frame |
`title` and `content` are written from somebody else's video, in its language. Show them to a person before you post them.
An `id` that is not a clipping of your workspace answers `404 Clipping not found`.
## OpenAPI
````yaml GET /clipping/{id}
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/{id}:
get:
tags:
- Clipping
summary: Get a clipping
description: >-
Not available on PostQueen yet.
A clipping's progress and its clips. Ask again every few seconds until
`status` is `completed` or `failed`. A `completed` clipping can still
carry failed clips, and an `error` when something went wrong after the
clips were made. `failed` means no clip was made and the minutes were
given back.
operationId: getClipping
parameters:
- name: id
in: path
required: true
description: The clipping's id from `POST /clipping`
schema:
type: string
responses:
'200':
description: The clipping and its clips
content:
application/json:
schema:
$ref: '#/components/schemas/Clipping'
example:
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'
clips:
- id: 9b2d4f61-0c3e-4a58-8e7f-2d1c6b5a4e30
title: Plan the month in one sitting
content: >-
We plan a whole month of posts in one afternoon. Here is
the order we do it in.
start: 312.4
end: 371.9
status: completed
error: null
mediaId: e639003b-f727-4a1e-87bd-74a2c48ae41e
path: >-
https://cdn.example.com/clip-9b2d4f61-0c3e-4a58-8e7f-2d1c6b5a4e30.mp4
thumbnail: >-
https://cdn.example.com/clip-9b2d4f61-0c3e-4a58-8e7f-2d1c6b5a4e30.jpg
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: '`Clipping not found`'
content:
application/json:
schema:
$ref: '#/components/schemas/NestError'
example:
statusCode: 404
message: Clipping not found
components:
schemas:
Clipping:
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
clips:
type: array
description: >-
The clips, in the order they appear in the video. Empty until the
moments are picked
items:
$ref: '#/components/schemas/ClippingClip'
NestError:
type: object
description: >-
The standard error shape: validation errors, not-found errors and rate
limits
properties:
statusCode:
type: integer
message:
oneOf:
- type: string
- type: array
items:
type: string
error:
type: string
ClippingClip:
type: object
properties:
id:
type: string
title:
type: string
description: A short title, written by AI
content:
type: string
description: >-
The post text written for the clip, without hashtags. Written from
somebody else's video: show it to a person before you post it
start:
type: number
description: Where the clip starts in the source video, in seconds
end:
type: number
description: Where the clip ends in the source video, in seconds
status:
type: string
enum:
- pending
- completed
- failed
error:
type:
- string
- 'null'
description: Why the clip failed
mediaId:
type:
- string
- 'null'
description: >-
The clip's id in the media library. Send it with `path` as a post's
media
path:
type:
- string
- 'null'
description: URL of the clip's MP4, once it is made
thumbnail:
type:
- string
- 'null'
description: URL of a JPEG of the clip's first frame
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.
````