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.
- Open Settings → Connected apps → Developers in VKit and press Create key. Tick only the scopes you will use.
- Copy the secret. It is shown once, at creation, and is not recoverable afterwards — only its digest is kept.
- 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.
| Scope | On the consent screen | What the creator is told |
|---|---|---|
profile.read | See your profile | Read your VKit account and workspace basics — your name, handle, plan and what your workspace can do. |
links.write | Create short links | Create and list short links for your workspace, and read how many people clicked them. |
page.write | Edit your Link in Bio page | Read and change your Link in Bio page — its theme, blocks, links and socials — and publish it. |
instagram.connect | Connect Instagram | See whether your Instagram account is connected and start a connection for you. It can never post to Instagram with this alone. |
automations.write | Manage your automations | Create, list, enable and disable your Instagram comment-to-DM automations. |
posts.write | Create posts | Draft posts in your Studio — captions, carousels and cover images — using your workspace credits. |
posts.schedule | Schedule posts | Put your posts on the calendar, move them and take them off again. |
analytics.read | Read your analytics | Read your follower, reach and engagement summaries. Never your followers’ personal details. |
community.manage | Manage your community | Read and manage your community — members, updates, events and tiers. |
broadcasts.write | Send broadcasts | Announce an update to your community and your connected channels on your behalf. |
commerce.book | Book and buy on your behalf | Look 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
| Tool | What it does |
|---|---|
get_capabilities | What this workspace can do right now. Call it first. |
get_me | Who the connection is, and which scopes were granted. |
get_upgrade_link | The creator’s plan, the link where they upgrade to Pro, and what is Pro-only. |
get_page | The link-in-bio document, its publish state and public URL. |
update_page | Edit the draft: theme, title, blocks, order. |
publish_page | Put the draft online. The only tool that goes public. |
build_page_from_profile | Compose a draft from an existing public profile. |
get_instagram_status | Connection, handle, and the permissions Meta granted. |
start_instagram_connect | A single-use consent URL for the creator to open. |
list_automations | Every comment-to-DM automation and its status. |
create_automation | Create one, switched off. Only the creator turns it on. |
list_post_models | Image models, credit prices, remaining balance. |
create_post | Generate a brand-true post. Spends credits. |
schedule_post | Put a post on the calendar, to named platforms. |
list_posts | The content calendar between two dates. |
list_targets | Where a post can actually go, and where it cannot. |
compose_post | Save a written post to several platforms at once. A draft unless told otherwise. |
validate_post | The per-platform verdict before saving: what fails, and the fix. |
publish_post_now | Send a written post immediately. The only tool that does. |
create_link | Mint a tracked short link. |
list_links | Short links with their click counts. |
get_analytics_summary | Page, Instagram and community in one read. |
get_community | The community, its numbers and its join URL. |
post_community_update | Post an update; optionally email every member. |
announce_to_community_and_channels | Write once, fan out to the feed, the members’ inboxes and every connected platform. Drafts; it does not send. |
list_broadcasts | Every announcement and how each channel went. |
approve_broadcast | Send a drafted announcement. Not reversible. |
cancel_broadcast | Withdraw one. Stops every channel that has not gone; what has gone stays gone. |
list_services | What a creator can be booked for, and the payment profile to use. |
search_availability | Open times for one service, with a stable slot id. |
create_booking | Book a slot and pay for it in one call. |
get_booking | One booking you made: status, time, payment. |
modify_booking | Move a booking. The same appointment, the same payment. |
cancel_booking | Cancel one. The result says whether the money came back. |
list_products | The digital products a creator sells. |
buy_product | Buy 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.
| Event | Sent when |
|---|---|
page.published | A Link in Bio page went live. |
automation.created | A comment-to-DM automation was created (in draft). |
automation.fired | An automation matched a comment and acted. |
post.scheduled | A post was put on the calendar. |
post.published | A scheduled post actually published. |
community.member_joined | Someone joined the creator's community. |
broadcast.sent | A broadcast finished going out. |
platform.ping | You 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.