Ben Milne Ask API

openapi: 3.2.0
info:
  title: benmilne.com Developer Ask API
  description: Public read-only multilingual API for benmilne.com content. Supports 14 languages via ?lang= query parameter. English is the default and source of truth. SSE streaming available for real-time search.
  version: 2.0.0
  contact:
    name: Ben Milne
    url: https://benmilne.com/api
  x-cli:
    name: benmilne-api
    install: npm install -g benmilne-api
    registry: https://www.npmjs.com/package/benmilne-api
  x-source:
    url: https://github.com/benmilne-com/agents
    type: github
  x-ratelimit:
    strategy: edge-cache
    description: Cloudflare edge caching serves most reads. No application-level rate limit enforced. Headers included on every JSON response.
    headers:
    - X-RateLimit-Limit
    - X-RateLimit-Remaining
    - X-RateLimit-Reset
  x-graphql:
    endpoint: https://benmilne.com/graphql
    introspection: true
    description: Read-only GraphQL API with Relay cursor pagination, typed errors, and full schema descriptions. POST queries to /graphql.
servers:
- url: https://benmilne.com
  description: Production
- url: https://benmilne.com/sandbox
  description: Sandbox (canned test data)
security:
- public: []
tags:
- name: Ask
paths:
  /ask:
    post:
      operationId: nlwebAsk
      summary: NLWeb natural-language query
      description: Accepts a natural-language question and returns matching content. Supports JSON or SSE streaming response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Natural-language question
                site:
                  type: string
                  description: 'Target site (default: benmilne.com)'
                streaming:
                  type: boolean
                  description: If true, return SSE stream instead of JSON
                  default: false
              required:
              - query
      responses:
        '200':
          description: Search results in NLWeb format or SSE stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NLWebResponse'
            text/event-stream:
              schema:
                type: string
        '400':
          description: Missing query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Ask
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        supported_languages:
          type: array
          items:
            type: string
      required:
      - error
    NLWebResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - success
          - error
        query:
          type: string
        site:
          type: string
        response:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              name:
                type: string
              description:
                type: string
              date:
                type: string
      required:
      - status
      - query
      - response
  securitySchemes:
    public:
      type: http
      scheme: bearer
      description: All read endpoints are public and unauthenticated. No API key or token is required.
externalDocs:
  description: benmilne.com developer portal
  url: https://benmilne.com/developers