# PostQuickAI API

REST API for PostQuickAI — generate content, schedule posts, manage social accounts, and run analytics across 8+ platforms. Bearer token auth (pq_live_*). Used directly or via the @postquickai/mcp MCP server for agent integration.

Version: 1.0.0
Base URL: https://www.postquick.ai/api

## Authentication

All endpoints require `Authorization: Bearer pq_live_...` header.
Obtain an API key from https://www.postquick.ai/dashboard/api (requires API add-on).

## Endpoints

### GET /v1/accounts

**operationId**: `listAccounts`
**summary**: List connected social accounts

Returns every social account (Twitter/X, Threads, Bluesky, LinkedIn, Facebook, Instagram, YouTube, TikTok) connected across all the user's content groups.
**tags**: Accounts

### DELETE /v1/accounts/{accountId}

**operationId**: `disconnectAccount`
**summary**: Disconnect a social account

Permanently disconnect a social account. Deletes stored OAuth tokens. Re-connecting requires the dashboard OAuth flow.
**tags**: Accounts

### POST /v1/captions/carousel

**operationId**: `generateCarouselCaption`
**summary**: Generate a carousel caption

Generate a caption specifically tailored for a multi-slide carousel post.
**tags**: AI Content

### POST /v1/captions/generate

**operationId**: `generateCaption`
**summary**: Generate a caption

Generate a social media caption with AI, optionally grounded in a content group's brand profile. Counts as 1 AI text generation.
**tags**: AI Content

### POST /v1/captions/video

**operationId**: `generateVideoCaption`
**summary**: Generate a video caption

Generate an engaging caption for a video post (hooks, CTAs, optimized for TikTok/Reels/Shorts).
**tags**: AI Content

### GET /v1/content-groups

**operationId**: `listContentGroups`
**summary**: List content groups

Returns every content group (a.k.a. "app" — one per brand/project) owned by the authenticated user.
**tags**: Content Groups

### POST /v1/content-groups

**operationId**: `createContentGroup`
**summary**: Create a content group

Creates a new content group. Content groups act as containers for posts, brand instructions, and connected social accounts. Subject to the content-group limit on your plan.
**tags**: Content Groups

### GET /v1/content-groups/{groupId}

**operationId**: `getContentGroup`
**summary**: Retrieve a content group

Returns a single content group with its associated platforms, social accounts, and brand instructions.
**tags**: Content Groups

### DELETE /v1/content-groups/{groupId}

**operationId**: `deleteContentGroup`
**summary**: Delete a content group

Permanently deletes a content group and all its associated posts. Social account connections are preserved.
**tags**: Content Groups

### GET /v1/content-groups/{groupId}/analytics

**operationId**: `getGroupAnalytics`
**summary**: Group analytics

Aggregate social performance analytics for all posts in a content group. Breaks down by platform, content type, and includes top posts + daily trend.
**tags**: Content Groups, Analytics

### GET /v1/content-groups/{groupId}/instructions

**operationId**: `getInstructions`
**summary**: Get brand instructions

Retrieves the brand profile + generation settings for a content group (brand_name, tone, target audience, topics, auto-generation flags, YOLO mode, etc.).
**tags**: Content Groups, Instructions

### PUT /v1/content-groups/{groupId}/instructions

**operationId**: `updateInstructions`
**summary**: Update brand instructions

Create or update brand profile fields for a content group. Upsert — any subset of fields can be passed.
**tags**: Content Groups, Instructions

### POST /v1/content/adjust-tone

**operationId**: `adjustTone`
**summary**: Adjust tone

Rewrite existing copy in a different tone while preserving meaning.
**tags**: AI Content

### POST /v1/content/custom-edit

**operationId**: `customEdit`
**summary**: Custom edit

Apply a free-form natural-language edit to existing copy.
**tags**: AI Content

### POST /v1/content/make-concise

**operationId**: `makeConcise`
**summary**: Make concise

Tighten copy while preserving meaning. Useful for Twitter/X 280-char limit.
**tags**: AI Content

### POST /v1/content/proofread

**operationId**: `proofread`
**summary**: Proofread

Grammar and spelling fixes while preserving voice and style.
**tags**: AI Content

### POST /v1/hashtags/generate

**operationId**: `generateHashtags`
**summary**: Generate hashtags

AI-generated hashtags optimized for the target platform. Platform-specific defaults: Instagram=30, Twitter=1-2, LinkedIn=3-5.
**tags**: AI Content

### POST /v1/images/generate

**operationId**: `generateImage`
**summary**: Generate an image

