Skip to main content
GET
/
api
/
partner
/
v1
/
accounts
curl --request GET \
  --url https://www.genviral.io/api/partner/v1/accounts \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Accounts retrieved",
  "data": {
    "scope": "workspace",
    "owner_user_id": "7be83ba4-14e5-47ba-a662-0ad42d852111",
    "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
    "accounts": [
      {
        "id": "54c22677-43f4-415f-a820-7dfd1fcd4bd5",
        "platform": "twitter",
        "type": "byo",
        "username": "jamesgrowth_",
        "display_name": "james",
        "status": "active",
        "workspace_id": null,
        "capabilities": {
          "supported_content_kinds": ["text_only", "single_image", "multi_image", "single_video"],
          "caption_limit": 4000,
          "media_limits": {
            "max_images": 4,
            "max_videos": 1
          },
          "unsupported_content_kind_reasons": {},
          "settings_schema": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "who_can_reply_post": {
                "type": "string",
                "enum": ["everyone", "following", "mentionedUsers", "subscribers", "verified"]
              },
              "made_with_ai": { "type": "boolean" },
              "paid_partnership": { "type": "boolean" }
            },
            "required": ["who_can_reply_post"]
          }
        }
      },
      {
        "id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
        "platform": "tiktok",
        "type": "hosted",
        "username": "ugc_trends_42",
        "display_name": "Hosted Trends 42",
        "status": "active",
        "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
        "capabilities": {
          "supported_content_kinds": ["single_image", "multi_image", "single_video"],
          "caption_limit": 500,
          "media_limits": {
            "max_images": 35,
            "max_videos": 1
          },
          "unsupported_content_kind_reasons": {
            "text_only": "Text-only posts are only available for connected BYO accounts; hosted accounts require media."
          },
          "settings_schema": {
            "type": "object",
            "additionalProperties": false,
            "properties": {}
          }
        }
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.genviral.io/llms.txt

Use this file to discover all available pages before exploring further.

List the social accounts available in the authenticated key scope - including both your own connected accounts (BYO) and hosted creator accounts. Use this endpoint to discover the account_id you need when calling Create Post, and to inspect what each account can publish before you build a payload.

​
Behavior

  • The API merges active BYO social accounts with active hosted accounts in scope.
  • Workspace keys return workspace accounts. Personal keys return personal accounts (user_id = owner_user_id, workspace_id IS NULL).
  • IDs are stable UUIDs constrained to key scope. If no active accounts exist, the endpoint returns an empty array.
  • Each account is normalized to expose the platform (tiktok, instagram, etc.) and a simplified type of byo or hosted.
  • Each account includes a capabilities object with supported content kinds, caption limits, media limits, unsupported reasons, and a machine-readable provider settings schema.
  • Text-only posting is available only for accounts whose capabilities.supported_content_kinds includes text_only.

​
Response

​
scope
string
Authenticated key scope: workspace or personal.
​
owner_user_id
string
Resolved owner user ID for the authenticated key.
​
workspace_id
string | null
Workspace ID for workspace keys, otherwise null.
​
accounts
array
List of social accounts available for posting.
curl --request GET \
  --url https://www.genviral.io/api/partner/v1/accounts \
  --header 'Authorization: Bearer <token>'

{
  "ok": true,
  "code": 200,
  "message": "Accounts retrieved",
  "data": {
    "scope": "workspace",
    "owner_user_id": "7be83ba4-14e5-47ba-a662-0ad42d852111",
    "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
    "accounts": [
      {
        "id": "54c22677-43f4-415f-a820-7dfd1fcd4bd5",
        "platform": "twitter",
        "type": "byo",
        "username": "jamesgrowth_",
        "display_name": "james",
        "status": "active",
        "workspace_id": null,
        "capabilities": {
          "supported_content_kinds": ["text_only", "single_image", "multi_image", "single_video"],
          "caption_limit": 4000,
          "media_limits": {
            "max_images": 4,
            "max_videos": 1
          },
          "unsupported_content_kind_reasons": {},
          "settings_schema": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "who_can_reply_post": {
                "type": "string",
                "enum": ["everyone", "following", "mentionedUsers", "subscribers", "verified"]
              },
              "made_with_ai": { "type": "boolean" },
              "paid_partnership": { "type": "boolean" }
            },
            "required": ["who_can_reply_post"]
          }
        }
      },
      {
        "id": "0f4f54d4-8cce-4fb7-8c7b-befbcb8af812",
        "platform": "tiktok",
        "type": "hosted",
        "username": "ugc_trends_42",
        "display_name": "Hosted Trends 42",
        "status": "active",
        "workspace_id": "4cb5d3fd-8c8f-4ed7-a17c-4ffb52c7e6ac",
        "capabilities": {
          "supported_content_kinds": ["single_image", "multi_image", "single_video"],
          "caption_limit": 500,
          "media_limits": {
            "max_images": 35,
            "max_videos": 1
          },
          "unsupported_content_kind_reasons": {
            "text_only": "Text-only posts are only available for connected BYO accounts; hosted accounts require media."
          },
          "settings_schema": {
            "type": "object",
            "additionalProperties": false,
            "properties": {}
          }
        }
      }
    ]
  }
}

​
Error Responses

  • 401 - authentication failed (missing/invalid/revoked token)
  • 402 subscription_required - active Creator/Professional/Business plan required
  • 403 tier_not_allowed - Scheduler tier cannot use Partner API
  • 500 accounts_failed - Database query failed unexpectedly