{"id":30257635,"url":"https://github.com/bkuhlmann/kagi-api","last_synced_at":"2025-08-15T16:05:23.489Z","repository":{"id":291473848,"uuid":"977732962","full_name":"bkuhlmann/kagi-api","owner":"bkuhlmann","description":"A Kagi API client for privacy focused information.","archived":false,"fork":false,"pushed_at":"2025-08-08T17:17:31.000Z","size":110,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-08T19:26:09.649Z","etag":null,"topics":["api","artificial-intelligence","kagi","privacy","ruby","search"],"latest_commit_sha":null,"homepage":"https://alchemists.io/projects/kagi-api","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bkuhlmann.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.adoc","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["bkuhlmann"]}},"created_at":"2025-05-04T21:10:43.000Z","updated_at":"2025-08-08T17:17:34.000Z","dependencies_parsed_at":"2025-05-04T21:47:49.323Z","dependency_job_id":"025bcbad-9c2d-4ea2-b1f9-de93438fb4da","html_url":"https://github.com/bkuhlmann/kagi-api","commit_stats":null,"previous_names":["bkuhlmann/kagi-api"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/bkuhlmann/kagi-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fkagi-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fkagi-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fkagi-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fkagi-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkuhlmann","download_url":"https://codeload.github.com/bkuhlmann/kagi-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkuhlmann%2Fkagi-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270594163,"owners_count":24612661,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","artificial-intelligence","kagi","privacy","ruby","search"],"created_at":"2025-08-15T16:02:48.137Z","updated_at":"2025-08-15T16:05:23.479Z","avatar_url":"https://github.com/bkuhlmann.png","language":"Ruby","funding_links":["https://github.com/sponsors/bkuhlmann"],"categories":["Ruby"],"sub_categories":[],"readme":":toc: macro\n:toclevels: 5\n:figure-caption!:\n\n:data_link: link:https://alchemists.io/articles/ruby_data[Data]\n:dry_monads_link: link:https://dry-rb.org/gems/dry-monads[Dry Monads]\n:kagi_link: link:https://kagi.com[Kagi]\n\n= Kagi API\n\nA 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.\n\n⚠️ *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].*\n\ntoc::[]\n\n== Features\n\n* Provides a {kagi_link} API client.\n* Provides full access to the Kagi APIs.\n* Provides a fault tolerant pipeline for API requests and responses.\n\n== Requirements\n\n. link:https://www.ruby-lang.org[Ruby].\n. A {kagi_link} account with an API key.\n\n== Setup\n\nTo install _with_ security, run:\n\n[source,bash]\n----\n# 💡 Skip this line if you already have the public certificate installed.\ngem cert --add \u003c(curl --compressed --location https://alchemists.io/gems.pem)\ngem install kagi-api --trust-policy HighSecurity\n----\n\nTo install _without_ security, run:\n\n[source,bash]\n----\ngem install kagi-api\n----\n\nYou can also add the gem directly to your project:\n\n[source,bash]\n----\nbundle add kagi-api\n----\n\nOnce the gem is installed, you only need to require it:\n\n[source,ruby]\n----\nrequire \"kagi/api\"\n----\n\n== Usage\n\nThis 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:\n\n[source,ruby]\n----\nclient = Kagi::API.new\n\ncase client.fast query: \"Ruby\"\n  in Success(payload) then puts payload\n  in Failure(response) then puts response\n  else puts \"Unknown HTTP response.\"\nend\n----\n\nSee xref:_endpoints[Endpoints] for further details.\n\n=== Configuration\n\nYou 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:\n\n[source,ruby]\n----\nclient = Kagi::API.new do |settings| settings.token = \"secret\" }\nclient.fast query: \"Ruby\"\n----\n\nIf you don't configure the client, then the following defaults will be used:\n\n[source,ruby]\n----\nclient = Kagi::API.new do |settings|\n  settings.content_type = \"application/json\"\n  settings.token = nil\n  settings.uri = \"https://kagi.com/api/v0\"\nend\n----\n\n=== Environment\n\nYou 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.\n\n* `KAGI_API_CONTENT_TYPE`: Defines the HTTP `Content-Type` header. You shouldn't need to change this. Default: `\"application/json\"`.\n* `KAGI_API_TOKEN`: Defines your personal key for API access. Default: `nil`.\n* `KAGI_API_URI`: Defines the API URI. Default: `\"https://kagi.com/api/v0\"`.\n\n=== Endpoints\n\nAll 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.\n\n==== Enrich News\n\nMessage `#enrich_news` to make API requests. Example:\n\n[source,ruby]\n----\nclient = Kagi::API.new\n\nclient.enrich_news q: \"Ruby programming language\"\n\n# Success(#\u003cdata Kagi::API::Models::Search meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=577, balance=2.259763\u003e, data=[#\u003cdata 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\u003e]\u003e)\n\nclient.enrich_news\n\n# Failure(#\u003cdata Kagi::API::Models::Error meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=87, balance=2.366512\u003e, error=[#\u003cdata Kagi::API::Models::Content::Error code=1, message=\"Missing q parameter\", reference=nil\u003e]\u003e)\n----\n\nSee link:https://help.kagi.com/kagi/api/enrich.html[Kagi API Documentation] for further details.\n\n==== Enrich Web\n\nMessage `#enrich_web` to make API requests. Example:\n\n[source,ruby]\n----\nclient = Kagi::API.new\n\nclient.enrich_web q: \"Ruby programming language\"\n\n# Success(#\u003cdata Kagi::API::Models::Search meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=451, balance=2.257763\u003e, data=[#\u003cdata 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\u003e]\u003e)\n\nclient.enrich_web\n\n# Failure(#\u003cdata Kagi::API::Models::Error meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=27, balance=2.362512\u003e, error=[#\u003cdata Kagi::API::Models::Content::Error code=1, message=\"Missing q parameter\", reference=nil\u003e]\u003e)\n----\n\nSee link:https://help.kagi.com/kagi/api/enrich.html[Kagi API Documentation] for further details.\n\n==== Fast\n\nMessage `#fast` to make API requests. Example:\n\n[source,ruby]\n----\nclient = Kagi::API.new\n\nclient.fast query: \"Ruby\"\n\n# Success(#\u003cdata Kagi::API::Models::Fast meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=2915, balance=2.362512\u003e, data=#\u003cdata 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=[]\u003e\u003e)\n\nclient.fast\n\n# Failure(#\u003cdata Kagi::API::Models::Error meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=26, balance=2.347512\u003e, error=[#\u003cdata Kagi::API::Models::Content::Error code=1, message=\"Parameter \\\"query\\\" is required and must not be empty\", reference=nil\u003e]\u003e)\n----\n\nSee link:https://help.kagi.com/kagi/api/fastgpt.html[Kagi API Documentation] for further details.\n\n==== Search\n\nMessage `#search` to make API requests. Example:\n\n[source,ruby]\n----\nclient = Kagi::API.new\n\nclient.search q: \"Ruby\"\n\n# Success(#\u003cdata Kagi::API::Models::Search meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=1225, balance=2.322512\u003e, data=[#\u003cdata 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\u003e]\u003e)\n\nclient.search\n\n# Failure(#\u003cdata Kagi::API::Models::Error meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=27, balance=2.322512\u003e, error=[#\u003cdata Kagi::API::Models::Content::Error code=1, message=\"Missing q parameter\", reference=nil\u003e]\u003e)\n----\n\nSee link:https://help.kagi.com/kagi/api/search.html[Kagi API Documentation] for further details.\n\n==== Summarize\n\nMessage `#summarize` to make API requests. Example:\n\n[source,ruby]\n----\nclient = Kagi::API.new\n\nclient.summarize url: \"https://www.ruby-lang.org/en\", summary_type: \"summary\"\n\n# Success(#\u003cdata Kagi::API::Models::Summary meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=3828, balance=2.261763\u003e, data=#\u003cdata 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\u003e\u003e)\n\nclient.summarize\n\n# Failure(#\u003cdata Kagi::API::Models::Error meta=#\u003cdata Kagi::API::Models::Content::Meta id=\"\u003credacted\u003e\", node=\"us-west2\", duration=114, balance=2.322512\u003e, error=[#\u003cdata Kagi::API::Models::Content::Error code=200, message=\"We are sorry, this input is not supported. (Invalid Input)\", reference=nil\u003e]\u003e)\n----\n\nSee link:https://help.kagi.com/kagi/api/summarizer.html[Kagi API Documentation] for further details.\n\n== Development\n\nTo contribute, run:\n\n[source,bash]\n----\ngit clone https://github.com/bkuhlmann/kagi-api\ncd kagi-api\nbin/setup\n----\n\nYou can also use the IRB console for direct access to all objects:\n\n[source,bash]\n----\nbin/console\n----\n\n== Tests\n\nTo test, run:\n\n[source,bash]\n----\nbin/rake\n----\n\n== link:https://alchemists.io/policies/license[License]\n\n== link:https://alchemists.io/policies/security[Security]\n\n== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]\n\n== link:https://alchemists.io/policies/contributions[Contributions]\n\n== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]\n\n== link:https://alchemists.io/projects/kagi-api/versions[Versions]\n\n== link:https://alchemists.io/community[Community]\n\n== Credits\n\n* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].\n* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkuhlmann%2Fkagi-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkuhlmann%2Fkagi-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkuhlmann%2Fkagi-api/lists"}