MENU navbar-image

Introduction

ViewsMax REST API: multi-platform posts, offers, tracking links, analytics, media, and connections. AI agents can also use the MCP server at /api/mcp — see https://viewsmax.com/ai.md and /api/ai for discovery.

This documentation aims to provide all the information you need to work with our API.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer vmx_{YOUR_API_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Authenticate with your ViewsMax API key (vmx_...) as a Bearer token: Authorization: Bearer vmx_.... Create or rotate it in the ViewsMax app under Settings → AI Assistant Access. Read-only keys can only call GET endpoints, and API keys are limited to the posts/offers/tracking/social/connections surface. Session tokens from POST /api/login also work and have full account access.

Discovery

AI capability discovery

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/ai" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/ai"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):

Show headers 
cache-control: max-age=3600, public
content-type: application/json
x-ratelimit-limit: 30
x-ratelimit-remaining: 29
vary: Origin
 

{
    "name": "ViewsMax",
    "summary": "Social posting + link tracking/analytics SaaS. AI agents act on a user's behalf: compose and schedule posts to YouTube, TikTok, X, LinkedIn, Threads, Instagram, and Bluesky; create offers and tracked links; read click, conversion, and revenue stats; research outlier videos (content that massively over-performed its channel) and get AI breakdowns of why they worked. User data is private — all access is authenticated.",
    "site": "https://viewsmax.com",
    "docs": {
        "agents": "https://viewsmax.com/ai.md",
        "llms_txt": "https://viewsmax.com/llms.txt",
        "api_reference": "https://api.viewsmax.com/docs",
        "openapi": "https://api.viewsmax.com/docs.openapi"
    },
    "mcp": {
        "endpoint": "https://api.viewsmax.com/api/mcp",
        "transport": "streamable-http",
        "auth": [
            {
                "type": "oauth2",
                "grant": "authorization_code",
                "pkce": true,
                "scopes": [
                    "mcp",
                    "mcp:read",
                    "mcp:write"
                ],
                "authorization_server_metadata": "https://api.viewsmax.com/.well-known/oauth-authorization-server",
                "protected_resource_metadata": "https://api.viewsmax.com/.well-known/oauth-protected-resource/api/mcp",
                "dynamic_client_registration": true
            },
            {
                "type": "api_key",
                "header": "Authorization: Bearer <key>",
                "key_prefix": "vmx_",
                "access_levels": [
                    "read",
                    "full"
                ],
                "obtain_at": "https://viewsmax.com/dashboard/settings"
            }
        ],
        "tools": [
            {
                "name": "list_connected_accounts",
                "description": "List every social account the user has connected, plus a Beehiiv newsletter connection if there is one — a platform can appear more than once when several accounts are connected on it. Each entry carries social_account_id or connection_id (matching list_brands) plus its store. Posts can only publish to connected platforms; use get_connect_url for anything missing. Beehiiv is connected via an API key on the Connections page, not get_connect_url, and is used for newsletter reach, not posting.",
                "access": "read"
            },
            {
                "name": "list_brands",
                "description": "List the user's brands — named groups of connected accounts (e.g. a brand holding a TikTok, an X and a YouTube account). Pass a brand id to create_post as brand_id to post to every connected account in the brand at once. Accounts with a status other than \"connected\" are skipped when posting.",
                "access": "read"
            },
            {
                "name": "upload_media",
                "description": "Download a file from a URL and host it on ViewsMax storage for use in posts. Returns a media entry ({type, url, path}) to pass to create_post. Supports jpeg/png/webp/gif images and mp4/mov video. Each call stores a new copy of the file, so don't repeat a call that already succeeded.",
                "access": "write"
            },
            {
                "name": "create_post",
                "description": "Compose a social post for one or more platforms (tiktok, youtube, x, linkedin, threads, instagram, bluesky). Target either platforms[] or brand_id (from list_brands, posts to every connected account in the brand) — not both. status \"draft\" (default) saves without publishing, \"posted\" publishes immediately, \"scheduled\" publishes at scheduled_at. TikTok takes a video (with a url) or a photo slideshow (one or more image urls); YouTube requires a video with a path — both come from upload_media. Instagram needs an image or video url. TikTok photo slideshows accept options.tiktok.auto_add_music (boolean, default false) to let TikTok auto-add its recommended background music; there is no music option for video posts or for Instagram. Publishing/scheduling to TikTok requires options.tiktok.privacy_level (one of PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY) — there is no default; branded_content cannot be SELF_ONLY. Ask the user which TikTok privacy_level to use and wait for their answer; never choose it for them. Ask the user which YouTube privacy_status to use (public, unlisted, or private) and wait for their answer; without it the video is public. Caption character limits: tiktok: 2200, youtube: 5000, x: 280, linkedin: 3000, threads: 500, instagram: 2200, bluesky: 300. Publishing is asynchronous: check per-platform results with get_post. Each call creates a new post, so don't repeat a call that already succeeded.",
                "access": "write"
            },
            {
                "name": "list_posts",
                "description": "List the user's posts, newest first, with per-platform publish status. Filter by status (draft, scheduled, posted) and/or a scheduled_at date window (from/to, ISO-8601). Returns one page at a time (25 by default); when has_more is true, ask for the next page.",
                "access": "read"
            },
            {
                "name": "get_post",
                "description": "Fetch one post by id, including each platform target's publish status (pending, publishing, published, failed) and error message.",
                "access": "read"
            },
            {
                "name": "update_post",
                "description": "Edit a draft or scheduled post: caption, media, platforms, schedule, or status. Setting status to \"posted\" publishes immediately. Posts that have already been published cannot be edited. Ask the user which TikTok privacy_level to use and wait for their answer; never choose it for them. Ask the user which YouTube privacy_status to use (public, unlisted, or private) and wait for their answer; without it the video is public. Caption character limits: tiktok: 2200, youtube: 5000, x: 280, linkedin: 3000, threads: 500, instagram: 2200, bluesky: 300.",
                "access": "write"
            },
            {
                "name": "delete_post",
                "description": "Delete a post and its platform targets. Does not remove content already published to the platforms.",
                "access": "write"
            },
            {
                "name": "list_offers",
                "description": "List the user's offers (tracked promotions) with their tracking links, goals, and per-offer click/conversion stats. Optional from/to date filter. Returns one page at a time (25 by default); when has_more is true, ask for the next page.",
                "access": "read"
            },
            {
                "name": "create_offer",
                "description": "Create an offer (a promotion to track). Requires offer_url; optional name and goals (conversion events with a conversion_url and value). Subject to the user's plan offer limit. Each call creates a new offer, so don't repeat a call that already succeeded.",
                "access": "write"
            },
            {
                "name": "get_offer",
                "description": "Fetch one offer by id, with its tracking links and goals.",
                "access": "read"
            },
            {
                "name": "update_offer",
                "description": "Update an offer's name, offer_url, goals, or links.",
                "access": "write"
            },
            {
                "name": "delete_offer",
                "description": "Delete an offer and stop tracking it.",
                "access": "write"
            },
            {
                "name": "create_tracking_link",
                "description": "Create a tracking link for an offer, to place in a video description, email, social bio, etc. Placement is one of: video, email, x, linkedin, podcast, blog, website, tiktok, ad, instagram, beehiiv, other — attaching a youtube_video_id or beehiiv_post_id auto-sets the matching placement. Each call creates a new tracking link, so don't repeat a call that already succeeded.",
                "access": "write"
            },
            {
                "name": "get_offer_stats",
                "description": "Aggregated analytics across the user's offers: video views, clicks, calls booked, email signups, and sales revenue. Optional from/to window.",
                "access": "read"
            },
            {
                "name": "get_stats_timeseries",
                "description": "Daily time-series of clicks and attributed revenue (one bucket per day, gaps zero-filled). Defaults to the last 28 days; filter with from/to and optionally a single offer via event_id.",
                "access": "read"
            },
            {
                "name": "disconnect_account",
                "description": "Disconnect a social account by platform (e.g. x, youtube, tiktok). Fully disconnects it — nothing is left half-connected — and any pending posts targeting that platform will fail to publish.",
                "access": "write"
            },
            {
                "name": "get_connect_url",
                "description": "Get the URL of the ViewsMax Connections page where the user can connect a social platform. The user must open the page in a browser and click Connect there — the OAuth approval happens on that page and cannot be completed inside this conversation.",
                "access": "write"
            },
            {
                "name": "create_feature_request",
                "description": "Submit a feature request to the ViewsMax team on the user's behalf. Don't use this for plan, billing, or purchase requests; tell the user to manage their plan in the ViewsMax app instead. Each call submits a new request, so don't repeat a call that already succeeded.",
                "access": "write"
            },
            {
                "name": "list_outliers",
                "description": "Browse outlier videos — content that massively over-performed its channel's average (outlier_score = views ÷ channel average views) across YouTube, TikTok and Instagram. Without `query` this is the curated/featured feed; with `query` it returns title matches already in the database. If the response `status` is \"queued\" or \"in_progress\" no scrape has finished for that query yet — call search_outliers to start one, then re-run this tool. Filter by platform, score, views, subscribers, publish date, duration (long/shorts), channel ids or ISO country codes. Paginated (per_page ≤ 50).",
                "access": "read"
            },
            {
                "name": "search_outliers",
                "description": "Start a background YouTube search (YouTube Data API) for outlier videos matching a keyword/topic. Returns immediately with status \"queued\"; results land in the shared outlier database over the next minute or two — poll list_outliers with the same `query` until its status is \"done\". Use exact_match to require the whole phrase. This search covers YouTube only: for TikTok and Instagram, add a single video by its link with fetch_outlier, or add a creator's channel with add_outlier_channel to pull in their recent videos.",
                "access": "write"
            },
            {
                "name": "get_outlier",
                "description": "Fetch one outlier video by platform + video id (as returned by list_outliers or fetch_outlier), including its channel, views, outlier score and engagement.",
                "access": "read"
            },
            {
                "name": "fetch_outlier",
                "description": "Pull a specific video into the outlier database from its URL so it can be analysed (get_outlier, generate_outlier_breakdown, save_outlier). If the video is already known it is returned immediately; otherwise ingestion is queued (`queued: true`) — poll get_outlier with the returned platform + video_id.",
                "access": "write"
            },
            {
                "name": "get_outlier_breakdown",
                "description": "Read the AI breakdown of an outlier video (hook, structure, why it worked, how to replicate it). `status` is none (never generated — call generate_outlier_breakdown), pending/processing (poll again), completed (`payload` holds the analysis) or failed (`error`).",
                "access": "read"
            },
            {
                "name": "generate_outlier_breakdown",
                "description": "Queue an AI breakdown of an outlier video (transcript + analysis of the hook, structure and why it over-performed). Generation runs in the background and takes up to a couple of minutes — poll get_outlier_breakdown until status is completed. Re-running for a video that already has a breakdown returns the existing one instead of regenerating.",
                "access": "write"
            },
            {
                "name": "list_saved_outliers",
                "description": "The user's saved-outliers library (videos they bookmarked with save_outlier), newest first, with tags and the video snapshot taken when saved. Filter by a title/channel query, tag names, platforms, or creator name. Returns one page at a time (25 by default); when has_more is true, ask for the next page.",
                "access": "read"
            },
            {
                "name": "save_outlier",
                "description": "Bookmark an outlier video into the user's library, optionally with tags (created on demand). Saving the same video again replaces its tags. The video must already be in the outlier database (list_outliers / fetch_outlier).",
                "access": "write"
            },
            {
                "name": "remove_saved_outlier",
                "description": "Remove a saved video from the user's outlier library by its saved id (from list_saved_outliers / save_outlier). The video itself stays in the outlier database.",
                "access": "write"
            },
            {
                "name": "add_outlier_channel",
                "description": "Add a creator's channel to the outlier database from a profile URL or @handle (YouTube, TikTok, Instagram) and pull in their 10 most recent videos, scored against that channel's own median. Also adds the channel to the user's competitor list. Not for video links — use fetch_outlier for those. Returns `status: done` with the channel when it was pulled in the last 24 hours; otherwise `queued: true` with an ingest_id — poll get_outlier_channel_ingest until `done`, then list_outliers with `channels: [channel.id]` (and `duration_type: shorts` for TikTok/Instagram) to see the videos. No AI breakdowns are generated.",
                "access": "write"
            },
            {
                "name": "get_outlier_channel_ingest",
                "description": "Poll a channel add started by add_outlier_channel. `status` is queued, processing, done (then `channel` is set and `videos_added` says how many videos landed — use channel.id in list_outliers `channels`), or failed (then `error` explains why). Pulls take ~10-60 seconds; poll every 5-10 seconds.",
                "access": "read"
            }
        ]
    },
    "rest": {
        "base_url": "https://api.viewsmax.com/api",
        "auth": "Same vmx_ API key as a Bearer token (posts, offers, tracking, stats, and outliers endpoints only; read-only keys are limited to GET).",
        "openapi": "https://api.viewsmax.com/docs.openapi"
    },
    "rate_limits": {
        "mcp_requests_per_minute": 120,
        "create_post_per_hour": 180,
        "upload_media_per_hour": 40,
        "search_outliers_per_hour": 30,
        "fetch_outlier_per_hour": 60,
        "generate_outlier_breakdown_per_hour": 30,
        "add_outlier_channel_per_hour": 10
    }
}

