API reference

Apps

Create, list, update, and delete the mobile apps you market with ViralSlides.

1 min readLast updated May 17, 2026 Edit this page

An App is the unit of marketing — niche, language, brand colors, and screenshots that drive every generation. CRUD endpoints below are scoped to your organization.

GET/v0/api/v1/appsAPI key or session

List apps in your organization, paginated.

Parameters

Name	In	Type	Description
page	query	integer	1-indexed page (default 1).
limit	query	integer	Items per page, max 100 (default 50).
status	query	string	Filter by status: ACTIVE or ARCHIVED.

Response

json

{
  "success": true,
  "data": [
    {
      "_id": "app_01HQ...",
      "organization_id": "org_01HQ...",
      "name": "Meditate Daily",
      "slug": "meditate-daily",
      "niche": "meditation",
      "language": "en",
      "status": "ACTIVE",
      "brand_primary_color": "#059669",
      "ios_url": "https://apps.apple.com/app/id...",
      "android_url": "https://play.google.com/store/apps/details?id=...",
      "screenshots": ["https://cdn.../screenshot-1.png"],
      "createdAt": "2026-05-01T10:00:00.000Z",
      "updatedAt": "2026-05-15T18:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1
}

cURL

Terminalbash

curl https://api.viralslides.app/v0/api/v1/apps \
  -H "Authorization: Bearer vs_live_..."

TypeScript / JS

Node.jstypescript

const res = await fetch("https://api.viralslides.app/v0/api/v1/apps", {
  headers: { Authorization: `Bearer ${process.env.VIRALSLIDES_API_KEY}` },
})
const json = await res.json()
console.log(json.data)

GET/v0/api/v1/apps/:idAPI key or session

Fetch a single app by id.

Parameters

Name	In	Type	Description
id*	path	string	App id, e.g. app_01HQ...

Response

json

{
  "success": true,
  "body": {
    "_id": "app_01HQ...",
    "name": "Meditate Daily",
    "slug": "meditate-daily",
    "niche": "meditation",
    "language": "en",
    "status": "ACTIVE"
  }
}

Errors

Status	Code	Description
404	APP_NOT_FOUND	No app with that id in your organization.

POST/v0/api/v1/appsAPI key or session

Create a new app. Subject to per-plan apps quota.

Parameters

Name	In	Type	Description
name*	body	string	2–80 chars.
niche	body	string	2–40 chars (e.g. "meditation").
language	body	string	ISO code, 2–8 chars (default "en").
target_audience	body	string	Free text, max 400 chars.
description	body	string	Long-form description, max 4000 chars.
ios_url	body	string	App Store URL.
android_url	body	string	Play Store URL.
website_url	body	string	Marketing site URL.
brand_primary_color	body	string	Hex, e.g. #059669.
brand_secondary_color	body	string	Hex.
brand_accent_color	body	string	Hex.
screenshots	body	string[]	URLs (use /uploads/screenshot first). Max 12.
value_props	body	string[]	Up to 12 short value props.
pain_points	body	string[]	Up to 12 pain points.
differentiators	body	string[]	Up to 12 differentiators.

Request

Request bodyjson

{
  "name": "Meditate Daily",
  "niche": "meditation",
  "language": "en",
  "brand_primary_color": "#059669",
  "ios_url": "https://apps.apple.com/app/id123",
  "screenshots": [
    "https://cdn.viralslides.app/.../shot-1.png",
    "https://cdn.viralslides.app/.../shot-2.png"
  ]
}

Response

json

{
  "success": true,
  "body": {
    "_id": "app_01HQ...",
    "slug": "meditate-daily",
    "name": "Meditate Daily",
    "status": "ACTIVE",
    "createdAt": "2026-05-17T12:00:00.000Z"
  }
}

cURL

Terminalbash

curl -X POST https://api.viralslides.app/v0/api/v1/apps \
  -H "Authorization: Bearer vs_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meditate Daily",
    "niche": "meditation",
    "language": "en"
  }'

TypeScript / JS

Node.jstypescript

const res = await fetch("https://api.viralslides.app/v0/api/v1/apps", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VIRALSLIDES_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Meditate Daily",
    niche: "meditation",
    language: "en",
  }),
})
const { body: app } = await res.json()

Errors

Status	Code	Description
400	VALIDATION_ERROR	One or more fields failed validation.
402	QUOTA_EXCEEDED	You've hit your plan's apps limit.
409	SLUG_EXISTS	Another app with the auto-generated slug already exists. Pass a unique slug.

PUT/v0/api/v1/apps/:idAPI key or session

Update an app. All fields optional — only the keys you send are touched.

Parameters

Name	In	Type	Description
id*	path	string	App id.
name	body	string	2–80 chars.
niche	body	string	2–40 chars.
language	body	string	ISO code.
status	body	string	ACTIVE or ARCHIVED.

Response

json

{ "success": true, "body": { "_id": "app_01HQ...", "name": "Meditate Daily v2", "status": "ACTIVE" } }

Errors

Status	Code	Description
400	VALIDATION_ERROR	Field validation failed.
404	APP_NOT_FOUND	App not in your organization.

DELETE/v0/api/v1/apps/:idAPI key or session

Delete an app. Cascades to slideshows and assets owned by it.

Parameters

Name	In	Type	Description
id*	path	string	App id.

Response

json

{ "success": true }

Errors

Status	Code	Description
404	APP_NOT_FOUND	App not in your organization.