API Documentation

API access is available on the Agency plan

Integrate PilotVex tools directly into your workflow with our REST API. Generate captions, optimize hashtags, and analyze posts programmatically.

Upgrade to Agency

Introduction

The PilotVex API gives you programmatic access to our AI-powered content tools. Build integrations, automate your content pipeline, or embed PilotVex capabilities directly into your own products.

Base URL
https://pilotvex.com/api/v1
Auth
Bearer token (API key)
Rate limits
500/day, 100/hour
Format
JSON request & response

Available Endpoints

Authentication

All API requests require a valid API key sent in the Authorization header.

1. Get an API Key

Generate an API key from your API Keys settings page. You can create up to 5 keys. Store them securely - they are only shown once.

2. Include the Header

Add the following header to every request:

bash
Authorization: Bearer pvx_your_key_here

3. Example Request

bash
text"text-sky-400">-violet-400 font"text-sky-400">-semibold">curl text-sky-400">-X text"text-sky-400">-violet-400 font"text-sky-400">-semibold">POST https://pilotvex.com/api/v1/caption \
  text-sky-400">-H "Authorization: Bearer pvx_your_key_here" \
  text-sky-400">-H "Content"text-sky-400">-Type: application/json" \
  text-sky-400">-d '{"topic": "AI tools for creators", "platform": "instagram"}'

Authentication Errors

401Missing, malformed, or invalid API key
403Valid key but account does not have Agency plan
POST/api/v1/caption

Generate platform-optimized captions powered by AI. Returns a ready-to-use caption tailored for your target platform, tone, and length.

Request Body

ParameterTypeDescription
topicstringThe topic or subject for the caption
platformstringTarget social media platform
Allowed: instagram, twitter, linkedin, youtube, tiktok, facebook, threads
Default: instagram
tonestringDesired tone of the caption
Allowed: professional, casual, humorous, inspirational, educational, storytelling
Default: professional
lengthstringDesired caption length
Allowed: short, medium, long
Default: medium
languagestringISO 639-1 language code
Allowed: en, es, fr, de, pt, hi, etc.
Default: en

Example Request

bash
text"text-sky-400">-violet-400 font"text-sky-400">-semibold">curl text-sky-400">-X text"text-sky-400">-violet-400 font"text-sky-400">-semibold">POST https://pilotvex.com/api/v1/caption \
  text-sky-400">-H "Authorization: Bearer pvx_your_key_here" \
  text-sky-400">-H "Content"text-sky-400">-Type: application/json" \
  text-sky-400">-d '{
    "topic": "benefits of morning routines",
    "platform": "instagram",
    "tone": "inspirational",
    "length": "medium",
    "language": "en"
  }'
javascript
400">text-violet-400">const 400">text-violet-400">response = 400">text-violet-400">await 400">text-violet-400">fetch("400">https:"text-zinc-600"400">>//pilotvex.com/api/v1/caption", {
  method: "400">POST",
  400">text-violet-400">headers: {
    "400">Authorization": "400">Bearer pvx_your_key_here",
    "400">Content-Type": "400">application/"text-violet-400"400">>json",
  },
  body: JSON.stringify({
    topic: "400">benefits of morning routines",
    platform: "400">instagram",
    tone: "400">inspirational",
    length: "400">medium",
  }),
});

400">text-violet-400">const 400">text-violet-400">data = 400">text-violet-400">await 400">text-violet-400">response.400">text-violet-400">json();
console.log(400">text-violet-400">data.result.caption);

Example Response

json
{
  "tool": "caption",
  "result": {
    "caption": "Rise and shine āœØ Your morning routine isn't just a habit - it's the foundation of your success story.\n\nHere's what happens when you commit to mornings:\nā†’ Clarity replaces chaos\nā†’ Productivity becomes effortless\nā†’ Your goals stop feeling distant\n\nThe most successful people don't just wake up early - they wake up intentionally.\n\nWhat's the first thing you do every morning? Drop it below šŸ‘‡\n\n#MorningRoutine #ProductivityTips #SuccessMindset"
  }
}
Try it out
POST/api/v1/hashtags