Request      

GET api/ai

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Posts

Compose multi-platform posts (YouTube, TikTok, X, LinkedIn, Threads, Instagram, Bluesky) as drafts, publish immediately, or schedule. One post fans out to per-platform targets that each report their own publish status — publishing is asynchronous, so poll GET /api/posts/{id}.

Re-queue publishing for a single failed platform target. Only a FAILED target can be retried, and only that target is touched — its siblings (which may already be published) are left alone, so a retry can never double-post to a platform that already succeeded.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/posts/architecto/targets/architecto/retry" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/posts/architecto/targets/architecto/retry"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/posts/{post}/targets/{target}/retry

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

post   string     

The post. Example: architecto

target   string     

The target. Example: architecto

List the user's posts (with targets). Optional filters: status, and a scheduled_at date window (from/to) used by the calendar view.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/posts" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/posts"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/posts

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Create a post.

requires authentication

Composes a post and fans it out to the given platforms. Save as a draft, publish immediately (status=posted), or schedule (status=scheduled with scheduled_at). Publishing is asynchronous — poll GET /api/posts/{id} for per-platform results.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/posts" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"caption\": \"Big news today!\",
    \"platforms\": [
        \"tiktok\",
        \"instagram\"
    ],
    \"media\": [
        {
            \"type\": \"image\",
            \"url\": \"https:\\/\\/cdn.example\\/1.jpg\",
            \"path\": \"posts\\/1\\/clip.mp4\"
        }
    ],
    \"status\": \"draft\",
    \"scheduled_at\": \"2026-07-20T18:30:00Z\",
    \"brand_id\": 1,
    \"overrides\": [],
    \"options\": []
}"

