Guard Customer API

The Guard Customer API is the stable, versioned API for programmatic access to your Praetorian Guard Platform (PGP) data — assets, seeds, technologies, vulnerabilities, exports, and retests. This guide walks you through creating credentials, authorizing in the interactive documentation, and calling the API from your own tools.

Interactive documentation

The API is fully described by an OpenAPI specification, available in two forms:

• Swagger UI (browse and try requests in the browser): https://api.app.guard.praetorian.com/api/v1/docs
• OpenAPI file (import into Postman, or generate a client): https://api.app.guard.praetorian.com/api/v1/openapi.json

All requests use the base URL https://api.app.guard.praetorian.com.

Prerequisites

You'll need three values before you start:

• Your Guard API key ID
• Your Guard API key secret
• Your Guard account username

The first two come from the API key you create below.

Creating an API Key

1. In Guard, click the user icon in the top right.
2. Select User Profile → API Keys.
3. Click Add Key.
4. Provide a name and an expiration date (max 1 year).
5. Copy the API key ID and API key secret.

Important: The API key secret is displayed only once. If you lose it, delete the key and create a new one.

Authorizing in Swagger UI

Every request needs two things: a bearer token obtained from your API key, and an Account header naming your Guard account. Swagger UI handles both once you authorize.

1. Open https://api.app.guard.praetorian.com/api/v1/docs.
2. Click Authorize.
3. In the oauth2 scheme, enter your API key ID as client_id and your API key secret as client_secret. Swagger exchanges them at /token and sends the returned JWT as a bearer token on each request.
4. In the account scheme, enter your Guard account username. Swagger sends it in the Account header on each request.
5. Click Close.

To confirm the setup works, expand GET /api/v1/assets, click Try it out, then Execute. A 200 response listing your assets confirms both schemes are active.

Calling the API from your own tools

Exchange your API key for a bearer token using the standard OAuth2 client credentials flow:

curl -X POST "https://api.app.guard.praetorian.com/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=<api-key-id>&client_secret=<api-key-secret>"

The response contains a JWT bearer token. Send it in the Authorization header, and send your account username in the Account header, on every request:

curl -G "https://api.app.guard.praetorian.com/api/v1/assets" \
  -H "Authorization: Bearer <jwt>" \
  -H "Account: <account-username>" \
  --data-urlencode 'query={"page":1,"limit":50,"orderBy":"updated","descending":true}'

Note: Both headers are required on every request. A missing Account header fails even with a valid bearer token.

Querying and filtering

List endpoints accept a single optional query parameter — a JSON object passed in the query string. It supports:

• search — full-text search phrase
• filters — constrained field filters (see below)
• page and limit — pagination
• orderBy and descending — sort field and direction

Filters compare a field against a value using one of =, <, <=, >, >=, STARTS WITH, ENDS WITH, IN, or IS NOT NULL, and can be negated with not. Combine filters with the AND and OR operators, which take a list of filters in value and omit field. For example, this query returns active assets or assets from AWS sources, matching the search phrase, newest first:

{
  "search": "internet-facing",
  "filters": [
    {
      "operator": "OR",
      "value": [
        { "field": "status", "operator": "=", "value": "A" },
        { "field": "source", "operator": "STARTS WITH", "value": "AWS" }
      ]
    }
  ],
  "orderBy": "updated",
  "descending": true,
  "page": 1,
  "limit": 50
}

Successful list responses return the matching resources in an items array.

Creating and updating resources

Write endpoints follow a consistent model:

• PUT creates a resource or replaces its customer-managed fields.
• PATCH updates only the fields you supply.
• A comment field on either records a history note — PUT sets an initial or additional note, PATCH appends a new note and preserves existing ones.

The Swagger UI documents the exact fields each resource accepts.

Exports

For bulk retrieval, queue an export instead of paging through list results:

1. Send POST /api/v1/exports with an entity_type (assets, vulnerabilities, seeds, or technologies) and a format (csv, json, or pdf). You can constrain the export with the same search and filters used for list queries.
2. The API responds 202 with an export job id and a status (queued, running, pass, fail, or unknown).
3. Poll GET /api/v1/exports/{id} until the job completes. A completed export includes a temporary download_url for the file.

Retests

Queue a retest of a demonstrated vulnerability the same way you queue an export — POST to start the job, then poll GET for status.

1. Copy the complete key from GET /api/v1/vulnerabilities (shape #risk#{dns}#{name}). Send POST /api/v1/retests with that value as vulnerability_key. The vulnerability must already be in Demonstrated status. The API responds 202 with a retest job id and a status (queued, running, pass, fail, blocked, skipped, or unknown).
2. Poll GET /api/v1/retests/{id} until the job completes. A job that is not yet complete omits result. When status is pass, the response includes result with the validation output (proposed_status, comment, evidence, proposed_by, proposed_at) and the current vulnerability_status.
3. A key that is not a risk key, or a vulnerability that is not demonstrated, is rejected with 400. An unknown vulnerability or job returns 404.

curl -X POST "https://api.app.guard.praetorian.com/api/v1/retests" \
  -H "Authorization: Bearer <jwt>" \
  -H "Account: <account-username>" \
  -H "Content-Type: application/json" \
  -d '{"vulnerability_key":"#risk#app.example.com#CVE-2024-1234"}'

Available resources

If you have any questions or run into issues, reach out to our support team at support@praetorian.com.