Generate strategic hashtag sets categorized by reach potential. Returns high-reach, medium-reach, and niche-specific hashtags optimized for discoverability.

Request Body

ParameterTypeDescription
descriptionstringTopic or content description for hashtag generation
platformstringTarget social media platform
Allowed: instagram, twitter, linkedin, youtube, tiktok
Default: instagram
nichestringYour content niche for more targeted hashtags
Allowed: general, tech, fitness, food, travel, fashion, business, education, etc.
Default: general

Example Request

bash
text"text-sky-400">-violet-400 font"text-sky-400">-semibold">curl text-sky-400">-X text"text-sky-400">-violet-400 font"text-sky-400">-semibold">POST https://pilotvex.com/api/v1/hashtags \
  text-sky-400">-H "Authorization: Bearer pvx_your_key_here" \
  text-sky-400">-H "Content"text-sky-400">-Type: application/json" \
  text-sky-400">-d '{
    "description": "AI"text-sky-400">-powered productivity tools for remote teams",
    "platform": "instagram",
    "niche": "tech"
  }'
javascript
400">text-violet-400">const 400">text-violet-400">response = 400">text-violet-400">await 400">text-violet-400">fetch("400">https:"text-zinc-600"400">>//pilotvex.com/api/v1/hashtags", {
  method: "400">POST",
  400">text-violet-400">headers: {
    "400">Authorization": "400">Bearer pvx_your_key_here",
    "400">Content-Type": "400">application/"text-violet-400"400">>json",
  },
  body: JSON.stringify({
    description: "400">AI-powered productivity tools for remote teams",
    platform: "400">instagram",
    niche: "400">tech",
  }),
});

400">text-violet-400">const 400">text-violet-400">data = 400">text-violet-400">await 400">text-violet-400">response.400">text-violet-400">json();
console.log(400">text-violet-400">data.result);

Example Response

json
{
  "tool": "hashtags",
  "result": {
    "high_reach": [
      "#AI", "#Productivity", "#RemoteWork", "#Technology",
      "#FutureOfWork", "#Automation", "#TechTools"
    ],
    "medium_reach": [
      "#AITools", "#ProductivityHacks", "#RemoteTeams",
      "#WorkFromAnywhere", "#TeamCollaboration", "#AIProductivity"
    ],
    "niche": [
      "#AIForTeams", "#RemoteProductivity", "#SmartWorkflow",
      "#AIWorkspace", "#DistributedTeams", "#ProductivityStack"
    ]
  }
}
Try it out
POST/api/v1/analyzer

Analyze existing post content for engagement potential, readability, and platform optimization. Returns scores and actionable suggestions to improve your content.

Request Body

ParameterTypeDescription
textstringThe post content to analyze
platformstringPlatform the post is intended for
Allowed: instagram, twitter, linkedin, youtube, tiktok, facebook, threads
Default: instagram

Example Request

bash
text"text-sky-400">-violet-400 font"text-sky-400">-semibold">curl text-sky-400">-X text"text-sky-400">-violet-400 font"text-sky-400">-semibold">POST https://pilotvex.com/api/v1/analyzer \
  text-sky-400">-H "Authorization: Bearer pvx_your_key_here" \
  text-sky-400">-H "Content"text-sky-400">-Type: application/json" \
  text-sky-400">-d '{
    "text": "Just launched our new product! Check it out at example.com. #launch #startup",
    "platform": "instagram"
  }'
