The API¶

Postulo's API is at /api/v1/, and it does exactly what the token you hand it allows. It began as the capture API — a way for something outside Postulo to hand over a posting, and nothing else — and that part is unchanged. Around it now sits the rest: reading a search, recording to it, downloading what was sent.

Two other surfaces are documented elsewhere. /healthz, /metrics and /logs answer machines about the instance rather than about a search: Health, metrics and logs. And a plugin runs inside Postulo instead of calling it: Writing a plugin.

Tokens and scopes¶

Settings → API tokens. Give it a name — the device or tool it is for — tick what it may do, choose when it expires, and Postulo shows you the token once. Only a hash is kept: a copy of the database is not a set of working credentials, and a lost token is replaced, not recovered.

A browser extension needs captures and nothing else; a leak costs its holder the ability to fill a review queue you will then decline. A mail client that files messages into listings needs listings:bind and nothing else; a leak costs its holder the ability to add entries to histories you can read. An agent starts with read and is given write when you trust it. Every timeline entry written through the API is signed with the token's name — via API token laptop-agent — so you can always see what an agent did, and undo it by hand.

A token is not a sign-in. It never reaches the web interface, and two-factor authentication does not apply to it. Revoke it from the same page; revoked and expired tokens answer 401 like a token that never existed.

Using it¶

Send the token as a bearer token. To check one and see its scopes:

curl -H "Authorization: Bearer YOUR_TOKEN" https://postulo.example.org/api/v1/me

It answers with the token's name, its owner's address, its scopes, the owner's time_zone, expires_at and last_used_at. It needs no scope of its own, so any live token may ask, and a client can tell a mistyped token from a network problem without creating anything.

Everything the API offers is described in OpenAPI at /api/v1/openapi.json — load it into any client or viewer; there is deliberately no documentation page served by Postulo, since its assets would have to come from a CDN the content security policy forbids. The refusals are described too, per call and with a Problem schema, so a generated client has a type for the 401 it is likelier to meet first than any answer: see Responses. The schema needs a credential like everything else: any live token, whatever its scopes, or a browser signed in to the instance. Reading it spends no allowance and does not count as using the token.

Lists are paginated with limit and offset and come back as {"items": [...], "count": n} — one page's rows, and the count of the whole list. Every list also takes updated_since, which is how a client catches up on a search it already holds a copy of rather than reading all of it again: see Catching up below.

Capturing a posting¶

Needs captures.

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://example.org/jobs/42"}' \
  https://postulo.example.org/api/v1/captures

Postulo fetches the one page — public addresses only, robots.txt honoured — reads it, and stores a capture for review. To capture a posting only a signed-in reader can see, or one behind bot protection, send the page source yourself and nothing is fetched:

  -d '{"url": "https://example.org/jobs/42", "html": "<!doctype html>..."}'

The response is 201 with the capture: title, company, location, source, status and a review_url. 422 means the page yielded nothing usable, or the address was refused, and detail says which. Nothing is created but the capture: the owner reviews it into a listing, and applies from there. GET /api/v1/captures lists the captures awaiting review, newest first, paginated like every other list.

Telling postings apart. Every capture the API answers with — on the list, from POST /captures and from the rendering call — carries a posting_key: an opaque name for the posting at its address. Two captures of one posting have the same key, however the address was spelled (http or https, with or without www. or a trailing slash, in either case), and two postings have different keys, so a client counts the postings waiting for review by counting distinct keys, without copying Postulo's rule for what is one address. POST /captures/known answers with the key of each address you ask about, which is how a client puts what it has not sent yet beside the list. The key is a hash keyed by your instance's secret and your account: it stays the same from one request to the next, it cannot be turned back into the address, and two accounts have different keys for one posting. So a token holding only captures gets it too, although it is not told the address. It changes if the instance's key does (POSTULO_FIELD_KEY, or SECRET_KEY where that is not set). An address that names no host has an empty key and matches nothing (#711).

Sending the same posting twice. If you send a capture and never see the answer, you cannot tell a lost reply from a lost request — and sending it again used to leave two captures of one posting to decline, and two notifications about it. Add an Idempotency-Key header, any string of your own invention with one posting behind it (a UUID is the obvious choice; up to 200 characters, and a longer key is refused with a 422 naming the header):

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1b2f0e-9c1a-4f2b-8f43-1f0a2b3c4d5e" \
  -d '{"url": "https://example.org/jobs/42"}' \
  https://postulo.example.org/api/v1/captures

The first answer given under that key is the answer you keep getting for 24 hours, exactly as it was: no page is fetched again, no second capture is made and nobody is told twice. Reusing a key for a different posting is a 422, because that is a bug in the client and answering it with the first capture would hide it; sending it again while the first is still being answered is a 409, and waiting a moment is the whole of the fix. A capture that was refused gives its key up again, so the obvious thing — retrying under the same key — is also the right thing. Without the header nothing is recorded and nothing is replayed, which is what a client that does not send one has always had.

