# pdatum API, v1

Job postings and the employers behind them, as an API. This is the data
jobwolverine.com and rxraven.com are built on. Alongside it: federal awards to
any company you name, BDC lenders' books from their SEC filings, the
registry of the private companies those lenders hold, the layoff notices
states publish under the WARN Act, franchisors' filings with the states, and
every private capital raise companies have reported to the SEC since 2008.

Base URL: `https://pdatum.pearachute.com/api/v1`. This page is served at
`/api/v1/docs` and needs no key.

## Authentication

Every endpoint except this page needs a key:

```
Authorization: Bearer pdatum_...
```

Keys are issued by hand for now. A key is shown once, when it is issued; we
store only a hash of it, so a lost key cannot be recovered, only replaced.
Keep keys out of browsers: responses carry no CORS headers, so a web page on
another site cannot use one.

A key reads everything unless it was issued narrower: its scopes are `all`,
which includes endpoints added after it was issued. A narrower key lists what
it may read: `jobs` reads `/jobs*`, `employers` reads `/employers*`, `awards`
reads `/awards`, `bdc` reads `/bdc/*`, `companies` reads `/companies*`,
`warn` reads `/warn*`, `franchises` reads `/franchises*`, and `raises` reads
`/raises*`. `GET /me` shows yours.

## Responses

Every response is JSON. A list looks like this:

```json
{"data": [...], "next_cursor": "WzE3MjcwMDAwMDAsIDQyXQ", "total": 8608}
```

- `total` is how many records matched the filters, across every page.
- `next_cursor` is `null` on the last page. To get the next page, pass it back
  as `cursor=` with the same filters. Cursors are opaque, so don't build or
  edit one.

A single record is `{"data": {...}}`.

### Ready, being read, or not here