const url = new URL(
    "https://api.viewsmax.com/api/posts"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "caption": "Big news today!",
    "platforms": [
        "tiktok",
        "instagram"
    ],
    "media": [
        {
            "type": "image",
            "url": "https:\/\/cdn.example\/1.jpg",
            "path": "posts\/1\/clip.mp4"
        }
    ],
    "status": "draft",
    "scheduled_at": "2026-07-20T18:30:00Z",
    "brand_id": 1,
    "overrides": [],
    "options": []
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/posts

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

caption   string  optional    

The post text / caption. Example: Big news today!

platforms   string[]  optional    

Target platforms: youtube, tiktok, instagram, x, linkedin, threads.

media   object[]  optional    

Media entries, usually from POST /api/posts/media.
type   string  optional    

image or video. Example: image

url   string  optional    

Public URL of the media. Example: https://cdn.example/1.jpg

path   string  optional    

Storage path (YouTube requires a video path). Example: posts/1/clip.mp4

status   string  optional    

draft (default), scheduled, or posted. Example: draft

scheduled_at   string  optional    

ISO-8601 datetime; required when status is scheduled. Example: 2026-07-20T18:30:00Z

brand_id   integer  optional    

The brand selected in the composer (informational). Example: 1

overrides   object  optional    

Per-platform caption overrides, keyed by platform.

options   object  optional    

Per-platform publish options, keyed by platform.
tiktok   object  optional    
privacy_level   string  optional    

TikTok privacy, e.g. SELF_ONLY or PUBLIC_TO_EVERYONE. Example: SELF_ONLY

auto_add_music   boolean  optional    

Auto-add TikTok's recommended music to a photo slideshow. Slideshows only; ignored for video. Defaults to false. Example: false

youtube   object  optional    
privacy_status   string  optional    

public, unlisted, or private. Example: public

instagram   object  optional    
cover_url   string  optional    

Public cover image URL for an Instagram Reel. Example: http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

linkedin   object  optional    
first_comment   string  optional    

A comment auto-posted right after publishing. Example: architecto

GET api/posts/{id}

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/posts/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/posts/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/posts/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the post. Example: architecto

PUT api/posts/{id}

requires authentication

Example request:
curl --request PUT \
    "https://api.viewsmax.com/api/posts/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/posts/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

PUT api/posts/{id}

PATCH api/posts/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the post. Example: architecto

DELETE api/posts/{id}

requires authentication

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/posts/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/posts/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

DELETE api/posts/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the post. Example: architecto

Post Media

Upload media (images / video) used by composed posts. Files are stored on the configured default disk (S3 in production) and returned as a public URL that the platform publishing APIs (e.g. TikTok PULL_FROM_URL) can fetch.

Upload a single post media file.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/posts/media" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \

const url = new URL(
    "https://api.viewsmax.com/api/posts/media"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/posts/media

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

type   string  optional    

image|video. Required.

file   file  optional    

Image or video file. Required.

Create a direct-upload session.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/posts/media/direct" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"type\": \"architecto\",
    \"filename\": \"architecto\",
    \"mime\": \"architecto\",
    \"size\": 16
}"

const url = new URL(
    "https://api.viewsmax.com/api/posts/media/direct"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "type": "architecto",
    "filename": "architecto",
    "mime": "architecto",
    "size": 16
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/posts/media/direct

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

type   string  optional    

image|video. Required. Example: architecto

filename   string  optional    

Original file name (display only). Required. Example: architecto

mime   string  optional    

File content type, e.g. video/mp4. Required. Example: architecto

size   integer  optional    

File size in bytes. Required. Example: 16

Complete a direct upload.

requires authentication

Finalizes the multipart upload (when upload_id is present), verifies the stored object against the declared type's size/mime limits (a presigned PUT cannot enforce size), and returns the media entry for the composer.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/posts/media/direct/complete" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"type\": \"architecto\",
    \"path\": \"architecto\",
    \"parts\": [
        {
            \"part_number\": 22,
            \"etag\": \"architecto\"
        }
    ]
}"

const url = new URL(
    "https://api.viewsmax.com/api/posts/media/direct/complete"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "type": "architecto",
    "path": "architecto",
    "parts": [
        {
            "part_number": 22,
            "etag": "architecto"
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/posts/media/direct/complete

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

type   string  optional    

image|video. Required. Example: architecto

path   string  optional    

Storage path returned by the session. Required. Example: architecto

upload_id   string  optional    

Multipart upload id (multipart only).

parts   object[]  optional    

Uploaded parts as {part_number, etag} (multipart only).
part_number   integer     

Must be at least 1. Example: 22

etag   string     

Example: architecto

Abort a multipart direct upload.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/posts/media/direct/abort" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"path\": \"architecto\",
    \"upload_id\": \"architecto\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/posts/media/direct/abort"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "path": "architecto",
    "upload_id": "architecto"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/posts/media/direct/abort

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

path   string  optional    

Storage path returned by the session. Required. Example: architecto

upload_id   string  optional    

Multipart upload id. Required. Example: architecto

Offers

Offers are products/campaigns being promoted (stored as tracking events). Each offer has an offer URL and conversion value, owns tracking links, and accumulates clicks and conversions. The stats and timeseries endpoints power the analytics dashboards.

Get a list of distinct offer URLs used by the authenticated user.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/tracking-events/offers" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-events/offers"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/tracking-events/offers

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Get aggregated stats for tracking events with date filtering and deduplication.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/tracking-events/stats" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-events/stats"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/tracking-events/stats

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Daily time-series of clicks and attributed revenue for the authenticated user, used by the Analytics overview area charts. Returns one bucket per day across the requested window (gaps filled with zeros).

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/tracking-events/timeseries" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-events/timeseries"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/tracking-events/timeseries

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

GA-style acquisition tables: where visitors actually came from.

requires authentication

GET /api/tracking-events/sources?from&to&event_id

Returns sources (grouped by classified platform — google, x, direct…) and referrers (grouped by the FULL referrer URL), each with distinct visitors + view counts. Pageview-based; falls back to link-click data (basis: "clicks") until the site has pageview beacons.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/tracking-events/sources" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-events/sources"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/tracking-events/sources

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

List the predefined conversion goal/event types (seeded reference list).

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/goal-types" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/goal-types"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/goal-types

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

GET api/tracking-events

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/tracking-events" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-events"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/tracking-events

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Store a newly created resource in storage.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/tracking-events" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"b\",
    \"offer_url\": \"http:\\/\\/bailey.com\\/\",
    \"conversion_value\": 4326.41688,
    \"goals\": [
        {
            \"event_type\": \"m\",
            \"conversion_url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\",
            \"conversion_value\": 8
        }
    ],
    \"links\": [
        {
            \"youtube_video_id\": \"architecto\",
            \"placement\": \"architecto\",
            \"name\": \"architecto\",
            \"description\": \"Et animi quos velit et fugiat.\"
        }
    ]
}"

const url = new URL(
    "https://api.viewsmax.com/api/tracking-events"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "b",
    "offer_url": "http:\/\/bailey.com\/",
    "conversion_value": 4326.41688,
    "goals": [
        {
            "event_type": "m",
            "conversion_url": "http:\/\/www.bailey.biz\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html",
            "conversion_value": 8
        }
    ],
    "links": [
        {
            "youtube_video_id": "architecto",
            "placement": "architecto",
            "name": "architecto",
            "description": "Et animi quos velit et fugiat."
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/tracking-events

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

name   string  optional    

Must not be greater than 255 characters. Example: b

offer_url   string     

Must be a valid URL. Example: http://bailey.com/

goals   object[]  optional    

Goals (conversion events) are optional at creation — added later on the offer page.
event_type   string     

Built-in types (conversion, call booked, email-signup, newsletter, trial) plus arbitrary user-defined "custom" events, which are stored verbatim. Must not be greater than 255 characters. Example: m

conversion_url   string     

Example: http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

conversion_value   number  optional    

Must be at least 0. Example: 8

conversion_value   number  optional    

Example: 4326.41688

links   object[]  optional    
youtube_video_id   string  optional    

Example: architecto

placement   string  optional    

Example: architecto

name   string  optional    

Example: architecto

description   string  optional    

Must not be greater than 255 characters. Example: Et animi quos velit et fugiat.

Display the specified resource.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/tracking-events/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-events/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/tracking-events/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the tracking event. Example: architecto

Update the specified resource in storage.

requires authentication

Example request:
curl --request PUT \
    "https://api.viewsmax.com/api/tracking-events/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"b\",
    \"offer_url\": \"http:\\/\\/bailey.com\\/\",
    \"conversion_value\": 4326.41688,
    \"goals\": [
        {
            \"event_type\": \"m\",
            \"conversion_url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\",
            \"conversion_value\": 8
        }
    ],
    \"links\": [
        {
            \"id\": 16,
            \"youtube_video_id\": \"architecto\",
            \"placement\": \"architecto\",
            \"name\": \"architecto\",
            \"description\": \"Et animi quos velit et fugiat.\"
        }
    ]
}"

