API-reference

GET/api/v1/vendors

List watched vendors with coverage

The whole inventory by default. Pass limit to opt into cursor paging for inventories that have outgrown one response.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/vendors \
  -H "Authorization: Bearer npk_..."

Eksempel på svar

{
  "vendors": [
    {
      "public_id": "ent_cloudflare",
      "status": "active",
      "notice_period_days": 30,
      "watched_since": "2026-05-01T09:00:00Z",
      "entity": {
        "public_id": "ent_cloudflare",
        "name": "Cloudflare, Inc.",
        "slug": "cloudflare",
        "domain": "cloudflare.com",
        "country_code": "US",
        "country": "United States",
        "operating_country_codes": [
          "US",
          "DE"
        ],
        "hq_address": "101 Townsend St, San Francisco, CA",
        "contact_info": {},
        "category_code": "cdn",
        "category": "CDN and edge",
        "disclosure_status": "resolved",
        "resolved_from": null
      },
      "coverage": {
        "node_count": 42,
        "resolved": 31,
        "publishes_nothing": 6,
        "not_yet_crawled": 5,
        "coverage_pct": 73.8,
        "computed_at": "2026-08-18T04:10:00Z"
      }
    }
  ],
  "meta": {
    "count": 1,
    "has_more": false,
    "next_cursor": null,
    "depth_limit": null
  }
}

Fejl

POST/api/v1/vendors

Start watching a vendorkræver write-scope

201 with created: true for a new watch; 200 with created: false when the vendor was already watched — a retry after a timeout lands there, not on an error. Refused with limit_reached when the plan's vendor allowance is used up.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/vendors \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"entity_public_id":"ent_stripe","notice_period_days":60}'

Fejl

GET/api/v1/vendors/{entity_public_id}

One watched vendor

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/vendors/... \
  -H "Authorization: Bearer npk_..."

Fejl

PATCH/api/v1/vendors/{entity_public_id}

Update a vendor's notice periodkræver write-scope

Parametre

Eksempel på forespørgsel

curl -X PATCH https://nthparty.io/api/v1/vendors/... \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"notice_period_days":30}'

Fejl

DELETE/api/v1/vendors/{entity_public_id}

Stop watching a vendorkræver write-scope

The watch is deleted; the alerts it produced stay — evidence does not un-happen.

Parametre

Eksempel på forespørgsel

curl -X DELETE https://nthparty.io/api/v1/vendors/... \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/vendors/{entity_public_id}/pause

Pause a vendorkræver write-scope

"Stop telling me about this." The change feed skips a paused vendor; the inventory and the graph still answer for it. Idempotent.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/vendors/.../pause \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/vendors/{entity_public_id}/resume

Resume a paused vendorkræver write-scope

Idempotent for a vendor that is already active. Refused with limit_reached when the vendor sits outside the plan's vendor allowance — the oldest vendors hold it, and a vendor a downgrade paused is outside it by definition. Remove an older vendor or change plan, then resume.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/vendors/.../resume \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/vendors/{entity_public_id}/graph

The subgraph beneath a vendor, as a tree

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/vendors/.../graph \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/vendors/{entity_public_id}/list

The same walk, flat

Root dropped — a vendor is not its own subprocessor — and ordered by depth. The endpoint a vendor-inventory export is built from.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/vendors/.../list \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/entities

Search companies

Exactly one of q (fuzzy name search, minimum 2 characters) or domain (exact lookup). Each row carries watched and watchlisted — this account's relationship to the company.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/entities \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/entities/{public_id}

One company

Answers for any company in the dataset, watched or not. Ids are durable — a merged-away id resolves to its survivor and says so in resolved_from.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/entities/... \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/changes

The change feed

Changes beneath the account's actively watched vendors, newest first, cursor-paginated. Defaults to the last 30 days; since widens or narrows the window. Bad filter values are refused, never ignored.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/changes \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/changes/{public_id}

One change, with its evidence

The change, the path from the watched vendor down to the company that moved, and the disclosure as published — evidence.raw_excerpt is quoted in its original language, beside the translated summary, never instead of it.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/changes/... \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/changes/{public_id}/evidence

One change's evidence artifact, as a file

The same artifact the console downloads (spec §7: "timestamped and suitable for pasting into a risk report"), in either of two content types from one field list. The format is a query parameter rather than a path extension, so a change id containing a dot stays an id. Defaults to CSV — the format every spreadsheet, GRC tool and ticket system reads. A change beneath no vendor this account watches is a 404, exactly as on the change itself.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/changes/.../evidence \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/alerts

