Skip to main content
Official API documentation for Genviral — automate TikTok & Instagram distribution across hosted creators and your own connected accounts.

​
Welcome to Genviral Partner API

The Partner Posting API gives you the exact same pipeline our in-product composer uses: upload or reference media, pick any mix of hosted & BYO accounts, and queue/schedule content programmatically. Every request flows through your Genviral workspace so posts, audit logs, analytics, and retries stay perfectly in sync with what you see at www.genviral.io.

​
Base URL

All requests are scoped to a workspace and should target the main Genviral origin: 
https://www.genviral.io/api/partner/v1

​
Authentication & API Keys

  1. Sign in at www.genviral.io/workspaces.
  2. Select the workspace you want to automate.
  3. Open the API Keys panel and generate a new key.
  4. Store the token (returned once) in your secrets manager.
Keys are formatted as <public_id>.<secret> (for example, gva_live_x1y2z3.abcd1234) and must be passed in the Authorization header: 
Authorization: Bearer <public_id>.<secret>
API keys are workspace-scoped. A key only sees the accounts, credits, and posts that belong to the workspace where it was issued, and every request automatically inherits that context.

​
Workspace-Aware Access

  • Hosted creators & BYO accounts: when you call GET /accounts, you’ll receive both the hosted roster assigned to the workspace and any BYO accounts your team connected.
  • Shared queues: posts scheduled through the API appear immediately inside the dashboard calendar/queue (/workspaces/{id}/posts) with metadata.source = "partner_api".
  • Billing & limits: subscription checks are enforced automatically (402 subscription_required) so you don’t have to handle plan logic yourself.
  1. Discover accounts via GET /accounts and cache the IDs you’ll target.
  2. Assemble payloads with captions, media URLs, music metadata, and per-account targeting.
  3. Schedule posts through POST /posts, optionally adding scheduled_at and external_id.
  4. Track delivery using GET /posts for workspace-wide status and GET /posts/{id} for canonical per-account states.
  5. Retry or edit posts using the dedicated PATCH /posts/{id} and POST /posts/retry endpoints when platforms require another attempt.
Bulk operators typically keep a manifest (CSV/JSON) that maps each video to the target accounts, caption, and schedule window. Stream that manifest with throttled requests (3–10 concurrent) and monitor progress with GET /posts.

​
Postman Collection

Import every endpoint in seconds by downloading the curated Postman collection:
  • Download collection
  • File lives in this repo at genviral-docs/api-reference/postman-collection.json, and the same JSON is mirrored to www.genviral.io/postman-collection.json so partners always have a stable URL to reference.
After importing, fill in the collection variables (base_url, workspace_id, partner_api_token, post_id) and you’ll be able to run the end-to-end workflow described above.

​
Next Steps

  • Response Pattern — learn the ok/code/message contract used everywhere.
  • Data Structures — understand the shapes returned for API keys, accounts, posts, and stats.
  • Endpoint Reference — jump into the account & post endpoints below when you’re ready to build.