Platform API

One API for a creator’s whole presence.

Their link-in-bio page, their Instagram comment-to-DM automations, their content studio, their community. Reach it over REST with an OAuth token, or hand an assistant our hosted MCP endpoint and let it do the work.

An API key, and your first call

An API key acts on your own workspace, server to server, with no OAuth dance. It is the fastest way to see the API work, and it is the right credential for anything you build for yourself. To act on someone else’s workspace you need the OAuth flow — a key can never reach another creator’s data.

  1. Open Settings → Connected apps → Developers in VKit and press Create key. Tick only the scopes you will use.
  2. Copy the secret. It is shown once, at creation, and is not recoverable afterwards — only its digest is kept.
  3. Send it as a bearer token.
curl https://api.vkit.app/v1/capabilities \
  -H "Authorization: Bearer vka_your_key_here"

/v1/capabilities is the right first call: it reports what the workspace can do right now and what the next useful action is, so nothing downstream has to guess.

Writes

Send an Idempotency-Key on every write. The first response for a key is stored for 24 hours and replayed (with Idempotency-Replayed: true) for an identical repeat; the same key with a different body is a 409 idempotency_key_reused. A retry that creates a second short link, or charges a second image generation, is the failure this prevents.

curl -X POST https://api.vkit.app/v1/links \
  -H "Authorization: Bearer vka_your_key_here" \
  -H "Idempotency-Key: 6f0c2a4e-newsletter-cta" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/newsletter"}'

Errors

Every failure is the same envelope, with a stable code to branch on.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This credential does not carry the page.write scope.",
    "status": 403,
    "request_id": "9f2c1a04-2f7e-4a1e-9b2d-6f1e0c3a5b77",
    "retryable": false,
    "field_errors": null,
    "details": { "required_scope": "page.write" },
    "docs_url": "https://api.vkit.app/docs#error-insufficient_scope"
  },
  "code": "insufficient_scope",
  "detail": "This credential does not carry the page.write scope."
}

details.required_scope names the scope you should have asked the creator for, so a 403 tells you what to fix rather than leaving you to ask for all eleven. request_id is the same id the response returns as X-Correlation-ID and the one every log line for that call is written under — quote it and we can find it.

Ceilings

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (seconds) and X-RateLimit-Scope, which names whichever bucket — your app, or this workspace — is the scarcer one. A 429 also carries Retry-After.

Trailing slashes

Both spellings resolve. /v1/me and /v1/me/ are the same route; the reference lists the canonical, slash-less form.

Acting for a creator: OAuth 2.1 with PKCE

Authorization code with PKCE, and nothing else. There is no implicit flow and no plain challenge method; a public client (browser, desktop, a connector) needs no secret, because PKCE is the proof. Discovery lives at /.well-known/oauth-authorization-server — point a generic OAuth client at it and it will find the rest.

0. Register your client, automatically

You do not need to ask anyone for a client id. The discovery document advertises a registration_endpoint (RFC 7591): an MCP client — Muse, Claude, ChatGPT, Cursor — registers itself at connect time, stores the client_id it is handed, and starts the flow below. Every client registered this way is a public PKCE client (token_endpoint_auth_method: none); redirect URIs must be https:// to a named host, with http://127.0.0.1:<port>/ and http://localhost:<port>/ allowed for desktop apps. The registration_access_token manages the registration (RFC 7592 GET/PUT/DELETE) and authenticates nothing else. A registration nobody connects within seven days is removed; the consent screen tells creators an app registered itself and has not been reviewed — email [email protected] with your client id to become a reviewed listing.

curl -X POST https://api.vkit.app/v1/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My assistant",
    "redirect_uris": ["https://my.assistant.example/oauth/callback"],
    "token_endpoint_auth_method": "none",
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "scope": "profile.read page.write"
  }'
# -> 201 { "client_id": "vkc_…", "registration_access_token": "vkg_…", … }

1. Send the creator to the consent screen

GET https://api.vkit.app/oauth/authorize
  ?response_type=code
  &client_id=<your client id>
  &redirect_uri=<one of your registered URIs, byte-identical>
  &scope=profile.read%20page.write
  &code_challenge=<BASE64URL(SHA256(verifier))>
  &code_challenge_method=S256
  &state=<your CSRF value>

They sign in, pick which of their VKits to connect, and read your scopes in the plain words below. redirect_uri is matched exactly, not by prefix — prefix matching on redirect URIs is the classic open redirect, so a URI that is not byte-identical to a registered one is refused before any redirect happens.

2. Exchange the code

curl -X POST https://api.vkit.app/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<the code>",
    "client_id": "<your client id>",
    "redirect_uri": "<the same URI>",
    "code_verifier": "<the verifier>"
  }'

You get a vkp_… access token (one hour), a vkr_… refresh token, the granted scope string and the one workspace this grant is bound to. A token names its own tenant: there is no workspace header, and sending one has no effect.

