---
title: "Read-only public records API."
description: "The Hacker Bob public records API exposes cleared Common Vulnerabilities and Exposures records and capability metadata through versioned, typed JSON endpoints. It cannot run security assessments."
canonical: "https://hackerbob.ai/api-reference.md"
last-updated: "2026-09-05"
---
# Read-only public records API.

> The Hacker Bob public records API exposes cleared Common Vulnerabilities and Exposures records and capability metadata through versioned, typed JSON endpoints. It cannot run security assessments.

## Base URL and authentication

The production base URL is https://hackerbob.ai/api/v1. Public records require no credential and accept cross-origin requests.

Browser sessions under /console are separate and must not be sent to the public API.

```sh
curl --fail --silent --show-error https://hackerbob.ai/api/v1/health
```

- [OpenAPI 3.1 specification](/openapi.json)
- [Authentication posture](/auth.md)

## Operations

GET /api/v1/cve-records lists records. GET /api/v1/cve-records/{recordId} retrieves one record. POST /api/v1/cve-records/batch retrieves up to 50 records without side effects.

GET /api/v1/capabilities returns public-interface boundaries. GET /api/v1/sandbox returns non-persistent contract metadata. GET or POST /ask searches the same record index using an NLWeb-compatible response.

- [List public records](/api/v1/cve-records)
- [Capability metadata](/api/v1/capabilities)
- [NLWeb search](/ask?query=netatalk)
- [Contract sandbox](/api/v1/sandbox)

## Quick start

Read a small page first, then follow pagination.nextCursor only when the caller needs the complete record set.

```sh
curl --fail --silent --show-error \
  'https://hackerbob.ai/api/v1/cve-records?limit=5'
```

- [CVE records API in Markdown](/api/v1/cve-records.md)

## JavaScript SDK

Import the zero-dependency ECMAScript module directly or download it with its TypeScript declarations. The SDK calls only the public read-only endpoints.

- [SDK guide](/sdk/index.md)
- [ECMAScript module](/sdk/hacker-bob.mjs)
- [TypeScript declarations](/sdk/hacker-bob.d.ts)

## Contract sandbox

GET /api/v1/sandbox returns deterministic contract metadata, boundaries, links, and example requests. The endpoint is non-persistent and does not use production workspace data.

The sandbox cannot start an assessment, interact with a target, or simulate an assessment result.

```sh
curl --fail --silent --show-error https://hackerbob.ai/api/v1/sandbox
```

- [Open the contract sandbox](/api/v1/sandbox)

## Batch lookup

Batch lookup accepts 1 to 50 CVE identifiers. It is side-effect free and safe to retry. An optional Idempotency-Key is accepted for caller correlation.

```sh
curl --fail --silent --show-error \
  -X POST https://hackerbob.ai/api/v1/cve-records/batch \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-request-1' \
  --data '{"recordIds":["CVE-2026-47747"]}'
```

## Response contract

Every OpenAPI operation has an operationId, description, typed success response, typed JSON error response, and active lifecycle metadata.

The health endpoint returns the service version and confirms that the hosted interface is read-only.

```sh
{"status":"ok","version":"1.0.0","readOnly":true,"assessmentExecution":false}
```

- [OpenAPI contract in Markdown](/openapi.md)

## Pagination and errors

List responses return pagination.nextCursor. Send that opaque value as cursor until nextCursor is null.

REST errors use application/json with error.code, error.message, and requestId. Requests over the published edge limit return HTTP 429 with Retry-After and RateLimit headers.

## Rate limit

The public edge permits 120 requests per 60-second window for each connecting address. Responses publish RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy.

When the limit is exhausted, wait for Retry-After before retrying. Do not retry HTTP 400 or 404 responses without changing the request.

## Versioning and deprecation

The major version is part of the URL. Compatible fields and operations may be added to v1. Breaking changes use a new major version.

Before retiring a version, Hacker Bob will publish a deprecation notice, send Deprecation and Sunset response headers, identify the successor version, and provide at least 90 days between notice and sunset.

- [API lifecycle policy](/api-policy.md)

## Local CLI

The hacker-bob npm package provides the command-line installer for the local assessment runtime. It is separate from the hosted read-only records API.

Run it only inside a project the operator is authorized to assess, then restart the selected Model Context Protocol host.

```sh
npx -y hacker-bob@latest install .
```

- [hacker-bob on npm](https://www.npmjs.com/package/hacker-bob)
- [Hacker Bob source](https://github.com/vmihalis/hacker-bob)

## MCP transport

The hosted MCP server exposes the same read-only data through Streamable HTTP. Its tool names, parameter schemas, behavioral annotations, and resources are published in the server card.

- [MCP endpoint](/mcp)
- [MCP discovery](/.well-known/mcp)
- [MCP server card](/.well-known/mcp/server-card.json)

## MCP Registry

The hosted public-records server retains the legacy registry identifier io.github.bobnetsec/hacker-bob-public-records for compatibility. Hacker Bob is the current product and company name.

Validated registry metadata declares the production Streamable HTTP endpoint and this repository as its source.

- [Official MCP Registry entry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.bobnetsec%2Fhacker-bob-public-records)
- [Registry server metadata](/server.json)

## A2A transport

The public Agent2Agent interface accepts A2A 1.0 JSON-RPC SendMessage requests and returns direct text messages from cleared public records and capability metadata.

It supports no streaming, push notifications, assessment execution, or target interaction.

- [A2A endpoint](/a2a)
- [A2A agent card](/.well-known/agent-card.json)

## Machine-readable alternative

- [This page as Markdown](https://hackerbob.ai/api-reference.md)
- [Agent index](https://hackerbob.ai/llms.txt)

Last revised 2026-09-05.