const url = new URL(
    "https://api.viewsmax.com/api/tracking-events/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "b",
    "offer_url": "http:\/\/bailey.com\/",
    "conversion_value": 4326.41688,
    "goals": [
        {
            "event_type": "m",
            "conversion_url": "http:\/\/www.bailey.biz\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html",
            "conversion_value": 8
        }
    ],
    "links": [
        {
            "id": 16,
            "youtube_video_id": "architecto",
            "placement": "architecto",
            "name": "architecto",
            "description": "Et animi quos velit et fugiat."
        }
    ]
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

PUT api/tracking-events/{id}

PATCH api/tracking-events/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the tracking event. Example: architecto

Body Parameters

name   string  optional    

Must not be greater than 255 characters. Example: b

offer_url   string  optional    

Must be a valid URL. Example: http://bailey.com/

goals   object[]  optional    
event_type   string     

Must not be greater than 255 characters. Example: m

conversion_url   string     

Example: http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

conversion_value   number  optional    

Must be at least 0. Example: 8

conversion_value   number  optional    

Example: 4326.41688

links   object[]  optional    
id   integer  optional    

Example: 16

youtube_video_id   string  optional    

For updating existing links. Example: architecto

placement   string  optional    

Example: architecto

name   string  optional    

Example: architecto

description   string  optional    

Must not be greater than 255 characters. Example: Et animi quos velit et fugiat.

Remove the specified resource from storage.

requires authentication

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/tracking-events/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-events/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

DELETE api/tracking-events/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the tracking event. Example: architecto

Tracking Links

Tracked links tied to an offer. Place them in videos, posts, emails, or bios; ViewsMax records clicks and attributes conversions back to the link (and the post/platform) that drove them.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/tracking-links" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"tracking_event_id\": 16,
    \"youtube_video_id\": \"architecto\",
    \"placement\": \"architecto\",
    \"placements\": [
        \"architecto\"
    ],
    \"beehiiv_post_id\": \"n\",
    \"x_post_id\": \"g\",
    \"instagram_media_id\": \"z\",
    \"name\": \"architecto\",
    \"description\": \"Et animi quos velit et fugiat.\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/tracking-links"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "tracking_event_id": 16,
    "youtube_video_id": "architecto",
    "placement": "architecto",
    "placements": [
        "architecto"
    ],
    "beehiiv_post_id": "n",
    "x_post_id": "g",
    "instagram_media_id": "z",
    "name": "architecto",
    "description": "Et animi quos velit et fugiat."
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Update the specified resource in storage.

requires authentication

Example request:
curl --request PUT \
    "https://api.viewsmax.com/api/tracking-links/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"architecto\",
    \"placement\": \"architecto\",
    \"placements\": [
        \"architecto\"
    ],
    \"youtube_video_id\": \"architecto\",
    \"beehiiv_post_id\": \"n\",
    \"x_post_id\": \"g\",
    \"instagram_media_id\": \"z\",
    \"description\": \"Eius et animi quos velit et.\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/tracking-links/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "architecto",
    "placement": "architecto",
    "placements": [
        "architecto"
    ],
    "youtube_video_id": "architecto",
    "beehiiv_post_id": "n",
    "x_post_id": "g",
    "instagram_media_id": "z",
    "description": "Eius et animi quos velit et."
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

PUT api/tracking-links/{id}

PATCH api/tracking-links/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the tracking link. Example: architecto

Body Parameters

name   string  optional    

Example: architecto

placement   string  optional    

Example: architecto

placements   string[]  optional    
youtube_video_id   string  optional    

Example: architecto

beehiiv_post_id   string  optional    

Must not be greater than 255 characters. Example: n

x_post_id   string  optional    

Must not be greater than 255 characters. Example: g

instagram_media_id   string  optional    

Must not be greater than 255 characters. Example: z

description   string  optional    

Example: Eius et animi quos velit et.

Remove the specified resource from storage.

requires authentication

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/tracking-links/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-links/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

DELETE api/tracking-links/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the tracking link. Example: architecto

List links for a specific event.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/tracking-events/architecto/links" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/tracking-events/architecto/links"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/tracking-events/{event}/links

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

event   string     

Example: architecto

Content

Post and manage content (long-form body text + optional media file) that can be attached to an Offer. Media is stored privately and streamed back via the media endpoint. All endpoints are scoped to the authenticated user.

Download content media

requires authentication

Streams the stored media file for the content. Useful for large files.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/contents/1/media" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/contents/1/media"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Example response (404, No media):


{
    "message": "This content has no media file."
}

Request      

GET api/contents/{id}/media

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The content id. Example: 1

List content

requires authentication

Returns the authenticated user's content, newest first. Optionally filter by offer or status.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/contents?offer_id=12&status=published" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/contents"
);

const params = {
    "offer_id": "12",
    "status": "published",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200, Success):


{
    "data": [
        {
            "id": 1,
            "user_id": 1,
            "offer_id": 12,
            "title": "Launch post",
            "body": "...",
            "media_filename": "promo.mp4",
            "media_mime": "video/mp4",
            "media_size": 8388608,
            "status": "published",
            "created_at": "2026-06-16T12:00:00.000000Z",
            "updated_at": "2026-06-16T12:00:00.000000Z"
        }
    ]
}

Request      

GET api/contents

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

offer_id   integer  optional    

Filter to content attached to this offer. Example: 12

status   string  optional    

Filter by status (draft|published). Example: published

Create content

requires authentication

Create a content post. Send as multipart/form-data when including a media file. The body accepts long-form text. media accepts a single file up to 50 MB.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/contents" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "title=5 ways to grow your channel"\
    --form "body=Once upon a time..."\
    --form "offer_id=12"\
    --form "status=published"\
    --form "media=@/tmp/phpTDFlbg" 
const url = new URL(
    "https://api.viewsmax.com/api/contents"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('title', '5 ways to grow your channel');
body.append('body', 'Once upon a time...');
body.append('offer_id', '12');
body.append('status', 'published');
body.append('media', document.querySelector('input[name="media"]').files[0]);

fetch(url, {
    method: "POST",
    headers,
    body,
}).then(response => response.json());

Example response (201, Created):


{
    "data": {
        "id": 1,
        "user_id": 1,
        "offer_id": 12,
        "title": "Launch post",
        "body": "...",
        "media_filename": "promo.mp4",
        "media_mime": "video/mp4",
        "media_size": 8388608,
        "status": "published"
    }
}

Example response (422, Validation error):


{
    "message": "The title field is required.",
    "errors": {
        "title": [
            "The title field is required."
        ]
    }
}

Request      

POST api/contents

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: multipart/form-data

Accept        

Example: application/json

Body Parameters

title   string     

The content title. Example: 5 ways to grow your channel

body   string  optional    

The long-form body text (no length limit). Example: Once upon a time...

offer_id   integer  optional    

The id of an offer (owned by you) to attach this content to. Example: 12

status   string  optional    

The status: draft or published. Defaults to draft. Example: published

media   file  optional    

A media file to attach (image/video/document, max 50 MB). Example: /tmp/phpTDFlbg

Show content

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/contents/1" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/contents/1"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200, Success):


{
    "data": {
        "id": 1,
        "title": "Launch post",
        "body": "...",
        "status": "published"
    }
}

Example response (404, Not found):


{
    "message": "No query results for model [App\\Models\\Content] 1"
}

Request      

GET api/contents/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The content id. Example: 1

Update content

requires authentication

Update fields and/or replace the media file. Send multipart/form-data to replace media.

Example request:
curl --request PUT \
    "https://api.viewsmax.com/api/contents/1" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: multipart/form-data" \
    --header "Accept: application/json" \
    --form "title=Updated title"\
    --form "body=New body text..."\
    --form "offer_id=12"\
    --form "status=published"\
    --form "media=@/tmp/phpUOKfMQ" 
const url = new URL(
    "https://api.viewsmax.com/api/contents/1"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "multipart/form-data",
    "Accept": "application/json",
};

const body = new FormData();
body.append('title', 'Updated title');
body.append('body', 'New body text...');
body.append('offer_id', '12');
body.append('status', 'published');
body.append('media', document.querySelector('input[name="media"]').files[0]);

fetch(url, {
    method: "PUT",
    headers,
    body,
}).then(response => response.json());

Example response (200, Updated):


{
    "data": {
        "id": 1,
        "title": "Updated title",
        "status": "published"
    }
}

Request      

PUT api/contents/{id}

PATCH api/contents/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: multipart/form-data

Accept        

Example: application/json

URL Parameters

id   integer     

The content id. Example: 1

