API Referencev1

CelebrityPersona API

Everything you need to query celebrities, outfits, news, movies, and reviews programmatically. All endpoints are GET-only and require an API key.

Get your API key API support

Introduction

The CelebrityPersona API v1 provides programmatic access to our full database of celebrity profiles, fashion outfits, news articles, upcoming movies, and movie reviews.

All endpoints are read-only (GET). Authentication is done with a personal API key passed in the x-api-key request header. You can generate your key from the dashboard → API Access section.

Current version

Protocol

HTTPS only

Response format

JSON

Authentication

How it works

Every request must include your API key in the x-api-key HTTP header. There is no OAuth or session-based authentication — just your key on every call.

Required header

x-api-key: cp_live_your_api_key_here

Getting your API key

1Log in to your CelebrityPersona account.
2Go to Dashboard → API Access.
3Click "Generate API Key" — your key is shown once immediately.
4To view the key again later, click "Reveal" and enter your account password.

Keep your key secret. Never expose it in client-side JavaScript, public repositories, or browser console logs. If your key is compromised, revoke it from the dashboard and generate a new one.

Missing or invalid key response

401 Unauthorized

{
  "success": false,
  "error": "INVALID_API_KEY",
  "message": "The provided API key is invalid or has been revoked."
}

Base URL

All API endpoints are relative to the following base URL:

bash

https://celebritypersona.com

A full endpoint URL is formed by appending the path to the base. For example:

bash

https://celebritypersona.com/api/v1/celebrities?page=1&limit=20

All requests must be made over HTTPS. HTTP requests will be redirected or rejected.

Pagination

All list endpoints return paginated results. Use the page and limit query parameters to navigate through results.

page

Page to retrieve (starts at 1)

Default: 1

limit

Items per page (max: 50)

Default: 20

Pagination object in response

pagination field

"pagination": {
  "page": 2,       // current page
  "limit": 20,     // items per page
  "total": 248,    // total items in database
  "pages": 13      // total pages available
}

Example — fetching page 3

bash

curl "https://celebritypersona.com/api/v1/celebrities?page=3&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

Error Handling

All error responses follow a consistent JSON structure with a success: false flag and a human-readable message.

Error response shape

{
  "success": false,
  "error": "QUOTA_EXCEEDED",          // machine-readable error code
  "message": "Monthly quota of 100 requests exceeded.",
  "quota": {                          // only present on 429 errors
    "used": 100,
    "total": 100,
    "resetsOn": "2026-03-01T00:00:00.000Z"
  }
}

CodeStatusMeaning

200OKRequest succeeded. Response body contains the requested data.

401UnauthorizedAPI key is missing, invalid, or has been revoked. Check your x-api-key header.

404Not FoundThe requested resource (celebrity, outfit, etc.) does not exist.

429Too Many RequestsMonthly quota exceeded. Upgrade your plan or wait for the quota to reset.

500Internal Server ErrorAn unexpected server error occurred. Contact support if the issue persists.

Rate Limits

API usage is measured in monthly requests. Each successful API call counts as one request. Quota resets on the 1st of every month at 00:00 UTC.

PlanRequests / monthPriceAccess

FreeRequests:100Price:FreeAll endpoints

StarterRequests:1,000Price:Contact usAll endpoints

ProRequests:10,000Price:Contact usAll endpoints

EnterpriseRequests:UnlimitedPrice:Contact usAll endpoints + priority support

To upgrade your plan, email info@celebritypersona.com with your registered email and the plan you want. Upgrades are applied same day.

Quota exceeded response (429)

429 Too Many Requests

{
  "success": false,
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly quota of 100 requests exceeded. Upgrade your plan to continue.",
  "quota": {
    "used": 100,
    "total": 100,
    "resetsOn": "2026-03-01T00:00:00.000Z"
  }
}

Celebrities

Retrieve celebrity profiles including their biography, physical attributes, filmography, social media, and more.

GET/api/v1/celebrities

GET/api/v1/celebrities/{slug}

GET/api/v1/celebritiesList celebrities

Query Parameters

ParameterTypeRequiredDescription