How often you may ask Postulo to fetch. A capture that Postulo fetches — one sent without html — is counted against POSTULO_CAPTURE_RATE, 30 an hour by default, per account, which is the tightest limit the instance has because it is the one thing that makes your server dial an address somebody else chose. It is the same allowance the capture form spends, so the two share one ceiling and a second token is not a second allowance. A capture that brings its own html fetches nothing and is not counted: those answer to POSTULO_API_RATE alone, 600 an hour per token, which is why a browser extension can send forty from one results page in one gesture. POST /captures/preview fetches too, so it is counted the same way. Over the limit is a 429, with detail saying how many are allowed in how long; wait, or raise the setting.

What the API says about caching, length and wrong tokens. Every answer carries Cache-Control: private, max-age=0, no-store, the calendar feeds and the JSON alike, so nothing you read is left in an HTTP cache after the token is revoked (#952). The free-text fields you write (a timeline body, a status note, notes on a company, contact or interview, a listing description, a letter body) take at most 40,000 characters; a longer one is a 422 naming the field, and its maxLength is in the OpenAPI document (#953). A wrong token is counted against the address that sent it and bars the address after sixty an hour on every address under /api/v1/, openapi.json, an unknown path and a wrong method included (#951). A capture sent with only the captures scope is answered, for the rendering call as for the list, without the address, company, location or source (#950).

To see what a page would be captured as first, send the same body to POST /api/v1/captures/preview. It answers 200 with the page's url, the source that read it, and data: every field of the posting as read — title, company_name, location, remote_type, employment_type, description, salary_min, salary_max, salary_currency, salary_period, posted_at, closes_at, url and source. It stores nothing and notifies nobody; it is refused exactly as a capture would be.

It also answers hinted: the fields of data that were read where your own corrections showed them on this site before, rather than from what the page states. Show them as such. A preview keeps no score.

To send corrections with the capture, add the fields that changed as data:

  -d '{"url": "https://example.org/jobs/42", "html": "<!doctype html>...",
       "data": {"title": "Senior Research Engineer", "location": "Lyon"}}'

The page is still read, so the capture's source is still the one that read it; each field in data replaces what was read, and the result is checked exactly as a source's own output is. A field that does not exist, an empty title or a salary that is not a number is a 422, with detail locating it under data, and nothing is stored. A corrected capture is still a capture: it waits for review, and the review screen opens with the corrections in it.

Corrections teach exactly as the review screen does: a field corrected to a value the page shows is remembered where it was, for that site (see Capturing postings).

Keeping the page. Where the instance and the account both keep pages — off by default, see Capturing postings — the source a capture was read from is kept beside it: the html you sent, or the page Postulo fetched. To not keep it for one capture, add "keep": {"source": false}. keep can only take something away; it never switches keeping on. Every capture in an answer carries a page member:

"page": {
  "source": true,
  "rendering": false,
  "rendering_type": "",
  "accepts_rendering": true,
  "rendering_url": "https://postulo.example.org/api/v1/captures/42/rendering",
  "rendering_types": ["image/png", "image/jpeg", "image/webp", "application/pdf"],
  "rendering_max_bytes": 10485760,
  "note": ""
}

note says in words why something the account asked to keep was not — larger than the instance keeps, or no room left for the account. The capture is made either way.

Sending a rendering. A picture of the whole page as the browser shows it is what only the browser can make. Send it after the capture, as the body of a PUT to the capture's rendering_url, under its own media type — not JSON, not a form:

curl -X PUT -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: image/png" \
  --data-binary @page.png https://postulo.example.org/api/v1/captures/42/rendering

Needs captures. It answers 201 with the capture when the rendering was kept, and 200 with the same body when those exact bytes were already kept — a retry after a lost reply is safe. A PNG, JPEG or WebP image or a PDF, and its first bytes must be what the type says. Content-Length is compared with rendering_max_bytes before the body is read, so ask accepts_rendering first and do not draw one that would be refused. A capture takes one rendering, while it is waiting for review; a different one sent later is refused rather than replacing it. Nothing in the API hands a kept page back.

A request larger than the API reads — about 2.5 MB, which a page's html can reach — is a 413 problem document of type #too-large, with max_bytes. It used to be an HTML 400.

To send several from one page — a results page lists forty postings and the useful gesture is look at forty, keep three — send one request per posting with the same page source and each posting's own address as url: Postulo reads the page again and picks the posting that names that address. Add batch so the arrivals are announced once rather than forty times:

  -d '{"url": "https://example.org/jobs/42", "html": "<!doctype html>...",
       "batch": {"size": 3, "position": 1}}'

