Viraly API Documentation - Developer Reference

Language:

Getting Started

The Viraly API gives you programmatic access to your workspace. Create and schedule posts, manage channels, retrieve analytics, and more. All API requests are scoped to your workspace via your API key.

Base URL

https://api.viraly.io/api/v1

Quick Start

Make your first API call to verify your key is working:

cURL

curl "https://api.viraly.io/api/v1/workspace" \
  -H "Authorization: Bearer vly_your_api_key"

Authentication

All API requests require a Bearer token in the Authorization header. API keys are created in your workspace settings and start with the vly_ prefix.

Authorization Header

Authorization: Bearer vly_your_api_key

Permission Scopes

Each API key has granular permissions. If a key lacks the required permission, the API returns a 403 error.

posts:readposts:writechannels:readchannels:writeanalytics:readbiolinks:readbiolinks:writemedia:readmedia:writesocial_sets:readsocial_sets:writecategories:readcategories:writehashtags:readhashtags:writeideas:readideas:writefeeds:readfeeds:writeurl_shortener:readurl_shortener:writesubscribers:readworkspace:read

Rate Limits

Rate limits are applied per API key and vary by subscription plan. When exceeded, the API returns 429 Too Many Requests.

Plan	Requests / Minute	Requests / Day
Free	30	1,000
Influencer	60	5,000
Business	120	20,000
Agency	300	100,000
Enterprise	600	500,000

Rate Limit Headers

Every response includes these headers:

Response Headers

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1712582400
Retry-After: 30  # Only on 429 responses

Pagination

List endpoints return paginated results. Use page and per_page query parameters to control pagination. The maximum per_page value is 100.

Paginated Response

{
  "data": [ ... ],
  "meta": {
    "requestId": "req_abc123",
    "pagination": {
      "page": 1,
      "perPage": 25,
      "total": 142,
      "totalPages": 6
    }
  }
}

Error Handling

The API uses standard HTTP status codes. Errors return a JSON body with a descriptive message.

Status	Meaning
200	Success
400	Bad request - invalid parameters
401	Unauthorized - invalid or missing API key
403	Forbidden - insufficient permissions
404	Not found - resource does not exist
429	Rate limit exceeded

Error Response

{
  "error": {
    "code": "not_found",
    "message": "Post with ID 'abc123' was not found.",
    "requestId": "req_abc123"
  }
}

AI / LLM Integration

Building with AI agents or LLMs? We provide a machine-readable API reference optimized for AI consumption. Point your AI agent or coding assistant to this file for complete endpoint coverage with structured examples.

viraly.io/llms.md

LLM-optimized API reference with every endpoint, parameter, and response shape

API Reference

Posts

Create, schedule, and manage social media posts across all connected channels.

Method	Endpoint	Description
GET	/posts	List posts
GET	/posts/{id}	Get a post
POST	/posts	Create a post
PUT	/posts/{id}	Update a post
DELETE	/posts/{id}	Delete a post
PUT	/posts/{id}/schedule	Reschedule a post
POST	/posts/{id}/publish	Publish a post immediately

GET/api/v1/postsposts:read

Retrieve a paginated list of posts with optional filters.

Query Parameters

social_set_idstring?Filter by social set

channel_idstring?Filter by channel

statusstring?Filter by status: draft, scheduled, published, failed

start_datestring?Start date (YYYY-MM-DD)

end_datestring?End date (YYYY-MM-DD)

pageinteger?Page number (default: 1)

per_pageinteger?Items per page (default: 25, max: 100)

sortstring?Sort by: created_at, scheduled_at, published_at

orderstring?Sort order: asc, desc

Request

cURL

curl "https://api.viraly.io/api/v1/posts" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "a8Kf3mN9",
      "title": "Exciting product launch!",
      "status": "Scheduled",
      "scheduledAt": "2026-04-15T14:00:00Z",
      "channelId": "pQ2rS5tU",
      "config": {
        "channelType": "Instagram",
        "caption": "We're thrilled to announce..."
      },
      "createdAt": "2026-04-08T10:30:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "pagination": {
      "page": 1,
      "perPage": 25,
      "total": 142,
      "totalPages": 6
    }
  }
}

GET/api/v1/posts/{id}posts:read

Get a post

Path Parameters

idstringPost ID

Request