ParampageTypeintegerRequirednoDescriptionPage number for pagination.Default: 1

ParamlimitTypeintegerRequirednoDescriptionNumber of results per page. Maximum: 50.Default: 20

ParamsearchTypestringRequirednoDescriptionSearch celebrities by name (case-insensitive).

ParamoccupationTypestringRequirednoDescriptionFilter by occupation (e.g. Actor, Singer).

ParamnationalityTypestringRequirednoDescriptionFilter by nationality (e.g. American, British).

ParamsortTypestringRequirednoDescriptionSort order.Default: latestValues: latest · oldest · name_asc · name_desc

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/celebrities?page=1&limit=10&sort=latest" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/celebrities?page=1&limit=10&sort=latest',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data, pagination } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "celebrities",
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 248,
    "pages": 25
  },
  "data": [
    {
      "_id": "64f3a1b2c8d9e0f1a2b3c4d5",
      "name": "Ryan Gosling",
      "slug": "ryan-gosling",
      "profileImage": "https://cdn.example.com/ryan-gosling.jpg",
      "occupation": ["Actor", "Director"],
      "nationality": "Canadian",
      "netWorth": "$70 million",
      "born": "1980-11-12",
      "age": 45,
      "isVerified": true,
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

GET/api/v1/celebrities/{slug}Get celebrity by slug

Path Parameters

ParameterTypePathDescription

ParamslugTypestringPathrequiredDescriptionThe URL-safe slug of the celebrity (e.g. ryan-gosling).

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/celebrities/ryan-gosling" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/celebrities/ryan-gosling',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "celebrities",
  "data": {
    "_id": "64f3a1b2c8d9e0f1a2b3c4d5",
    "name": "Ryan Gosling",
    "slug": "ryan-gosling",
    "born": "1980-11-12",
    "birthPlace": "London, Ontario, Canada",
    "age": 45,
    "nationality": "Canadian",
    "occupation": ["Actor", "Director"],
    "height": "6 ft 0 in",
    "netWorth": "$70 million",
    "introduction": "Ryan Thomas Gosling is a Canadian actor...",
    "career": "Gosling began his career as a child actor...",
    "socialMedia": {
      "instagram": "https://instagram.com/ryangosling"
    },
    "profileImage": "https://cdn.example.com/ryan-gosling.jpg",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Outfits

Browse celebrity outfit collections including designer details, purchase links, event context, and brand information.

GET/api/v1/outfits

GET/api/v1/outfits/{slug}

GET/api/v1/outfitsList outfits

Query Parameters

ParameterTypeRequiredDescription

ParampageTypeintegerRequirednoDescriptionPage number for pagination.Default: 1

ParamlimitTypeintegerRequirednoDescriptionNumber of results per page. Maximum: 50.Default: 20

ParamsearchTypestringRequirednoDescriptionSearch outfits by title.

ParamcelebrityTypestringRequirednoDescriptionFilter by celebrity slug (e.g. ryan-gosling).

ParamcategoryTypestringRequirednoDescriptionFilter by outfit category (e.g. Casual, Formal).

ParambrandTypestringRequirednoDescriptionFilter by brand name.

ParamsortTypestringRequirednoDescriptionSort order.Default: latestValues: latest · oldest · popular · title_asc

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/outfits?celebrity=ryan-gosling&limit=5" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/outfits?celebrity=ryan-gosling&limit=5',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data, pagination } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "outfits",
  "pagination": { "page": 1, "limit": 5, "total": 38, "pages": 8 },
  "data": [
    {
      "_id": "65a4b2c3d4e5f6a7b8c9d0e1",
      "title": "Met Gala 2024 Look",
      "slug": "ryan-gosling-met-gala-2024",
      "celebrity": {
        "name": "Ryan Gosling",
        "slug": "ryan-gosling",
        "profileImage": "https://cdn.example.com/ryan-gosling.jpg"
      },
      "images": ["https://cdn.example.com/outfit1.jpg"],
      "event": "Met Gala 2024",
      "designer": "Gucci",
      "brand": "Gucci",
      "category": "Formal",
      "color": "Black",
      "price": "$4,500",
      "purchaseLink": "https://gucci.com/...",
      "tags": ["Met Gala", "Gucci", "Tuxedo"],
      "likesCount": 1240,
      "isFeatured": true,
      "createdAt": "2024-05-07T12:00:00.000Z"
    }
  ]
}

GET/api/v1/outfits/{slug}Get outfit by slug

Path Parameters

ParameterTypePathDescription

ParamslugTypestringPathrequiredDescriptionThe URL-safe slug of the outfit.

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/outfits/ryan-gosling-met-gala-2024" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/outfits/ryan-gosling-met-gala-2024',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "outfits",
  "data": {
    "_id": "65a4b2c3d4e5f6a7b8c9d0e1",
    "title": "Met Gala 2024 Look",
    "slug": "ryan-gosling-met-gala-2024",
    "celebrity": {
      "name": "Ryan Gosling",
      "slug": "ryan-gosling",
      "nationality": "Canadian"
    },
    "images": ["https://cdn.example.com/outfit1.jpg"],
    "event": "Met Gala 2024",
    "designer": "Gucci",
    "description": "A stunning black tuxedo with gold lapels...",
    "tags": ["Met Gala", "Gucci", "Tuxedo"],
    "purchaseLink": "https://gucci.com/...",
    "price": "$4,500",
    "brand": "Gucci",
    "category": "Formal",
    "likesCount": 1240,
    "createdAt": "2024-05-07T12:00:00.000Z"
  }
}

News

Access celebrity news articles including full content, category, author, associated celebrity, and publication metadata.

GET/api/v1/news

GET/api/v1/news/{slug}

GET/api/v1/newsList news articles

Query Parameters

ParameterTypeRequiredDescription

ParampageTypeintegerRequirednoDescriptionPage number for pagination.Default: 1

ParamlimitTypeintegerRequirednoDescriptionNumber of results per page. Maximum: 50.Default: 20

ParamsearchTypestringRequirednoDescriptionSearch articles by title.

ParamcategoryTypestringRequirednoDescriptionFilter by news category (e.g. Fashion, Movies).

ParamcelebrityTypestringRequirednoDescriptionFilter by celebrity slug.

ParamfeaturedTypebooleanRequirednoDescriptionReturn only featured articles.Values: true · false

ParamsortTypestringRequirednoDescriptionSort order.Default: latestValues: latest · oldest · popular

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/news?category=Fashion&limit=5" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/news?category=Fashion&limit=5&sort=latest',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data, pagination } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "news",
  "pagination": { "page": 1, "limit": 5, "total": 194, "pages": 39 },
  "data": [
    {
      "_id": "66b5c3d4e5f6a7b8c9d0e1f2",
      "title": "Ryan Gosling's Barbie Press Tour Outfits Ranked",
      "slug": "ryan-gosling-barbie-press-tour-outfits-ranked",
      "excerpt": "From pink suits to classic tuxedos, every look rated.",
      "thumbnail": "https://cdn.example.com/news1.jpg",
      "author": "Emma Wilson",
      "category": "Fashion",
      "tags": ["Barbie", "Fashion", "Press Tour"],
      "publishDate": "2024-07-22T08:00:00.000Z",
      "featured": true,
      "celebrity": {
        "name": "Ryan Gosling",
        "slug": "ryan-gosling"
      },
      "createdAt": "2024-07-22T08:00:00.000Z"
    }
  ]
}