Body Parameters

title   string  optional    

The content title. Example: Updated title

body   string  optional    

The long-form body text. Example: New body text...

offer_id   integer  optional    

The id of an offer (owned by you) to attach. Example: 12

status   string  optional    

draft or published. Example: published

media   file  optional    

Replacement media file (max 50 MB). Example: /tmp/phpUOKfMQ

Delete content

requires authentication

Deletes the content and any stored media file.

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/contents/1" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/contents/1"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (204, Deleted):

Empty response

Request      

DELETE api/contents/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The content id. Example: 1

Connections

Legacy connection management (YouTube/TikTok/Instagram OAuth token exchange). Prefer the /api/social endpoints for new integrations.

List the authenticated user's connections.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/connections" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/connections"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/connections

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Delete a connection belonging to the caller.

requires authentication

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/connections/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/connections/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

DELETE api/connections/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the connection. Example: architecto

Return the TikTok creator's allowed posting options (privacy levels, comment/duet/stitch availability, max duration). The composer must render the privacy/interaction UI from this before a post can be published.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/connections/tiktok/creator-info" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/connections/tiktok/creator-info"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/connections/tiktok/creator-info

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

List every platform the app supports plus whether it is configured.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/social/platforms" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/platforms"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/social/platforms

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

List the authenticated user's connected accounts (optionally by platform).

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/social/accounts" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/accounts"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/social/accounts

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Disconnect (delete) a connected account.

requires authentication

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/social/accounts/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/accounts/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

DELETE api/social/accounts/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the account. Example: architecto

Build the OAuth authorization URL for a platform. The frontend opens this, the user grants access, and the provider redirects back to redirect_uri with a `code` to be sent to exchange().

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/social/architecto/auth-url" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/architecto/auth-url"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/social/{platform}/auth-url

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

platform   string     

Example: architecto

Exchange an authorization code (returned to the frontend callback) for tokens and persist the connected account(s).

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/social/architecto/exchange" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"code\": \"architecto\",
    \"state\": \"architecto\",
    \"redirect_uri\": \"http:\\/\\/bailey.com\\/\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/social/architecto/exchange"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "code": "architecto",
    "state": "architecto",
    "redirect_uri": "http:\/\/bailey.com\/"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/social/{platform}/exchange

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

platform   string     

Example: architecto

Body Parameters

code   string     

Example: architecto

state   string  optional    

Example: architecto

redirect_uri   string  optional    

Must be a valid URL. Example: http://bailey.com/

Connect a non-OAuth platform (e.g. Bluesky) with direct credentials.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/social/architecto/connect" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/architecto/connect"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/social/{platform}/connect

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

platform   string     

Example: architecto

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/social/x/users/search?q=jane&social_account_id=1" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"q\": \"b\",
    \"social_account_id\": 16
}"

const url = new URL(
    "https://api.viewsmax.com/api/social/x/users/search"
);

const params = {
    "q": "jane",
    "social_account_id": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "q": "b",
    "social_account_id": 16
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 30
x-ratelimit-remaining: 29
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Social Posts

Earlier posting surface (predates /api/posts). Prefer the Posts endpoints for new integrations; these remain for existing clients.

The user's X posts published through the app (both posting stores), newest first — used to pin a tracking link to a live tweet. Pure DB read; the X API plan doesn't allow timeline reads.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/social/x/posts" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/x/posts"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/social/x/posts

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

List the user's posts (most recent first).

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/social/posts" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/posts"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/social/posts

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Create a post and publish (or schedule) it to the chosen accounts.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/social/posts" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"content\": \"b\",
    \"link\": \"n\",
    \"account_ids\": [
        16
    ],
    \"scheduled_at\": \"2052-10-25\",
    \"media\": [
        {
            \"url\": \"http:\\/\\/bailey.com\\/\",
            \"type\": \"video\",
            \"mime\": \"architecto\",
            \"alt\": \"architecto\"
        }
    ]
}"

const url = new URL(
    "https://api.viewsmax.com/api/social/posts"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "content": "b",
    "link": "n",
    "account_ids": [
        16
    ],
    "scheduled_at": "2052-10-25",
    "media": [
        {
            "url": "http:\/\/bailey.com\/",
            "type": "video",
            "mime": "architecto",
            "alt": "architecto"
        }
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/social/posts

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

content   string  optional    

Must not be greater than 10000 characters. Example: b

link   string  optional    

Must be a valid URL. Must not be greater than 1024 characters. Example: n

media   object[]  optional    
url   string  optional    

This field is required when media is present. Must be a valid URL. Example: http://bailey.com/

type   string  optional    

Example: video

Must be one of:
  • image
  • video
mime   string  optional    

Example: architecto

alt   string  optional    

Example: architecto

account_ids   integer[]  optional    
scheduled_at   string  optional    

Must be a valid date. Must be a date after now. Example: 2052-10-25

GET api/social/posts/{id}

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/social/posts/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/posts/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/social/posts/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the post. Example: architecto

Retry the failed targets of a post.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/social/posts/architecto/retry" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/social/posts/architecto/retry"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/social/posts/{id}/retry

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the post. Example: architecto

API Keys

MCP API key management: one non-expiring key per user, rotate-to-invalidate. The key is a Sanctum personal access token scoped to the mcp ability, stored hashed; only a display hint is recoverable, so the plaintext is returned exactly once from rotate(). The key authenticates the MCP server (/api/mcp) and the posts/offers/tracking REST surface; these management endpoints themselves require a login session, not a key.

GET api/user/api-key

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/user/api-key" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/user/api-key"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/user/api-key

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

POST api/user/api-key/rotate

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/user/api-key/rotate" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"access\": \"read\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/user/api-key/rotate"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "access": "read"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 12
x-ratelimit-remaining: 10
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/user/api-key/rotate

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

access   string  optional    

Example: read

Must be one of:
  • read
  • full

Plans

Display a listing of plans.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/plans" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/plans"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/plans

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Display the specified plan.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/plans/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/plans/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/plans/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the plan. Example: architecto

Feature Requests

List feature requests, sorted by top votes (default) or newest.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/feature-requests" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/feature-requests"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/feature-requests

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Create a feature request and auto-upvote it for the creator.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/feature-requests" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"title\": \"b\",
    \"description\": \"Eius et animi quos velit et.\",
    \"category\": \"v\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/feature-requests"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "title": "b",
    "description": "Eius et animi quos velit et.",
    "category": "v"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/feature-requests

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

title   string     

Must not be greater than 255 characters. Example: b

description   string     

Example: Eius et animi quos velit et.

category   string  optional    

Must not be greater than 255 characters. Example: v

Toggle the caller's vote on a feature request.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/feature-requests/architecto/upvote" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/feature-requests/architecto/upvote"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/feature-requests/{id}/upvote

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the feature request. Example: architecto

Auth

Session authentication. POST /api/login returns a bearer token with full account access. AI agents should prefer a vmx_ API key (Settings → AI Assistant Access) or the MCP OAuth flow instead of storing passwords.

Register a new user

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/register" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"b\",
    \"email\": \"zbailey@example.net\",
    \"password\": \"-0pBNvYgxw\",
    \"marketing_consent\": false
}"

const url = new URL(
    "https://api.viewsmax.com/api/register"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "b",
    "email": "zbailey@example.net",
    "password": "-0pBNvYgxw",
    "marketing_consent": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (422):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "password": [
            "The password field confirmation does not match."
        ]
    }
}

Request      

POST api/register

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

name   string     

Must not be greater than 255 characters. Example: b

email   string     

Must be a valid email address. Must not be greater than 255 characters. Example: zbailey@example.net

password   string     

Must be at least 8 characters. Example: -0pBNvYgxw

marketing_consent   boolean  optional    

Example: false

Login user

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/login" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"gbailey@example.net\",
    \"password\": \"|]|{+-\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/login"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "gbailey@example.net",
    "password": "|]|{+-"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid credentials"
}

Request      

POST api/login

Headers

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

email   string     

Must be a valid email address. Example: gbailey@example.net

password   string     

Example: |]|{+-

Send password reset email

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/forgot-password" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"gbailey@example.net\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/forgot-password"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "gbailey@example.net"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": true,
    "message": "If an account with that email exists, we have sent a password reset link."
}