3. Refresh, with rotation

Rotation is mandatory. The refresh token you present is dead the moment the new pair is issued, so persist the new one before using the new access token. Presenting a rotated-away refresh token is treated as theft and revokes the whole family.

curl -X POST https://api.vkit.app/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"refresh_token","refresh_token":"vkr_…","client_id":"…"}'

A creator can revoke you at any time from Connected apps in VKit, and their grant also dies the moment their membership of that workspace does. Handle 401 invalid_token by sending them through the flow again, never by retrying.

Scopes

Eleven, and the list is closed. Ask for what you will use: the right-hand column is what the creator reads on the consent screen, word for word, so an over-broad request is something they see.

ScopeOn the consent screenWhat the creator is told
profile.readSee your profileRead your VKit account and workspace basics — your name, handle, plan and what your workspace can do.
links.writeCreate short linksCreate and list short links for your workspace, and read how many people clicked them.
page.writeEdit your Link in Bio pageRead and change your Link in Bio page — its theme, blocks, links and socials — and publish it.
instagram.connectConnect InstagramSee whether your Instagram account is connected and start a connection for you. It can never post to Instagram with this alone.
automations.writeManage your automationsCreate, list, enable and disable your Instagram comment-to-DM automations.
posts.writeCreate postsDraft posts in your Studio — captions, carousels and cover images — using your workspace credits.
posts.scheduleSchedule postsPut your posts on the calendar, move them and take them off again.
analytics.readRead your analyticsRead your follower, reach and engagement summaries. Never your followers’ personal details.
community.manageManage your communityRead and manage your community — members, updates, events and tiers.
broadcasts.writeSend broadcastsAnnounce an update to your community and your connected channels on your behalf.
commerce.bookBook and buy on your behalfLook up your bookable services and products, hold a time, and take payment for it. Money settles to your own Stripe account, exactly as it does when somebody books you from your page.

Note what instagram.connect does not do: it can report a connection and start one, and it can never post to Instagram. Publishing to Instagram depends on Meta’s content-publish approval for that specific account, which is a fact about the connection rather than a scope we can grant — ask GET /v1/posts/targets before you promise a creator a post will go out.

The MCP endpoint

A hosted Model Context Protocol server at https://api.vkit.app/mcp, streamable HTTP, with 50 tools over the same API. Point any MCP client at it; it holds no state, so there is nothing to provision.

{
  "mcpServers": {
    "vkit": {
      "type": "http",
      "url": "https://api.vkit.app/mcp"
    }
  }
}

Authenticate by sending the creator’s token as Authorization: Bearer vkp_…. A client that speaks OAuth will find the flow itself from the metadata at /.well-known/mcp.json. The server never stores a token, a session or a transcript: a tool call is one API request made with the credential you sent.

The last eight tools are the buyer face — they book and buy from a creator on a customer’s behalf, address the creator by their public handle, and take a partner key (vkx_…) that VKit issues to a registered buyer agent. There is no OAuth flow for a partner to run: a partner uses an API key issued by VKit rather than a creator’s authorization. A creator credential carrying commerce.book works too, for that creator’s own shop.

The tools

ToolWhat it does
get_capabilitiesWhat this workspace can do right now. Call it first.
get_meWho the connection is, and which scopes were granted.
get_upgrade_linkThe creator’s plan, the link where they upgrade to Pro, and what is Pro-only.
get_pageThe link-in-bio document, its publish state and public URL.
update_pageEdit the draft: theme, title, blocks, order.
publish_pagePut the draft online. The only tool that goes public.
build_page_from_profileCompose a draft from an existing public profile.
get_instagram_statusConnection, handle, and the permissions Meta granted.
start_instagram_connectA single-use consent URL for the creator to open.
list_automationsEvery comment-to-DM automation and its status.
create_automationCreate one, switched off. Only the creator turns it on.
list_post_modelsImage models, credit prices, remaining balance.
create_postGenerate a brand-true post. Spends credits.
schedule_postPut a post on the calendar, to named platforms.
list_postsThe content calendar between two dates.
list_targetsWhere a post can actually go, and where it cannot.
compose_postSave a written post to several platforms at once. A draft unless told otherwise.
validate_postThe per-platform verdict before saving: what fails, and the fix.
publish_post_nowSend a written post immediately. The only tool that does.
create_linkMint a tracked short link.
list_linksShort links with their click counts.
get_analytics_summaryPage, Instagram and community in one read.
get_communityThe community, its numbers and its join URL.
post_community_updatePost an update; optionally email every member.
announce_to_community_and_channelsWrite once, fan out to the feed, the members’ inboxes and every connected platform. Drafts; it does not send.
list_broadcastsEvery announcement and how each channel went.
approve_broadcastSend a drafted announcement. Not reversible.
cancel_broadcastWithdraw one. Stops every channel that has not gone; what has gone stays gone.
list_servicesWhat a creator can be booked for, and the payment profile to use.
search_availabilityOpen times for one service, with a stable slot id.
create_bookingBook a slot and pay for it in one call.
get_bookingOne booking you made: status, time, payment.
modify_bookingMove a booking. The same appointment, the same payment.
cancel_bookingCancel one. The result says whether the money came back.
list_productsThe digital products a creator sells.
buy_productBuy one with a shared payment token.

