4got API documentation
======================

4got exposes a JSON/MessagePack API for programmatic search.
All API endpoints require authentication unless noted otherwise.


ENDPOINTS
---------

  GET /api/v1/search?q=QUERY&category=web
      Native 4got search API. Returns merged, deduplicated results
      from all engines with cross-engine scoring.

      Parameters:
        q         - search query (required)
        category  - web, images, videos, news, music (default: web)
        page      - page number (default: 1)
        t         - time range: day, week, month, year (optional)

      Response fields:
        query, category, elapsed_ms, engines_used, engines_errored,
        results (array of {score, engines, items})

  GET /api/v1/web?s=QUERY
      4get-compatible web search. Uses the same response envelope as
      4get's /api/v1/web endpoint for drop-in compatibility.

  GET /api/v1/images?s=QUERY
      4get-compatible image search.

  GET /api/v1/videos?s=QUERY
      4get-compatible video search.

  GET /api/v1/news?s=QUERY
      4get-compatible news search.

  GET /api/v1/music?s=QUERY
      4get-compatible music search.

  GET /api/v1/ac?q=QUERY
      Autocomplete suggestions from multiple backends.
      No authentication required.
      Returns a JSON array of suggestion strings.

  GET /ami4got
      Instance information (version, engine count, uptime, etc.).
      CORS enabled. No authentication required.
      Returns: status, server info, real_searches, bot_requests,
               api_enabled, version, instances list.

  GET /api/v1/cache?key=HASH
  POST /api/v1/cache
      Peer cache sharing endpoints.
      Requires peer_cache permission or Bearer peer_secret.

  POST /api/v1/proxy?service=SERVICE&...
      Service proxy endpoint. Friends proxy services for each other.
      Requires peer_cache permission or Bearer peer_secret.
      The instance must have allow-proxy configured for the service.

      Services:
        translation  - text, target (lang code)
        deepl        - text, target
        lingva       - text, target
        nllb         - text, target
        wolfram      - query
        autocomplete - query

      Response: {"result": "...", "service": "...", "via": "hostname"}


AUTHENTICATION
--------------

  Three methods, checked in order:

  1. Bearer token (owner access):
     Authorization: Bearer <owner_secret>

  2. API key:
     X-API-Key: <key>

     API keys are generated by the instance owner at /admin/users.
     Each key has specific permissions (api_access, no_pow, etc.).

  3. Session cookie:
     A valid 4got_session cookie from passing the captcha or PoW
     challenge. Useful for browser-based API calls.


  GET /feed/search?q=QUERY&category=web
      Per-query Atom feed of search results. Subscribe in any RSS
      reader to get fresh results for a query on each poll.
      Requires authentication. Respects Cache-Control for poll interval.

  GET /api/openapi.yaml
      OpenAPI 3.0 YAML specification for all API endpoints.
      No authentication required.


MESSAGEPACK
-----------

  To receive MessagePack instead of JSON, set the Accept header:

    Accept: application/msgpack

  All endpoints that return JSON also support MessagePack with the
  same field names. MessagePack responses are smaller and faster to
  parse for non-browser clients.


CSV
---

  To receive CSV instead of JSON from /api/v1/search, either set:

    Accept: text/csv

  or append ?format=csv to the query string. The CSV has headers:
  title, url, snippet, engine.


RATE LIMITS
-----------

  The instance owner sets a per-day search limit (default: 200).
  API key users share this limit. Exceeding it returns HTTP 429.


EXAMPLES
--------

  # Search with API key
  curl -H "X-API-Key: YOUR_KEY" "https://HOST/api/v1/search?q=hello"

  # 4get-compatible search
  curl -H "X-API-Key: YOUR_KEY" "https://HOST/api/v1/web?s=hello"

  # Autocomplete (no auth needed)
  curl "https://HOST/api/v1/ac?q=hel"

  # MessagePack response
  curl -H "X-API-Key: YOUR_KEY" \
       -H "Accept: application/msgpack" \
       "https://HOST/api/v1/search?q=hello"

  # Time-filtered search
  curl -H "X-API-Key: YOUR_KEY" \
       "https://HOST/api/v1/search?q=hello&t=week"


SOURCE
------

  4got is written in Go. Inspired by 4get and SearXNG.
  https://git.lolcat.ca/lolcat/4get  (inspiration)