Request      

POST api/forgot-password

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

email   string     

Must be a valid email address. Must not be greater than 255 characters. Example: gbailey@example.net

Reset password using token

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/reset-password" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"gbailey@example.net\",
    \"token\": \"architecto\",
    \"password\": \"]|{+-0pBNvYg\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/reset-password"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "gbailey@example.net",
    "token": "architecto",
    "password": "]|{+-0pBNvYg"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (422):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "password": [
            "The password field confirmation does not match."
        ]
    }
}

Request      

POST api/reset-password

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

email   string     

Must be a valid email address. Must not be greater than 255 characters. Example: gbailey@example.net

token   string     

Example: architecto

password   string     

Must be at least 8 characters. Example: ]|{+-0pBNvYg

Verify a user's email via the magic-link token. Logs the user in on success.

requires authentication

Idempotent under React StrictMode double-calls.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/auth/verify-email" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"token\": \"architecto\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/auth/verify-email"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "token": "architecto"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (422):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "message": "This verification link is invalid or has expired."
}

Request      

POST api/auth/verify-email

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

token   string     

Example: architecto

Resend a verification magic link. Always returns 200 (no account enumeration).

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/auth/resend-verification" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"email\": \"gbailey@example.net\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/auth/resend-verification"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "email": "gbailey@example.net"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": true
}

Request      

POST api/auth/resend-verification

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

email   string     

Must be a valid email address. Example: gbailey@example.net

Logout user (revoke token)

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/logout" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/logout"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/logout

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Get authenticated user profile

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/profile" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/profile"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/profile

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Refresh token (create new token and revoke old one)

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/refresh" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/refresh"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/refresh

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Audience Growth

Read-only analytics over the daily snapshot tables (audience_snapshots, post_metric_snapshots) populated by audience:refresh / posts:refresh-metrics. Revenue Growth reuses TrackingEventController@getTimeseries and isn't here.

Per-platform follower series over the date range, one entry per connected account: current count, day-over-day delta across the range, and points.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/analytics/audience" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/analytics/audience"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/analytics/audience

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Posts ranked by engagement (total, latest snapshot in range) with a day-over-day delta. Optional ?platform= filter.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/analytics/posts" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/analytics/posts"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/analytics/posts

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Boosts

Per-account Boost automations (X-only v1): Auto Repost retweets a post once it reaches a like threshold; Auto Promo replies to it with a promo comment. Checks run 6h apart, up to 3 times per post, and stop on success.

All of the user's boost settings, keyed for the Boosts page.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/boosts/settings" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/boosts/settings"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/boosts/settings

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Create or update one feature's setting on one connected account.

requires authentication

Example request:
curl --request PUT \
    "https://api.viewsmax.com/api/boosts/settings/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"feature\": \"architecto\",
    \"enabled\": false,
    \"likes_threshold\": 22,
    \"promo_text\": \"architecto\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/boosts/settings/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "feature": "architecto",
    "enabled": false,
    "likes_threshold": 22,
    "promo_text": "architecto"
};

fetch(url, {
    method: "PUT",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

PUT api/boosts/settings/{socialAccountId}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

socialAccountId   string     

Example: architecto

Body Parameters

feature   string     

Example: architecto

enabled   boolean     

Example: false

likes_threshold   integer     

Must be at least 1. Must not be greater than 1000000. Example: 22

promo_text   string  optional    

Example: architecto

Recent boost activity (triggered/exhausted/failed checks), newest first.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/boosts/activity" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/boosts/activity"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/boosts/activity

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Brands

Named groups of connected accounts. Selecting a brand in the composer auto-selects every account in it. Members may come from either account store: social_accounts (X, Instagram, ...) or legacy connections (YouTube, TikTok).

List the authenticated user's brands with their member accounts.

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/brands" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/brands"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/brands

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Create a brand.

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/brands" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"name\": \"Acme\",
    \"social_account_ids\": [
        1,
        2
    ],
    \"connection_ids\": [
        3
    ]
}"

const url = new URL(
    "https://api.viewsmax.com/api/brands"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "name": "Acme",
    "social_account_ids": [
        1,
        2
    ],
    "connection_ids": [
        3
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/brands

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

name   string     

Brand name, unique per user. Example: Acme

social_account_ids   integer[]  optional    

Ids from the social accounts store.

connection_ids   integer[]  optional    

Ids from the legacy connections store (YouTube/TikTok).

Update a brand. Member lists are replaced only when their key is present, so a rename-only payload never wipes membership.

requires authentication

Example request:
curl --request PUT \
    "https://api.viewsmax.com/api/brands/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/brands/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "PUT",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

PUT api/brands/{id}

PATCH api/brands/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the brand. Example: architecto

Delete a brand. Member accounts are untouched; posts keep existing but lose their brand link.

requires authentication

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/brands/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/brands/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

DELETE api/brands/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the brand. Example: architecto

Endpoints

POST api/free-tools/transcript

requires authentication

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/free-tools/transcript" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"platform\": \"youtube\",
    \"url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/free-tools/transcript"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "platform": "youtube",
    "url": "http:\/\/www.bailey.biz\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (422):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 15
x-ratelimit-remaining: 14
vary: Origin
 

{
    "success": false,
    "message": "That doesn't look like a valid youtube link."
}

Request      

POST api/free-tools/transcript

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

platform   string     

Example: youtube

Must be one of:
  • youtube
  • tiktok
  • instagram
url   string     

Must be a valid URL. Must not be greater than 2048 characters. Example: http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

GET api/health

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/health" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/health"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "status": "healthy",
    "timestamp": "2026-10-02T07:31:18.968796Z",
    "service": "Title Embedding API",
    "version": "1.0.0"
}

Request      

GET api/health

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

GET api/user/settings

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/user/settings" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/user/settings"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/user/settings

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

PATCH api/user/settings

requires authentication

Example request:
curl --request PATCH \
    "https://api.viewsmax.com/api/user/settings" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"notify_post_failures\": true,
    \"locale\": \"es\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/user/settings"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "notify_post_failures": true,
    "locale": "es"
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

PATCH api/user/settings

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

notify_post_failures   boolean  optional    

Example: true

locale   string  optional    

Example: es

Must be one of:
  • en
  • es
  • de
  • fr
  • pt

GET api/user

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/user" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/user"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/user

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

GET api/user/mcp-activity

requires authentication

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/user/mcp-activity" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/user/mcp-activity"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/user/mcp-activity

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Image Generation

APIs for generating AI images using Flux 2

Get Image Generation Configuration

requires authentication

Retrieve configuration options for image generation including available methods, quality presets, defaults, and limits.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/image/generate/config" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/image/generate/config"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "message": "Configuration retrieved successfully",
    "data": {
        "enabled": true,
        "methods": [
            "generate",
            "head_swap"
        ],
        "qualities": [
            "fast",
            "normal",
            "high",
            "very_high"
        ],
        "defaults": {
            "quality": "fast",
            "steps": 4,
            "refine_enabled": false,
            "inpainting_enabled": true,
            "number_of_images": 1
        },
        "limits": {
            "max_prompt_length": 2000,
            "max_image_size_bytes": 10485760,
            "max_additional_images": 3,
            "max_number_of_images": 10
        }
    }
}

Request      

GET api/image/generate/config

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

List Generated Images

requires authentication

Get a paginated list of the authenticated user's generated images. Can be filtered by status and method.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/image/generate?status=completed&method=generate&per_page=15" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/image/generate"
);

const params = {
    "status": "completed",
    "method": "generate",
    "per_page": "15",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{"success":true,"message":"Images retrieved successfully","data":{"current_page":1,"data":[...],"per_page":15,"total":100}}

Request      

GET api/image/generate

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

status   string  optional    

Filter by status: pending, processing, completed, failed. Example: completed

method   string  optional    

Filter by method: generate, head_swap. Example: generate

per_page   integer  optional    

Number of results per page. Example: 15

Create Image Generation Request

requires authentication

Create a new image generation request. Credits will be deducted based on the number of images requested (50 credits per image).

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/image/generate" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"method\": \"generate\",
    \"quality\": \"normal\",
    \"prompt\": \"A person standing confidently in front of a mountain\",
    \"base_image_url\": \"https:\\/\\/example.com\\/image.jpg\",
    \"number_of_images\": 2
}"