The alert inbox

Open alerts by default — the inbox is about what is unhandled. meta.counts answers "is anything waiting" without fetching rows. Cursor-paginated.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/alerts \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/alerts/{id}/acknowledge

Acknowledge an alertkræver write-scope

"I have looked." Does not stop alerting and hides nothing. Idempotent — the stored timestamp is the first one, so a client that cannot tell whether its POST landed sends it again.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/alerts/.../acknowledge \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/alerts/{id}/dismiss

Dismiss an alertkræver write-scope

"This does not matter here" — the verb that closes an alert, for the ticketing integration reflecting a resolution made by a person. Requires a key deliberately minted with the write scope. Idempotent.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/alerts/.../dismiss \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/exposure

Which of my vendors depend on this company?

"Not exposed" is an answer, not an empty state: exposed: false travels with the count checked and the named clear list. An unknown id is a 404 — "we have never heard of that company" and "none of your vendors reach it" are opposite findings.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/exposure?entity=... \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/concentration

The portfolio concentration report

Counted over deduplicated entities, top 12 providers, each with the watched vendors that reach it. Requires the concentration entitlement (Pro) in addition to API access; refused with plan_required otherwise. The coverage caveat travels with the report — concentration is computed over what is resolved.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/concentration \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/compare

Two vendors' chains, side by side

Shared dependencies, what only one side brings, and each side's coverage — either side can be any company. A side that cannot be resolved is refused naming the side, so a script comparing a candidate list knows which id to fix.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/compare?a=...&b=... \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/watchlist

List watchlist entries

Each entry answers "is this company in my graph today, and through which vendors?" live. in_graph is three-valued: true, false, or null when the id no longer names a company.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/watchlist \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/watchlist

Add a company to the watchlistkræver write-scope

201 with created: true for a new entry; 200 with created: false when the company was already listed — the same statement made twice.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/watchlist \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"entity_public_id":"ent_openai","note":"Named in the incident review 2026-08"}'

Fejl

DELETE/api/v1/watchlist/{entity_public_id}

Remove a company from the watchlistkræver write-scope

Parametre

Eksempel på forespørgsel

curl -X DELETE https://nthparty.io/api/v1/watchlist/... \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/rules

List rules

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/rules \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/rules

Create a rulekræver write-scope

Validation is the model's — the same gate the console builder runs, so the API cannot accept a rule the builder would refuse. An empty condition_tree is the catch-all. Refusals carry error.errors (field → messages) beside the sentence.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/rules \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Critical jurisdictions","severity":"critical","delivery_mode":"immediate","scope":"account","channels":["email","webhook"],"condition_tree":{"kind":"group","join":"and","children":[{"kind":"condition","field":"change.type","op":"is","value":"jurisdiction_shift"}]}}'

Fejl

POST/api/v1/rules/preview

Dry-run a rule without saving itkræver write-scope

What would this rule have matched, and what does it match now? The probe is validated exactly as a save would be, so the preview cannot accept a shape the save would reject. A POST (the tree travels in the body), so it sits behind the write scope — the caller previewing a rule is the caller about to write one.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/rules/preview \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"account","condition_tree":{"kind":"group","join":"and","children":[{"kind":"condition","field":"change.type","op":"is","value":"entity_added"}]}}'

Fejl

GET/api/v1/rules/{public_id}

One rule

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/rules/... \
  -H "Authorization: Bearer npk_..."

Fejl

PATCH/api/v1/rules/{public_id}

Update a rulekræver write-scope

Only the keys sent are touched — {"enabled": false} is the toggle; there is no separate toggle path.

Parametre

Eksempel på forespørgsel

curl -X PATCH https://nthparty.io/api/v1/rules/... \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Fejl

DELETE/api/v1/rules/{public_id}

Delete a rulekræver write-scope

Parametre

Eksempel på forespørgsel

curl -X DELETE https://nthparty.io/api/v1/rules/... \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/exports

List exports

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/exports \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/exports

Request an exportkræver write-scope

Asynchronous by design — answers **202** with a pending row; poll GET /api/v1/exports/{public_id} until it is done. vendor and since apply to change_history_csv only; a vendor not actively watched is refused rather than ignored. A change_history_csv file holds at most the 200 most recent changes matching its filters — for a longer history, narrow it by vendor or page the change feed (GET /api/v1/changes). The export and its file are deleted 30 days after it completes.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/exports \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"kind":"change_history_csv","since":"2026-07-01T00:00:00Z"}'