cURL

curl "https://api.viraly.io/api/v1/posts/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "id": "a8Kf3mN9",
    "title": "Exciting product launch!",
    "status": "Scheduled",
    "scheduledAt": "2026-04-15T14:00:00Z",
    "channelId": "pQ2rS5tU",
    "config": {
      "channelType": "Instagram",
      "caption": "We're thrilled to announce our new feature..."
    },
    "createdAt": "2026-04-08T10:30:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

POST/api/v1/postsposts:write

Create a post

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/posts" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "channelId": "pQ2rS5tU",
  "config": {
    "channelType": "Instagram",
    "caption": "Check out our latest update!",
    "mediaType": "Image"
  },
  "scheduledAt": "2026-04-15T14:00:00Z",
  "timezone": "America/New_York"
}'

Response

JSON

{
  "data": {
    "id": "x7Lp9Qr2",
    "status": "Scheduled",
    "scheduledAt": "2026-04-15T14:00:00Z",
    "channelId": "pQ2rS5tU",
    "createdAt": "2026-04-08T11:00:00Z"
  },
  "meta": { "requestId": "req_def456" }
}

PUT/api/v1/posts/{id}posts:write

Update a post

Path Parameters

idstringPost ID

Request

cURL

curl -X PUT "https://api.viraly.io/api/v1/posts/{id}" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "channelId": "pQ2rS5tU",
  "config": {
    "channelType": "Instagram",
    "caption": "Updated caption for our launch post!"
  },
  "scheduledAt": "2026-04-16T10:00:00Z"
}'

Response

JSON

{
  "data": {
    "id": "a8Kf3mN9",
    "status": "Scheduled",
    "scheduledAt": "2026-04-16T10:00:00Z"
  },
  "meta": { "requestId": "req_ghi789" }
}

DELETE/api/v1/posts/{id}posts:write

Delete a post

Path Parameters

idstringPost ID

Request

cURL

curl -X DELETE "https://api.viraly.io/api/v1/posts/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{}

PUT/api/v1/posts/{id}/scheduleposts:write

Reschedule a post

Path Parameters

idstringPost ID

Request

cURL

curl -X PUT "https://api.viraly.io/api/v1/posts/{id}/schedule" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduledAt": "2026-04-20T09:00:00Z",
  "timezone": "America/New_York"
}'

Response

JSON

{
  "data": {
    "id": "a8Kf3mN9",
    "status": "Scheduled",
    "scheduledAt": "2026-04-20T09:00:00Z"
  },
  "meta": { "requestId": "req_jkl012" }
}

POST/api/v1/posts/{id}/publishposts:write

Publish a post immediately

Path Parameters

idstringPost ID

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/posts/{id}/publish" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "id": "a8Kf3mN9",
    "status": "Publishing"
  },
  "meta": { "requestId": "req_mno345" }
}

Channels

View and manage connected social media channels (profiles/pages).

Method	Endpoint	Description
GET	/channels	List channels
GET	/channels/{id}	Get a channel
GET	/channels/{id}/stats	Get channel statistics

GET/api/v1/channelschannels:read

List channels

Query Parameters

social_set_idstring?Filter by social set

Request

cURL

curl "https://api.viraly.io/api/v1/channels" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "pQ2rS5tU",
      "name": "Viraly Official",
      "type": "Instagram",
      "username": "@viraly",
      "status": "Active",
      "pictureUrl": "https://...",
      "createdAt": "2025-10-01T08:00:00Z"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

GET/api/v1/channels/{id}channels:read

Get a channel

Path Parameters

idstringChannel ID

Request

cURL

curl "https://api.viraly.io/api/v1/channels/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "id": "pQ2rS5tU",
    "name": "Viraly Official",
    "type": "Instagram",
    "username": "@viraly",
    "status": "Active",
    "createdAt": "2025-10-01T08:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

GET/api/v1/channels/{id}/statschannels:read

Get channel statistics

Path Parameters

idstringChannel ID

Request

cURL

curl "https://api.viraly.io/api/v1/channels/{id}/stats" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "totalPosts": 284,
    "scheduledPosts": 12,
    "publishedPosts": 265,
    "failedPosts": 7
  },
  "meta": { "requestId": "req_abc123" }
}

Social Sets

Social sets are logical groupings of channels (e.g., 'Client A', 'Marketing Team').

