API
Start audits and read their results from outside PersonaMark, with a key for one site.
The API lets something outside PersonaMark start an audit of a site and read its results. For example, a GitHub workflow can audit the site after every deploy and report whether the score went down. It works with a key you make in the site's Settings › API tab.
A key reaches one site and no other. It can read that site's audits, start a new one, check the site's ownership, and audit or run personas on a pull request's preview, and nothing else: it can't change settings, mark issues, run personas on the live site or see other sites.
Make a key
Only an owner can make or revoke keys.
Give the key a name that says where it's used, like GitHub Actions, and choose Make a key.
pm_, and store it as a secret where it's used.The key is shown once. PersonaMark keeps only a fingerprint of it, so if you lose it, revoke it and make another. The list shows each key's name, its first characters, when it was made and when it was last used. A site can have up to 10 keys.
Revoking a key takes effect at once: anything using it is refused from then on.
Send a request
Send the key in an Authorization header to https://work.personamark.app/api/v1/…:
curl -H "Authorization: Bearer $PERSONAMARK_API_KEY" \
https://work.personamark.app/api/v1/siteEvery response is JSON. A request that fails has an error with our own message. A missing,
unknown or revoked key gets a 401, and an audit or job of another site gets the same 404 as one
that doesn't exist.
| Request | What it does |
|---|---|
GET /site | The site's domain, whether it's verified, its verification meta tag's metaName and metaContent, and its latest audit. |
POST /site/verify | Checks ownership now, as Check ownership does, and answers with status (verified, not_found or unreachable) and verified. |
GET /audits?page= | The site's audits, newest first, 20 at a time, with total. |
POST /audits | Starts an audit and answers 202 with its jobId. |
GET /jobs/{jobId} | The audit's progress: status (queued, running, succeeded, failed or cancelled), its stage, and auditId once it's done. |
GET /audits/{id} | The audit's score, its scores by area, its issues by severity, and its checks in the order of the To do tab. |
GET /audits/{id}/compare | The audit against the one before it: the score change, each area's change, and the issues that are new, regressed or fixed, by check. |
GET /audits/{id}/issues | Every issue with its status, 100 at a time. Filter with check, severity and status (new, regressed, recurring, changed or intended). |
GET /audits/{id}/pages | One page, named by ?url=: its issues by check and its title and description rewrites. |
compare takes ?vs= with the id of an earlier complete audit to compare with that one instead.
It follows the same rules as the audit's Summary:
- A partial audit's score, or two audits scored by different rules, isn't compared, so
changeisnull. - Issues you've marked intended are left out.
- An issue is fixed only if this audit could read its page.
Each check lists at most 20 of its pages, and pages counts them all. Every check in these
responses has an appUrl, which opens that check's issues in PersonaMark.
pages matches url without its fragment or tracking parameters like utm_source, so a campaign
link finds the page. A page that redirected is found by either address. It leaves out issues you've
marked intended, and answers 404 when the audit has neither issues nor rewrites for the page, and
400 without a url. Each rewrite has title, description, its status on the To do tab,
an appUrl, and source set to model_suggestion: a model wrote it, so review it before you use
it.
POST /site/verify un-verifies the site when it finds no proof, and changes nothing when it
couldn't run the check, as Check ownership does. See
Prove you own the site.
Starting audits
POST /audits runs the same audit as Run audit. It's refused:
- with
409if the site isn't verified - with
409and the running audit'sjobIdif an audit is already going, so you can wait on that one instead - with
429if the key has started 24 audits and preview runs in the last 24 hours
An audit takes a few minutes. Poll GET /jobs/{jobId} every 20 seconds or so until status is
succeeded, then read GET /audits/{auditId}/compare. When stalled is true, the audit has
been waiting for a while and may not start soon.
Audit a preview deployment
A pull request's preview deployment can be audited before it merges and compared with your latest audit. An owner first allows the preview's hosts in Settings › Crawling, and the preview must carry the site's verification meta tag; see Preview deployments.
| Request | What it does |
|---|---|
POST /previews | Starts a preview audit from JSON: url, and optionally ref, sha and pull_request to label it. Answers 202 with previewId. |
GET /previews/{id} | Its status, stage, and once it's done its score and productionScore. |
GET /previews/{id}/compare | The preview against production, in the same shape as compare: the score change and the issues new, back or fixed, by check. |
POST /previews is refused with 422 for a URL that isn't https on one of the site's preview
hosts, and with 409 and that preview's ids while the same preview is already being audited. It
counts towards the key's 24 a day.
A preview audit crawls the preview the way an audit crawls the site, but reads it as if it were
production, so its issues line up with your latest audit's, and issues you've marked intended stay
that way. Google can't reach a protected preview, so there's no PageSpeed: the preview's score and
the production score it's compared with both leave performance out, which is why
productionScore can differ from your latest audit's score. Vercel marks every preview noindex
with a header, which the audit ignores; a robots meta tag in the page still counts. Preview audits
are listed on the Audits tab and never count as one of the site's audits.
Run a persona on a preview
A pull request can break a journey without adding a single SEO issue: the signup button moves, or the checkout form stops submitting. To catch that before it merges, send a persona at a goal on the preview and compare the run with that pair's last scored run on the live site. It works like an end-to-end test, except the check is a goal in plain words rather than a script.
The preview needs the same setup as a preview audit (allowed hosts and the meta tag), and the goal must start on this site.
| Request | What it does |
|---|---|
GET /personas | The project's personas and the goals that start on this site, with their ids. signsIn marks a goal that uses a test account. |
POST /preview-runs | Starts a run from JSON: url, persona_id, goal_id, and optionally ref, sha and pull_request. Answers 202 with previewRunId. |
GET /preview-runs/{id} | Its status, and once it's done its run and production, each with outcome, score, areas and friction, and scoreChange. |
friction counts the problems the run hit by severity (blocking, moderate, minor) and lists
the steps they happened at. production is null when the pair has never been scored on the live
site, and scoreChange is null until both runs have a score. production.url opens that run in
PersonaMark.
POST /preview-runs is refused with 422 for a URL that isn't https on one of the site's preview
hosts, with 404 for a persona and goal that aren't this site's, and with 409 and the run's ids
while the same persona is already trying the same goal on that preview. It counts towards the key's
24 a day.
What's the same as any run: the guardrails, the caps of 40 steps, 8 minutes and $2 of model calls, and at most two runs going at once across your organization. What's different:
- It stays on the preview's host. A goal that needs your app on another subdomain can't get there, and says so as friction.
- No test-account logins unless an owner allows them. A goal that signs in is refused with
422until an owner turns on logins in Preview deployments, since the preview runs code nobody has merged yet. - It's kept apart from your runs. Preview runs don't appear on the Scores tab, in past runs, deltas, the weekly digest or alerts, and a later preview still compares with the live site. Their cost shows under Preview runs in Model spend.
Each run is several model calls, so pick a few pairs that cover the journeys you'd hate to break,
rather than every persona at every goal. The score is a model's judgement, not a measurement: a
change of a few points can be noise, and a new blocking problem or an outcome that went from
completed to gave_up is the stronger signal.
Run it after a deploy
The PersonaMark audit action does all of this in a GitHub workflow: it starts an audit, waits for it, and writes what changed since the audit before into the job's summary. It also comments the same summary on the pull request the deployed commit came from, or on the commit when no pull request has it, so whoever made the change sees it.
In your GitHub repository, open Settings › Secrets and variables › Actions and add
the key as a secret named PERSONAMARK_API_KEY.
Add the workflow below as .github/workflows/personamark.yml, so it runs once your production
deploy is live.
Deploy to production. When the workflow finishes, the pull request gets a comment, and the run's summary has the same: the score, its change and the issues by check, with a link to the audit.
For a site on Vercel:
name: PersonaMark audit
on:
deployment_status:
jobs:
audit:
if: >-
github.event.deployment_status.state == 'success' &&
github.event.deployment.environment == 'Production'
runs-on: ubuntu-latest
timeout-minutes: 40
permissions:
pull-requests: write # comment on the pull request
contents: write # or on the commit, when there's no pull request
steps:
- uses: function-form/personamark-action@v1
with:
api-key: ${{ secrets.PERSONAMARK_API_KEY }}
fail-on: new-highWithout those permissions, the step can't comment: it says so in a warning and carries on. Set
comment: false to keep the result to the run's summary.
fail-on decides when the step fails:
none, the default: never, only reportnew-high: when an issue of high severity is new or backscore-drop:<n>: when the score fell bynor morerun-failed: when a persona didn't reach its goal on the preview, though it does on the live site (or has never run there)run-score-drop:<n>: when a persona's score on the preview fell bynor more against the live site's
To use several, separate them with commas. If the audit doesn't finish within timeout-minutes
(30 by default), the step stops waiting. The audit carries on in PersonaMark, and the step passes
unless fail-on asks for something.
This audits the site's own domain, so run it after a production deploy. To audit a pull request's
preview before it merges, give the action preview-url, as in the action's README; see
Audit a preview deployment for what that needs first.
With preview-url, personas also sends personas at their goals on the preview: one
<persona-id>:<goal-id> pair a line, with the ids from GET /personas, at most 5.
- uses: function-form/personamark-action@v1
with:
api-key: ${{ secrets.PERSONAMARK_API_KEY }}
preview-url: ${{ github.event.deployment_status.environment_url }}
personas: |
3f2b8c1e-7a4d-4e9b-8c21-5d6f7a8b9c0d:8b0f3c2e-4f0a-4f7e-9f61-0d1d3a8f5b21
fail-on: new-high, run-failedThe comment then has a table under the preview audit with each run's outcome, score, change and
problems, and a link to the live site's run it was compared with. See
Run a persona on a preview for what a run there can and can't do.
run-failed is the steadier rule: a model's score can move a few points between runs of the same
page.
If something goes wrong
| What the step says | What to do |
|---|---|
Could not start an audit: Send a live… | The secret is missing, misspelled or revoked. Make a new key and update the secret. |
Verify this site… | Prove ownership in the site's Settings › General, then deploy again. |
…24 audits and runs in the last 24 hours | The key's daily limit. A workflow that runs on every push can reach it; run it on production deploys only. |
…still queued… | The audit hasn't started within the timeout. It will still run; its result is on the site's Audits tab. |
This is the site's first complete audit | Nothing to compare yet. The next run reports changes. |
Use it from an AI assistant
The same key works with an MCP server at https://work.personamark.app/api/mcp, so an assistant
like Claude Code can read the site's audits and start one. To add it to Claude Code:
claude mcp add --transport http personamark https://work.personamark.app/api/mcp \
--header "Authorization: Bearer $PERSONAMARK_API_KEY"Other assistants that support remote MCP servers over HTTP take the same address and header.
| Tool | What it does |
|---|---|
get_site | The site's domain, whether it's verified, and its latest audit. |
list_audits | The site's audits, newest first. |
get_audit | An audit's score, scores by area, and the checks to fix, in order. |
get_audit_page | One page's issues by check, and its title and description rewrites. |
list_issues | An audit's issues with their status, filtered by check and severity. |
compare_audits | What changed since the audit before, or since one you name. |
start_audit | Starts an audit. |
verify_site | Checks the site's ownership now. |
get_audit_job | An audit's progress, and its id once it's done. |
start_preview_audit | Starts an audit of a preview deployment. |
get_preview | A preview audit's progress and score. |
compare_preview | What a preview would change against production. |
list_personas | The personas and the goals that start on this site, with their ids. |
start_preview_run | Sends a persona at a goal on a preview deployment. |
get_preview_run | A preview run's outcome and score beside production's. |
Only the three that start something and verify_site do anything but read. The tools return the
same things as the requests above, by the same rules.
What responses contain
Responses carry our own labels, scores and page addresses, never what a page wrote. An issue's
message, page titles and Search Console figures aren't part of the API. A page's title and
description rewrites are, marked model_suggestion because a model wrote them. The model's
reasoning and its other notes aren't.
A preview run gives its outcome, scores and friction counts, never the model's summary, friction
points or recommendations. A model wrote those after reading the preview, and a page can steer it,
so they'd be unsafe in a pull request comment that anyone with access to the repository reads.
GET /personas returns your own persona names and goal sentences.