diff --git a/doc/nonicons.nvim.txt b/doc/nonicons.nvim.txt
index aca5336..0fd5043 100644
--- a/doc/nonicons.nvim.txt
+++ b/doc/nonicons.nvim.txt
@@ -53,6 +53,33 @@ API                                                            *nonicons-api*
     Parameters: ~
         {name}  `string`  Icon name (e.g. `'lua'`, `'python'`, `'git-branch'`)
 
+    Returns: ~
+        `string?`  The single-character nonicons glyph
+
+                                                       *nonicons.get_icon()*
+`require('nonicons').get_icon(name, ext)`
+    Returns the nonicons character for a file, resolved by filename and/or
+    extension. Returns `nil` if no match is found (caller decides fallback).
+
+    Resolution order: exact extension → exact filename → extracted extension.
+
+    Parameters: ~
+        {name}  `string?`  Filename (e.g. `'init.lua'`, `'Makefile'`)
+        {ext}   `string?`  File extension (e.g. `'lua'`, `'py'`)
+
+    Returns: ~
+        `string?`  The single-character nonicons glyph
+
+                                              *nonicons.get_icon_by_filetype()*
+`require('nonicons').get_icon_by_filetype(ft)`
+    Returns the nonicons character for a vim filetype. Returns `nil` if no
+    match is found.
+
+    Resolution order: direct mapping key → extension table → filetype table.
+
+    Parameters: ~
+        {ft}  `string`  Vim filetype (e.g. `'python'`, `'typescriptreact'`)
+
     Returns: ~
         `string?`  The single-character nonicons glyph
 
@@ -128,8 +155,9 @@ mason.nvim ~
 
 oil.nvim ~
 
-    No configuration needed. oil.nvim reads the devicons extension/filename
-    tables directly, which nonicons.nvim mutates on load.
+    No configuration needed. oil.nvim detects nonicons.nvim and uses it as a
+    direct icon provider. If devicons is also loaded, the devicons override
+    still applies to other plugins.
 
 fzf-lua ~
 >lua
diff --git a/lua/nonicons/init.lua b/lua/nonicons/init.lua
index dbdb186..42c1539 100644
--- a/lua/nonicons/init.lua
+++ b/lua/nonicons/init.lua
@@ -40,4 +40,18 @@ function M.apply()
   end
 end
 
+function M.get_icon(name, ext)
+  local key = require('nonicons.resolve').resolve_name(name, ext)
+  if key then
+    return M.get(key)
+  end
+end
+
+function M.get_icon_by_filetype(ft)
+  local key = require('nonicons.resolve').resolve_filetype(ft)
+  if key then
+    return M.get(key)
+  end
+end
+
 return M