size is how many the gesture sends and position this one's place in it, from 1. The first of a batch is announced — Captured 3 postings from example.org — and the others arrive without a word. A posting read off a results page is usually a stub: a title, a company and a place, with the description left to the advert's own page. It is a capture to triage, not a listing to read.

To ask whether a posting has been captured before, send its address — and its title and company, if known — to POST /api/v1/captures/known, up to a hundred at a time:

  -d '{"postings": [{"url": "https://example.org/jobs/42",
                     "title": "Research Engineer", "company": "Black Mesa"}]}'

It answers, per posting, with its posting_key (see above), listings — the listings at that address, however it was spelled — captures, the captures of it still waiting for review, and similar, listings with that title at that company at another address, which is how a board that mints a fresh address on every visit hides a duplicate. Nothing is refused on the strength of it: the extension says captured before and the choice is yours. The web form and the review screen say the same.

The browser extensions¶

The capture API was built for a browser extension, and there is one — for Chromium-based browsers (Chrome, Edge, Brave, Vivaldi, Opera, Arc) and for Firefox and its forks, including Firefox for Android:

• postulo-chromium holds the source, one Manifest V3 codebase built for both browsers.
• postulo-firefox assembles the Firefox package from it and carries what addons.mozilla.org needs.

Set it up once: make a token under Settings → API tokens with the captures scope and nothing more, then paste your Postulo's address and the token into the extension's settings. Test asks Postulo who the token is; Save asks the browser for permission to reach your address. From then on, on a job posting, the button (or Alt+Shift+P) reads the page as your browser sees it — so a posting only visible to a signed-in reader, or one behind bot protection, is captured too — and shows in the popup what Postulo read from it. Correct whatever it got wrong, then Send for review: the capture arrives in the review queue with your corrections, and the popup links to its review screen. Against a Postulo older than the preview, it sends straight away instead. The page goes to your server and nowhere else: no analytics, no third-party requests, no permission to run on any site until you press the button.

Keeping the page. An extension already sends the source, as html, so where your account keeps sources a page captured through it keeps its source. Sending a rendering of the page — a picture of the whole of it, as you were seeing it — is the extensions' next step and not built yet; the call above is what they will use.

Reading¶

Needs read. Everything is the token owner's; another person's records are 404, as they are in the web interface.

A language is a BCP 47 tag in its canonical form wherever the API gives one — pt-BR, en-GB, sr-Cyrl — in language on a CV, a letter and a document, and in record_language on the profile. Blank means nobody has said. Postulo used to write these in lower case; a tag says the same thing in any case, so compare without regard to it.

Every list in that table — the calls with no {id} in them, apart from /insights, /search, /profile and the calendar feed — is paginated: limit and offset in, {"items": [...], "count": n} out, and updated_since for catching up. So is GET /captures. limit defaults to 100 and is at most 200: a larger one is a 422, and the OpenAPI schema declares the bound. A page is read inside one transaction, so a bound keeps one call from holding the instance's database for as long as it likes; walk a bigger account with offset, or with updated_since and after_id.

Catching up¶

Needs read (or captures, for the capture queue). Every list takes updated_since, a moment, and answers with the rows that changed at or after it, oldest change first. Every row carries an updated_at, and with its id that is the cursor: read a page, remember the updated_at and the id of the last row on it, and ask again with both.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://postulo.example.org/api/v1/applications?updated_since=2026-09-15T08:00:00Z&after_id=123&limit=100"

Send after_id too: rows that share one updated_at, as after an import or a bulk edit, would otherwise hand you the same page for ever. GET /captures takes it as well.

The ordering is the point. A list in the order things were recorded cannot be walked with a cursor, so a list asked what has changed is ordered by when it changed instead, with ties broken by id so nothing swaps places between one page and the next. Remember to encode the moment: a +00:00 offset in a query string is read as a space unless it is escaped, so Z is the easier spelling.

One thing it cannot tell you: a deletion. A row that is gone cannot appear in a list of rows, so anything keeping a mirror still has to notice absences itself. Outbound webhooks, which tell the receiver as things happen, exist (see Webhooks), but carry no deletion event either: a mirror still has to notice absences itself.

Writing¶

Needs write. Every write goes through the same services as the forms, so the event log stays the single truth.

A time must carry an offset (Z or +02:00); one without is a 422 naming the field, in a body and in updated_since. GET /me returns the owner's time_zone, to build the offset from. A call made with a token is carried out in its owner's language and time zone, so the reminder and timeline entry of an interview booked here name the hour as the owner reads it. A write that is refused, as a company's or an interview's can be over its identifiers or contacts, keeps nothing of what it had begun to save.

Filing into a listing's history¶

Needs listings:bind — or read to choose and write to record, which a token that holds them already has. It is two calls, for a client that only attaches things: a mail client filing the message you are reading into the listing it is about.

