For developers and AI agents

The People Forever API

Create a complete forever profile in one request, or add to an existing one. Everything the edit page can do, the API can do: details, story, chapters, quick facts, questions, family, timeline, quotes, photos by URL, YouTube videos and social links.

Keys

Make a key under Settings → API keys and send it on every request:

Authorization: Bearer pf_…

Keys act as your account: profiles you create belong to you. 120 requests per minute. The machine-readable spec is at /api/v1/openapi.json.

Endpoints

• GET /api/v1/me: check the key.
• GET /api/v1/profiles?q=name: search first, so you don’t create a duplicate.
• POST /api/v1/profiles: create. Returns 201 with the profile, what was added, and any warnings (for example a photo that could not be fetched). Returns 409 with the existing profile if a public one with that name exists; send allowDuplicate: true for a genuine namesake.
• GET /api/v1/profiles/{slug}: read everything back.
• PATCH /api/v1/profiles/{slug}: update. Scalar fields replace; family, timeline, quotes, social links, photos and videos are appended (duplicates ignored); sections replace by key; facts and faqs replace wholesale.
• POST /api/v1/profiles/{slug}/photos: upload an image file (multipart, field file) when you have the bytes rather than a link. Photos in the JSON body can also carry base64 in data with a mimeType.
• DELETE /api/v1/profiles/{slug}: delete a profile you own.
• GET /api/v1/events?q=, POST /api/v1/events, GET/PATCH /api/v1/events/{slug}: disaster, accident and attack pages with news links and the people lost (creating and changing events needs an admin key). Attach a person to an event by sending events: ["event-slug"] when creating or updating their profile, or profiles: ["profile-slug"] on the event.

Example

curl -X POST https://peopleforever.com/api/v1/profiles \
  -H "Authorization: Bearer pf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Gloria", "lastName": "Steinem",
    "bornOn": "1934-03-25", "diedOn": "2026-09-02",
    "birthPlace": "Toledo, Ohio", "deathPlace": "Manhattan, New York City",
    "occupation": "Journalist, writer, organiser",
    "epitaph": "The journalist who gave a movement its words.",
    "story": "Gloria Steinem was…\n\nSecond paragraph…",
    "visibility": "PUBLIC", "isPublicFigure": true, "category": "Literature", "country": "US",
    "wikipediaUrl": "https://en.wikipedia.org/wiki/Gloria_Steinem",
    "facts": [{ "label": "Age at death", "value": "92" }, { "label": "Spouse", "value": "David Bale (2000–2003)" }],
    "family": [{ "relation": "Spouse", "name": "David Bale", "note": "married 2000, died 2003" }],
    "timeline": [{ "date": "1972-07", "title": "Ms. magazine launches" }],
    "quotes": [{ "text": "This is no simple reform. It really is a revolution.", "context": "Address to the Women of America, 1971" }],
    "sections": [{ "key": "death", "title": "Death", "body": "She died at home in Manhattan on 2 September 2026, aged 92.\n\nNo cause was given." }],
    "faqs": [{ "question": "How did Gloria Steinem die?", "answer": "She died at home in Manhattan on 2 September 2026, at 92. No cause of death has been made public." }],
    "photos": [{ "url": "https://upload.wikimedia.org/…/Gloria_Steinem.jpg", "credit": "Lynn Gilbert, CC BY-SA 4.0, via Wikimedia Commons", "portrait": true }],
    "videos": ["https://www.youtube.com/watch?v=…"],
    "posts": ["https://x.com/…/status/…", "https://www.instagram.com/p/…/"],
    "socialLinks": [{ "platform": "instagram", "url": "https://www.instagram.com/…/" }]
  }'

Writing a good profile

• Pets: send kind: "PET" with species and breed; they are listed on /pets and never treated as public figures.
• Answer what people search for. Chapters (sections) should cover early life, career, death, personal life, beliefs, controversies, legacy, books and awards. FAQs should be phrased the way people type them: “How did she die?”, “Was she married?”, “Did she have children?”.
• Only documented facts. Say “not made public” rather than guessing; anything after today’s date is written in the future tense.
• Photos can be given three ways: a direct URL, base64 in the JSON, or a multipart file upload. They need a free licence and a credit for public figures (Wikimedia Commons is ideal). The first photo becomes the portrait and cover unless you flag others.
• Videos are YouTube only. Individual X, Instagram, Facebook or TikTok posts go in posts (permalinks such as x.com/…/status/… or instagram.com/p/…) and render as embedded cards; socialLinks is for the person’s own accounts. Links inside text stay plain text.
• The same ground rules apply as on the site: abusive language is refused, and every page is subject to review.