API
Use RetainerProof from a script or an agent
The API writes to the account that owns the key. It creates and updates sites, reads status, publishes the public status page, adds the same work-log entries the dashboard form does, and posts release notes for a care site or an app. A check uses the same Run check now path.
I keep the step-by-step pages separate from this reference. Release notes covers the dashboard, curl, GitHub Actions, GitLab CI, and an n8n or Zapier step. Add a site from a script covers creating a site, turning the status page on, and adding a status path, including the n8n step when a CRM adds a client. Both are listed on Docs.
Auth
Create a named key under Brand settings → API keys. The full key is shown once. RetainerProof stores only a SHA-256 hash. Send it on every request:
Authorization: Bearer rp_live_…
Keys look like rp_live_ plus a random secret. An account can keep 10 active keys. Revoke a key and it stops working. A key cannot read or write another account. Calls need an active subscription, same as the app. The limit is 60 requests a minute per key.
Base URL: https://retainerproof.com/api/v1. JSON in and out. Machine-readable spec: /api/v1/openapi.json.
Errors
401missing, invalid, or revoked key.403the account has no active subscription.404that site or entry is not on this account.409the plan site limit, the app pack limit, or the extra-check cap is already reached. Nothing new is created.422the body failed the same checks as the form.429over 60 requests in a minute.Retry-Afteris in seconds.
GET /api/v1/sites
Each care site: id, name, url, cadence, uptimeIntervalSeconds, statusEnabled, statusPageUrl (null while the status page is off), and status with state, summary, and checkedAt. The list does not include the secret digest URL. Apps and proof packs are omitted.
curl -s https://retainerproof.com/api/v1/sites \
-H "Authorization: Bearer rp_live_…"
GET /api/v1/sites/:id
Status for one site: uptime percent for the current period, TLS and domain expiry, last check time, cadence, statusPageUrl when the page is on, and the secret client digest URL.
curl -s https://retainerproof.com/api/v1/sites/SITE_ID \
-H "Authorization: Bearer rp_live_…"
POST /api/v1/sites
Add a monitored site. name is required (max 80 characters). url is an http(s) address. cadence is optional: daily, twice_daily, weekly, or monthly. Omitted cadence uses the account default. uptimeIntervalSeconds is optional and sets the live check: 30, 60, 120, 300, 900, 1800, or 3600. The default is 900 (15 minutes). Any other value returns 422. The response is site with id, digestUrl, and statusPageUrl (null until the status page is on). A new site does not start a check.
Starter allows 5 sites, Studio 25, Agency 100. Apps and proof packs do not use a site slot. At the limit the response is 409 with error set to site_limit. Existing sites stay.
curl -s -X POST https://retainerproof.com/api/v1/sites \
-H "Authorization: Bearer rp_live_…" \
-H "Content-Type: application/json" \
-d '{"name":"Harbor","url":"https://harbor.example","cadence":"weekly","uptimeIntervalSeconds":60}'
PATCH /api/v1/sites/:id
Change name, url, cadence, uptimeIntervalSeconds, or statusEnabled. Send only the fields you want to change. statusEnabled: true turns on the public status page and creates a token the same way the dashboard does. Turning it off keeps the token and returns statusPageUrl: null, so the link stops opening. Turning it on again uses the same link.
curl -s -X PATCH https://retainerproof.com/api/v1/sites/SITE_ID \
-H "Authorization: Bearer rp_live_…" \
-H "Content-Type: application/json" \
-d '{"statusEnabled":true}'
DELETE /api/v1/sites/:id
Deletes one care site on the account that owns the key, plus its work log, checks, extra paths, sample URLs, and public status link. The key cannot delete another account. An app id or a proof-pack id is not deleted here. Both cases return 404 and leave every row in place. 204 means that site is gone. Call DELETE only when you mean to remove that site.
curl -s -X DELETE https://retainerproof.com/api/v1/sites/SITE_ID \
-H "Authorization: Bearer rp_live_…"
Status paths
GET and POST /api/v1/sites/:id/targets. PATCH and DELETE /api/v1/sites/:id/targets/:targetId. These are the extra checks on the digest and the public status page. label is required (max 60). url is a path such as /api/health or an http(s) URL. expected is 2xx, 3xx, any, or an HTTP status code. intervalMode is uptime or site. A site allows 12 extra checks. The 13th returns 409 with error target_limit. A duplicate URL returns 422. PATCH keeps any field you omit.
curl -s -X POST https://retainerproof.com/api/v1/sites/SITE_ID/targets \
-H "Authorization: Bearer rp_live_…" \
-H "Content-Type: application/json" \
-d '{"label":"Health","url":"/api/health","expected":"200"}'
POST /api/v1/apps
Add an app status page. An app does not use a site slot and does not send a care digest. name is required. url is optional. The response is app with id and statusPageUrl. Apps start with the status page on. Studio includes 1 app pack. Agency includes 3. Extra packs add more. With no pack left the response is 409 with error app_limit.
curl -s -X POST https://retainerproof.com/api/v1/apps \
-H "Authorization: Bearer rp_live_…" \
-H "Content-Type: application/json" \
-d '{"name":"Billing API","url":"https://api.harbor.example"}'
Zapier and n8n
Use an HTTP Request step. Method POST, URL https://retainerproof.com/api/v1/sites, header Authorization set to Bearer rp_live_…, JSON body {"name":"Harbor","url":"https://harbor.example","cadence":"weekly"}. Read site.id from the response. A second step can PATCH that id with {"statusEnabled":true} and store site.statusPageUrl. A third step POSTs /api/v1/sites/SITE_ID/targets to add a path. Stop on 409 (plan limit) and on 429 (wait for Retry-After). Do not send DELETE unless you mean to remove that site.
Release notes
GET and POST /api/v1/sites/:id/releases. PATCH and DELETE /api/v1/sites/:id/releases/:releaseId. The same paths work for an app id. A proof pack id returns 404.
title is required (max 140 characters). version is optional (max 40). body is Markdown (max 8000). Raw HTML is escaped when the page is rendered. releasedAt is an ISO time or YYYY-MM-DD. Omit it to use the current time. visibility is public or internal. Public notes appear on the status page. A care site also shows them on the client digest, under What shipped. Internal notes stay in the dashboard. source is manual, api, or git. Omit it and this route stores api. commitSha is an optional hex string. url is an optional http(s) address. Both are stored for a later git view and are not drawn on the public page. A site holds 80 notes. The 81st returns 409 with error release_limit.
curl -s -X POST https://retainerproof.com/api/v1/sites/SITE_ID/releases \
-H "Authorization: Bearer rp_live_…" \
-H "Content-Type: application/json" \
-d '{"title":"Faster checkout","version":"1.4.0","body":"Checkout now keeps the cart when a card is declined.","visibility":"public"}'
GitHub Actions
Post a public note when a tag is pushed. Store the key as a repository secret named RETAINERPROOF_KEY. This step does not read the repository. It only calls the API. Replace SITE_ID with the care site or app id.
name: Release note
on:
push:
tags:
- "v*"
jobs:
note:
runs-on: ubuntu-latest
steps:
- name: Post the release
env:
RETAINERPROOF_KEY: ${{ secrets.RETAINERPROOF_KEY }}
run: |
curl -sS -f -X POST https://retainerproof.com/api/v1/sites/SITE_ID/releases \
-H "Authorization: Bearer $RETAINERPROOF_KEY" \
-H "Content-Type: application/json" \
-d "{\"title\":\"${GITHUB_REF_NAME}\",\"version\":\"${GITHUB_REF_NAME}\",\"visibility\":\"public\",\"source\":\"api\",\"body\":\"Shipped ${GITHUB_REF_NAME}.\"}"
Work log
GET and POST /api/v1/sites/:id/work-log. PATCH and DELETE /api/v1/sites/:id/work-log/:entryId.
Fields match the dashboard form. title is required (max 120 characters). date is YYYY-MM-DD or omit it. note is optional (max 2000). category is Update, Content, Fix, Meeting, or Other. minutes is optional, from 1 to 10080. The form names work_date, description, and tag also work.
Set author to llm when a model wrote the line. generatedBy means the same thing, and so does the header X-RetainerProof-Author: llm. The same field works on a release note. If that account requires approval, the line is saved as pending. The API still returns it. The client digest, the digest email, and the public status page leave it out until you approve it.
curl -s -X POST https://retainerproof.com/api/v1/sites/SITE_ID/work-log \
-H "Authorization: Bearer rp_live_…" \
-H "Content-Type: application/json" \
-d '{"title":"Homepage copy refresh","date":"2026-10-04","note":"Rewrote the hero.","category":"Content","minutes":45}'
Client digest recipients
GET and PUT /api/v1/sites/:id/recipients. emails replaces the list (max 5). Optional enabled and cadence (each, weekly, or monthly) control the email that goes out after a scheduled check. An address that unsubscribed stays unsubscribed. The response does not include unsubscribe tokens or any mail API key.
curl -s -X PUT https://retainerproof.com/api/v1/sites/SITE_ID/recipients \
-H "Authorization: Bearer rp_live_…" \
-H "Content-Type: application/json" \
-d '{"emails":["[email protected]"],"enabled":true,"cadence":"weekly"}'
Client email and your own Resend key
On each site, Brand settings can email up to five client addresses after a scheduled digest: status, uptime, certificate and domain dates, and work-log lines, plus a button to the secret digest. Cadence is every digest, weekly, or monthly. Each mail has a one-click unsubscribe.
By default those messages (and status-page incident mail) send through RetainerProof’s Resend account. The From name is your studio name via RetainerProof. Reply-To is your brand contact email. Or paste your own Resend API key and a From address on a domain you verified in Resend. Test & save sends a test and stores the key only if that succeeds. The key is encrypted and is not shown again. If that key later fails, the client mail is not sent from the RetainerProof domain. Freelancer red alerts keep using RetainerProof mail.
The public status page has its own subscribe form. That address is confirmed before any incident mail, then gets one message when the site goes down and one when it recovers.
POST /api/v1/sites/:id/check
Starts the same check as Run check now. If a check is already running for that site, the response is that job and a second check is not queued. 202 with jobId, status, and alreadyRunning.
curl -s -X POST https://retainerproof.com/api/v1/sites/SITE_ID/check \
-H "Authorization: Bearer rp_live_…"
Prompt for an LLM agent
Paste this into Claude, ChatGPT, Cursor, or another agent that can call HTTP. Replace the key. Do not commit the key or put it on a client page.
You can update a RetainerProof account over HTTP.
Base URL: https://retainerproof.com/api/v1
Authorization: Bearer rp_live_PASTE_KEY
OpenAPI: https://retainerproof.com/api/v1/openapi.json
Rules:
- Never send the key to anyone else or store it in a public file.
- GET /sites to find the site id. The list includes statusPageUrl when the public status page is on.
- POST /sites with JSON name, url, optional cadence (daily, twice_daily, weekly, monthly), and optional uptimeIntervalSeconds (30, 60, 120, 300, 900, 1800, 3600; default 900) to add a monitored site. Other interval values return 422. 409 site_limit means the plan is full. Do not retry in a loop.
- PATCH /sites/{id} with name, url, cadence, uptimeIntervalSeconds, or statusEnabled. statusEnabled true publishes the status page and returns statusPageUrl. false hides it and keeps the same token.
- DELETE /sites/{id} removes that care site and its history. Use it only when the user asked to delete that site. 404 means nothing was deleted (another account, an app, or a proof pack).
- GET or POST /sites/{id}/targets to list or add a status path (label, url such as /api/health, optional expected and intervalMode). PATCH or DELETE /sites/{id}/targets/{targetId} to change or remove one. 409 target_limit means the site already has 12.
- POST /apps with JSON name and optional url to add an app status page. 409 app_limit means this account has no app pack left. An app does not use a site slot.
- GET or POST /sites/{id}/releases to list or add a release note. The id may be a care site or an app. title is required. version, body (Markdown), releasedAt, visibility (public or internal), source (manual, api, or git), commitSha, and url are optional. Public notes show on the status page and, for a care site, on the digest as What shipped. commitSha and url are stored for a later git view and are not drawn on the public page. 409 release_limit means the site already has 80 notes.
- PATCH or DELETE /sites/{id}/releases/{releaseId} to change or remove one note. 404 means that id is not on this account.
- POST /sites/{id}/work-log with JSON title, optional date (YYYY-MM-DD), note, category (Update, Content, Fix, Meeting, Other), and optional minutes. Set author to llm when a model wrote the line.
- When a model wrote a release note, set author to llm on that post too. If approvalStatus is pending, clients cannot see that line yet. Do not treat a pending line as published.
- PATCH or DELETE /sites/{id}/work-log/{entryId} to change or remove an entry.
- POST /sites/{id}/check to run the same check as the dashboard. If alreadyRunning is true, wait; do not start another.
- GET or PUT /sites/{id}/recipients to read or replace client digest emails (max 5). cadence is each, weekly, or monthly.
- 401 means the key is missing or revoked. 403 means the subscription is not active. 404 means that id is not on this account. 409 means a plan limit. 429 means wait for Retry-After.
Also see pricing and a sample client digest.