kagi-api

A Kagi API client for privacy focused information.

https://github.com/bkuhlmann/kagi-api

Keywords

Repository

A Kagi API client for privacy focused information.

README.adoc

:toc: macro
:toclevels: 5
:figure-caption!:

:data_link: link:https://alchemists.io/articles/ruby_data[Data]
:dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads]
:kagi_link: link:https://kagi.com[Kagi]

= Kagi API

A monadic API client for {kagi_link} 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_link}) 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 link:https://kagifeedback.org/d/5445-reconsider-yandex-integration-due-to-the-geopolitical-status-quo[here].*

toc::[]

== Features

* Provides a {kagi_link} API client.
* Provides full access to the Kagi APIs.
* Provides a fault tolerant pipeline for API requests and responses.

== Requirements

. link:https://www.ruby-lang.org[Ruby].
. A {kagi_link} account with an API key.

== Setup

To install _with_ security, run:

[source,bash]
----
# 💡 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:

[source,bash]
----
gem install kagi-api
----

You can also add the gem directly to your project:

[source,bash]
----
bundle add kagi-api
----

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

[source,ruby]
----
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_link}) based on result of the API call. This allows you pattern match in your own code when using each endpoint. Example:

[source,ruby]
----
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 xref:_endpoints[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 link:https://kagi.com/settings?p=api[account settings]) to start using the client:

[source,ruby]
----
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:

[source,ruby]
----
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_link} object you can immediately interact with. See below to learn more about each endpoint.

==== Enrich News

Message `#enrich_news` to make API requests. Example:

[source,ruby]
----
client = Kagi::API.new

client.enrich_news q: "Ruby programming language"

# Success(#, data=[#]>)

client.enrich_news

# Failure(#, error=[#]>)
----

See link:https://help.kagi.com/kagi/api/enrich.html[Kagi API Documentation] for further details.

==== Enrich Web

Message `#enrich_web` to make API requests. Example:

[source,ruby]
----
client = Kagi::API.new

client.enrich_web q: "Ruby programming language"

# Success(#, data=[#]>)

client.enrich_web

# Failure(#, error=[#]>)
----

See link:https://help.kagi.com/kagi/api/enrich.html[Kagi API Documentation] for further details.

==== Fast

Message `#fast` to make API requests. Example:

[source,ruby]
----
client = Kagi::API.new

client.fast query: "Ruby"

# Success(#, data=#>)

client.fast

# Failure(#, error=[#]>)
----

See link:https://help.kagi.com/kagi/api/fastgpt.html[Kagi API Documentation] for further details.

==== Search

Message `#search` to make API requests. Example:

[source,ruby]
----
client = Kagi::API.new

client.search q: "Ruby"

# Success(#, data=[#]>)

client.search

# Failure(#, error=[#]>)
----

See link:https://help.kagi.com/kagi/api/search.html[Kagi API Documentation] for further details.

==== Summarize

Message `#summarize` to make API requests. Example:

[source,ruby]
----
client = Kagi::API.new

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

# Success(#, data=#>)

client.summarize

# Failure(#, error=[#]>)
----

See link:https://help.kagi.com/kagi/api/summarizer.html[Kagi API Documentation] for further details.

== Development

To contribute, run:

[source,bash]
----
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:

[source,bash]
----
bin/console
----

== Tests

To test, run:

[source,bash]
----
bin/rake
----

== link:https://alchemists.io/policies/license[License]

== link:https://alchemists.io/policies/security[Security]

== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://alchemists.io/policies/contributions[Contributions]

== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]

== link:https://alchemists.io/projects/kagi-api/versions[Versions]

== link:https://alchemists.io/community[Community]

== Credits

* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].
* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].

Owner

Citation (CITATION.cff)

cff-version: 1.2.0
message: Please use the following metadata when citing this project in your work.
title: Kagi API
abstract: A Kagi API client for privacy focused information.
version: 0.2.0
license: Hippocratic-2.1
date-released: 2025-07-15
authors:
  - family-names: Kuhlmann
    given-names: Brooke
    affiliation: Alchemists
    orcid: https://orcid.org/0000-0002-5810-6268
keywords:
 - ruby
 - kagi
 - api
 - search
 - privacy
 - artificial_intelligence
repository-code: https://github.com/bkuhlmann/kagi-api
repository-artifact: https://rubygems.org/gems/kagi-api
url: https://alchemists.io/projects/kagi-api

GitHub Events

Packages