# API

Every route of the Guardian console API and the ingest host, authentication, roles, error shape and status codes.

Guardian has two hosts:

| Host | Serves |
|---|---|
| `https://guardian.vulnes.is` | The Resolve Platform API under `/v1/guardian/...`, the AWS templates under `/v1/templates/...`, `/v1/health` |
| `https://ingest.vulnes.is` | Log ingest under `/v1/ingest/...`, authenticated by [ingest token](/siem/sources/ingest-tokens.md) |

## Authentication

Resolve Platform API requests carry `Authorization: Bearer <access token>`, the OIDC access token of a signed-in Resolve Platform session (an RS256 JWT issued by Vulnesis sign-in). Guardian verifies it, looks up the user, and resolves your organisation from the user. No route takes an organisation from the request. Vulnesis API keys are not accepted here.

The template downloads and `/v1/health` need no token.

## Access

| Condition | Answer |
|---|---|
| Not signed in, or the token is invalid or expired | `401` |
| Plan below Business, or no active ingest pack | `402` with `needs: "business"` or `needs: "pack"` (every route but `me`, `help` and billing) |
| Not an owner or admin, on token, Cloudflare and billing checkout routes | `403` |

Errors are JSON: `{ "error": "<message>", "code": "<code>" }`, plus `needs` on a `402`. Codes include `sign_in` (401), `plan` (402), `compile`, `source`, `limit`, `exists` and `in_use` (400), `budget` (429) and `internal` (500).

## Resolve Platform API

All paths are under `https://guardian.vulnes.is/v1/guardian`.

| Method and path | Does | Page |
|---|---|---|
| `GET /me` | Organisation, plan, role, whether Guardian is active and what it `needs`, the pack and subscription, packs on sale, today's ingest state, limits | |
| `POST /billing/checkout` | `{ pack, returnUrl? }`: a Stripe checkout for `guardian_5`, `guardian_25` or `guardian_100`. `409` if a subscription is already active. | [Packs](/siem/reference/packs-and-limits.md) |
| `POST /billing/portal` | `{ returnUrl? }`: the Stripe portal to change or cancel the pack | [Packs](/siem/reference/packs-and-limits.md) |
| `GET /help` | Templates, syntax and table columns | [Syntax](/siem/search/syntax.md) |
| `POST /search` | Run a search | [Syntax](/siem/search/syntax.md#api) |
| `POST /compile` | The SQL a search would run | [Syntax](/siem/search/syntax.md#api) |
| `POST /translate` | Search language to Sigma or back | [Syntax](/siem/search/syntax.md#switching-to-sigma) |
| `GET, POST /searches`; `PATCH, DELETE /searches/{id}` | Saved searches | [Saved searches](/siem/search/saved-searches.md) |
| `GET, POST /rules`; `GET, PATCH, DELETE /rules/{id}` | Alert rules | [Rules](/siem/detection/rules.md) |
| `POST /rules/upload` | Up to 200 Sigma files | [Rules](/siem/detection/rules.md#upload) |
| `POST /rules/{id}/suppressions`; `DELETE /rules/{id}/suppressions/{n}` | Suppressions | [Rules](/siem/detection/rules.md#tuning) |
| `POST /rules/{id}/test`, `POST /rules/{id}/backfill`, `GET /rules/{id}/runs` | Test, backfill, run history | [Rules](/siem/detection/rules.md#test-and-backfill) |
| `GET /catalogue?q=` | SigmaHQ rules that compile and the indicator rules | [Rules](/siem/detection/rules.md#rule-sources) |
| `GET /alerts`; `PATCH /alerts/{id}` | Alerts | [Alerts](/siem/alerts/alerts.md#api) |
| `GET, POST /triggers`; `PATCH, DELETE /triggers/{id}` | Triggers | [Triggers](/siem/alerts/triggers.md) |
| `POST /triggers/dry-run`, `POST /triggers/{id}/dry-run` | Fires the levers would have made in the last 24 hours | [Triggers](/siem/alerts/triggers.md#dry-run) |
| `GET /triggers/{id}/fires`, `GET /fires/{id}` | Fire records | [Triggers](/siem/alerts/triggers.md#fires) |
| `GET, POST /sends`; `PATCH, DELETE /sends/{id}` | Scheduled sends | [Scheduled reports](/siem/alerts/scheduled-reports.md) |
| `POST /sends/{id}/preview`, `POST /sends/{id}/send-now` | Preview, send now | [Scheduled reports](/siem/alerts/scheduled-reports.md#api) |
| `GET /sources` | Ingest tokens, Cloudflare jobs, datasets offered | [Ingest tokens](/siem/sources/ingest-tokens.md) |
| `POST /sources/tokens`; `DELETE /sources/tokens/{id}` | Create (shown once) or revoke a token | [Ingest tokens](/siem/sources/ingest-tokens.md) |
| `GET /sources/aws` | Template links, quick-create links, CLI commands, your external id | [AWS](/siem/sources/aws.md) |
| `POST /sources/cloudflare/check` | `{ apiToken, accountId? }`: permission check | [Cloudflare](/siem/sources/cloudflare.md#token-permissions) |
| `POST /sources/cloudflare` | `{ apiToken, accountId, zoneIds, datasets }`: create Logpush jobs | [Cloudflare](/siem/sources/cloudflare.md) |
| `POST /sources/cloudflare/remove` | `{ apiToken, ids }`: delete jobs | [Cloudflare](/siem/sources/cloudflare.md#remove-jobs) |
| `GET /connections` | Your messaging connections, for destination pickers | |
| `GET /surface?rangeMs=&from=&to=&refresh=1` | The attack surface: an aggregate of the tenant's `http_events` and `waf_events` by route, ASN and country. The window is `rangeMs` (1 hour to 30 days, default one day) or `from` and `to` (at most 30 days). The answer is cached and says `cached: true`; `refresh=1` recomputes it. | |
| `PUT /surface/templates` | `{ version, templates: [{ method, path, key }] }`: replaces the tenant's route and operation template set, at most 20,000. Ingest matches request paths against it to fill `path_template`. Vulnesis pushes it. | [Tables](/siem/search/tables.md) |
| `GET /usage` | Fourteen days of bytes scanned, queries and rows ingested, and the daily budget | [Packs](/siem/reference/packs-and-limits.md) |

An unknown path answers `404`; a known path with the wrong method `405`.

## Unauthenticated routes

| Method and path | Returns |
|---|---|
| `GET https://guardian.vulnes.is/v1/templates/vulnetix-siem.yaml` | The delivery CloudFormation template |
| `GET https://guardian.vulnes.is/v1/templates/vulnetix-guardian-readonly.yaml` | The investigation role template |
| `GET https://guardian.vulnes.is/v1/health` | `{ "ok": true }` |

## Ingest

| Method and path | Token kind | Page |
|---|---|---|
| `POST https://ingest.vulnes.is/v1/ingest/aws/{flow,dns,cloudtrail}` | `aws`, as `X-Amz-Firehose-Access-Key` | [AWS](/siem/sources/aws.md#responses-firehose-sees) |
| `POST https://ingest.vulnes.is/v1/ingest/cloudflare/<dataset>` | `cloudflare`, as `Authorization: Bearer` | [Cloudflare](/siem/sources/cloudflare.md#responses-logpush-sees) |
| `POST https://ingest.vulnes.is/v1/ingest/events` | `events`, as `Authorization: Bearer` | [Events API](/siem/sources/events.md) |
