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",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
}
},
"additionalProperties": {}
}
},
"posting_times": ["09:00", "17:30"]
},
{
"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": {}
}
},
"posting_times": []
}
]
}
}
Accounts
Get Accounts
List connected social accounts and discover per-account posting capabilities, media limits, caption limits, and settings schemas for the Genviral social media API.
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",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
}
},
"additionalProperties": {}
}
},
"posting_times": ["09:00", "17:30"]
},
{
"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": {}
}
},
"posting_times": []
}
]
}
}
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 simplifiedtypeofbyoorhosted. - Each account includes a
capabilitiesobject 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_kindsincludestext_only. posting_timeslists the times of day set for the account in the Genviral Social Hub, as wall-clockHH:MM, earliest first. Get Suggested Post Slot uses them to pick the next free time.
Response
string
Authenticated key scope:
workspace or personal.string
Resolved owner user ID for the authenticated key.
string | null
Workspace ID for workspace keys, otherwise
null.array
List of social accounts available for posting.
Show Account Object
Show Account Object
string
UUID account ID returned by
/accounts. Use this in the accounts array
when creating a post.string
The platform name (e.g.,
instagram, tiktok).string
Type of account:
byo (connected by user) or hosted (managed virtual
account).string
The handle or username.
string
The display name of the account.
string
Current status of the account connection.
string | null
Workspace that owns the account, or
null in personal scope.object
Posting capabilities for this account.
Show Capabilities Object
Show Capabilities Object
string[]
Content kinds this account can publish through Genviral. Values
include
text_only, single_image, multi_image, and
single_video.number
Maximum caption length for this account after platform/account policy
is applied.
object
Media limits such as
max_images, max_videos, and optionally
max_video_seconds.object
Reason strings keyed by unsupported content kind.
object
JSON Schema for this provider’s public Partner POST settings object. TikTok and Pinterest
settings are sent as top-level
tiktok and pinterest objects; all other provider
settings are sent under settings.<provider>.string[]
Times of day set for this account in the Genviral Social Hub, as wall-clock
HH:MM (for
example 09:00), unique and earliest first. The same clock time applies in any time zone.
Empty when none are set.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",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"pattern": "\\S"
}
},
"additionalProperties": {}
}
},
"posting_times": ["09:00", "17:30"]
},
{
"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": {}
}
},
"posting_times": []
}
]
}
}
Error Responses
401- authentication failed (missing/invalid/revoked token)402 subscription_required- active Creator/Professional/Business plan required403 tier_not_allowed- Scheduler tier cannot use Partner API500 accounts_failed- Database query failed unexpectedly