Project

kagi-api

0.0
No release in over 3 years
kagi-apibkuhlmann/kagi-apiHomepageDocumentationSource CodeBug Tracker
A Kagi API client for privacy focused information.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
588
Stars
1
Forks
0
Watchers
1
 Releases
Current version
0.1.1
Total releases
3
First release
1980-01-02
Latest release
1980-01-02
 Development
Primary Language
Ruby
Licenses
Hippocratic-2.1
Average date of last 50 commits
2025-04-30
Reverse Dependencies
0

 Dependencies

Runtime

inspectable
~> 0.3
cogger
~> 1.2
containable
~> 1.2
dry-monads
~> 1.8
http
~> 5.2
infusible
~> 4.3
initable
~> 0.4
pipeable
~> 1.3
zeitwerk
~> 2.7
 Project Readme

Kagi API

A monadic API client for Kagi privacy focused information. This allows you to access the full Kagi API using a fault tolerant pipeline to yield whole value objects (i.e. Data) for immediate interaction within your own applications.

⚠️ Roughly ~2% of funds go to Yandex search results that Kagi uses in their searches. Unfortunately, Yandex is a Russian company that helps fund corrupt propaganda, the killing of Ukrainians, and other despicable acts. I was not aware of this when I wrote this API client which also violates my software license. More can be found here.

Table of Contents
  • Features
  • Requirements
  • Setup
  • Usage
    • Configuration
    • Environment
    • Endpoints
      • Enrich News
      • Enrich Web
      • Fast
      • Search
      • Summarize
  • Development
  • Tests
  • License
  • Security
  • Code of Conduct
  • Contributions
  • Developer Certificate of Origin
  • Versions
  • Community
  • Credits

Features

  • Provides a Kagi API client.

  • Provides full access to the Kagi APIs.

  • Provides a fault tolerant pipeline for API requests and responses.

Requirements

  1. Ruby.

  2. A Kagi account with an API key.

Setup

To install with security, run:

# 💡 Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install kagi-api --trust-policy HighSecurity

To install without security, run:

gem install kagi-api

You can also add the gem directly to your project:

bundle add kagi-api

Once the gem is installed, you only need to require it:

require "kagi/api"

Usage

This client provides access to multiple endpoints. Each endpoint will answer either answer a Success or Failure (as provided by Dry Monads) based on result of the API call. This allows you pattern match in your own code when using each endpoint. Example:

client = Kagi::API.new

case client.fast query: "Ruby"
  in Success(payload) then puts payload
  in Failure(response) then puts response
  else puts "Unknown HTTP response."
end

See Endpoints for further details.

Configuration

You can configure the client using a block and adjusting the content_type, token, and/or uri settings as desired. For example, you’d only need to supply your Kagi API token (as found via your account settings) to start using the client:

client = Kagi::API.new do |settings| settings.token = "secret" }
client.fast query: "Ruby"

If you don’t configure the client, then the following defaults will be used:

client = Kagi::API.new do |settings|
  settings.content_type = "application/json"
  settings.token = nil
  settings.uri = "https://kagi.com/api/v0"
end

Environment

You can configure the client via the following environment variables. This is handy when you don’t want to use block syntax or want fallbacks when no configuration is provided.

  • KAGI_API_CONTENT_TYPE: Defines the HTTP Content-Type header. You shouldn’t need to change this. Default: "application/json".

  • KAGI_API_TOKEN: Defines your personal key for API access. Default: nil.

  • KAGI_API_URI: Defines the API URI. Default: "https://kagi.com/api/v0".

Endpoints

All endpoints are accessible via the client instance. Each will answer a Success or Failure result you can pattern match against. Even better, within each result, you’ll get a Data object you can immediately interact with. See below to learn more about each endpoint.

Enrich News

Message #enrich_news to make API requests. Example:

client = Kagi::API.new

client.enrich_news q: "Ruby programming language"

# Success(#<data Kagi::API::Models::Search meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=577, balance=2.259763>, data=[#<data Kagi::API::Models::Content::Search type=0, rank=nil, title="The Ruby Programming Language (Ruby)", url="https://github.com/ruby/ruby", snippet="For a complete list of ways to install Ruby...", published_at=2025-05-04 09:17:12 UTC, thumbnail=nil>]>)