GET/api/v1/news/{slug}Get news article by slug

Path Parameters

ParameterTypePathDescription

ParamslugTypestringPathrequiredDescriptionThe URL-safe slug of the news article.

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/news/ryan-gosling-barbie-press-tour-outfits-ranked" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/news/ryan-gosling-barbie-press-tour-outfits-ranked',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "news",
  "data": {
    "_id": "66b5c3d4e5f6a7b8c9d0e1f2",
    "title": "Ryan Gosling's Barbie Press Tour Outfits Ranked",
    "slug": "ryan-gosling-barbie-press-tour-outfits-ranked",
    "content": "<p>The Barbie press tour gave us some of the most...</p>",
    "excerpt": "From pink suits to classic tuxedos, every look rated.",
    "thumbnail": "https://cdn.example.com/news1.jpg",
    "author": "Emma Wilson",
    "category": "Fashion",
    "tags": ["Barbie", "Fashion", "Press Tour"],
    "publishDate": "2024-07-22T08:00:00.000Z",
    "featured": true,
    "celebrity": {
      "name": "Ryan Gosling",
      "slug": "ryan-gosling",
      "nationality": "Canadian"
    }
  }
}

Movies

Retrieve upcoming and released movie data including cast, synopsis, trailer, ticket links, box office projections, and release dates.