Fejl

GET/api/v1/exports/{public_id}

Poll one export

Three-state status; failed carries its reason and download_path is null until the file exists. 30 days after completion the export is deleted and this answers 404.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/exports/... \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/exports/{public_id}/download

Download the file

The one endpoint whose success response is a file, not JSON. Streams through the app with the stored content type and filename. A file not (or never) available is a **409** with code not_ready — poll the export until it is done. Files are kept for 30 days after the export completes, then deleted with the export (404).

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/exports/.../download \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/attestations

List closed-month attestations

Newest month first, cursor-paginated. A closed month never changes, which is what makes an old attestation still worth quoting. Months that have been claimed and not yet signed are not listed.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/attestations \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/attestations/current

The rolling 30-day attestation

Built and signed on this request. It is never stored, because a document about "the last 30 days" is stale the moment it lands in a row — so public_id and download_path are null on it. This is the endpoint a continuously-syncing connector polls.

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/attestations/current \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/attestations/keys

The public keys attestations are verified against

Every signature names its key by id; this is where that id resolves. Retired keys stay listed so documents issued before a rotation keep verifying. Keys are raw 32-byte Ed25519 public keys, base64url without padding — a verifier wants 32 bytes, not a certificate container.

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/attestations/keys \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/attestations/{public_id}/download

Download the attestation as a PDF

The same document as a page, rendered from the stored payload and never recounted, so the file and the JSON cannot disagree about a month. The signature, its key id and the verification recipe are printed on the page. A month claimed and not yet signed is a **409** with code not_ready.

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/attestations/.../download \
  -H "Authorization: Bearer npk_..."

Fejl

GET/api/v1/webhook_endpoints

List webhook endpoints

Never includes the signing secret.

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/webhook_endpoints \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/webhook_endpoints

Create a webhook endpointkræver write-scope

The response carries secret — **the only time it is shown besides a rotation**. Store it; it cannot be read back. Events default to everything catalogued. The URL must be public HTTPS we can reach. The companion notification channel is created with it, so alerts and raw change events arrive at the same destination.

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/webhook_endpoints \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/nthparty","description":"SIEM intake","events":["alert.created"]}'

Fejl

GET/api/v1/webhook_endpoints/{public_id}

One webhook endpoint

Parametre

Eksempel på forespørgsel

curl https://nthparty.io/api/v1/webhook_endpoints/... \
  -H "Authorization: Bearer npk_..."

Fejl

PATCH/api/v1/webhook_endpoints/{public_id}

Update a webhook endpointkræver write-scope

Re-enabling a disabled endpoint asks for its own parameter (active: true) — a save that fixes a URL does not silently restart a receiver the dispatcher shut off.

Parametre

Eksempel på forespørgsel

curl -X PATCH https://nthparty.io/api/v1/webhook_endpoints/... \
  -H "Authorization: Bearer npk_..." \
  -H "Content-Type: application/json" \
  -d '{"active":true}'

Fejl

DELETE/api/v1/webhook_endpoints/{public_id}

Delete a webhook endpointkræver write-scope

Tears down the endpoint and its companion channel together.

Parametre

Eksempel på forespørgsel

curl -X DELETE https://nthparty.io/api/v1/webhook_endpoints/... \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/webhook_endpoints/{public_id}/rotate_secret

Rotate the signing secretkræver write-scope

A planned rotation with a 24-hour overlap: both secrets sign until the window closes, so the consumer deploys the new one without a minute where verification fails. The new secret is in this response and nowhere else.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/webhook_endpoints/.../rotate_secret \
  -H "Authorization: Bearer npk_..."

Fejl

POST/api/v1/webhook_endpoints/{public_id}/regenerate_secret

Regenerate the signing secret (no overlap)kræver write-scope

For a leaked secret. Issues a new secret and discards the old one — and any previous secret still inside a rotation window — at once, so the next delivery is signed with the new secret only. Deliveries fail verification until the consumer deploys it. The new secret is in this response and nowhere else.

Parametre

Eksempel på forespørgsel

curl -X POST https://nthparty.io/api/v1/webhook_endpoints/.../regenerate_secret \
  -H "Authorization: Bearer npk_..."

Fejl