API & MCP reference

Talk to VibeHub from code.

One REST surface, one TypeScript SDK, one MCP server. Capture sessions from any agent, attach them to commits, query your vibes, and trigger workflows.

Quickstart MCP server Back to docs

Quickstart

Capture a commit in three calls.

The most common API flow: open a session, append messages, and attach it to a commit.

bash# 1) Start a session
curl -X POST https://vibehub.co/api/sdk/sessions \
  -H "Authorization: Bearer vbh_..." \
  -H "Content-Type: application/json" \
  -d '{"source":"cursor","model":"claude-opus-4-7"}'
# → { "session": { "id": "ses_…", "status": "open" } }

# 2) Append a message
curl -X POST https://vibehub.co/api/sdk/sessions/ses_…/attach \
  -H "Authorization: Bearer vbh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sha": "1a2b3c4d…",
    "projectId": "prj_…",
    "message": "feat: add waitlist"
  }'

Prefer the SDK or the MCP server for any non-trivial integration — both wrap this surface and add idempotency keys, retries, and types.

Authentication

Bearer tokens, vbh_ prefix.

Every API call carries a token from the dashboard at Settings → API tokens. The plaintext is shown once at creation — store it like any other secret.

httpPOST /api/sdk/sessions HTTP/1.1
Host: vibehub.co
Authorization: Bearer vbh_3f9c…b21
Content-Type: application/json

{ "source": "cursor" }

PREFIXTokens start with vbh_. Anything else is rejected.
STORAGEOnly the sha-256 hash is stored. Treat tokens as you would any API key.
REVOKEDELETE /api/cli/tokens/:id or the dashboard.
DASHBOARDBrowser-based UI requests use session cookies — same surface, different auth.

SDK

@vibehub/sdk for TypeScript.

A tiny, typed wrapper around the REST surface. Works in Node 18+, Bun, Deno, and the browser.

Install

npm i @vibehub/sdk
# or
pnpm add @vibehub/sdk
bun add @vibehub/sdk

Create a client

tsimport { createClient } from "@vibehub/sdk";

const vb = createClient({
  apiUrl: "https://vibehub.co",
  token: process.env.VIBEHUB_TOKEN!,
});

End-to-end capture

ts// 1) start a session
const session = await vb.startSession({
  source: "cursor",
  model: "claude-opus-4-7",
  externalId: "cursor-chat-123", // idempotency key
});

// 2) stream messages
await vb.appendMessages(session.id, [
  { role: "user",      content: "fix the foo bug" },
  { role: "assistant", content: "Looking at src/foo.ts…" },
]);

// 3) attach to a commit
await vb.attachToCommit(session.id, {
  sha: "1a2b3c4d…",
  projectId: "prj_…",
  message: "fix: foo bug",
});

One-shot capture

For agents that already have the whole conversation in memory by the time they commit.

tsawait vb.captureCommit({
  projectId,
  sha,
  message: "feat: thing",
  committedAt: new Date(),
  diff: gitDiff,
  filesChanged: 3,
  insertions: 42,
  deletions: 7,
  conversation: {
    source: "windsurf",
    messages: [
      { role: "user",      content: "…" },
      { role: "assistant", content: "…" },
    ],
  },
});

Method index

startSession(input)

Open a session. Idempotent via externalId.

appendMessages(id, msgs)

Append one or many messages; sequence is server-assigned.

getSession(id, { includeMessages? })

Fetch a session with optional messages.

listSessions({ status?, projectId?, limit? })

List the authenticated user's sessions.

updateSession(id, patch)

Patch summary, status, or endedAt.

attachToCommit(id, params)

Close the session and link it to a git commit.

captureCommit(input)

Bulk POST: commit + conversation in one call.

createProject(input)

listProjects()

List the user's projects.

REST

Endpoint reference.

All endpoints are JSON-in / JSON-out, return standard HTTP status codes, and live under https://vibehub.co.

Projects

GET/api/projects

List the user's projects.

POST/api/projects

Create or reuse a project by (owner, slug).

GET/api/projects/:slug/branches

List remote branches for a project.

POST/api/projects/:slug/mirror

Link or refresh a GitHub mirror.

Vibes & commits

GET/api/vibes

Browse vibes (filter by project, tag, builder).

GET/api/vibes/:id

Fetch a single vibe with its bundle.

POST/api/cli/commits

GET/api/cli/commits/:sha

Fetch a commit by SHA.

Sessions (SDK & MCP backend)

POST/api/sdk/sessions

Open a new session, or reuse one by externalId.

GET/api/sdk/sessions/:id

Fetch a session, optionally with messages.

PATCH/api/sdk/sessions/:id

Patch summary, status, or endedAt.

POST/api/sdk/sessions/:id/attach

Close the session and link it to a commit.

Workflows & runs

GET/api/workflows

List workflows.

POST/api/workflows

Create a new workflow.

GET/api/workflows/:id

Fetch a workflow and its triggers.

POST/api/workflows/:id/trigger

Trigger a run with typed inputs.

GET/api/runs

List recent runs across workflows.

GET/api/runs/:id

Fetch a single run with logs.

Collections, builders, activity

GET/api/collections

List the user's collections.

POST/api/collections

Create a collection.

POST/api/collections/:id/vibes