Generate an AI image via Gemini Flash (default), GPT Image 1.5, or Nano Banana Pro. Image is uploaded to Supabase Storage; response includes a public URL.
**tags**: Images

### GET /v1/me

**operationId**: `getMe`
**summary**: Authenticated user info

Returns the authenticated user's email, user ID, subscription plan, and API key info.
**tags**: Account

### GET /v1/posts

**operationId**: `listPosts`
**summary**: List posts

List posts filtered by content group and/or status. Use this to enumerate posts before acting on a specific one.
**tags**: Posts

### POST /v1/posts/create

**operationId**: `createPost`
**summary**: Create a post

Manually create a post with your own content. Supports text, image, carousel, and video post types. Media URLs must be publicly accessible.
**tags**: Posts

### POST /v1/posts/generate

**operationId**: `generatePost`
**summary**: Generate a post

Uses the content group's brand profile (tone, audience, topics) to generate a new post via AI. Counts as 1 AI text generation.
**tags**: Posts

### GET /v1/posts/{postId}

**operationId**: `getPost`
**summary**: Retrieve a post

Fetch a single post by ID.
**tags**: Posts

### PUT /v1/posts/{postId}

**operationId**: `updatePost`
**summary**: Update a post

Update content, platforms, media, scheduling, or thread parts on an existing post.
**tags**: Posts

### DELETE /v1/posts/{postId}

**operationId**: `deletePost`
**summary**: Delete a post

Permanently deletes a post. Cannot be undone.
**tags**: Posts

### GET /v1/posts/{postId}/analytics

**operationId**: `getPostAnalytics`
**summary**: Post analytics

Per-platform social performance metrics (views, likes, comments, shares, saves) for a post, plus 30-day history.
**tags**: Posts, Analytics

### PUT /v1/posts/{postId}/images

**operationId**: `updatePostImages`
**summary**: Update post images

Attach, replace, or remove images on a post.
**tags**: Posts

### POST /v1/posts/{postId}/publish

**operationId**: `publishPost`
**summary**: Publish a post

Immediately publish a post to the specified platforms. Returns success/failure per platform.
**tags**: Posts

### POST /v1/posts/{postId}/regenerate

**operationId**: `regeneratePost`
**summary**: Regenerate a post

Rewrite an existing post with AI based on natural-language feedback. Optionally regenerate the image.
**tags**: Posts

### POST /v1/posts/{postId}/reset-platforms

**operationId**: `resetPostPlatforms`
**summary**: Reset posted platforms

Clear posted_platforms and error_message so the post can be republished cleanly. Useful after fixing a failed publish.
**tags**: Posts

### POST /v1/posts/{postId}/schedule

**operationId**: `schedulePost`
**summary**: Schedule a post

Schedule a post for future publishing. Cron picks it up and publishes automatically.
**tags**: Posts

### GET /v1/usage

**operationId**: `getUsage`
**summary**: Usage & limits

Returns current monthly usage vs. plan limits for text generation, image generation, video credits, and content groups.
**tags**: Account

### POST /v1/videos/generate

**operationId**: `generateVideo`
**summary**: Generate a video

Start an async video generation job. Poll with getVideoStatus. Returns a video post record with status="generating".
**tags**: Videos

### GET /v1/videos/{videoId}

**operationId**: `getVideo`
**summary**: Retrieve a video

Fetch a single video post by ID.
**tags**: Videos

### PUT /v1/videos/{videoId}

**operationId**: `updateVideo`
**summary**: Update a video

Update title, description, platforms, or scheduling for a video post.
**tags**: Videos

### DELETE /v1/videos/{videoId}

**operationId**: `deleteVideo`
**summary**: Delete a video

Permanently deletes a video post.
**tags**: Videos

### POST /v1/videos/{videoId}/publish

**operationId**: `publishVideo`
**summary**: Publish a video

Immediately publish a video to TikTok, YouTube, Instagram Reels, or Twitter/X.
**tags**: Videos

### POST /v1/videos/{videoId}/reset-platforms

**operationId**: `resetVideoPlatforms`
**summary**: Reset video posted platforms

Clear posted_platforms/error_message on a video so it can be republished.
**tags**: Videos

### POST /v1/videos/{videoId}/schedule

**operationId**: `scheduleVideo`
**summary**: Schedule a video

Schedule a video post for future publishing.
**tags**: Videos

### GET /v1/videos/{videoId}/status

**operationId**: `getVideoStatus`
**summary**: Check video status

Poll the generation status of a video. Returns status (pending/generating/draft/failed), progress, and the final video URL when ready.
**tags**: Videos

---

For the full machine-readable spec, see /openapi.json.
For agent integrations, see /ai-agents.