Method	Endpoint	Description
GET	/social-sets	List social sets
POST	/social-sets	Create a social set
GET	/social-sets/{id}	Get a social set
PUT	/social-sets/{id}	Update a social set

GET/api/v1/social-setssocial_sets:read

List social sets

Request

cURL

curl "https://api.viraly.io/api/v1/social-sets" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "b7Qr4kL2",
      "name": "Marketing",
      "code": "MK",
      "colorHex": "#9333EA",
      "timezone": "America/New_York",
      "createdAt": "2025-09-15T12:00:00Z"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

POST/api/v1/social-setssocial_sets:write

Create a social set

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/social-sets" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Client B",
  "timezone": "Europe/London"
}'

Response

JSON

{
  "data": {
    "id": "c9Ws5nM3",
    "name": "Client B",
    "timezone": "Europe/London",
    "createdAt": "2026-04-08T12:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

GET/api/v1/social-sets/{id}social_sets:read

Get a social set

Path Parameters

idstringSocial Set ID

Request

cURL

curl "https://api.viraly.io/api/v1/social-sets/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "id": "b7Qr4kL2",
    "name": "Marketing",
    "code": "MK",
    "colorHex": "#9333EA",
    "timezone": "America/New_York",
    "createdAt": "2025-09-15T12:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

PUT/api/v1/social-sets/{id}social_sets:write

Update a social set

Path Parameters

idstringSocial Set ID

Request

cURL

curl -X PUT "https://api.viraly.io/api/v1/social-sets/{id}" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Updated Name",
  "timezone": "America/Chicago"
}'

Response

JSON

{
  "data": {
    "id": "b7Qr4kL2",
    "name": "Updated Name",
    "timezone": "America/Chicago"
  },
  "meta": { "requestId": "req_abc123" }
}

Bio Links

Create and manage link-in-bio pages with custom themes, links, and subscriber collection.

Method	Endpoint	Description
GET	/biolinks	List bio links
GET	/biolinks/{id}	Get a bio link
POST	/biolinks	Create a bio link
PUT	/biolinks/{id}	Update a bio link
DELETE	/biolinks/{id}	Delete a bio link
GET	/biolinks/{id}/linked-channels	Get linked channels for a bio link
PUT	/biolinks/{id}/linked-channels	Update linked channels
GET	/biolinks/{id}/subscribers	List bio link subscribers

GET/api/v1/biolinksbiolinks:read

List bio links

Query Parameters

social_set_idstring?Filter by social set

Request

cURL

curl "https://api.viraly.io/api/v1/biolinks" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "d2Xp7rK8",
      "title": "My Links",
      "slug": "viraly",
      "domain": null,
      "createdAt": "2025-11-20T10:00:00Z"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

GET/api/v1/biolinks/{id}biolinks:read

Get a bio link

Path Parameters

idstringBio Link ID

Request

cURL

curl "https://api.viraly.io/api/v1/biolinks/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "id": "d2Xp7rK8",
    "title": "My Links",
    "slug": "viraly",
    "config": "...",
    "domain": null,
    "socialSetId": "TrrdKTIr",
    "createdAt": "2025-11-20T10:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

POST/api/v1/biolinksbiolinks:write

Create a bio link

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/biolinks" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "My New Page",
  "slug": "my-brand",
  "socialSetId": "TrrdKTIr"
}'

Response

JSON

{
  "data": {
    "id": "f3Xp8rK9",
    "title": "My New Page",
    "slug": "my-brand",
    "createdAt": "2026-04-09T10:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

PUT/api/v1/biolinks/{id}biolinks:write

Update a bio link

Path Parameters

idstringBio Link ID

Request

cURL

curl -X PUT "https://api.viraly.io/api/v1/biolinks/{id}" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Updated Title"
}'

Response

JSON

{
  "data": {
    "id": "d2Xp7rK8",
    "title": "Updated Title",
    "slug": "viraly"
  },
  "meta": { "requestId": "req_abc123" }
}

DELETE/api/v1/biolinks/{id}biolinks:write

Delete a bio link

Path Parameters

idstringBio Link ID

Request

cURL

curl -X DELETE "https://api.viraly.io/api/v1/biolinks/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{}

GET/api/v1/biolinks/{id}/linked-channelsbiolinks:read

Get linked channels for a bio link

Path Parameters

idstringBio Link ID

Request

cURL

curl "https://api.viraly.io/api/v1/biolinks/{id}/linked-channels" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "lc1234",
      "channelId": "VQ4fKSE9",
      "isEnabled": true,
      "displayStyle": "link"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

PUT/api/v1/biolinks/{id}/linked-channelsbiolinks:write

Update linked channels

Path Parameters

idstringBio Link ID

Request

cURL

curl -X PUT "https://api.viraly.io/api/v1/biolinks/{id}/linked-channels" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "channels": [
    { "channelId": "VQ4fKSE9", "isEnabled": true }
  ]
}'

