API v1.0.0

Hanasand Public Intelligence API

Versioned, metadata-safe access to production-backed public intelligence. Version 1 is read-only: POST search operations are retrieval operations, and no mutation or idempotency-key contract is advertised.

Create API key OpenAPI JSON

Customer onboarding

Organization, API key, first request.

Keys are bound to one organization, use fixed read-only v1 scopes, expire after 90 days, and reveal the secret only once. Tenant-scoped alerts cannot be switched with request headers.

Checking your signed-in organizations.

Authenticated request

curl "https://api.hanasand.com/api/v1/actors?limit=20" \
  -H "X-API-Key: $HANASAND_API_KEY"

Authentication

Send a provisioned key in X-API-Key. Single search is anonymously rate-limited; batch search and most collection routes accept an exact method-and-route key scope or an authenticated session. Tenant-scoped alerts require an organization API key.

Responses include X-Request-Id and quota headers. API responses are no-store; failures and partial batches keep their real status.

Endpoints

Method	Path	Purpose	Access	Key scope
POST	/ti/search	Search public threat intelligence	Anonymous	None
POST	/ti/search/batch	Search up to 25 unique queries	API key or session	POST /api/v1/ti/search/batch
GET	/actors	Actor intelligence profiles	API key or session	GET /api/v1/actors
GET	/aliases	Actor aliases linked to canonical profiles	API key or session	GET /api/v1/aliases
GET	/incidents	Structured incidents inferred from public evidence	API key or session	GET /api/v1/incidents
GET	/claims	Structured intelligence claims	API key or session	GET /api/v1/claims
GET	/evidence	Capture-to-intelligence evidence links	API key or session	GET /api/v1/evidence

Generate TypeScript types

npx openapi-typescript https://hanasand.com/api/openapi/ti -o src/hanasand-api.d.ts

Typed client

import createClient from 'openapi-fetch'
import type { paths } from './hanasand-api'

const api = createClient<paths>({
  baseUrl: 'https://api.hanasand.com/api/v1',
  headers: { 'X-API-Key': process.env.HANASAND_API_KEY! }
})

const { data, error } = await api.GET('/actors', {
  params: { query: { limit: 20 } }
})
if (error) throw new Error(error.error.message)

Stable errors

BadRequestInvalid input

UnauthorizedMissing or invalid credentials

ForbiddenCredential scope does not permit this operation

RateLimitedRate limit exceeded

InternalErrorUnexpected request processing failure

UnavailableUpstream intelligence service unavailable

Compatibility

Additive fields and endpoints may be introduced within v1. Removing or changing existing fields, semantics, authentication, or pagination requires a new major API version.

v1 exposes no public mutations. Search POSTs are retrieval-only and safe to retry; no Idempotency-Key header is required.

Evidence boundary

Public responses exclude raw stolen material, restricted locators, customer tenant data, secrets, and internal object references.