client.enrich_news

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=87, balance=2.366512>, error=[#<data Kagi::API::Models::Content::Error code=1, message="Missing q parameter", reference=nil>]>)

See Kagi API Documentation for further details.

Enrich Web

Message #enrich_web to make API requests. Example:

client = Kagi::API.new

client.enrich_web q: "Ruby programming language"

# Success(#<data Kagi::API::Models::Search meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=451, balance=2.257763>, data=[#<data Kagi::API::Models::Content::Search type=0, rank=nil, title="Ruby Programming Language", url="https://www.ruby-lang.org/en/", snippet="There is a vulnerability about Command Injection in RDoc which is bundled in Ruby. There is an XML round-trip vulnerability in REXML gem bundled with Ruby. And there is also an unintentional file creation vulnerability in tempfile library bundled with Ruby on Windows, because it uses tmpdir internally.", published_at=nil, thumbnail=nil>]>)

client.enrich_web

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=27, balance=2.362512>, error=[#<data Kagi::API::Models::Content::Error code=1, message="Missing q parameter", reference=nil>]>)

See Kagi API Documentation for further details.

Fast

Message #fast to make API requests. Example:

client = Kagi::API.new

client.fast query: "Ruby"

# Success(#<data Kagi::API::Models::Fast meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=2915, balance=2.362512>, data=#<data Kagi::API::Models::Content::Fast output="Ruby is a dynamic, open-source programming language that focuses on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write. Ruby supports multiple programming paradigms, including functional, object-oriented, and imperative. It is also known for its flexible nature, allowing developers to easily modify its parts. ", tokens=1172, references=[]>>)

client.fast

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=26, balance=2.347512>, error=[#<data Kagi::API::Models::Content::Error code=1, message="Parameter \"query\" is required and must not be empty", reference=nil>]>)

See Kagi API Documentation for further details.

Search

Message #search to make API requests. Example:

client = Kagi::API.new

client.search q: "Ruby"

# Success(#<data Kagi::API::Models::Search meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=1225, balance=2.322512>, data=[#<data Kagi::API::Models::Content::Search type=0, rank=nil, title="Ruby Programming Language", url="https://www.ruby-lang.org/en/", snippet="A dynamic, open source programming language with a focus on simplicity and productivity. It has an elegant syntax that is natural to read and easy to write.", published_at=nil, thumbnail=nil>]>)

client.search

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=27, balance=2.322512>, error=[#<data Kagi::API::Models::Content::Error code=1, message="Missing q parameter", reference=nil>]>)

See Kagi API Documentation for further details.

Summarize

Message #summarize to make API requests. Example:

client = Kagi::API.new

client.summarize url: "https://www.ruby-lang.org/en", summary_type: "summary"

# Success(#<data Kagi::API::Models::Summary meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=3828, balance=2.261763>, data=#<data Kagi::API::Models::Content::Summary output="The Ruby Programming Language is a dynamic, open-source language designed for simplicity and productivity, featuring an elegant syntax that is easy to read and write. It is well-known for its straightforward \"Hello World!\" program, which requires minimal syntax. The Ruby community actively shares updates, including recent releases such as Ruby 3.5.0-preview1, Ruby 3.4.3, and Ruby 3.3.8, along with security advisories highlighting vulnerabilities like CVE-2025-43857 related to the net-imap gem. \n\nUsers can easily get started with Ruby through resources like \"Try Ruby!\" and \"Ruby in Twenty Minutes.\" The website offers extensive documentation, libraries, and success stories, encouraging participation in a vibrant community through mailing lists, user groups, and issue tracking. Ruby's commitment to user engagement is evident through various community platforms where developers can collaborate and share knowledge. The site also provides multilingual support, making Ruby accessible to a global audience.", tokens=2025>>)

client.summarize

# Failure(#<data Kagi::API::Models::Error meta=#<data Kagi::API::Models::Content::Meta id="<redacted>", node="us-west2", duration=114, balance=2.322512>, error=[#<data Kagi::API::Models::Content::Error code=200, message="We are sorry, this input is not supported. (Invalid Input)", reference=nil>]>)

See Kagi API Documentation for further details.

Development

To contribute, run:

git clone https://github.com/bkuhlmann/kagi-api
cd kagi-api
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bin/rake

Credits