Response

JSON

{}

GET/api/v1/biolinks/{id}/subscriberssubscribers:read

List bio link subscribers

Path Parameters

idstringBio Link ID

Query Parameters

pageinteger?Page number

per_pageinteger?Items per page

Request

cURL

curl "https://api.viraly.io/api/v1/biolinks/{id}/subscribers" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "e4Yq9sL0",
      "email": "subscriber@example.com",
      "name": "Jane Doe",
      "createdAt": "2026-03-15T14:30:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "pagination": { "page": 1, "perPage": 25, "total": 89, "totalPages": 4 }
  }
}

Analytics

Trigger analytics syncs for connected channels. Analytics data is fetched from each platform's API.

Method	Endpoint	Description
POST	/analytics/{channelId}/sync	Trigger analytics sync

POST/api/v1/analytics/{channelId}/syncanalytics:read

Enqueues a background job to fetch the latest analytics data from the platform.

Path Parameters

channelIdstringChannel ID

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/analytics/{channelId}/sync" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "status": "sync_started",
    "channelId": "pQ2rS5tU"
  },
  "meta": { "requestId": "req_abc123" }
}

Media

Upload and manage media files (images, videos) used in posts.

Method	Endpoint	Description
GET	/media	List media items
GET	/media/{id}	Get a media item
DELETE	/media/{id}	Delete a media item
GET	/media/collections	List media collections

GET/api/v1/mediamedia:read

List media items

Query Parameters

social_set_idstring?Filter by social set

collection_idstring?Filter by collection

pageinteger?Page number

per_pageinteger?Items per page

Request

cURL

curl "https://api.viraly.io/api/v1/media" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "f6Zr1tM2",
      "type": 0,
      "status": "Ready",
      "createdAt": "2026-04-01T08:15:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "pagination": { "page": 1, "perPage": 25, "total": 53, "totalPages": 3 }
  }
}

GET/api/v1/media/{id}media:read

Get a media item

Path Parameters

idstringMedia item ID

Request

cURL

curl "https://api.viraly.io/api/v1/media/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "id": "f6Zr1tM2",
    "role": "PostAttachment",
    "type": "Image",
    "status": "Ready",
    "tags": [],
    "socialSetId": "TrrdKTIr",
    "createdAt": "2026-04-01T08:15:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

DELETE/api/v1/media/{id}media:write

Delete a media item

Path Parameters

idstringMedia item ID

Request

cURL

curl -X DELETE "https://api.viraly.io/api/v1/media/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{}

GET/api/v1/media/collectionsmedia:read

List media collections

Query Parameters

social_set_idstring?Filter by social set

Request

cURL

curl "https://api.viraly.io/api/v1/media/collections" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "mc1234",
      "name": "Campaign Assets",
      "order": 0,
      "starred": false,
      "tags": [],
      "socialSetId": "TrrdKTIr",
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

Hashtags

Manage saved hashtag groups for quick reuse in posts.

Method	Endpoint	Description
GET	/hashtags	List hashtag groups
POST	/hashtags	Create a hashtag group
PUT	/hashtags/{id}	Update a hashtag group
DELETE	/hashtags/{id}	Delete a hashtag group

GET/api/v1/hashtagshashtags:read

List hashtag groups

Query Parameters

social_set_idstring?Filter by social set

Request

cURL

curl "https://api.viraly.io/api/v1/hashtags" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "g8As3uN4",
      "topic": "Product Launch",
      "hashtags": "#launch #newproduct #excited #startup"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

POST/api/v1/hashtagshashtags:write