GET/api/v1/movies

GET/api/v1/movies/{slug}

GET/api/v1/moviesList movies

Query Parameters

ParameterTypeRequiredDescription

ParampageTypeintegerRequirednoDescriptionPage number for pagination.Default: 1

ParamlimitTypeintegerRequirednoDescriptionNumber of results per page. Maximum: 50.Default: 20

ParamsearchTypestringRequirednoDescriptionSearch movies by title.

ParamgenreTypestringRequirednoDescriptionFilter by genre (e.g. Action, Drama, Comedy).

ParamstatusTypestringRequirednoDescriptionFilter by movie status.Values: upcoming · released · in-production

ParamfeaturedTypebooleanRequirednoDescriptionReturn only featured movies.Values: true · false

ParamsortTypestringRequirednoDescriptionSort order.Default: latestValues: latest · oldest · release_asc · release_desc · title_asc

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/movies?genre=Action&status=upcoming" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/movies?genre=Action&status=upcoming&limit=10',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data, pagination } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "movies",
  "pagination": { "page": 1, "limit": 10, "total": 56, "pages": 6 },
  "data": [
    {
      "_id": "67c6d4e5f6a7b8c9d0e1f2g3",
      "title": "The Gray Man 2",
      "slug": "the-gray-man-2",
      "releaseDate": "2025-07-04T00:00:00.000Z",
      "poster": "https://cdn.example.com/gray-man-2.jpg",
      "genre": ["Action", "Thriller"],
      "director": "Anthony Russo",
      "status": "upcoming",
      "synopsis": "Court Gentry returns for another globe-trotting mission...",
      "anticipationScore": 87,
      "language": ["English"],
      "featured": true,
      "createdAt": "2024-09-01T00:00:00.000Z"
    }
  ]
}

GET/api/v1/movies/{slug}Get movie by slug

Path Parameters

ParameterTypePathDescription

ParamslugTypestringPathrequiredDescriptionThe URL-safe slug of the movie.

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/movies/the-gray-man-2" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/movies/the-gray-man-2',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "movies",
  "data": {
    "_id": "67c6d4e5f6a7b8c9d0e1f2g3",
    "title": "The Gray Man 2",
    "slug": "the-gray-man-2",
    "releaseDate": "2025-07-04T00:00:00.000Z",
    "poster": "https://cdn.example.com/gray-man-2.jpg",
    "backdrop": "https://cdn.example.com/gray-man-2-backdrop.jpg",
    "genre": ["Action", "Thriller"],
    "director": "Anthony Russo",
    "writers": ["Joe Russo", "Christopher Markus"],
    "cast": [
      { "name": "Ryan Gosling", "character": "Court Gentry", "role": "Lead" }
    ],
    "synopsis": "Court Gentry returns...",
    "trailer": "https://youtube.com/watch?v=...",
    "ticketLinks": [
      { "platform": "Fandango", "url": "https://fandango.com/...", "available": true }
    ],
    "budget": 200000000,
    "anticipationScore": 87,
    "duration": 122,
    "mpaaRating": "PG-13",
    "status": "upcoming"
  }
}

Reviews

Access movie reviews and ratings including critic scores, audience scores, pros and cons, verdicts, and aggregated IMDb/Rotten Tomatoes data.

GET/api/v1/reviews

GET/api/v1/reviews/{slug}

GET/api/v1/reviewsList reviews

Query Parameters