const url = new URL(
    "https://api.viewsmax.com/api/image/generate"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "method": "generate",
    "quality": "normal",
    "prompt": "A person standing confidently in front of a mountain",
    "base_image_url": "https:\/\/example.com\/image.jpg",
    "number_of_images": 2
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (202):


{
    "success": true,
    "message": "Image generation started",
    "data": {
        "id": 123,
        "status": "pending",
        "method": "generate",
        "quality": "normal",
        "estimated_time_seconds": 40
    }
}

Example response (400):


{
    "success": false,
    "message": "For generate method, please upload a base image, provide an image URL, or set a default reference image at /user/default-image."
}

Example response (400):


{
    "success": false,
    "message": "Reference image is required for head swap. You can upload a default image at /user/default-image."
}

Example response (400):


{
    "success": false,
    "message": "Failed to download or validate base image from URL. Please check the URL and try again."
}

Example response (503):


{
    "success": false,
    "message": "Image generation feature is not enabled"
}

Request      

POST api/image/generate

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

method   string  optional    

The generation method. Must be one of: generate, head_swap. Default: head_swap. Example: generate

quality   string  optional    

The quality preset. Must be one of: fast, normal, high, very_high. Default: fast. Example: normal

prompt   string  optional    

Text prompt for generation (max 2000 characters). Example: A person standing confidently in front of a mountain

base_image   file  optional    

Required for head_swap, optional for generate. Image file (max 10MB). Provide either base_image or base_image_url.

base_image_url   string  optional    

Required for head_swap, optional for generate. URL to download the base image from. Provide either base_image or base_image_url. Example: https://example.com/image.jpg

reference_image   file  optional    

Optional reference image file (max 10MB). For generate method, this is the person to generate. For head_swap method, this is the source face.

number_of_images   integer  optional    

Number of images to generate (1-10). Default: 1. Example: 2

Get Generated Image Details

requires authentication

Retrieve detailed information about a specific generated image.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/image/generate/123" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/image/generate/123"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{"success":true,"message":"Generated image retrieved successfully","data":{"id":123,"method":"generate","quality":"normal","status":"completed","prompt":"A person standing confidently","base_image_url":"https://...","reference_image_url":"https://...","result_image_url":"https://...","result_image_urls":["https://...","https://..."],"result_image_count":2,"megapixel":0.5,"steps":4,"refine_enabled":false,"inpainting_enabled":true,"number_of_images":2,"error_message":null,"processing_log":[...],"created_at":"2024-01-28T10:00:00Z","updated_at":"2024-01-28T10:01:00Z"}}

Example response (404):


{
    "success": false,
    "message": "Generated image not found"
}

Request      

GET api/image/generate/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer  optional    

The ID of the generated image. Example: 123

Get Image Generation Status

requires authentication

Check the processing status of a generated image. Use this to poll for completion.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/image/generate/123/status" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/image/generate/123/status"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "message": "Status retrieved successfully",
    "data": {
        "id": 123,
        "status": "processing",
        "is_complete": false,
        "is_successful": false
    }
}

Example response (200):


{
    "success": true,
    "message": "Status retrieved successfully",
    "data": {
        "id": 123,
        "status": "completed",
        "is_complete": true,
        "is_successful": true,
        "result_image_url": "https://...",
        "result_image_urls": [
            "https://..."
        ],
        "result_image_count": 2
    }
}

Example response (200):


{
    "success": true,
    "message": "Status retrieved successfully",
    "data": {
        "id": 123,
        "status": "failed",
        "is_complete": true,
        "is_successful": false,
        "error_message": "Error details..."
    }
}

Example response (404):


{
    "success": false,
    "message": "Generated image not found"
}

Request      

GET api/image/generate/{id}/status

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer  optional    

The ID of the generated image. Example: 123

Download Generated Image

requires authentication

Download the generated image file. Returns a binary PNG file.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/image/generate/123/download" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/image/generate/123/download"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (400):


{
    "success": false,
    "message": "No result image available for download"
}

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Example response (404):


{
    "success": false,
    "message": "Generated image not found"
}

Request      

GET api/image/generate/{id}/download

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer  optional    

The ID of the generated image. Example: 123

Delete Generated Image

requires authentication

Delete a generated image and all associated files.

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/image/generate/123" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/image/generate/123"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "message": "Generated image deleted successfully"
}

Example response (404):


{
    "success": false,
    "message": "Generated image not found"
}

Request      

DELETE api/image/generate/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer  optional    

The ID of the generated image. Example: 123

Outliers

Outlier videos: content that massively over-performed its channel's average (outlier_score = views ÷ channel average views) across YouTube, TikTok and Instagram. Browse the shared database, pull in specific URLs, and get AI breakdowns of why a video worked.

Browse outliers

requires authentication

Paginated outlier videos. Without query this is the curated feed; with query it returns title matches already in the database plus a status (queued / in_progress / done) for the background scrape of that term — start one with the search endpoint.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/outliers" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"query\": \"architecto\",
    \"min_score\": 39,
    \"min_views\": 84,
    \"max_views\": 12,
    \"min_subs\": 77,
    \"max_subs\": 8,
    \"published_before\": \"2026-10-02T07:31:19\",
    \"published_after\": \"2026-10-02T07:31:19\",
    \"sort_by\": \"recent\",
    \"keyword_match\": \"architecto\",
    \"featured\": true,
    \"platform\": \"tiktok\",
    \"channels\": [
        \"architecto\"
    ],
    \"countries\": [
        \"ng\"
    ],
    \"page\": 66,
    \"per_page\": 17
}"

const url = new URL(
    "https://api.viewsmax.com/api/outliers"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "query": "architecto",
    "min_score": 39,
    "min_views": 84,
    "max_views": 12,
    "min_subs": 77,
    "max_subs": 8,
    "published_before": "2026-10-02T07:31:19",
    "published_after": "2026-10-02T07:31:19",
    "sort_by": "recent",
    "keyword_match": "architecto",
    "featured": true,
    "platform": "tiktok",
    "channels": [
        "architecto"
    ],
    "countries": [
        "ng"
    ],
    "page": 66,
    "per_page": 17
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/outliers

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

query   string  optional    

Example: architecto

min_score   number  optional    

Must be at least 0. Example: 39

min_views   number  optional    

Must be at least 0. Example: 84

max_views   number  optional    

Must be at least 0. Example: 12

min_subs   number  optional    

Must be at least 0. Example: 77

max_subs   number  optional    

Must be at least 0. Example: 8

published_before   string  optional    

Must be a valid date. Example: 2026-10-02T07:31:19

published_after   string  optional    

Must be a valid date. Example: 2026-10-02T07:31:19

sort_by   string  optional    

Example: recent

Must be one of:
  • score
  • date
  • views
  • recent
keyword_match   string  optional    

Example: architecto

duration_type   string  optional    
featured   boolean  optional    

Example: true

platform   string  optional    

Example: tiktok

Must be one of:
  • youtube
  • tiktok
  • instagram
channels   string[]  optional    
countries   string[]  optional    

Must contain only letters. Must be 2 characters.

page   integer  optional    

Must be at least 1. Example: 66

per_page   integer  optional    

Must be at least 1. Must not be greater than 100. Example: 17

List outlier channels

requires authentication

Distinct channels in the outlier database (for the channels filter of the browse endpoint).

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/outliers/channels" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"platform\": \"instagram\",
    \"q\": \"architecto\",
    \"limit\": 22
}"

const url = new URL(
    "https://api.viewsmax.com/api/outliers/channels"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "platform": "instagram",
    "q": "architecto",
    "limit": 22
};

