Get started with the Nebulock Hunts API

The Nebulock Hunts API is currently available only to active Nebulock customers.

API Keys for your organization can be obtained and managed by administrator roles in the Nebulock platform. Authentication requires API keys in the custom headers X-API-Key-ID and X-API-Key-Secret.

The current rate limit is 60 requests per minute.

Access is currently limited to the listed endpoints in the Hunts API. We are continually adding endpoints to our external APIs and new endpoints will be added to our documentation accordingly.

Overview

The Hunts API exposes four related resources for running and reviewing AI-driven threat investigations.

Hunts

A hunt is an AI-driven threat investigation kicked off with a natural-language prompt (e.g. "find lateral movement attempts in the last 24 hours"). When you create a hunt, Nebulock spins up an agent that processes the request asynchronously and produces one or more directives — the discrete sub-queries the agent executes against your data. Hunts created through the API are tagged with source: "api", distinguishing them from hunts created in the Nebulock UI.

Typical flow:

1. POST /hunts to create a hunt with your prompt.
2. Poll GET /hunts/{hunt_id} until every directive reaches a terminal status (completed, failed, or stopped).
3. Inspect the directives and their blocks (structured findings) on the hunt detail.
4. Optionally POST /hunts/{hunt_id}/directives to add a follow-up prompt against the same hunt.

Hunt Suggestions

Hunt suggestions are AI-generated investigation ideas derived from threat-intelligence context — useful for proactive hunting when you don't have a specific prompt in mind. You can list existing recommended suggestions, request a fresh batch of new ones for a piece of intel, or pull a single suggestion's details to review before turning it into a hunt.

Typical flow:

1. POST /hunt-suggestions to generate a batch (returns a job ID).
2. GET /hunt-suggestions/jobs/{job_id} to retrieve the generated suggestions.
3. GET /hunt-suggestions to browse previously generated suggestions for your organization.
4. Use any suggestion's directive text as the message body for a new POST /hunts call.

Hunt Reports

A hunt report is a formatted writeup of a completed hunt — both rendered markdown and a downloadable PDF — suitable for sharing with stakeholders. Reports are generated on demand after the hunt finishes, and generation itself is asynchronous, so you'll poll until the report reaches a terminal status.

Typical flow:

1. PATCH /hunts/{hunt_id}/generate-report to trigger generation (returns the hunt with an embedded hunt_report reference).
2. Poll GET /hunt-reports/{hunt_report_id} until status is completed or failed.
3. GET /hunt-reports/{hunt_report_id}/pdf to download the PDF, or read content_markdown directly from the JSON detail.
4. POST /hunt-reports/{hunt_report_id}/retry if generation failed and you want another attempt.

Hunt Report Feedback

Feedback captures a reviewer's verdict on a hunt report — typically used to mark whether the report's conclusions were confirmed or disputed, with an optional free-text comment. Feedback is append-only (you can keep adding entries; nothing is mutated or deleted), which makes it suitable for tracking review history and closing the loop on hunt accuracy.

Typical flow:

1. POST /hunt-reports/{hunt_report_id}/feedback with a verdict and optional comment.
2. GET /hunt-reports/{hunt_report_id}/feedback to list all submitted feedback for that report, oldest first.