Choosing the listing. GET /listings/choices lists your listings as little of each as recognising one takes: id, title, company_name, location, state, noted_at and updated_at — no description, no salary, no applications. q narrows to the ones whose title or company contains the words; state is all (the default), undecided, new, shortlisted, discarded, applied or closed. It is paginated like every list, and takes updated_since and after_id.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://postulo.example.org/api/v1/listings/choices?q=research"

Recording the entry. POST /listings/{id}/events:

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind": "email_received", "summary": "Re: Research Engineer", "body": "We would like to talk.", "external_id": "<talk@blackmesa.example>"}' \
  https://postulo.example.org/api/v1/listings/42/events

It answers 201 with the entry — id, listing_id, kind, occurred_at, summary, body, contact_id, document_id, capture_id, external_id, actor (the token's name, as on a timeline) and created_at — or 200 with the one already filed under that external_id. A contact_id or a document_id that is not yours is a 422, the same answer as one that does not exist. The words are kept as text and shown as text: nothing in an entry is ever read as markup or turned into a link, and none of it reaches the report's spreadsheet or a calendar.

Downloading¶

Needs documents:read. GET /documents/{source}/{id}/download, where source is upload or rendered; the download_url on each document is exactly this.

Giving an AI agent a way in¶

Postulo has no AI in it and never asks you for an API key. If you want an agent to know about your job search anyway, run postulo-mcp beside the agent you already use. It speaks the Model Context Protocol on one side and this API on the other, so the agent gets no privileged path: it can do exactly what your token allows, and nothing else.

Make a token with Read everything, and point the agent at it:

{
  "mcpServers": {
    "postulo": {
      "command": "postulo-mcp",
      "env": {
        "POSTULO_URL": "https://postulo.example.org",
        "POSTULO_TOKEN": "the token you just made"
      }
    }
  }
}

Two things worth deciding deliberately. A read token shows the model your whole job search — applications and their timelines, companies and people, CVs and letters as text, reminders, interviews and figures. And writing is off unless you turn it on, with postulo-mcp --write and a token carrying write; every write an agent makes then appears on the timeline with the token's name against it, so you can see it and undo it. The one delete the API has — a reminder — is not offered as a tool.

Every call¶

The same calls as above, as one list, with the scope each needs. A test in Postulo's repository reads this list against the API itself, so a call that is added without a line here fails there.

Responses¶

401 is a missing, mistyped, revoked or expired token — nothing more is said, because confirming a token exists is itself information. 403 is a live token without the scope the call needs, and detail names the scope — or the scopes, where more than one would do. 404 is a record that is not yours, or does not exist; the two are deliberately indistinguishable. 409 is an Idempotency-Key that another request is still using; wait a moment and send it again. A 409 of type #not-kept is a rendering this capture will not take — its reason is switched-off, decided, already-kept or no-room. 411 is an upload that did not say how large it is, 413 one that is larger than this call takes, and 415 one of a kind it does not keep. 422 is a value that will not do, with detail saying why. 429 is an allowance spent — either the token's own (POSTULO_API_RATE) or, on a capture Postulo has to fetch, the account's (POSTULO_CAPTURE_RATE) — and detail says how many are allowed in how long.

What a refusal looks like¶

Every one of them is a problem document, as RFC 9457 describes: Content-Type: application/problem+json, five members, and the id of the request. That includes an address that does not exist (401 without a live token, 404 with one) and a method an address does not take (405, with its Allow header).

{
  "type": "https://source.tiagoagueda.com/postulo/postulo/wiki/The-capture-API#insufficient-scope",
  "title": "This token does not carry the scope this call needs",
  "status": 403,
  "detail": "This token does not have the 'read' scope.",
  "instance": "/api/v1/applications",
  "request_id": "5f0c2a9e7b1d4c38a6e0f1b2c3d4e5f6",
  "scope": "read"
}

A type may carry members of its own, as scope does above. Ignore any you do not know: more may be added, and that is not a breaking change.

The types with a name¶

Everything else is about:blank, where the status code is the whole story.

Changed in 0.4.0. Refusals used to be {"detail": "…"} under application/json. A client that reads detail and shows it is unaffected — detail is an RFC 9457 member and still a sentence. Two things did change: the media type is application/problem+json (match the +json suffix rather than the whole string), and a validation failure's detail is now a sentence instead of the list of field errors — the list moved to errors, unchanged in shape. A client that iterated detail must read errors instead.

Changed since. detail is a translated sentence for every refusal, and in the account's language: it had been translated for about one refusal in five, and in whatever language the client asked for, which for a script is English and for a browser extension is the browser's. Every refusal carries request_id. Where several scopes would do, detail lists them with commas. A call made with a token is also carried out in its owner's language and time zone, so an interview booked through the API is worded on the timeline, and its reminder timed, the way one booked on the page is. None of this changes what a client does: branch on type, show detail.