fetch(url, {
    method: "GET",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/outliers/channels

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

platform   string  optional    

Example: instagram

Must be one of:
  • youtube
  • tiktok
  • instagram
q   string  optional    

Example: architecto

limit   integer  optional    

Must be at least 1. Must not be greater than 100. Example: 22

Add a channel

requires authentication

Queue a pull of the creator's most recent videos. Returns HTTP 200 with status: done when the channel was already pulled in the last 24 hours, otherwise HTTP 202 with an ingest_id to poll.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/outliers/channels/add" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"platform\": \"tiktok\",
    \"input\": \"https:\\/\\/www.tiktok.com\\/@khaby.lame\",
    \"max_videos\": 10
}"

const url = new URL(
    "https://api.viewsmax.com/api/outliers/channels/add"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "platform": "tiktok",
    "input": "https:\/\/www.tiktok.com\/@khaby.lame",
    "max_videos": 10
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
x-ratelimit-limit: 10
x-ratelimit-remaining: 8
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/outliers/channels/add

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

platform   string  optional    

Required for a bare @handle: youtube, tiktok or instagram. Example: tiktok

input   string     

Profile URL or @handle. Example: https://www.tiktok.com/@khaby.lame

max_videos   integer  optional    

How many recent videos to pull (5-50, default 10). Example: 10

Channel ingest status

requires authentication

Poll an ingest started by the add endpoint until status is done (then channel is set) or failed (then error explains why).

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/outliers/channels/ingests/12" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/outliers/channels/ingests/12"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/outliers/channels/ingests/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The ingest id. Example: 12

requires authentication

Queue a background scrape for a keyword/topic. Poll the browse endpoint with the same query until its status is done.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/outliers/search" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"term\": \"faceless youtube automation\",
    \"exact_match\": false
}"

const url = new URL(
    "https://api.viewsmax.com/api/outliers/search"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "term": "faceless youtube automation",
    "exact_match": false
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Fetch an outlier by URL

requires authentication

Ingest a single video by URL so it can be analysed. Known videos return immediately; otherwise ingestion is queued (HTTP 202, queued: true) — poll the show endpoint with the returned platform + video_id. YouTube goes through the YouTube API; TikTok/Instagram go through CaptAPI (no channel-listing endpoint there, so those are pulled one URL at a time).

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/outliers/fetch" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"platform\": \"instagram\",
    \"url\": \"http:\\/\\/www.bailey.biz\\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html\"
}"

const url = new URL(
    "https://api.viewsmax.com/api/outliers/fetch"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "platform": "instagram",
    "url": "http:\/\/www.bailey.biz\/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html"
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/outliers/fetch

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

platform   string     

Example: instagram

Must be one of:
  • youtube
  • tiktok
  • instagram
url   string     

Must be a valid URL. Example: http://www.bailey.biz/quos-velit-et-fugiat-sunt-nihil-accusantium-harum.html

List library tags

requires authentication

Distinct tag names the user has applied to saved outliers.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/outliers/tags" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/outliers/tags"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/outliers/tags

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

List saved outliers

requires authentication

The user's library, newest first.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/outliers/library?q=hook&tags[]=architecto&platforms[]=architecto&creator=architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/outliers/library"
);

const params = {
    "q": "hook",
    "tags[0]": "architecto",
    "platforms[0]": "architecto",
    "creator": "architecto",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/outliers/library

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

q   string  optional    

Matches saved title or channel name. Example: hook

tags   string[]  optional    

Only items carrying any of these tag names.

platforms   string[]  optional    

youtube, tiktok, instagram.

creator   string  optional    

Channel/creator name filter. Example: architecto

Save an outlier

requires authentication

Bookmark a video into the library with a snapshot of its stats. Saving the same video again replaces its tags.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/outliers/library" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"platform\": \"tiktok\",
    \"video_id\": \"architecto\",
    \"snapshot\": [],
    \"tags\": [
        \"b\"
    ]
}"

const url = new URL(
    "https://api.viewsmax.com/api/outliers/library"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "platform": "tiktok",
    "video_id": "architecto",
    "snapshot": [],
    "tags": [
        "b"
    ]
};

fetch(url, {
    method: "POST",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/outliers/library

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

platform   string     

Example: tiktok

Must be one of:
  • youtube
  • tiktok
  • instagram
video_id   string     

Example: architecto

snapshot   object     
tags   string[]  optional    

Must not be greater than 50 characters.

Update a saved outlier's tags

requires authentication

Example request:
curl --request PATCH \
    "https://api.viewsmax.com/api/outliers/library/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"tags\": [
        \"b\"
    ]
}"

const url = new URL(
    "https://api.viewsmax.com/api/outliers/library/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

let body = {
    "tags": [
        "b"
    ]
};

fetch(url, {
    method: "PATCH",
    headers,
    body: JSON.stringify(body),
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

PATCH api/outliers/library/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the library. Example: architecto

Body Parameters

tags   string[]  optional    

Must not be greater than 50 characters.

Remove a saved outlier

requires authentication

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/outliers/library/architecto" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/outliers/library/architecto"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

DELETE api/outliers/library/{id}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   string     

The ID of the library. Example: architecto

Get an outlier

requires authentication

A single outlier video with its channel.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/outliers/youtube/dQw4w9WgXcQ" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/outliers/youtube/dQw4w9WgXcQ"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/outliers/{platform}/{videoId}

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

platform   string     

youtube, tiktok, or instagram. Example: youtube

videoId   string     

The platform's video id. Example: dQw4w9WgXcQ

Get an outlier's AI breakdown

requires authentication

status is none (never generated), pending/processing (poll again), completed (payload holds the analysis) or failed (error).

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/outliers/youtube/dQw4w9WgXcQ/breakdown" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/outliers/youtube/dQw4w9WgXcQ/breakdown"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

GET api/outliers/{platform}/{videoId}/breakdown

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

platform   string     

youtube, tiktok, or instagram. Example: youtube

videoId   string     

The platform's video id. Example: dQw4w9WgXcQ

Generate an outlier's AI breakdown

requires authentication

Queues generation (transcript + LLM analysis); poll the GET endpoint until status is completed. An existing breakdown is returned, not regenerated.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/outliers/youtube/dQw4w9WgXcQ/breakdown" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/outliers/youtube/dQw4w9WgXcQ/breakdown"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (401):

Show headers 
cache-control: no-cache, private
content-type: application/json
vary: Origin
 

{
    "success": false,
    "message": "Invalid token"
}

Request      

POST api/outliers/{platform}/{videoId}/breakdown

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

platform   string     

youtube, tiktok, or instagram. Example: youtube

videoId   string     

The platform's video id. Example: dQw4w9WgXcQ

User Default Reference Image

APIs for managing a user's default reference image for image generation

Get Default Reference Image

requires authentication

Retrieve the authenticated user's current default reference image.

Example request:
curl --request GET \
    --get "https://api.viewsmax.com/api/user/default-image" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/user/default-image"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "message": "Default reference image retrieved successfully",
    "data": {
        "has_default_image": true,
        "image_url": "https://your-domain.com/storage/user-defaults/1/image.png"
    }
}

Example response (200):


{
    "success": true,
    "message": "No default reference image set",
    "data": {
        "has_default_image": false,
        "image_url": null
    }
}

Request      

GET api/user/default-image

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Upload Default Reference Image

requires authentication

Upload a new default reference image for the authenticated user. This image will be used as a fallback when no reference image is provided in generation requests.

Example request:
curl --request POST \
    "https://api.viewsmax.com/api/user/default-image" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \

const url = new URL(
    "https://api.viewsmax.com/api/user/default-image"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "POST",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "message": "Default reference image uploaded successfully",
    "data": {
        "has_default_image": true,
        "image_url": "https://your-domain.com/storage/user-defaults/1/image.png"
    }
}

Request      

POST api/user/default-image

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Body Parameters

image   file  optional    

Image file (max 10MB). Required.

Delete Default Reference Image

requires authentication

Remove the authenticated user's default reference image.

Example request:
curl --request DELETE \
    "https://api.viewsmax.com/api/user/default-image" \
    --header "Authorization: Bearer vmx_{YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://api.viewsmax.com/api/user/default-image"
);

const headers = {
    "Authorization": "Bearer vmx_{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "DELETE",
    headers,
}).then(response => response.json());

Example response (200):


{
    "success": true,
    "message": "Default reference image removed successfully"
}

Example response (400):


{
    "success": false,
    "message": "No default reference image to remove"
}

Request      

DELETE api/user/default-image

Headers

Authorization        

Example: Bearer vmx_{YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json