Create a hashtag group

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/hashtags" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "Product Launch",
  "hashtags": "#launch #newproduct #excited",
  "socialSetId": "TrrdKTIr"
}'

Response

JSON

{
  "data": {
    "id": "h1Bs4uN5",
    "topic": "Product Launch",
    "hashtags": "#launch #newproduct #excited"
  },
  "meta": { "requestId": "req_abc123" }
}

PUT/api/v1/hashtags/{id}hashtags:write

Update a hashtag group

Path Parameters

idstringHashtag group ID

Request

cURL

curl -X PUT "https://api.viraly.io/api/v1/hashtags/{id}" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "topic": "Updated Topic",
  "hashtags": "#updated #hashtags"
}'

Response

JSON

{
  "data": {
    "id": "g8As3uN4",
    "topic": "Updated Topic",
    "hashtags": "#updated #hashtags"
  },
  "meta": { "requestId": "req_abc123" }
}

DELETE/api/v1/hashtags/{id}hashtags:write

Delete a hashtag group

Path Parameters

idstringHashtag group ID

Request

cURL

curl -X DELETE "https://api.viraly.io/api/v1/hashtags/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{}

Method	Endpoint	Description
GET	/categories	List categories
POST	/categories	Create a category
PUT	/categories/{id}	Update a category
DELETE	/categories/{id}	Delete a category

Ideas

Manage content idea boards and individual ideas for content planning.

Method	Endpoint	Description
GET	/idea-boards	List idea boards
POST	/ideas	Create an idea
GET	/idea-boards/{boardId}/ideas	List ideas in a board
PUT	/ideas/{id}	Update an idea
DELETE	/ideas/{id}	Delete an idea

GET/api/v1/idea-boardsideas:read

List idea boards

Query Parameters

social_set_idstring?Filter by social set

Request

cURL

curl "https://api.viraly.io/api/v1/idea-boards" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "i2Cu7wP8",
      "name": "Q2 Campaign Ideas",
      "description": "Ideas for Q2 product launch",
      "colorHex": "#10B981"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

POST/api/v1/ideasideas:write

Create an idea

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/ideas" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "boardId": "i2Cu7wP8",
  "title": "Behind-the-scenes video",
  "caption": "Show the team working on the new feature",
  "notes": "Film during standup on Thursday"
}'

Response

JSON

{
  "data": {
    "id": "j4Dv9xQ0",
    "title": "Behind-the-scenes video",
    "status": "Active",
    "boardId": "i2Cu7wP8",
    "createdAt": "2026-04-08T13:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

GET/api/v1/idea-boards/{boardId}/ideasideas:read

List ideas in a board

Path Parameters

boardIdstringIdea Board ID

Request

cURL

curl "https://api.viraly.io/api/v1/idea-boards/{boardId}/ideas" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "j4Dv9xQ0",
      "title": "Behind-the-scenes video",
      "caption": "Show the team working on the new feature",
      "status": "Draft",
      "displayOrder": 0,
      "boardId": "i2Cu7wP8",
      "createdAt": "2026-04-08T13:00:00Z"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

PUT/api/v1/ideas/{id}ideas:write

Update an idea

Path Parameters

idstringIdea ID

Request

cURL

curl -X PUT "https://api.viraly.io/api/v1/ideas/{id}" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Updated idea title",
  "caption": "Updated caption"
}'

Response

JSON

{
  "data": {
    "id": "j4Dv9xQ0",
    "title": "Updated idea title",
    "status": "Active"
  },
  "meta": { "requestId": "req_abc123" }
}

DELETE/api/v1/ideas/{id}ideas:write

Delete an idea

Path Parameters

idstringIdea ID

Request

cURL

curl -X DELETE "https://api.viraly.io/api/v1/ideas/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{}

Feeds

Manage RSS feed collections and individual feeds for content curation.

Method	Endpoint	Description
GET	/feed-collections	List feed collections
GET	/feeds	List feeds
POST	/feeds	Create a feed
DELETE	/feeds/{id}	Delete a feed

GET/api/v1/feed-collectionsfeeds:read

List feed collections

Query Parameters

socialSetIdstringSocial set ID

Request

cURL

curl "https://api.viraly.io/api/v1/feed-collections" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "fc1234",
      "name": "Industry News",
      "description": "Top industry RSS feeds",
      "displayOrder": 0,
      "socialSetId": "TrrdKTIr"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

GET/api/v1/feedsfeeds:read

List feeds

Query Parameters

socialSetIdstringSocial set ID

Request

cURL

curl "https://api.viraly.io/api/v1/feeds" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "fd5678",
      "name": "TechCrunch",
      "url": "https://techcrunch.com/feed/",
      "status": "Active",
      "socialSetId": "TrrdKTIr"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}

