Developers · romance

Getting a key

Go to Dashboard → Settings → Developers and ask for a key. Say what you’re building. Your key shows once, so copy it right away. It starts working when staff approve it, and you get a notification when that happens.

You can have 2 keys at once. Treat a key like a password: keep it on your server, never in a website’s code or a public repo. If one leaks, delete it and ask for a new one.

Sending it

Send the key in the Authorization header. x-api-key works too.

const r = await fetch('https://romance.rip/api/v1/users/zai', {
  headers: { authorization: `Bearer ${process.env.ROMANCE_KEY}` },
});
const { user } = await r.json();

Get a page

GET https://romance.rip/api/v1/users/:name

Use a username, an alias, or a UID like 2 or %232 (that’s #2 in a link).

{
  "user": {
    "uid": 2,
    "username": "zai",
    "displayName": "zai",
    "url": "https://romance.rip/zai",
    "bio": ["romance isn't dead."],
    "avatar": "https://romance.rip/u/....webp",
    "banner": null,
    "card": "https://romance.rip/api/card/zai",
    "accent": "#fa6188",
    "note": "in class rn",
    "badges": [{ "id": "owner", "label": "Owner", "color": "#fa6188" }],
    "links": [{ "title": "tiktok", "url": "https://tiktok.com/@...", "platform": "tiktok" }],
    "views": 3100,
    "hearts": 42,
    "joined": "2026-10-20T18:02:11.000Z",
    "location": null,
    "discord": { "id": "123456789012345678" }
  }
}

Anything the person hides on their page comes back as null or empty: views, hearts, location, badges, Discord. Links are the public ones on their page.

Search

GET https://romance.rip/api/v1/search?q=za

At least 2 letters. Matches the start of usernames and anywhere in display names. Up to 10 results, best match first.

{
  "results": [
    { "uid": 2, "username": "zai", "displayName": "zai", "avatar": "https://...", "url": "https://romance.rip/zai" }
  ]
}

Share card

Every page has a ready-made picture at https://romance.rip/api/card/:name, 1200 by 630. It’s public and needs no key, so it’s the easiest way to make a nice embed. It’s in the card field, and it’s null if the person switched it off.

Limits

Per minute60 requests per key.

Per day5000 requests per key, reset at midnight UTC.

FreshnessAnswers can be up to a minute old. Cache on your side too.

ErrorsErrors come back as { "error": "..." } with 400, 401, 404 or 429.

Rules

Only show what you get back. Don’t store pages in bulk or build copies of romance.
Don’t call your bot or site official, and don’t use the romance logo as your own.
People can switch apps off for their page. When a page goes away, stop showing it.
Staff can switch any key off. Breaking these rules gets it switched off.

Help

Ask in a ticket in the Discord. Ideas for new endpoints are welcome too. The rest of the docs are at romance.rip/docs.

Build on romance.