Skip to content

Recapply API · v1

Make recap links from any tool

Send a first name and a few numbers, get back a private recap link. Use it from Zapier, Make, or your own code. No code needed for the first two.

Make a link: one request
curl -X POST http://localhost:3000/api/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"people":[{"name":"Noah","role":"Team lead","email":"noah@example.com","stats":{"commits":1627,"projects":21,"longest_streak":77,"top_percent":5}}]}'
Base address
http://localhost:3000/api/v1
Sign in with
Authorization: Bearer key
Format
JSON in, JSON out

Every endpoint

01What it does

The Recapply API makes private recap links. You send people (a first name and their numbers), and get back one link per person, in your company's brand. Then you send each link however you like: email, text, your app.

  • It works with Zapier and Make, so you can connect 6,000+ apps without code.
  • It only makes links. We keep each person's first name (scrambled) and simple counts (opened, shared, saved) so your People page works. We do not keep their numbers, email or phone, and the API can't list, read or change them later.
  • Your template, colors and words come from your saved brand. A request can pick a year or month recap, how long links stay open, the language, and (with style) how the links look. You can set your logo with /api/v1/logo and make recaps in its colors; photos stay in the dashboard.

02Your API key

A company admin makes keys in the dashboard under Developers. A key looks like rc_live_… and is shown once: copy it then. You can have up to 5 keys and revoke any of them at any time.

Send it on every request as a header:

Header
Authorization: Bearer YOUR_API_KEY

Keep keys on a server or in Zapier or Make. Never put one in a web page or app that people download: anyone with the key can make links for your company.

03Test your key

GET /api/v1/me says which company the key belongs to and its plan. Use it as the “test connection” step.

Request
curl http://localhost:3000/api/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
  "company": {
    "name": "Acme Fitness"
  },
  "plan": {
    "id": "starter",
    "name": "Starter",
    "status": "active",
    "monthlyRecaps": 10000
  },
  "planRequired": true,
  "key": {
    "name": "Zapier",
    "createdAt": "2026-10-23T09:00:00.000Z"
  }
}

04Your fields

GET /api/v1/template lists the numbers your recap expects: each one's header (the name to send), its label, whether it's a whole number or a decimal, and its allowed range. They follow your template on the Brand page, so check here after you change it.

Response (coding template)
{
  "template": "coding",
  "name": {
    "field": "name",
    "required": true,
    "max": 20
  },
  "stats": [
    {
      "header": "commits",
      "key": "commits",
      "label": "Commits",
      "type": "integer",
      "min": 0
    },
    {
      "header": "top_percent",
      "key": "pct",
      "label": "Top percent (1–100)",
      "type": "integer",
      "min": 1,
      "max": 100
    }
  ],
  "maxPeoplePerRequest": 500
}

06Change how links look

Links look like your saved brand. To change the look for one request, add a style object next to people. To change it for one person, put style inside that person: their own values win over the request's. Leave style out and nothing changes. Each value is checked and limited exactly like the Brand page, and only things that are safe to carry in a link are allowed (no logo, no photo, no image address). A wrong value is a 400 invalid_body for the request's style, or ok: false with the field named (like people[1].style.font) for one person.

