HoneyLabs Bulk API

openapi: 3.2.0
info:
  title: HoneyLabs Bulk API
  version: 1.2.0
  summary: Primary honeypot sensor observations, queryable.
  description: 'HoneyLabs publishes what its own internet-facing honeypot sensors observe. Every record is first-hand.


    **If you are an AI agent, prefer the MCP server** at `https://mcp.honeylabs.net/mcp` (server card: `https://mcp.honeylabs.net/mcp/server-card`). The tools aggregate for you, so one call replaces a client you would otherwise write and maintain.


    **Prefer list endpoints over loops.** `/api/cves` returns every CVE currently being probed in one request; requesting them one id at a time costs far more for both sides and will hit limits quickly.


    Keys are free and issued at once at https://honeylabs.net/dashboard. Plans, prices and limits are in `/pricing.json`; every interface is listed in `/.well-known/api-catalog` (RFC 9727).'
  contact:
    name: HoneyLabs
    url: https://honeylabs.net
  license:
    name: HoneyLabs terms of service
    url: https://honeylabs.net/terms
  termsOfService: https://honeylabs.net/terms
servers:
- url: https://honeylabs.net
security:
- bearerAuth: []
tags:
- name: Bulk
  description: Submit a list of addresses.
paths:
  /api/enrich/preview:
    post:
      tags:
      - Bulk
      operationId: previewEnrich
      summary: Cost and validity of a submission, before spending credits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  description: Free text; addresses are extracted from it.
              required:
              - text
      responses:
        '200':
          description: Cost estimate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichPreview'
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '429':
          description: Limit reached. The body names a cheaper endpoint for the same question; Retry-After is accurate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
  /api/enrich:
    post:
      tags:
      - Bulk
      operationId: enrich
      summary: Verdicts for a list of addresses in one submission
      description: 'Finds every public IPv4 and IPv6 address in `text` (a list, a CSV column or a raw log), drops duplicates and skips private and reserved addresses without billing them. One credit per address; bulk runs may use up to half of the plan''s daily credits. The per-request cap is `enrich_addresses_per_request` in /pricing.json, and 10 without a key. The response is a server-sent event stream with one row per address and a final row carrying `"_summary": true`, the `job_id` and `remaining_today`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
              required:
              - text
      responses:
        '200':
          description: Server-sent stream of enriched rows
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '429':
          description: Limit reached. The body names a cheaper endpoint for the same question; Retry-After is accurate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
  /api/enrich/{job_id}/results:
    get:
      tags:
      - Bulk
      operationId: enrichResults
      summary: The result set of one enrichment run, kept 24 hours
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: 00000000-0000-4000-8000-000000000000
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - csv
          - stix
          default: json
      responses:
        '200':
          description: Every row of the run. JSON is {results, watermark}; stix is a STIX 2.1 bundle.
          content:
            application/json:
              schema:
                type: object
            text/csv:
              schema:
                type: string
            application/stix+json;version=2.1:
              schema:
                type: object
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '404':
          description: Job not found, expired after 24 hours, or owned by another account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
      security:
      - bearerAuth: []
  /api/enrich/{job_id}/report:
    get:
      tags:
      - Bulk
      operationId: enrichReport
      summary: A Markdown incident report for one enrichment run
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        example: 00000000-0000-4000-8000-000000000000
      - name: template
        in: query
        schema:
          type: string
          enum:
          - standard
          - executive
          - technical
          default: standard
      responses:
        '200':
          description: Markdown report
          content:
            text/markdown:
              schema:
                type: string
        '400':
          description: Unknown template
        '401':
          description: No account. The body names the free signup path and the exact header to send.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
        '404':
          description: Job not found, expired after 24 hours, or owned by another account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Refusal'
      security:
      - bearerAuth: []
components:
  schemas:
    EnrichPreview:
      type: object
      properties:
        ip_count:
          type: integer
        invalid:
          type: integer
        dupes:
          type: integer
        cost_credits:
          type: integer
        allowed:
          type: boolean
        flags:
          type: array
          items:
            type: string
    Refusal:
      type: object
      description: Every refusal names what to do instead. Read it before retrying.
      properties:
        error:
          type: string
        detail:
          type: string
        how_to_fix:
          type: string
          example: 'Authorization: Bearer <your-api-key>'
        signup:
          type: string
          format: uri
        docs:
          type: string
          format: uri
        cheaper_route:
          type: object
          properties:
            instead_of:
              type: string
            use:
              type: string
            why:
              type: string
        alternatives:
          type: array
          items:
            type: object
            properties:
              when:
                type: string
              use:
                type: string
              why:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Free key from https://honeylabs.net/dashboard
externalDocs:
  description: Docs with worked examples
  url: https://honeylabs.net/docs