ParameterTypeRequiredDescription

ParampageTypeintegerRequirednoDescriptionPage number for pagination.Default: 1

ParamlimitTypeintegerRequirednoDescriptionNumber of results per page. Maximum: 50.Default: 20

ParamsearchTypestringRequirednoDescriptionSearch reviews by movie title.

ParamminRatingTypefloatRequirednoDescriptionMinimum rating filter (0–10).Default: 0

ParammaxRatingTypefloatRequirednoDescriptionMaximum rating filter (0–10).Default: 10

ParamfeaturedTypebooleanRequirednoDescriptionReturn only featured reviews.Values: true · false

ParamsortTypestringRequirednoDescriptionSort order.Default: latestValues: latest · oldest · rating_high · rating_low

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/reviews?minRating=8&sort=rating_high&limit=5" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/reviews?minRating=8&sort=rating_high&limit=5',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data, pagination } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "reviews",
  "pagination": { "page": 1, "limit": 5, "total": 72, "pages": 15 },
  "data": [
    {
      "_id": "68d7e5f6a7b8c9d0e1f2g3h4",
      "title": "Barbie (2023) Review",
      "slug": "barbie-2023-review",
      "movieTitle": "Barbie",
      "poster": "https://cdn.example.com/barbie.jpg",
      "rating": 9.1,
      "excerpt": "A visually stunning and surprisingly profound film...",
      "author": { "name": "James Porter", "credentials": "Senior Film Critic" },
      "publishDate": "2023-07-21T00:00:00.000Z",
      "featured": true,
      "scores": {
        "criticsScore": 88,
        "audienceScore": 83,
        "imdbRating": 6.9,
        "rottenTomatoesScore": 88
      },
      "verdict": "A must-watch cinematic experience.",
      "stats": { "views": 15420, "likes": 3240 }
    }
  ]
}

GET/api/v1/reviews/{slug}Get review by slug

Path Parameters

ParameterTypePathDescription

ParamslugTypestringPathrequiredDescriptionThe URL-safe slug of the review.

Required header: x-api-key: YOUR_API_KEY

Request Examples

cURL

curl -X GET "https://celebritypersona.com/api/v1/reviews/barbie-2023-review" \
  -H "x-api-key: YOUR_API_KEY"

JavaScript (fetch)

const res = await fetch(
  'https://celebritypersona.com/api/v1/reviews/barbie-2023-review',
  { headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data } = await res.json();

Example Response

200 OK

{
  "success": true,
  "version": "v1",
  "resource": "reviews",
  "data": {
    "_id": "68d7e5f6a7b8c9d0e1f2g3h4",
    "title": "Barbie (2023) Review",
    "slug": "barbie-2023-review",
    "movieTitle": "Barbie",
    "poster": "https://cdn.example.com/barbie.jpg",
    "rating": 9.1,
    "content": "<p>Greta Gerwig's Barbie is a genre-defying film...</p>",
    "excerpt": "A visually stunning and surprisingly profound film.",
    "author": {
      "name": "James Porter",
      "bio": "Senior film critic with 12 years experience.",
      "credentials": "Senior Film Critic"
    },
    "movieDetails": {
      "releaseYear": 2023,
      "director": "Greta Gerwig",
      "genre": ["Comedy", "Fantasy"],
      "runtime": 114
    },
    "scores": {
      "criticsScore": 88,
      "audienceScore": 83,
      "imdbRating": 6.9,
      "rottenTomatoesScore": 88
    },
    "pros": ["Visually inventive", "Sharp screenplay", "Excellent performances"],
    "cons": ["Slightly uneven second act"],
    "verdict": "A must-watch cinematic experience.",
    "publishDate": "2023-07-21T00:00:00.000Z",
    "stats": { "views": 15420, "likes": 3240 }
  }
}

Changelog

v1.0.0Current25 Feb 2026

Initial release of CelebrityPersona Public API.
Endpoints: celebrities, outfits, news, movies, reviews.
API key management: generate, reveal (with password), revoke.
Usage tracking: monthly quota, daily hit counters.
Free tier: 100 requests / month.