https://github.com/bkuhlmann/kagi-api
A Kagi API client for privacy focused information.
https://github.com/bkuhlmann/kagi-api
api artificial-intelligence kagi privacy ruby search
Last synced: 11 months ago
JSON representation
A Kagi API client for privacy focused information.
- Host: GitHub
- URL: https://github.com/bkuhlmann/kagi-api
- Owner: bkuhlmann
- License: other
- Created: 2025-05-04T21:10:43.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-08T17:17:31.000Z (11 months ago)
- Last Synced: 2025-08-08T19:26:09.649Z (11 months ago)
- Topics: api, artificial-intelligence, kagi, privacy, ruby, search
- Language: Ruby
- Homepage: https://alchemists.io/projects/kagi-api
- Size: 107 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- Funding: .github/FUNDING.yml
- License: LICENSE.adoc
- Citation: CITATION.cff
Awesome Lists containing this project
README
: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].