Developer documentation

VoidGram API
Programmatic access to your local install

Drive VoidGram the same way the app does — same endpoints, same payloads, same Prisma-backed database. Authenticate with a Bearer key instead of the UI session cookie and you have a stable, versioned REST surface at /api/v1/*.

The API binds to localhost on your machine. Nothing is proxied through a VoidGram server — there isn't one. Your API keys, request bodies, uploaded media, and responses never leave your device.

Start here

Walkthrough

Quickstart →

Get from zero to a published post in about ten minutes. Five end-to-end workflows with curl, TypeScript, and Python.

Complete

Reference →

Every endpoint in /api/v1, every schema, every field. The exhaustive contract — pinned to the OpenAPI spec.

Quick reference

Errors →

All error codes the API can emit, grouped by category, with HTTP status and recovery hints.

Integration

MCP server →

Drive VoidGram from Claude Code, Claude Desktop, and any other MCP host. Installation, tools, prompts, troubleshooting.

+ What's in v3.3.0

  • •Bearer-authenticated REST at /api/v1/*
  • •OpenAPI 3.1 machine-readable spec at /api/v1/openapi.json
  • •Uploads, drafts, publish, schedule, post history
  • •Cloudflare diagnostics (read-only)
  • •Story repost core flows (status, config, enable, scan, history)
  • •Private API credentials lifecycle
  • •MCP server for Claude Code + Claude Desktop

− What's not in v3.3.0

  • •LAN or public access — the server binds to localhost only
  • •Webhooks — all event-driven patterns are polling today
  • •Per-key scopes — every key is full-access
  • •Built-in idempotency keys — dedupe your own retries
  • •Official SDK — TypeScript and Python SDKs planned for v3.4
  • •Multi-user isolation — every key shares the same desktop user
  • •Facebook cross-post for cloud-scheduled posts (local-scheduled posts work)

At a glance

Base URL
http://localhost:3001/api/v1
Auth header
Authorization: Bearer vg_live_…
Rate limits
100 req/min and 1000 req/hour per key
OpenAPI spec
GET /api/v1/openapi.json
Swagger UI
http://localhost:3001/api/docs
Stability
/api/v1 is frozen across the v3.x line

Need the app first?

The API only runs while the VoidGram desktop app is open. It's a single installer — no servers, no accounts, no subscriptions.

Download VoidGram