FieldTypeWhat it does
colorwayinteger | stringA preset color set of your template: its index or its id (see colorways). Replaces your own brand colors for this link.
colorsobjectYour own two colors: { "main": "#2747e8", "accent": "#ffb81c" }. Use either colorway or colors.
fontstringFont style. One of: magazine, modern, playful.
coverstringCover layout. One of: classic, big, center.
texturestringPage texture. One of: none, grain, dots, lines.
roundbooleanRounded corners on bars, squares and the barcode.
outlinebooleanBig numbers drawn as outlines.
raritybooleanfalse makes plain cards with no rarity tier (no Common to Legendary badge, chart or foil). Default: your saved brand's setting.
footerstringA short line at the bottom of every inside page. Up to 32 characters.
barcodebooleanfalse hides the barcode on the covers.
stickerstringA sticker on the cover. One of: none, star, heart, bolt, sparkle, smile.
badgestringLetters in a round badge on the cover. Up to 3 characters.
animationstringHow pages turn in the story. One of: smooth, flip, zoom, stack, liquid, glitch, confetti.
headlinestringCover headline. Up to 60 characters.
signoffstringBack cover message. Up to 80 characters.
aboutstringA few lines about your company, small on the back cover. Up to 280 characters.
inkstringText color as #rrggbb, or "" for automatic. Kept readable: a color that would be hard to read is moved to the nearest shade that reads, and you get a warning.
paperstringPage color as #rrggbb, or "" for automatic. Same readability guard as ink.
backgroundobjectGenerated artwork behind the pages and the card: { "mode": "art", "seed": 0-9999, "palette": [2 to 5 #rrggbb colors] }, or { "mode": "off" }, or { "mode": "ai" } to use your saved AI art set (a different picture of it per person; needs AI art switched on and a set made on the Brand page; it never makes new pictures, so it costs nothing). Photos are dashboard-only; set a logo with POST /api/v1/logo.
personalLinestringOnly inside a person's own style. Your own line for that person, in place of the cover headline under their name. Links, @ and < > are removed. Up to 120 characters.
Request: modern font and your colors for everyone, Noah gets his own line, Mei a heart and no background
{
  "style": {
    "font": "modern",
    "cover": "big",
    "colors": {
      "main": "#2747e8",
      "accent": "#ffb81c"
    },
    "sticker": "star",
    "background": {
      "mode": "art",
      "seed": 7,
      "palette": [
        "#3b5bdb",
        "#c2255c"
      ]
    }
  },
  "people": [
    {
      "name": "Noah",
      "stats": {
        "commits": 1627,
        "projects": 21,
        "longest_streak": 77,
        "top_percent": 5
      },
      "style": {
        "personalLine": "Noah shipped more than anyone this year."
      }
    },
    {
      "name": "Mei",
      "stats": {
        "commits": 1627,
        "projects": 21,
        "longest_streak": 77,
        "top_percent": 5
      },
      "style": {
        "sticker": "heart",
        "background": {
          "mode": "off"
        }
      }
    }
  ]
}

Your own words per person. personalLine is your own sentence for that person (up to 120 characters). Write it in your system, or with your own AI, and send it here: we use it as you wrote it, and only remove links, @ and < >. It shows under their name and on their card, instead of the cover headline.

AI art set. A company that turns on AI art on its Brand page gets a small saved set of backgrounds made from its colors."background": { "mode": "ai" } gives each person one picture of that set (the same person always gets the same one). It only uses the saved set and never makes new pictures, so it costs nothing and never changes your bill. Without a saved set, or with AI art off, the link keeps your saved look.

Readable colors. If your ink (text) color would be hard to read on the page, it is drawn as the nearest shade that reads, and the person's warning says so.

GET /api/v1/style returns this list as data, your template's color sets (with the index and id to send as colorway), the limits and your current look, so you can build a picker.

Request
curl http://localhost:3000/api/v1/style \
  -H "Authorization: Bearer YOUR_API_KEY"

08Errors

Errors always look like { "error": { "code": "…", "message": "…" } }. Check the code; the message is written for people and may change.

400invalid_jsonThe body isn't valid JSON.
400invalid_bodyThe JSON isn't in either accepted shape, "people" is empty or over the limit, or "period", "month", "expiresInDays", "lang" or the request's "style" isn't valid (the field is named in details).
413body_too_largeA logo request is over 800 KB (or the file is over 512 KB). Use a smaller PNG, JPG or WebP.
422invalid_logoThe logo isn't a PNG, JPG or WebP, or it is bigger than 2000 x 2000 pixels. SVG is not accepted.
422logo_fetch_failedWe couldn't get the logo from your link (it must be a public https link to an image).
422unreadable_logoWe couldn't read that image.
422no_colorsWe couldn't find any colors in that image (empty or fully see-through).
503logos_offLogos aren't set up on this server, so a logo can't be saved. Preview still works.
401invalid_keyNo key, a mistyped key, or a revoked or expired key.
402plan_requiredYour company needs a plan to make links.
402limit_reachedThis batch would go over this month's recaps. The message says how many are left.
413body_too_largeThe body is over 256 KB. Send fewer people per request.
422invalid_peopleNobody in the request could get a link. Each person's reason is in "links".
429rate_limitedToo many requests. Wait the seconds in the Retry-After header.
503unavailableWe couldn't check the key just now. Try again shortly.

09Limits

  • 500 people per request, and a body up to 256 KB.
  • 60 requests a minute per key. After 20 wrong keys from one address, that address waits 10 minutes.
  • Your plan's monthly recaps apply. One link for one person is one recap.
  • 5 keys per company.
  • Logo requests: 12 a minute per company, a body up to 800 KB, and a logo file up to 512 KB.

10Logo recipe

Make a whole batch of recaps in your logo's colors, in three calls.

  1. Look at your logo first. This saves nothing. The reply has a style with your logo's main and accent colors and a matching background. It is color matching from the picture, not AI.
    Step 1: look at the logo
    curl http://localhost:3000/api/v1/logo/preview \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "url": "https://example.com/logo.png" }'
  2. Save it as your company logo, and keep its colors as your brand colors with applyLook. Leave applyLook out to keep your colors as they are. Use "applyLook": "full" instead to also put the logo on every page and use its shape as the background.
    Step 2: save the logo
    curl http://localhost:3000/api/v1/logo \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "url": "https://example.com/logo.png", "place": "both", "applyLook": true }'
  3. Make links with the style from step 1 (or leave style out to use your saved brand):
    Step 3: make links
    curl http://localhost:3000/api/v1/links \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "style": <the "style" from step 1>, "people": [ { "name": "Noah", "stats": { "commits": 1627 } } ] }'

Your logo can be a PNG, JPG or WebP up to 512 KB. To remove it later, send DELETE http://localhost:3000/api/v1/logo.

11Zapier recipe

For example: a new row in Google Sheets, or a new customer in Stripe, gets their recap link by email.

  1. In Zapier, make a Zap. Pick the trigger: where new people come from. For example Google Sheets → New Spreadsheet Row, Stripe → New Customer, or HubSpot → New Contact.
  2. Add an action: search for Webhooks by Zapier and choose the event POST.
  3. URL: http://localhost:3000/api/v1/links. Payload Type: Json (Form works too). Leave Wrap Request In Array on No.
  4. Data: add one row per field and map each to your trigger's value: name, commits, projects, longest_streak, top_percent. Optional: role (job or team) and email, which comes back with the link for your next step.
  5. Headers: key Authorization, value Bearer YOUR_API_KEY (your key from Developers in the dashboard).
  6. Test the step. You get back a url: that person's private recap link.
  7. Add one more action to send it, for example Gmail → Send Email or Twilio → Send SMS, and put the Url from the webhook step in the message.

Zapier's own guide: Send webhooks in Zap workflows.

12Make recipe

The same in Make, with the HTTP app.

  1. In Make, start a scenario with the app your people come from, for example Google Sheets → Watch New Rows or Shopify → Watch Orders.
  2. Add the HTTP app's Make a request module.
  3. URL: http://localhost:3000/api/v1/links. Method: POST.
  4. Headers: name Authorization, value Bearer YOUR_API_KEY.
  5. Body content type: application/json. Choose JSON string as the input method and paste this into the body, then swap each {{1.…}} for the matching value from your first module:
    Body to paste into Make
    { "people": [ { "name": "{{1.name}}", "email": "{{1.email}}", "stats": { "commits": "{{1.commits}}", "projects": "{{1.projects}}", "longest_streak": "{{1.longest_streak}}", "top_percent": "{{1.top_percent}}" } } ] }
  6. Turn on Parse response, run once, and use links[1].url (Make counts from 1) in your email or message module.

Make's own guide: HTTP app.

13Embed in your app

Put each person's recap inside your own app or site, so they see it without an email. Make the link with the API, then show it with one button.

  1. Make the person's link on your server with POST http://localhost:3000/api/v1/links, the same call as above. The reply has a url for each person. Keep it on your server and hand it to the page only for the person who is signed in.
  2. Add our script once (any page that shows the button), then add a button with that person's link. A tap opens their recap full screen on a phone, and as a card on a big screen.
    A button
    <button type="button" data-recapply-link="http://localhost:3000/r/PERSON_RECAP_LINK">See my year</button>
    <script src="http://localhost:3000/embed.js" async></script>
  3. Or open it from your own code, for example after your app fetches the link.
    From your code
    <script src="http://localhost:3000/embed.js" async></script>
    <script>
      // After you fetch the person's link from your server:
      document.getElementById("see-my-year").addEventListener("click", function () {
        window.Recapply.open("http://localhost:3000/r/PERSON_RECAP_LINK");
      });
      // Optional: run something when the person closes the recap.
      window.addEventListener("recapply:close", function () {});
    </script>
  4. Or put the recap in a box on your page. Use /embed/ and the token from the end of the link (the part after /r/). Only this address can be shown in a box on other sites.
    A box on your page
    <iframe
      src="http://localhost:3000/embed/PERSON_RECAP_LINK"
      title="Your year in review"
      allow="clipboard-write; web-share"
      referrerpolicy="no-referrer"
      style="width:100%;max-width:420px;height:720px;border:0;border-radius:16px"
    ></iframe>
  5. Optional: hear when it is ready or closed. The box sends two short messages with no names, numbers or links in them. The script above handles this for you.
    Listen to the box
    window.addEventListener("message", function (e) {
      if (e.origin !== "http://localhost:3000") return;
      if (e.data && e.data.type === "recapply:close") { /* hide your box */ }
      if (e.data && e.data.type === "recapply:ready") { /* the recap has loaded */ }
    });
  • The script only opens secure (https) recap links from localhost:3000. Any other address is ignored.
  • The person can close it with the Close button or the Esc key. The page behind stays put and does not scroll.
  • A link that was switched off or has run out shows a short "This recap isn't available" message.
  • No cookies. Opens, shares and saves still count on your People page.

14Privacy and security

  • We keep only a fingerprint (hash) of each key, never the key itself.
  • The people you send are turned into links. We keep only each first name (scrambled) and simple counts, not numbers, email or phone. We don't log request bodies or keys.
  • Each link carries that one person's name and numbers, signed so nobody can change them. Anyone with a link can open it, so send it only to that person.
  • Revoking a key stops it within about 30 seconds, usually at once.