javascript
400">text-violet-400">const 400">text-violet-400">response = 400">text-violet-400">await 400">text-violet-400">fetch("400">https:"text-zinc-600"400">>//pilotvex.com/api/v1/analyzer", {
  method: "400">POST",
  400">text-violet-400">headers: {
    "400">Authorization": "400">Bearer pvx_your_key_here",
    "400">Content-Type": "400">application/"text-violet-400"400">>json",
  },
  body: JSON.stringify({
    text: "400">Just launched our new product! Check it out at example.com. "text-zinc-600"400">>#launch #startup",
    platform: "400">instagram",
  }),
});

400">text-violet-400">const 400">text-violet-400">data = 400">text-violet-400">await 400">text-violet-400">response.400">text-violet-400">json();
console.log(400">text-violet-400">data.result);

Example Response

json
{
  "tool": "analyzer",
  "result": {
    "engagement_score": 45,
    "readability_score": 72,
    "sentiment": "positive",
    "word_count": 14,
    "hashtag_count": 2,
    "has_call_to_action": true,
    "has_emoji": false,
    "suggestions": [
      "Add emojis to increase engagement by ~25% on Instagram",
      "Expand caption length - top-performing Instagram posts average 138-150 characters",
      "Include 8-15 relevant hashtags for optimal reach",
      "Add a question to encourage comments and boost algorithmic ranking",
      "Avoid external links in Instagram captions - use 'link in bio' instead"
    ],
    "platform_fit": "moderate"
  }
}
Try it out
POST/api/v1/thumbnailCOMING SOON

Generate thumbnail ideas and compositions for video content. This endpoint is currently in development and will return a 501 status.

Request Body

ParameterTypeDescription
titlestringVideo or content title for the thumbnail
platformstringTarget platform
Allowed: youtube, tiktok, instagram
Default: youtube
stylestringVisual style preference
Allowed: bold, minimal, vibrant, dark, professional
Default: bold

Not yet available

The thumbnail API endpoint is under active development. Requests to this endpoint currently return 501 Not Implemented. Use the dashboard tool in the meantime.

Error Handling

All errors return a consistent JSON format with an error field. Always check the HTTP status code and handle errors gracefully.

Error Response Format

json
{
  "error": "Human-readable error message"
}

Status Codes

StatusMeaning
200Success
400Bad Request
401Unauthorized
403Forbidden
429Rate Limited
500Server Error
501Not Implemented

Rate Limit Details

100
requests per hour per API key
500
requests per day per API key

When rate limited, the API returns a 429 status with a retryAfter field indicating seconds until the limit resets. Your monthly plan usage limit also applies.

Rate Limit Response Example

json
{
  "error": "Rate limit exceeded. 100 requests/hour.",
  "retryAfter": 45
}

Code Examples

Complete, copy-paste-ready examples in popular languages. Replace pvx_your_key_here with your actual API key.

JavaScript / Node.js

javascript
400">text-violet-400">const PILOTVEX_API_KEY = "400">pvx_your_key_here";
400">text-violet-400">const BASE_URL = "400">https:"text-zinc-600"400">>//pilotvex.com/api/v1";

400">text-violet-400">async 400">text-violet-400">function generateCaption(topic, platform = "400">instagram") {
  400">text-violet-400">const 400">text-violet-400">response = 400">text-violet-400">await 400">text-violet-400">fetch(BASE_URL + "400">/caption", {
    method: "400">POST",
    400">text-violet-400">headers: {
      "400">Authorization": "400">Bearer " + PILOTVEX_API_KEY,
      "400">Content-Type": "400">application/"text-violet-400"400">>json",
    },
    body: JSON.stringify({ topic, platform }),
  });

  400">text-violet-400">if (!400">text-violet-400">response.ok) {
    400">text-violet-400">const err = 400">text-violet-400">await 400">text-violet-400">response.400">text-violet-400">json();
    throw new Error(err.error || "400">Request failed");
  }

  400">text-violet-400">const 400">text-violet-400">data = 400">text-violet-400">await 400">text-violet-400">response.400">text-violet-400">json();
  400">text-violet-400">return 400">text-violet-400">data.result.caption;
}