Add a vibe to a collection.

GET/api/builders

Browse public builders & profiles.

POST/api/builders/:id/follow

Follow / unfollow a builder.

GET/api/activity

Activity feed for the authenticated user.

GET/api/analytics

Project-level analytics summary.

Agent (dashboard chat)

POST/api/agent/chat

Stream a chat turn (Server-Sent Events).

GET/api/agent/tools

List tools the agent has access to.

GET/api/agent/metrics

Per-conversation usage metrics.

GET/api/agent/conversations

List the user's agent conversations.

GET/api/agent/conversations/:id

Fetch a conversation with its turns.

Account & tokens

GET/api/me

The authenticated user's profile.

GET/api/cli/tokens

List the user's API tokens (metadata only).

POST/api/cli/tokens

Mint a new token. The plaintext is returned once.

DELETE/api/cli/tokens/:id

Revoke a token.

GET/api/cli/projects

CLI-shaped list of projects (used by vb).

GET/api/cli/branches

CLI-shaped branch listing.

GET/api/cli/mirrors

List linked GitHub mirrors.

POST/api/cli/mirrors/push

Trigger a mirror push.

Billing & misc

POST/api/billing/checkout

Start a Stripe checkout session.

POST/api/billing/portal

Open the customer portal.

POST/api/billing/webhook

Stripe webhook receiver.

GET/api/notifications

In-app notifications feed.

POST/api/signups

Public waitlist signup endpoint.

GET/api/health

Service health probe.

Operations

Errors, idempotency & rate limits.

Predictable failure modes and replay safety for any integration that can't afford double-writes.

Status codes — 200/201 success, 400 validation, 401 bad token, 403 not your resource, 404 not found, 409 conflict (e.g. project slug taken), 429 rate-limited.
Error body — always { "error": "human-readable", "code"?: "snake_case_key" }.
Idempotency — session creation accepts an externalId; commit registration is idempotent by SHA + project.
Rate limits — soft cap of 60 req/min per token on writes, 300 req/min on reads. Hard limits live on Team plans.
SDK — VibeHubError carries .status and the parsed .body.

MCP

Model Context Protocol server.

vibehub-mcp is a stdio MCP server. Drop it into any MCP-capable IDE and the agent gains a small toolbelt that records the chat and attaches it to commits.

Install

# install globally
npm i -g vibehub-mcp

# or run on demand
npx vibehub-mcp

The server reads two env vars: VIBEHUB_API_URL (defaults to https://vibehub.co) and VIBEHUB_TOKEN (required — same vbh_… token as the SDK).

How sessions work

A session is an open conversation. It starts open, accumulates messages, and becomes attached when linked to a commit. The current session id is persisted at ~/.vibehub/mcp-state.json so tools like vibehub_append_message can omit sessionId.

Encourage the agent to actually use these tools by adding an instruction to your project rules file (.cursorrules, AGENTS.md, etc) — see the patterns below.

MCP

The vibehub_* toolbelt.

Every MCP-capable agent that mounts the server sees these tools. They map 1:1 onto SDK calls and persist the “current session” locally so the agent doesn't need to thread an id everywhere.

vibehub_start_session

Open a new session and remember it as current. Call once per chat.

vibehub_append_message

Append a single user/assistant/tool/system message.

vibehub_append_messages

Batch-append messages (useful for backfilling).

vibehub_attach_to_commit

Close the session and link it to a SHA. Creates the commit row if needed.

vibehub_current_session

Return the active session id, status, and message count.

vibehub_list_projects

List the user's VibeHub projects (id, slug, name).

vibehub_create_project

Create (or reuse) a project by name. Sets visibility.

Suggested agent instructions

Paste into your IDE's system prompt, project rules, or AGENTS.md:

Use the `vibehub_*` tools to record this conversation.
  • Call vibehub_start_session once at the start with source set to the IDE name.
  • After every assistant response, call vibehub_append_message with role
    "assistant" and the response content.
  • When the user commits, call vibehub_attach_to_commit with the SHA.

MCP

IDE configuration.

Anywhere that accepts a stdio MCP server command + args + env, the same three lines work.

Cursor

~/.cursor/mcp.json

json{
  "mcpServers": {
    "vibehub": {
      "command": "npx",
      "args": ["-y", "vibehub-mcp"],
      "env": {
        "VIBEHUB_API_URL": "https://vibehub.co",
        "VIBEHUB_TOKEN": "vbh_…"
      }
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

json{
  "mcpServers": {
    "vibehub": {
      "command": "npx",
      "args": ["-y", "vibehub-mcp"],
      "env": {
        "VIBEHUB_API_URL": "https://vibehub.co",
        "VIBEHUB_TOKEN": "vbh_…"
      }
    }
  }
}

Windsurf · Continue.dev · Zed

Any MCP-capable IDE uses the same command + args + env shape — the exact config file changes, but the contents don't.

json{
  "command": "npx",
  "args": ["-y", "vibehub-mcp"],
  "env": {
    "VIBEHUB_API_URL": "https://vibehub.co",
    "VIBEHUB_TOKEN": "vbh_…"
  }
}

For zero-friction commits, point your IDE's commit flow at vb commit --attach-session <id> — the CLI calls attach_to_commit for you.