POST/api/v1/feedsfeeds:write

Create a feed

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/feeds" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "TechCrunch",
  "url": "https://techcrunch.com/feed/",
  "socialSetId": "TrrdKTIr"
}'

Response

JSON

{
  "data": {
    "id": "fd9012",
    "name": "TechCrunch",
    "url": "https://techcrunch.com/feed/",
    "status": "Active"
  },
  "meta": { "requestId": "req_abc123" }
}

DELETE/api/v1/feeds/{id}feeds:write

Delete a feed

Path Parameters

idstringFeed ID

Request

cURL

curl -X DELETE "https://api.viraly.io/api/v1/feeds/{id}" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{}

URL Shortener

Create shortened URLs with click tracking and analytics.

Method	Endpoint	Description
GET	/short-urls	List shortened URLs
POST	/short-urls	Create a shortened URL
GET	/short-urls/{shortCode}/clicks	Get click analytics for a shortened URL

GET/api/v1/short-urlsurl_shortener:read

List shortened URLs

Query Parameters

pageinteger?Page number

per_pageinteger?Items per page

Request

cURL

curl "https://api.viraly.io/api/v1/short-urls" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": 1234,
      "shortCode": "abc123",
      "originalUrl": "https://example.com/very-long-url",
      "shortUrl": "https://vly.to/abc123",
      "totalClicks": 847,
      "createdAt": "2026-03-01T10:00:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "pagination": { "page": 1, "perPage": 25, "total": 15, "totalPages": 1 }
  }
}

POST/api/v1/short-urlsurl_shortener:write

Create a shortened URL

Request

cURL

curl -X POST "https://api.viraly.io/api/v1/short-urls" \
  -H "Authorization: Bearer vly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/my-very-long-campaign-url?utm_source=social"
}'

Response

JSON

{
  "data": {
    "id": 1235,
    "shortCode": "def456",
    "originalUrl": "https://example.com/my-very-long-campaign-url?utm_source=social",
    "shortUrl": "https://vly.to/def456",
    "createdAt": "2026-04-08T14:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

GET/api/v1/short-urls/{shortCode}/clicksurl_shortener:read

Get click analytics for a shortened URL

Path Parameters

shortCodestringShort code of the URL

Request

cURL

curl "https://api.viraly.io/api/v1/short-urls/{shortCode}/clicks" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "totalClicks": 847,
    "clicks": [
      {
        "country": "United States",
        "city": "New York",
        "device": "Desktop",
        "os": "Windows",
        "createdAt": "2026-04-08T15:30:00Z"
      }
    ]
  },
  "meta": { "requestId": "req_abc123" }
}

Workspace

View workspace information, plan details, and team members.

Method	Endpoint	Description
GET	/workspace	Get workspace info
GET	/workspace/users	List workspace users

GET/api/v1/workspaceworkspace:read

Get workspace info

Request

cURL

curl "https://api.viraly.io/api/v1/workspace" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": {
    "id": "k6Ew1yR2",
    "name": "Acme Marketing",
    "plan": "Business",
    "status": "Active",
    "createdAt": "2025-06-01T00:00:00Z"
  },
  "meta": { "requestId": "req_abc123" }
}

GET/api/v1/workspace/usersworkspace:read

List workspace users

Request

cURL

curl "https://api.viraly.io/api/v1/workspace/users" \
  -H "Authorization: Bearer vly_your_api_key"

Response

JSON

{
  "data": [
    {
      "id": "l8Fx3zS4",
      "name": "John Smith",
      "email": "john@acme.com",
      "role": "Owner",
      "status": "Active",
      "createdAt": "2025-06-01T00:00:00Z"
    },
    {
      "id": "m0Gy5aT6",
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "role": "Member",
      "status": "Active",
      "createdAt": "2025-07-15T10:30:00Z"
    }
  ],
  "meta": { "requestId": "req_abc123" }
}