400">text-zinc-600">// Usage
400">text-violet-400">const caption = 400">text-violet-400">await generateCaption("400">AI tools for creators", "400">linkedin");
console.log(caption);

Python

python
400">text-violet-400">import 400">text-violet-400">requests

PILOTVEX_API_KEY = "400">pvx_your_key_here"
BASE_URL = "400">https:"text-zinc-600"400">>//pilotvex.com/api/v1"

400">text-violet-400">def generate_caption(topic, platform="400">instagram", tone="400">professional"):
    400">text-violet-400">response = 400">text-violet-400">requests.post(
        f"400">{BASE_URL}/caption",
        400">text-violet-400">headers={
            "400">Authorization": f"400">Bearer {PILOTVEX_API_KEY}",
            "400">Content-Type": "400">application/"text-violet-400"400">>json",
        },
        400">text-violet-400">json={
            "400">topic": topic,
            "400">platform": platform,
            "400">tone": tone,
        },
    )

    400">text-violet-400">response.raise_for_status()
    400">text-violet-400">data = 400">text-violet-400">response.400">text-violet-400">json()
    400">text-violet-400">return 400">text-violet-400">data["400">result"]["400">caption"]

400">text-violet-400">def get_hashtags(description, platform="400">instagram", niche="400">general"):
    400">text-violet-400">response = 400">text-violet-400">requests.post(
        f"400">{BASE_URL}/hashtags",
        400">text-violet-400">headers={
            "400">Authorization": f"400">Bearer {PILOTVEX_API_KEY}",
            "400">Content-Type": "400">application/"text-violet-400"400">>json",
        },
        400">text-violet-400">json={
            "400">description": description,
            "400">platform": platform,
            "400">niche": niche,
        },
    )

    400">text-violet-400">response.raise_for_status()
    400">text-violet-400">data = 400">text-violet-400">response.400">text-violet-400">json()
    400">text-violet-400">return 400">text-violet-400">data["400">result"]

400">text-zinc-600"># Usage
caption = generate_caption("400">AI tools for creators", "400">linkedin", "400">professional")
400">text-violet-400">print(caption)

hashtags = get_hashtags("400">machine learning tutorials", "400">instagram", "400">tech")
400">text-violet-400">print(hashtags["400">high_reach"])

cURL

bash
# Generate a caption
text"text-sky-400">-violet-400 font"text-sky-400">-semibold">curl text-sky-400">-X text"text-sky-400">-violet-400 font"text-sky-400">-semibold">POST https://pilotvex.com/api/v1/caption \
  text-sky-400">-H "Authorization: Bearer pvx_your_key_here" \
  text-sky-400">-H "Content"text-sky-400">-Type: application/json" \
  text-sky-400">-d '{"topic": "AI tools for creators", "platform": "linkedin", "tone": "professional"}'

# Generate hashtags
text"text-sky-400">-violet-400 font"text-sky-400">-semibold">curl text-sky-400">-X text"text-sky-400">-violet-400 font"text-sky-400">-semibold">POST https://pilotvex.com/api/v1/hashtags \
  text-sky-400">-H "Authorization: Bearer pvx_your_key_here" \
  text-sky-400">-H "Content"text-sky-400">-Type: application/json" \
  text-sky-400">-d '{"description": "machine learning tutorials", "platform": "instagram", "niche": "tech"}'

# Analyze a post
text"text-sky-400">-violet-400 font"text-sky-400">-semibold">curl text-sky-400">-X text"text-sky-400">-violet-400 font"text-sky-400">-semibold">POST https://pilotvex.com/api/v1/analyzer \
  text-sky-400">-H "Authorization: Bearer pvx_your_key_here" \
  text-sky-400">-H "Content"text-sky-400">-Type: application/json" \
  text-sky-400">-d '{"text": "Your post content here...", "platform": "instagram"}'