Nothing here goes public on its own. Editing a page does not publish it. Creating an automation does not switch it on. Scheduling a post to a platform that cannot publish books a reminder for the creator and says so, rather than reporting a post that will never happen. Announcing drafts every channel and stops; approving is its own call.

And nothing confirms a booking nobody has. A taken slot answers 409 slot_unavailable, a declined card answers 402 payment_declined with nothing held, and a creator who has not opted in to agent bookings answers 403 agent_bookings_disabled. Pass an Idempotency-Key on every write: a retry without one is a second appointment and a second charge.

Webhooks

A creator adds an endpoint in VKit and picks the events they want. Each delivery is a JSON POST carrying X-VKit-Event, X-VKit-Delivery and a signature.

X-VKit-Signature: t=1758300000,v1=<hex hmac-sha256>

Verify it over <t>.<raw body bytes> with your endpoint’s secret, compare in constant time, and reject a timestamp more than a few minutes old — the timestamp is inside the signed material precisely so a captured delivery cannot be replayed at you next week.

const signed = `${timestamp}.${rawBody}`;
const expected = createHmac("sha256", secret).update(signed).digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(received));

Answer 2xx quickly and do your work afterwards. A non-2xx is retried four times over about ten minutes, then given up on; past that a destination is down rather than flaky, and a queue that keeps retrying a dead endpoint starves the live ones.

EventSent when
page.publishedA Link in Bio page went live.
automation.createdA comment-to-DM automation was created (in draft).
automation.firedAn automation matched a comment and acted.
post.scheduledA post was put on the calendar.
post.publishedA scheduled post actually published.
community.member_joinedSomeone joined the creator's community.
broadcast.sentA broadcast finished going out.
platform.pingYou pressed Send test delivery.

Free and Pro

Most creators who connect an assistant are on the Free plan, and VKit does not nag them in-app. When a call exercises a feature that is part of Pro — a Story or DM trigger, a follow gate, an email ask, a motion wallpaper, hiding VKit branding — the API answers 402 plan_required. Nothing was changed and nothing was silently downgraded. Reads are always free.

{
  "error": {
    "code": "plan_required",
    "message": "Follow gates is part of VKit Pro. Ask the creator to upgrade at the link, then retry.",
    "status": 402,
    "details": {
      "feature": "automation_follow_gate",
      "feature_label": "Follow gates",
      "plan": "pro",
      "current_plan": "free",
      "upgrade_url": "https://platform.vkit.app/upgrade?via=agent&feature=automation_follow_gate",
      "price": { "monthly": "$19", "annual": "$190", "first_month": "$4.99" },
      "check": { "path": "/v1/me", "field": "workspace.plan" }
    }
  }
}

Hand the creator details.upgrade_url as a link. It is theirs to open: it signs them in if needed, names what the assistant asked for, and takes them through VKit’s own Stripe Checkout. When they come back, re-read GET /v1/me — workspace.plan moves off free and workspace.upgrade_url becomes null — and retry the call. There is no webhook for a plan change; one GET is the whole check.

To offer the upgrade before trying, read the plan-gated rows on GET /v1/capabilities (each carries entitlement.state and, while it is upgrade_required, the same upgrade_url) or call GET /v1/upgrade — the MCP tool get_upgrade_link — for the plan, the link, the price and every Pro-only feature in one read.

The TypeScript SDK

The same client our own apps use, in platform mode. Typed resources, typed errors, idempotency keys as a first-class argument.

import { createVKitClient } from "@saveasy/sdk";

const vkit = createVKitClient({
  platformUrl: "https://api.vkit.app",
  platformToken: process.env.VKIT_TOKEN, // vkp_… or vka_…
});

const page = await vkit.v1.page.get();
await vkit.v1.page.update({
  blocks: {
    add: [{ type: "external_link", stable_key: "substack",
            config: { title: "My Substack", url: "https://ava.substack.com" } }],
    reorder: ["substack"],
  },
});
await vkit.v1.page.publish({ idempotencyKey: "publish-2026-09-19" });

Read the spec

openapi.json is generated from the server and describes only /v1. Generate a client in any language from it.

Point an agent here

llms.txt summarises the whole platform in a page, for a model that landed on this host first.

Become a partner

Registering an OAuth app, sandbox workspaces and review: the partner program.