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 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 is strictly scoped by the API key, so data access stays isolated to either one workspace or one personal owner context.

​
Base URL

All requests should target the main Genviral origin. Scope is inferred from the API key metadata (scope, workspace_id, owner_user_id): 
https://www.genviral.io/api/partner/v1

​
Authentication & API Keys

  1. Sign in at www.genviral.io.
  2. Open the API Keys page.
  3. Choose key scope:
    • Personal for Creator/Professional usage without workspace selection.
    • Workspace for Business team usage in a specific workspace.
  4. Generate a key and 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 single-scope credentials. A key is either workspace-scoped (workspace_id set) or personal-scoped (owner_user_id set). Requests never fall through to unscoped data.

​
Scope-Aware Access

  • Accounts: GET /accounts returns accounts in key scope only. Workspace keys return workspace accounts; personal keys return accounts where user_id = owner_user_id and workspace_id IS NULL.
  • Posts/files/slideshows/packs/templates: all endpoints enforce the same scope boundary from the key.
  • Billing & tiers: Partner API requires an active Creator, Professional, or Business subscription (402 subscription_required when missing). Scheduler tier is blocked (403 tier_not_allowed).
  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 scope-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 the curated collection (accounts, files, posts, slideshows, packs, and templates) in seconds:
  • 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, partner_api_token, post_id, slideshow_id, pack_id, template_id, image_id, slide_index, analytics_target_id, analytics_refresh_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.