Some data is read for you only after somebody asks for it (a BDC book), or
on our own schedule (a state's WARN notices). Whatever you ask for, the
status says which of these you got:

| Status | Meaning | Examples |
|---|---|---|
| 200 | Here it is. | A book that has been read. Notices from states we have read. |
| 202 | It's being read, so there's nothing here yet. Ask again later; `Retry-After` gives a time in seconds. This isn't an error, and an empty answer would be wrong. | A book asked for the first time, whose read the request started. A state waiting for its first read. |
| 404 | It isn't here, and nothing is reading it. | A ticker that isn't a BDC, or whose read failed lately. A state we don't read. |

A 202's `data` says what is being read and where it stands, so its shape
differs from the 200 it will become: check the status before you read the
body. A 5xx is never one of these. It means something failed, as below.

An error looks like this:

```json
{"error": {"code": "invalid_parameter", "message": "posted_since: expected a whole number, got 'yesterday'"}}
```

| Status | `code` | Meaning |
|---|---|---|
| 400 | `invalid_parameter`, `invalid_cursor` | A parameter could not be read. Unknown parameters are refused, not ignored. |
| 401 | `missing_key`, `invalid_key`, `revoked_key`, `expired_key` | The key is absent, wrong, revoked or expired. |
| 403 | `insufficient_scope` | The key lacks the scope this endpoint needs. |
| 404 | `not_found` | No such endpoint or record, or nothing we read: see above. |
| 429 | `rate_limited` | Slow down; honour `Retry-After`. The limit is 5 requests a second per key, in bursts of up to 60. |
| 503 | `source_unavailable` | A source we ask on your behalf did not answer. Nothing is known either way; honour `Retry-After`. |

All times are epoch seconds, UTC.

## Jobs

### `GET /jobs`

Open jobs, newest first.

| Parameter | |
|---|---|
| `brand` | `jobwolverine` or `rxraven`. Omit it for both. |
| `employer` | An employer slug, from `/employers`. |
| `q` | Text in the position or the company name. |
| `location` | Text in the location. |
| `remote` | `true` or `false`. |
| `posted_since`, `posted_before` | Epoch seconds. These filter on the posting date, which is the first-seen date when the source gave none. |
| `detail` | `summary` (the default) gives a description excerpt. `full` gives the whole text, capped at 100 records a page. |
| `limit` | 1 to 500 (100 with `detail=full`). The default is 100. |
| `cursor` | From the previous page. |

A job:

```json
{
  "id": 48213,
  "position": "Senior Data Engineer",
  "company": "Acme Corp",
  "employer": "acme",
  "location": "Boston, MA",
  "remote": false,
  "salary_min": 150000, "salary_max": 180000, "salary_currency": "USD",
  "tags": ["python", "senior"],
  "description": "...", "description_is_excerpt": true,
  "application_url": "https://...", "source_url": "https://...",
  "brand": "jobwolverine",
  "open": true,
  "posted_at": 1727000000,
  "first_seen_at": 1727003600,
  "last_seen_at": 1727500000,
  "updated_at": null
}
```

Field notes:

- `employer` is the slug of the employer record, or `null` when the company
  name has no record of its own.
- `posted_at` is `null` when the source gave no posting date. `first_seen_at`
  is always when we found the job.
- `last_seen_at` is the last time a crawl still listed the job.
- Salaries are whole units of `salary_currency`. Most jobs don't state a
  salary, and both fields are `null` then.

### `GET /jobs/count`

Takes the same filters as `/jobs` and returns `{"data": {"count": n}}`. It's
cheap, so use it to size a query before pulling the results.

### `GET /jobs/{id}`

One job, open or closed, with its full description.

### `GET /jobs/changes?since=T`

Every job added, closed or reopened after `T`, oldest change first. Closed
jobs are included with `"open": false`, and each record carries `changed_at`.
It takes `brand`, `detail`, `limit` and `cursor`.

This is how to keep a copy in sync without pulling everything again:

1. Pull `/jobs` once, and note the time you started.
2. From then on, call `/jobs/changes?since=<last changed_at you saw, minus 1>`.
   Follow `next_cursor` to the end, and upsert each record by `id`.

Times are whole seconds, so the "minus 1" means a record may arrive twice. It
never means one is missed.

## Employers

### `GET /employers`

Employer records, in id order.

| Parameter | |
|---|---|
| `q` | Text in the name. |
| `domain` | An exact domain, e.g. `pfizer.com`. |
| `brand` | Only employers with open jobs on that brand. |
| `limit`, `cursor` | As for `/jobs`. |

An employer:

```json
{
  "id": 17, "slug": "acme", "name": "Acme Corp", "domain": "acme.com",
  "origin": "postings", "created_at": 1726000000,
  "open_postings": {"jobwolverine": 12, "rxraven": 0},
  "hiring": true
}
```

`hiring` is `true` when there are open jobs, or when our own check of the
employer's hiring pages found some. It is `false` when that check found hiring
pages with nothing open. It is `null` when we can't tell, which is not the
same as not hiring.

### `GET /employers/{slug}`

One employer. On top of the list fields it carries:

- `aliases`: the company names that resolve to this employer.
- `facts`: every fact we hold, each as
  `{key, value, source, method, observed_at}`.
- `history`: every value those facts have had, oldest first, in the same
  shape.

Every fact names its source. `method` is which version of our own check
produced the value when the source is ours (`probe`), and `null` for a source
that has no versions. When the method changes, history gets a row even if the
value did not: that row is the new version's starting point, not a change at
the employer. Compare values only within one source and method -- a better
check finding a hiring page is not the employer starting to hire.

## Federal awards

### `GET /awards`

Contracts, IDVs and grants a federal agency has awarded to a company, from
[USAspending.gov](https://www.usaspending.gov), the federal government's public
record of its spending. Any company, not only one we hold a record for: ask by
name. We look it up when you ask and keep the answer for a month, so the first
request for a name takes some seconds and later ones do not.

| Parameter | |
|---|---|
| `name` | A company name. Repeat it for other names the company goes by, up to 5. |
| `employer` | An employer slug: its name and aliases are used, plus any `name` given. |

One of the two is required.

```json
{
  "data": {
    "names": ["Acme Corp"],
    "employer": null,
    "found": true,
    "recipients": [{
      "name": "ACME CORP",
      "spellings": ["ACME CORP", "ACME CORP."],
      "one_word_name": false,
      "contracts": {
        "count": 12, "amount": 48210000, "capped": false,
        "latest_period_end": 1798675200,
        "agencies": ["Department of Defense", "Department of Energy"],
        "largest": [{"award_id": "W00000-25-C-0001", "amount": 9100000.0,
                     "agency": "Department of Defense",
                     "period_start": 1735689600, "period_end": 1798675200}]
      },
      "idvs": {"count": 3, "amount": null, "...": "..."},
      "grants": {"...": "..."}
    }],
    "loans_only": [],
    "source": "usaspending.gov",
    "observed_at": 1791475191
  }
}
```

- **A recipient is matched on its whole name.** Case, punctuation and a legal
  form at the end (Inc, LLC, Corp) are ignored; nothing else is, and a longer
  name never matches a shorter one: "Gulf Winds" is not "Gulf Winds
  International". `spellings` are the ways USAspending writes the one
  recipient, and each award is counted once across them.
- **`one_word_name: true` means confirm it first.** "Alloy" is more than one
  business, and the name alone cannot say which one this is.
- `contracts` are definitive contracts, purchase orders, delivery orders and
  BPA calls. `idvs` are the vehicles orders are later placed under --
  government-wide contracts, IDIQs, schedules, BPAs -- so their `amount` is
  `null`. `grants` are grants and cooperative agreements. A type with no
  awards is absent.
- `amount` is the total obligated, in US dollars, over awards with activity
  since October 2007. `capped: true` means there were more awards of that type
  than we read, and `count` and `amount` cover the largest 200 for each
  spelling.
- `latest_period_end` is when the latest of its awards' periods of
  performance ends -- when the work comes up for renewal.
- **Loans are left out**, PPP among them: a loan is not revenue. A recipient
  whose name matched but who holds only loans is listed in `loans_only`.
- `found: false` means USAspending has no award to a recipient by these names.
  When USAspending does not answer at all, the response is a `503`, never
  `found: false`.
- `observed_at` is when the oldest answer this response is built from was
  fetched from USAspending.
- Prime awards only. Subcontracts are not in it.

## BDC books

What a business development company reports lending, read from its SEC
filings: who it lends to, on what terms, what it says each loan is worth, and
how every other lender we read marks the same loans. One lender at a time, by
ticker. Everything comes from public filings and state notices.

A book is built once and kept, then served as it was built: the same `version`
is the same data, byte for byte, so cache on it. Asking for a lender we have
never read starts its first read. A book is rebuilt when somebody asks for it
again with `POST /bdc/books`, which reads whatever the lender has filed since,
and a rebuild that changes nothing keeps the version it had.

A quarter already filed can still change: when our reader improves, or a
quarter turns out to have been read the wrong way, it is read again the next
time its lender is read, and the new book has a new `version`. Each filing
says which `reader` read its positions. A backtest that must be repeatable
should pin a `version` or a `recorded_at`.

### `POST /bdc/books`

```
{"ticker": "WHF"}
```

Read a lender now: for the first time, again to take in what it has filed
since, or again after a read that failed. Answers `202` with the request, whose
`status` is `queued`, then `reading`, then `ready`, `needs_work` or `failed`;
follow it at `GET /bdc/books/{ticker}`. A ticker we have not read before takes
a while: every quarterly filing since structured data began, in 2022 or 2023
for nearly every filer. Asking again while a request is open returns that
request. A CIK works where a lender has no ticker.

Reads wait their turn alongside everything else we read, so a busy day can
mean a wait. Nothing anyone asks for jumps the line.

### `GET /bdc/books/{ticker}`

The book's manifest (see "Ready, being read, or not here"):

- **200** with the book.
- **202** with the request while a read is under way, with `Retry-After`. For
  a lender we have never read, this request starts the read, so you don't
  need a `POST` first.
- **404** when there's nothing to read. That's a ticker that isn't a business
  development company, or one whose read failed in the last week; the message
  says why. Within that week only a `POST` reads it again. With `recorded_at`,
  a 404 also means we held no book for it by then, and asking that way never
  starts a read.

| Parameter | |
|---|---|
| `recorded_at` | Epoch seconds: the book as we held it then, not now. With it, a request returns the same answer every time. |

```json
{
  "ticker": "WHF", "lender": "whf", "name": "WhiteHorse Finance, Inc.",
  "cik": "0001552198",
  "status": "ready", "version": "87adfe96d67108e288f5",
  "recorded_at": 1791161463,
  "as_of": 1782777600, "first_as_of": 1664496000, "quarters": 16,
  "reconciliation": [{"as_of": 1782777600, "form": "10-Q", "read": 569290000,
                      "reported": 569202000, "reconciled": true}],
  "coverage": {"as_of": 1782777600, "share": 16.8},
  "lenders_read_in_full": 10,
  "tables": {
    "positions": {"rows": 3595, "sha256": "...",
                  "url": "/api/v1/bdc/books/WHF/positions?version=87adfe96d67108e288f5"},
    "...": {}
  },
  "caveats": ["Other lenders mark 17% of this book's direct fair value at 2026-06-30. Nothing here says anything about the rest.", "..."],
  "request": null
}
```

- `status` is `ready`, or `needs_work` when the positions we read do not sum
  to within 0.5% of the total the lender reports for its latest quarter.
  `reconciliation` shows both numbers either way.
- `coverage.share` is the percentage of the direct book's fair value in loans
  another lender also marks. A comparison says nothing about the rest.
- `caveats` are sentences for whoever reads the book, a model or a person.
  Read them before any number.
- `request` is a newer read under way while this version is served.

### `GET /bdc/books/{ticker}/{table}`

One table, as JSON lines (`application/x-ndjson`), one record per line, keys
sorted. Takes `version` (from the manifest; the latest if omitted) or
`recorded_at`. `X-Book-Version` names the version served. `pdatum bdc pull`
writes every table and the manifest to a folder.

| Table | One row per |
|---|---|
| `filings` | 10-Q or 10-K: `as_of`, `filed_at`, `accession`, positions read, the sum read against the total reported, and the `reader` that read them. The total is the one the filing itself reported, unless only a later filing's total for the same date matches what we read, or the filing reported none; `reported_in` names the filing it came from. |
| `positions` | Security per filing: `company`, `identifier` (the lender's own words), `class`, `principal` and `currency`, `cost`, `fair_value`, `mark`, rates in basis points, `maturity`, `acquired_at`. |
| `companies` | Company the lender has held: every name it is filed under, with its kind (`legal`, `trade`, `former`) and source, and the other lenders that hold it. |
| `comparisons` | Term loan per quarter that another lender also marks: this lender's mark, each other lender's, the median and the gap. |
| `events` | Change between consecutive filings: `entry`, `exit`, `reworded`, or the field that moved, with `before` and `after`. |
| `amendments` | Term change a lender reported on a shared loan: PIK on or off, spread, maturity extended. |
| `totals` | Figure the lender reports for its whole portfolio, from its XBRL: realized losses, NAV, debt, fair value, cost. As filed, restatements included. |
| `warn` | State WARN notice naming one of its borrowers. |
| `figures` | Figure a report would quote, already computed: `key`, `value`, `unit`, `as_of`, and `definition`. Quote these rather than working them out. |

Money is whole US dollars, except `principal`, which is in `currency`. A mark
is fair value per 100 of par, and `null` where there is no par to mark against,
where par is in another currency, and on undrawn commitments. No filer tags
non-accrual per loan; a mark below 80 is the usual proxy, and only a proxy.

A lender sometimes writes two holdings in exactly the same words, two tranches
of one loan for instance. Both are rows of `positions` with the same
`identifier`, so a filing's positions are not keyed by it alone; `events`
follows each of them, the larger with the larger.

## Companies

The registry: every business at least one lender we read reports holding,
under every name a filing gives it. A private borrower has no ticker and no
filings of its own; it is a line in its lenders' schedules, spelled a little
differently by each. A company is our join of those lines, and its `slug` is
the `company` in every book table. Read it on its own to match names, or beside
a book to know who each borrower is.

### `GET /companies`

Companies, in id order.

| Parameter | |
|---|---|
| `q` | Text in any of the company's current names. |
| `lender` | Only companies that lender has reported holding: its slug or ticker. |
| `domain` | An exact domain. |
| `limit`, `cursor` | As for `/jobs`. |

```json
{
  "slug": "acme-buyer-inc", "name": "Acme Fastening",
  "names": [
    {"name": "Acme Buyer, Inc.", "kind": "legal",
     "source": "whf-10q-2024-06-30-xbrl", "recorded_at": 1789862400},
    {"name": "Acme Fastening", "kind": "trade",
     "source": "mfic-10k-2025-12-31-xbrl", "recorded_at": 1790553600}
  ],
  "domain": "acmefastening.com",
  "employer": "acme-fastening",
  "lenders": ["mfic", "whf"],
  "created_at": 1789862400
}
```

- `kind` is `legal` (the registered entity that owes a security), `trade` (the
  name the business goes by) or `former` (a name it used to have).
- `source` is where we first read a name, and `recorded_at` when.
- `employer` is the slug of the matching record under `/employers`, or `null`
  when we have not matched the company to a website we could confirm.
- `lenders` are the slugs of every lender that has reported holding it.

### `GET /companies/{slug}`

One company. On top of the list fields it carries:

- `retired_names`: names we once read for it and no longer believe, each with
  `retired_at`. Kept, because someone may hold one.
- `held_by`: each lender and book (`direct` or `jv`) holding it, with the
  lender's ticker and the first and last `as_of` it was reported.
- `merged_into`: `null`.

**A slug never stops answering.** When two companies turn out to be one, the
one folded away keeps its slug, and asking for it returns
`{"slug": ..., "name": ..., "merged_into": "<the survivor's slug>", "merged_at": T}`
with a `Location` header for the survivor. Its names, positions and notices
are the survivor's now, so a book you pulled before shows them under the old
slug and the next one under the new. A slug is never given to another company.

### `GET /companies/resolve?name=...`

A name as someone wrote it, in; the company it belongs to, out.

```json
{"name": "Acme Buyer, Inc.", "status": "matched", "company": "acme-buyer-inc", "request": null}
```

- `status` is `matched`, with `company`; `ambiguous`, with `candidates`, and
  never a choice between them; or `unknown`, which means no company we hold has
  that name, not that no such business exists.
- Matching is on the name with case and spacing ignored, and nothing else:
  punctuation counts, so "Acme Buyer Inc" is not "Acme Buyer, Inc.". A near miss
  is `unknown`, because a wrong match is worse than none.
- An `unknown` answer lists `similar`, up to ten: companies with a name that is
  yours once case, punctuation and a trailing legal form are set aside
  (`"how": "spelling"`), then companies with a name containing yours word for
  word (`"contains"`). None of them is a match until you decide it is.
- `request` is the newest search for the name (below), or `null`.

### `POST /companies/resolve`

```
{"name": "Acme Buyer, Inc."}
```

The same answer, for any name. When we hold it, `200`. When we do not, we look
for it: `202`, with a `request` whose `status` is `queued`, then `searching`,
`reading` and `done`, or `failed`. Follow it with `GET /companies/resolve?name=`.

A search asks EDGAR's full text search which 10-Qs and 10-Ks write the name
down, keeps the filers that are business development companies, and reads
every one we have not read, as `POST /bdc/books` would. The request lists them
in `lenders`, each with its `status`: `read` (we had), `partial` (read only for
borrowers we already knew, so it will not add this one), or its book's status.
A lender we have never read takes a while, so a search can take hours.

When it is `done`, the answer is the registry's again, with everything those
filings say. It can still be `unknown` -- the filings wrote something containing
your name, and `similar` lists what -- and `lenders: []` means no BDC we can find
names it. Asking again while a search is open, or within a week of one
finishing, returns that search; after that, the name is searched afresh.

## WARN notices

An employer with 100 or more staff has to give 60 days' notice of a mass
layoff or a closure, and each state publishes the notices it gets, in its own
format. Here is every notice from every state we read, in one shape. Where the
employer's name is a company we track or an employer we hold a record for,
the notice links to it.

Not every state is read. **Check `/warn/states` before you count anything by
state.** A state we don't read isn't a state with no layoffs.

So `/warn`, `/warn/count` and `/warn/changes` never answer a state they hold
no notices from as if it had none. A query covers the states it names in
`state`, or every state we read if it names none. Whatever other filters it
has, it gets one of these (see "Ready, being read, or not here"):

- **404** when every state it names is one we don't read. The message says
  why we don't read each one.
- **202** when nothing it covers has been read yet, because those states are
  waiting for their first read. The body names them, and `Retry-After` gives
  a time in seconds:

  ```json
  {"data": {"status": "waiting", "states": ["ny", "tx"]}}
  ```

- **200** otherwise. Its `unread` lists the states it covers that its answer
  holds nothing from: states it named that we don't read, and states still
  waiting for their first read. It's `[]` when nothing was left out. Read it
  before you treat a count as complete.

  ```json
  {"data": [...], "next_cursor": null, "total": 2, "unread": ["tx"]}
  ```

### `GET /warn`

Notices, by notice date, newest first. Notices whose state gave no notice
date come last.

| Parameter | |
|---|---|
| `state` | A two-letter state code, like `tx`. Repeat it for more than one state. |
| `company` | A company slug, from `/companies`. |
| `employer` | An employer slug, from `/employers`. |
| `q` | Text in the employer's name, as the state wrote it. |
| `notice_since`, `notice_before` | Epoch seconds. These filter on the notice date, so they leave out notices without one. |
| `limit`, `cursor` | As for `/jobs`. |

```json
{
  "id": 4821,
  "state": "tx",
  "employer": "Unleashed Brands (Towson)",
  "location": "Bedford, Tarrant",
  "workers": 48,
  "kind": null,
  "notice_at": 1716422400,
  "effective_at": 1716249600,
  "company": "unleashed-brands",
  "matched": "Unleashed Brands",
  "employer_slug": null,
  "source": "https://www.twc.texas.gov/data-reports/warn-notice",
  "observed_at": 1790553600
}
```

- `employer`, `location` and `kind` are the state's own words. `kind` is how
  the state labels the notice, like layoff, closure or temporary. Many states
  don't label it, so it's often `null`.
- `workers` is how many people the notice says are affected. It's `null` when
  the state doesn't publish a count; Missouri never does.
- `notice_at` is when the employer gave notice. `effective_at` is when the
  layoff starts. Either one is `null` when the state leaves it out.
  `notice_at` is also `null` when the state's date can't be real: notice comes
  before a state publishes it, so a notice date more than a day after we read
  the notice is a typo, and we don't guess what was meant. Rhode Island lists
  two notices from 2018 as given in 2108.
- `company` is the slug of the company under `/companies` whose name this
  employer's name is, and `matched` is that name. `employer_slug` is the same
  thing for `/employers`. Both are `null` when there's no such record, which
  is true of most notices.
- **A link means the names are the same, not that we confirmed it's the same
  business.** We ignore case, punctuation and a legal form like Inc or LLC,
  plus a site in parentheses at the end. Nothing else is ignored, and a longer
  name never matches a shorter one. A name that two of our records share
  isn't linked to either. A one-word name only links when the word is
  distinctive, or when the legal form matches too. A company's former names
  never link, because the old name usually belongs to some other business by
  then. Check a link before you rely on it.
- `source` is the page where the state publishes its notices.
- `observed_at` is when we first read the notice. We keep every notice we've
  read, including ones the state later took down: New York, for one, shows
  only the current year.

### `GET /warn/count`

Takes the same filters as `/warn` and returns `{"data": {"count": n}, "unread": [...]}`.

### `GET /warn/changes?since=T`

Every notice we read for the first time after `T`, plus every notice that got
a new `company` or `employer_slug` link after `T`, or that we corrected after
`T`, like a `notice_at` we found couldn't be real. Oldest change first, and
each record carries `changed_at`. It takes `state`, `limit` and `cursor`. A
link appears when a company or employer record shows up after the notice, so
a notice from last year can come through again. Sync it the way you sync
`/jobs/changes`, upserting by `id`.

### `GET /warn/states`

Every state and DC, whether we read it or not. Not paged.

```json
{
  "state": "tx", "read": true, "unread_because": null,
  "source": {"name": "Texas Workforce Commission",
             "url": "https://www.twc.texas.gov/data-reports/warn-notice"},
  "last_read_at": 1790035200, "rows_read": 2510,
  "notices": 2510, "first_notice_at": 1577923200, "last_notice_at": 1789948800
}
```

- We read every state with a reader of our own. Every request we make
  identifies itself as pdatum, so we don't read a state whose site only
  answers a browser in disguise, or only answers with certificate checks
  turned off.
- `unread_because` says why we don't read a state yet.
- `last_read_at` is when we last read the state's site, and `rows_read` is
  how many notices it showed then. If `last_read_at` stays old, our reader
  has stopped working: that's a gap in our data, not a quiet month for the
  state. Both are `null` for a state we read that is still waiting for its
  first read; queries over it answer `202` until then.
- `notices` is how many notices we hold from the state. It can be more than
  `rows_read`, because we keep the notices a state has taken down.
- `first_notice_at` and `last_notice_at` are the oldest and newest notice
  dates we hold for the state.

## Franchise filings

Before a franchisor sells franchises in some states, it files there: either
a registration, or a notice that it's exempt from registering. Each state
lists those filings in its own format. Here is every filing from every state
we read, in one shape. Texas's list goes back to 1985. Florida's holds every
franchisor whose exemption is current there, plus the ones that lapsed in the
last year, and we keep each one once we've read it.
Where one of the franchisor's names is a company we track or an employer we
hold a record for, the filing links to it.

A franchisor usually files under a company named for its brand, not the
company a lender holds. Lift Brands files as Snap Fitness, Inc., for example.
So most filings link to nothing by name. A filing can also link to a company
because one of us reviewed the link and recorded the evidence, such as a
state's order naming the brand, or the parent named in the disclosure
document. `evidence` says which kind of link you're looking at.

Not every state is read. **Check `/franchises/states` before you count
anything by state.** A state we don't read isn't a state with no franchisors.
`/franchises`, `/franchises/count` and `/franchises/changes` answer `404`,
`202` and `200` exactly as `/warn` does, with `unread` on every `200`.

### `GET /franchises`

Filings, newest filing date first. Filings without a usable date come last.

| Parameter | |
|---|---|
| `state` | A two-letter state code, like `tx`. Repeat it for more than one state. |
| `company` | A company slug, from `/companies`. |
| `employer` | An employer slug, from `/employers`. |
| `q` | Text in the franchisor's names, as the state wrote them. |
| `status` | `registered`, `exempt`, `expired` or `terminated`. |
| `filed_since`, `filed_before` | Epoch seconds. These filter on `filed_at`, so they leave out filings without one. |
| `limit`, `cursor` | As for `/jobs`. |

```json
{
  "id": 11029,
  "state": "tx",
  "filing": "2025-0413",
  "filed_as": "PP FRANCHISE LLC",
  "name": "PP FRANCHISE LLC",
  "names": [{"name": "PP FRANCHISE LLC", "kind": "legal"}],
  "kind": "exemption",
  "status": "exempt",
  "state_status": null,
  "filed_at": 1753142400,
  "registered_at": null,
  "exempt_at": 1753142400,
  "terminated_at": null,
  "expires_at": null,
  "address": "3275 NEWPORT HIGHWAY, BUILDING 5, SEVIERVILLE, TN 37876",
  "city": "SEVIERVILLE",
  "region": "TN",
  "zip": "37876",
  "company": "pepper-palace-inc",
  "matched": null,
  "evidence": "California DFPI's order of 9 Sep 2025 (APP00003140) registers PP Franchise LLC as the franchisor of Pepper Palace",
  "employer_slug": null,
  "source": "https://direct.sos.state.tx.us/businessopportunity/BusOpSearch.asp",
  "observed_at": 1793289600
}
```

- `filing` is the state's own number for the filing: a Texas file number like
  `2025-0413`, or a Florida license number like `BF52617`. Texas reused some
  numbers in the 1980s, so a number alone doesn't identify a filing, though
  `id` does. Some old Texas filings have no number at all.
- `filed_as` is the franchisor's name exactly as the state wrote it, often
  several names on separate lines. Florida writes the franchisor's name and its
  brands in two fields, so its `filed_as` has them on two lines. `names` splits
  it up: the franchisor's `legal` name first, then its brands (`trade`) and the
  names it used to have (`former`). `name` is the legal name. Florida tags some
  brands with how they're offered, like "(Unit)", or with "(R)". Those tags
  aren't in `names`.
- `kind` is `registration` or `exemption`. `status` is `registered`,
  `exempt`, `expired` or `terminated`. `expired` means a filing the state
  renews every year wasn't renewed. `terminated` means the franchisor or the
  state ended it. Texas marks every filing's status the same way, so we work
  out its status from its dates, and either field is `null` when Texas gave
  no date to go on.
- `state_status` is the status in the state's own words, where those say more
  than `status` does. Florida's are `Registered`, `Expired`, `Cancelled`,
  `Closed - Out of Business` and `Closed - Change of Owner`, among others.
  A Florida exemption on file reads `Registered` there, and its `status` is
  `exempt`. Florida's `Not Soliciting` and `Law NA` have a `status` of `null`.
  `state_status` is `null` for Texas.
- `filed_at` is when the franchisor registered or filed its exemption. In
  Florida, that's when its license was first issued.
  `registered_at`, `exempt_at` and `terminated_at` are the dates the state
  lists. Florida doesn't date a termination. `expires_at` is when a filing the
  state renews every year runs out unless it's renewed, so for an `expired`
  filing it's when it lapsed. A date the state wrote that can't be real (some
  Texas years read 0222 or 3007) is `null`.
- `address` is the franchisor's address as the state lists it, on one line.
  `region` (the state or province) and `zip` come from its end, and `city`
  from its last line in Texas, or from the city Florida lists separately. Each
  is `null` when the address doesn't read as one.
- `company` is the slug of a company under `/companies`. When one of the
  filing's legal or brand names is that company's name, `matched` is the name
  that matched, by the same rule as `/warn`. Former names never link. When
  one of us reviewed the link instead, `matched` is `null` and `evidence` says
  what it rests on. A reviewed link replaces a link by name. `employer_slug`
  is the same for `/employers`, by name only. All of these are `null` for
  most filings.
- **A link by name means the names are the same, not that we confirmed it's
  the same business.** Check one before you rely on it.
- The state's contact for a filing isn't served: it often names a person.
- `observed_at` is when we first read the filing. We keep every filing we've
  read.

### `GET /franchises/count`

Takes the same filters as `/franchises` and returns `{"data": {"count": n}, "unread": [...]}`.

### `GET /franchises/changes?since=T`

Every filing we read for the first time after `T`, plus every filing the
state changed after `T` (a termination date, a brand added, a new address, a
yearly renewal that moves `expires_at`) or that got a new `company` or
`employer_slug` link. Oldest change first, and
each record carries `changed_at`. It takes `state`, `limit` and `cursor`. Sync
it the way you sync `/jobs/changes`, upserting by `id`.

### `GET /franchises/states`

Every state and DC, whether we read it or not. Not paged.

```json
{
  "state": "tx", "read": true, "unread_because": null,
  "source": {"name": "Texas Secretary of State",
             "url": "https://direct.sos.state.tx.us/businessopportunity/BusOpSearch.asp"},
  "last_read_at": 1793289600, "rows_read": 16348,
  "filings": 16320, "first_filed_at": 501206400, "last_filed_at": 1793116800
}
```

- `unread_because` says why we don't read a state. Some states publish
  nothing online. Some put their search behind a CAPTCHA, which we don't
  solve. For some we haven't written a reader yet. `source` says where a
  person can look when a state has a page.
- `last_read_at` is when we last read the state's list, and `rows_read` is
  how many rows it showed then. If `last_read_at` stays old, our reader has
  stopped working. We read each state once a week.
- `filings` is how many filings we hold from the state. It can be less than
  `rows_read`, because a state's list can show the same filing twice.
- `first_filed_at` and `last_filed_at` are the oldest and newest filing dates
  we hold for the state.

## Private capital raises

A company that sells securities privately under Regulation D files a Form D
with the SEC within 15 days of its first sale. The form says who the company
is, which exemption it relies on, how much it's offering, how much it has sold
and to how many investors. For a private company, that's often the only
number it ever publishes. Here is every Form D an operating company has filed
since 2008: 360,000 filings from 186,000 companies by the end of September
2026, with a few hundred more each business day. Where the company's name is
a company we track or an employer we hold a record for, the filing links to it.

Pooled investment funds (hedge, private equity, venture and other funds)
file Form Ds too, and aren't included. Neither are the people a Form D names,
its related persons and signers.

Every `200` carries `read_through`: the last day whose Form Ds we hold all of,
in epoch seconds. Until our first read there is nothing to answer with, so
`/raises`, `/raises/count` and `/raises/changes` answer `202` with
`{"status": "waiting"}`.

### `GET /raises`

Filings, newest filing date first.

| Parameter | |
|---|---|
| `company` | A company slug, from `/companies`. |
| `employer` | An employer slug, from `/employers`. |
| `cik` | The issuer's SEC Central Index Key, a number. |
| `q` | Text in the issuer's name, as this filing gives it. |
| `industry` | One of the SEC's industry groups, such as `Biotechnology`, `Other Technology` or `Restaurants`. Not case-sensitive. An unknown one is refused with the list. |
| `region` | A US state's two letters, such as `CA`, for the issuer's address. |
| `min_sold` | Whole dollars: only filings that report at least this much sold. |
| `filed_since`, `filed_before` | Epoch seconds, on `filed_at`. |
| `limit`, `cursor` | As for `/jobs`. |

```json
{
  "id": 355880,
  "accession": "0001974654-26-000003",
  "form": "D",
  "amends": null,
  "offering": "021-597236",
  "filed_at": 1789084800,
  "cik": 1974654,
  "name": "Harvey AI Corp",
  "names": [{"name": "Harvey AI Corp", "kind": "legal"},
            {"name": "Counsel AI Corp", "kind": "former"}],
  "co_issuers": [],
  "entity_type": "Corporation",
  "jurisdiction": "DELAWARE",
  "incorporated": "2022",
  "address": "201 THIRD STREET\nSUITE 500",
  "city": "SAN FRANCISCO",
  "region": "CA",
  "country": null,
  "zip": "94103",
  "industry": "Other Technology",
  "revenue_range": "Decline to Disclose",
  "exemptions": ["06b"],
  "securities": ["equity"],
  "business_combination": false,
  "first_sale_at": 1787875200,
  "first_sale_yet_to_occur": false,
  "offered": null,
  "offered_indefinite": true,
  "sold": 550299446,
  "remaining": null,
  "min_investment": 0,
  "investors": 28,
  "non_accredited_investors": 0,
  "sales_commissions": 0,
  "finders_fees": 0,
  "paid_to_related_persons": 0,
  "company": "harvey-ai-corporation",
  "matched": "Harvey AI Corporation",
  "employer_slug": null,
  "source": "https://www.sec.gov/Archives/edgar/data/1974654/000197465426000003/0001974654-26-000003-index.htm",
  "observed_at": 1793893646
}
```

- `accession` is the SEC's number for this filing, and `source` is its page on
  EDGAR. `form` is `D` for a new notice or `D/A` for an amendment, and
  `amends` is the accession number an amendment changes. An amendment usually
  updates `sold` and `investors`, so the newest filing of an offering says how
  far it got.
- `offering` is the SEC's file number for the offering, shared by every
  filing of it. A filing from the last few weeks may have `null` here until
  the SEC's quarterly data set gives it, which counts as a change.
- `name` is the issuer as this filing names it. `names` adds the names it
  says it used before (`former`). `co_issuers` lists any other issuers on the
  same filing, each with its `name` and `cik`.
- `incorporated` is the year, or `"over five years ago"`, `"within five
  years"` or `"yet to be formed"` when the filer gave no year.
- `region` is the issuer's US state, and `null` outside the US, where
  `country` says where, as the SEC writes it.
- `industry` and `revenue_range` are the filer's own answers.
  `revenue_range` is often `"Decline to Disclose"`.
- `exemptions` are the rules the filer relies on, in the form's codes: `06b`
  and `06c` are Rule 506(b) and 506(c), `04` is Rule 504, and `3C.1` and
  `3C.7` are the Investment Company Act exclusions. `securities` is what is on
  offer: `equity`, `debt`, `option or warrant`, `other: ...` with the filer's
  description, and so on.
- `offered` is the total offering, `null` with `offered_indefinite: true` when
  the filer gave no limit. `sold` is how much has been sold so far,
  `remaining` what is left (`null` when indefinite), and `investors` how many
  have already invested. Amounts are whole US dollars.
- `first_sale_at` is the date of the first sale, or `null` with
  `first_sale_yet_to_occur: true`.
- `sales_commissions` and `finders_fees` are what the filer paid to sell the
  offering. `paid_to_related_persons` is how much of the money goes to its own
  executive officers, directors or promoters.
- `company`, `matched` and `employer_slug` link the issuer by name, by the
  same rule as `/warn`. Former names never link. **A link by name means the
  names are the same, not that we confirmed it's the same business**: a
  common name can link several issuers to one company. `cik` and the address
  tell issuers apart.
- `observed_at` is when we first read the filing.

### `GET /raises/count`

Takes the same filters as `/raises` and returns
`{"data": {"count": n}, "read_through": T}`.

### `GET /raises/changes?since=T`

Every filing we read for the first time after `T`, plus every filing the SEC's
record changed after `T` or that got a new `company` or `employer_slug` link.
Oldest change first, and each record carries `changed_at`. It takes `limit`
and `cursor`. Sync it the way you sync `/jobs/changes`, upserting by `id`.

## `GET /me`

The key you are calling with: its name, holder, scopes and expiry, plus
`usage` for today and the last 30 days. Usage counts requests, and records
returned.

## MCP

AI apps that call tools can use pdatum as an MCP server, at

```
https://pdatum.pearachute.com/mcp
```

In Claude, open **Settings › Connectors**, choose **Add custom connector**,
name it `pdatum` and paste the address. **Connect** opens a pdatum page that
asks for your key; paste it and choose **Allow**. ChatGPT connects the same
way in Developer mode, with OAuth chosen and the client ID and secret left
empty. The app then uses your key, so revoking the key disconnects it.

Apps you configure yourself can send the key as a header instead,
`Authorization: Bearer pdatum_...`. In Claude Code:

```
claude mcp add --transport http pdatum https://pdatum.pearachute.com/mcp --header "Authorization: Bearer pdatum_..."
```

In Cursor, in `~/.cursor/mcp.json`:

```json
{"mcpServers": {"pdatum": {"url": "https://pdatum.pearachute.com/mcp",
                           "headers": {"Authorization": "Bearer pdatum_..."}}}}
```

Each tool is one of the endpoints above, called with your key, so it reads
what your key's scopes allow, shares its rate limit, and counts in its usage.

| Tool | Endpoint |
|---|---|
| `search_jobs`, `get_job` | `GET /jobs`, `GET /jobs/{id}` |
| `search_employers`, `get_employer` | `GET /employers`, `GET /employers/{slug}` |
| `get_federal_awards` | `GET /awards` |
| `get_bdc_book`, `read_bdc_table` | `GET /bdc/books/{ticker}`, `GET /bdc/books/{ticker}/{table}` |
| `request_bdc_read` | `POST /bdc/books` |
| `search_companies`, `get_company` | `GET /companies`, `GET /companies/{slug}` |
| `resolve_company`, `request_company_search` | `GET` and `POST /companies/resolve` |
| `search_warn_notices`, `list_warn_states` | `GET /warn`, `GET /warn/states` |
| `search_franchise_filings`, `list_franchise_states` | `GET /franchises`, `GET /franchises/states` |
| `search_raises` | `GET /raises` |

Answers are the endpoints' own, with three changes for a model:

- Times are UTC dates, not epoch seconds: `2026-09-30` for a day, and
  `2026-09-30T01:00:00Z` when the time of day is known. Time filters take a
  date, a date and time, epoch seconds, or an age such as `7d`.
- A `202` is `{"ready": false, ...}`, with when to ask again.
- `read_bdc_table` serves a table a slice at a time, with `offset` and
  `limit`, and says how many rows it has.

Counting is a search's `total`. The changes feeds aren't tools: sync with
the API or `pdatum`.

The server speaks MCP's Streamable HTTP transport, stateless, with JSON
responses, and protocol versions 2024-11-05 to 2025-11-25. Sign-in is OAuth
2.1 with PKCE (S256) and dynamic client registration, described at
`/.well-known/oauth-authorization-server`; the token it issues is your key.
