` - Article slug, permalink identifier (`a-XXXXXXXX`), or UUID
```json Sample output (--json) theme={"system"}
{
"data": {
"article": {
"id": "a1b2c3d4-1111-2222-3333-444455556666",
"slug": "getting-started",
"title": "Getting Started Guide",
"state": "published",
"full_url": "https://spinkart.neetokb.com/articles/getting-started",
"url": "/articles/getting-started",
"html_content": "Welcome
This is a getting started guide.
",
"author": {
"name": "Oliver Smith",
"email": "oliver@example.com",
"profile_image_url": null
},
"category": {
"id": "b7e91c2a-8f43-4d0e-9a15-6c2d8e7f1b3a",
"name": "Getting Started"
}
},
"meta": {
"url": "/articles/getting-started",
"page_title": "Getting Started - Knowledge Base",
"meta_description": "A comprehensive guide to help you get started with our platform"
}
}
}
```
## Create an article
This command creates an article in a category. Use this when you want to publish content from a script or a content pipeline instead of the editor.
```bash theme={"system"}
neetokb articles create \
--title "Getting Started" \
--slug getting-started \
--category "Getting Started,Installation" \
--html-content "Welcome
Example content
" \
--state draft
```
| Flag | Type | Required | Default | Description |
| ---------------- | ------------- | -------- | ------- | ---------------------------------------------------- |
| `--category` | `stringSlice` | Yes | `[]` | Category path (comma-separated, e.g. 'Parent,Child') |
| `--html-content` | `string` | | | Article HTML content |
| `--slug` | `string` | | | Article slug |
| `--state` | `string` | | | Article state (draft/published) |
| `--title` | `string` | | | Article title |
`--category` is the category path, most specific first: `"Installation,Getting Started"` places the article in `Installation`, whose parent is `Getting Started`. Names are matched, not IDs or slugs. Omit `--state` and the article is created as a draft.
```json Sample output (--json) theme={"system"}
{
"data": {
"article": {
"id": "a1b2c3d4-1111-2222-3333-444455556666",
"slug": "getting-started",
"permalink": "a-84af178b"
}
},
"breadcrumbs": [
{ "label": "Show", "command": "neetokb articles show " }
]
}
```
With `--quiet`, this prints only the new article's ID.
## Update an article
This command updates an existing article's title, body, slug, or state. Use this to publish a draft, correct content, or rename an article's URL.
```bash theme={"system"}
neetokb articles update a-84af178b --title "Getting Started Guide"
neetokb articles update a-84af178b --state published
```
**Required arguments:**
* `` - Article slug, permalink identifier (`a-XXXXXXXX`), or UUID
| Flag | Type | Required | Default | Description |
| ---------------- | -------- | -------- | ------- | ------------------------------- |
| `--html-content` | `string` | | | Article HTML content |
| `--slug` | `string` | | | Article slug |
| `--state` | `string` | | | Article state (draft/published) |
| `--title` | `string` | | | Article title |
Only the flags you pass are changed. `--slug` can be modified only while the article is published.
```json Sample output (--json) theme={"system"}
{
"data": {
"article": {
"id": "a1b2c3d4-1111-2222-3333-444455556666",
"slug": "getting-started",
"title": "Getting Started Guide",
"state": "published",
"permalink": "a-84af178b"
}
}
}
```
## Unlisted links
An unlisted link is a secret URL that lets anyone view a published article without signing in. For fields and response details, see the [API reference](/api-reference/articles/get-unlisted-link).
### Get an unlisted link
This command fetches an article's unlisted link, creating a never-expiring one if the article does not have one yet. Use this when you want to share a published article outside your knowledge base.
```bash theme={"system"}
neetokb articles unlisted-links get getting-started
```
**Required arguments:**
* `` - Article slug, permalink identifier (`a-XXXXXXXX`), or UUID
```json Sample output (--json) theme={"system"}
{
"data": {
"unlisted_link": {
"url": "https://spinkart.neetokb.com/public/p-1a2b3c4d5e",
"enabled": true,
"expiration_type": "never",
"expiration_date": null
}
},
"breadcrumbs": [
{
"label": "Regenerate",
"command": "neetokb articles unlisted-links regenerate "
}
]
}
```
An expired link is replaced with a fresh one automatically. The article must be published; a draft returns an error.
### Regenerate an unlisted link
This command issues a new unlisted link and invalidates the old URL immediately. Use this when a link has been shared too widely, or when you want the link to expire.
```bash theme={"system"}
neetokb articles unlisted-links regenerate getting-started
neetokb articles unlisted-links regenerate getting-started --expiration-type seven_days
neetokb articles unlisted-links regenerate getting-started \
--expiration-type custom --expiration-date 2026-08-21T10:00:00Z
```
**Required arguments:**
* `` - Article slug, permalink identifier (`a-XXXXXXXX`), or UUID
| Flag | Type | Required | Default | Description |
| ------------------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--expiration-date` | `string` | | | Exact expiry datetime (ISO8601, future). Required with --expiration-type custom; implies custom when --expiration-type is omitted; rejected alongside presets or never |
| `--expiration-type` | `string` | | | Expiration preset: never (default, no expiration), one\_day, seven\_days, thirty\_days, or custom; preset dates are computed server-side and reject --expiration-date |
The presets `one_day`, `seven_days`, and `thirty_days` compute the expiry on the server and reject `--expiration-date`. Use `custom` together with `--expiration-date` for an exact time; passing `--expiration-date` alone is treated as `custom`.
```json Sample output (--json) theme={"system"}
{
"data": {
"unlisted_link": {
"url": "https://spinkart.neetokb.com/public/p-9f8e7d6c5b",
"enabled": true,
"expiration_type": "seven_days",
"expiration_date": "2026-08-07T10:00:00.000Z"
}
},
"breadcrumbs": [
{
"label": "Get",
"command": "neetokb articles unlisted-links get "
}
]
}
```
# Authors
Source: https://apidocs.neetokb.com/cli-reference/authors
List the people who have written articles in your knowledge base.
An author is a workspace user credited on one or more articles. For fields and response details, see the [API reference](/api-reference/authors/list).
Samples on this page show the `--json` envelope, which stays stable across terminals; the default pretty output picks columns to fit your terminal width. See [Output formats](/cli/output-formats).
## List authors
This command lists the authors in your workspace. Use this when you want to see who contributes content, or to match an article's author to a workspace account.
```bash theme={"system"}
neetokb authors list
```
| Flag | Type | Required | Default | Description |
| ------------- | ----- | -------- | ------- | ------------------------ |
| `--page` | `int` | | `0` | Page number |
| `--page-size` | `int` | | `0` | Items per page (max 100) |
```json Sample output (--json) theme={"system"}
{
"data": [
{
"name": "Oliver Smith",
"email": "oliver@example.com",
"profile_image_url": null
}
],
"breadcrumbs": [
{ "label": "List articles", "command": "neetokb articles list" }
],
"pagination": {
"total_records": 1,
"total_pages": 1,
"current_page_number": 1,
"page_size": 30
}
}
```
The list covers authors only. To manage workspace access, see [Team members](/cli-reference/team-members).
# Categories
Source: https://apidocs.neetokb.com/cli-reference/categories
List the categories that organize your knowledge base.
A category groups articles in your knowledge base and can nest inside another category. For fields and response details, see the [API reference](/api-reference/categories/list).
Samples on this page show the `--json` envelope, which stays stable across terminals; the default pretty output picks columns to fit your terminal width. See [Output formats](/cli/output-formats).
## List categories
This command lists the category tree with article counts. Use this when you want a category ID to filter articles by, or to check where a new article should go before creating it.
```bash theme={"system"}
neetokb categories list
neetokb categories list --page-size 100
```
| Flag | Type | Required | Default | Description |
| ------------- | ----- | -------- | ------- | ------------------------ |
| `--page` | `int` | | `0` | Page number |
| `--page-size` | `int` | | `0` | Items per page (max 100) |
```json Sample output (--json) theme={"system"}
{
"data": [
{
"id": "b7e91c2a-8f43-4d0e-9a15-6c2d8e7f1b3a",
"name": "Getting Started",
"slug": "getting-started",
"description": null,
"parent_id": null,
"depth": 0,
"articles_count": 12,
"categories_count": 2,
"total_articles_count": 18,
"url": "/categories/getting-started",
"subcategories": [],
"ancestors": []
}
],
"breadcrumbs": [
{
"label": "List articles in category",
"command": "neetokb articles list --category-id "
}
],
"pagination": {
"total_records": 1,
"total_pages": 1,
"current_page_number": 1,
"page_size": 30
}
}
```
`subcategories` nests the full child categories, and `ancestors` lists the parents up to the root. `articles_count` covers the category itself; `total_articles_count` includes its subcategories.
Pass an `id` from this list to [`neetokb articles list --category-id`](/cli-reference/articles#list-articles). To place a new article, [`neetokb articles create --category`](/cli-reference/articles#create-an-article) takes category *names*, not these IDs.
# Commands overview
Source: https://apidocs.neetokb.com/cli-reference/overview
Every neetokb command grouped by resource, with links to the full reference.
## Global flags
These flags work on every command and are left out of the per-command flag tables below. See [Output formats](/cli/output-formats) for details.
| Flag | Description |
| ------------- | ----------------------------------------------------- |
| `--json` | Output as JSON |
| `--quiet` | Output raw data only (no envelope) |
| `--toon` | Output in TOON format (token-optimized for AI agents) |
| `--subdomain` | Override saved subdomain |
### articles
Manage articles
| Command | Description |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`neetokb articles create`](/cli-reference/articles) | Create an article |
| [`neetokb articles list`](/cli-reference/articles) | List articles |
| [`neetokb articles show`](/cli-reference/articles) | Show an article |
| [`neetokb articles unlisted-links get`](/cli-reference/articles) | Fetch an article's unlisted share link, creating a never-expiring one if none exists (article-id: slug, permalink identifier a-XXXXXXXX, or UUID; article must be published) |
| [`neetokb articles unlisted-links regenerate`](/cli-reference/articles) | Regenerate an article's unlisted share link, invalidating the old URL immediately (article-id: slug, permalink identifier a-XXXXXXXX, or UUID; article must be published) |
| [`neetokb articles update`](/cli-reference/articles) | Update an article |
### authors
List article authors
| Command | Description |
| ------------------------------------------------ | ------------ |
| [`neetokb authors list`](/cli-reference/authors) | List authors |
### categories
Manage categories
| Command | Description |
| ------------------------------------------------------ | --------------- |
| [`neetokb categories list`](/cli-reference/categories) | List categories |
### doctor
Check CLI health and connectivity
| Command | Description |
| ------------------------------------------ | --------------------------------- |
| [`neetokb doctor`](/cli-reference/utility) | Check CLI health and connectivity |
### login
Authenticate to NeetoKB via browser
| Command | Description |
| ----------------------------------------- | ----------------------------------- |
| [`neetokb login`](/cli-reference/utility) | Authenticate to NeetoKB via browser |
### logout
Sign out and clear saved credentials
| Command | Description |
| ------------------------------------------ | ------------------------------------ |
| [`neetokb logout`](/cli-reference/utility) | Sign out and clear saved credentials |
### recommendations
Manage recommendations
| Command | Description |
| ---------------------------------------------------------------- | -------------------- |
| [`neetokb recommendations list`](/cli-reference/recommendations) | List recommendations |
### search
Search articles
| Command | Description |
| ------------------------------------------- | --------------- |
| [`neetokb search`](/cli-reference/articles) | Search articles |
### setup
Set up NeetoKB for AI coding assistants
| Command | Description |
| -------------------------------------------------- | ------------------------------------------- |
| [`neetokb setup claude`](/cli-reference/utility) | Register NeetoKB plugin with Claude Code |
| [`neetokb setup codex`](/cli-reference/utility) | Add NeetoKB instructions for OpenAI Codex |
| [`neetokb setup copilot`](/cli-reference/utility) | Add NeetoKB instructions for GitHub Copilot |
| [`neetokb setup cursor`](/cli-reference/utility) | Write NeetoKB rules for Cursor IDE |
| [`neetokb setup gemini`](/cli-reference/utility) | Add NeetoKB instructions for Gemini CLI |
| [`neetokb setup windsurf`](/cli-reference/utility) | Write NeetoKB rules for Windsurf IDE |
### team-members
Manage team members
| Command | Description |
| ------------------------------------------------------------ | -------------------- |
| [`neetokb team-members create`](/cli-reference/team-members) | Invite team members |
| [`neetokb team-members delete`](/cli-reference/team-members) | Remove a team member |
| [`neetokb team-members list`](/cli-reference/team-members) | List team members |
| [`neetokb team-members show`](/cli-reference/team-members) | Show a team member |
| [`neetokb team-members update`](/cli-reference/team-members) | Update a team member |
### update
Update the CLI to the latest version
| Command | Description |
| ------------------------------------------ | ------------------------------------ |
| [`neetokb update`](/cli-reference/utility) | Update the CLI to the latest version |
### version
Print the CLI version
| Command | Description |
| ------------------------------------------- | --------------------- |
| [`neetokb version`](/cli-reference/utility) | Print the CLI version |
### whoami
Show current authenticated user(s)
| Command | Description |
| ------------------------------------------ | ---------------------------------- |
| [`neetokb whoami`](/cli-reference/utility) | Show current authenticated user(s) |
### workspace
Manage workspace
| Command | Description |
| ---------------------------------------------------- | -------------------------- |
| [`neetokb workspace info`](/cli-reference/workspace) | Show workspace information |
# Recommendations
Source: https://apidocs.neetokb.com/cli-reference/recommendations
Fetch the articles NeetoKB recommends for a page or URL.
A recommendation is a group of articles NeetoKB suggests for a given page, used to surface contextual help. For fields and response details, see the [API reference](/api-reference/recommendations/get).
Samples on this page show the `--json` envelope, which stays stable across terminals; the default pretty output picks columns to fit your terminal width. See [Output formats](/cli/output-formats).
## List recommendations
This command returns the recommended articles for a page. Use this when you want to preview what your in-app help widget would show for a URL, or to build your own contextual help surface.
```bash theme={"system"}
neetokb recommendations list
neetokb recommendations list --match-uri feedback
```
| Flag | Type | Required | Default | Description |
| ------------- | -------- | -------- | ------- | ----------------------------- |
| `--match-uri` | `string` | | | Filter recommendations by URI |
| `--page` | `int` | | `0` | Page number |
| `--page-size` | `int` | | `0` | Items per page (max 100) |
`--match-uri` is the relative or full URL of the page you want suggestions for. Omit it to get the default recommendations.
```json Sample output (--json) theme={"system"}
{
"data": [
{
"title": "Feedback",
"articles": [
{
"id": "a1b2c3d4-1111-2222-3333-444455556666",
"title": "Collecting customer feedback",
"category": {
"id": "b7e91c2a-8f43-4d0e-9a15-6c2d8e7f1b3a",
"name": "Getting Started"
}
}
]
}
],
"breadcrumbs": [
{ "label": "List articles", "command": "neetokb articles list" }
],
"pagination": {
"total_records": 1,
"total_pages": 1,
"current_page_number": 1,
"page_size": 30
}
}
```
Each entry is a titled group holding the articles recommended for it. Pass an article `id` to [`neetokb articles show`](/cli-reference/articles#show-an-article) to read the full content.
# Team members
Source: https://apidocs.neetokb.com/cli-reference/team-members
List, view, invite, update, and remove team members.
A team member is a user in your workspace. For fields and response details, see the [API reference](/api-reference/team-members/list).
Samples on this page show the `--json` envelope, which stays stable across terminals; the default pretty output picks columns to fit your terminal width. See [Output formats](/cli/output-formats).
## List team members
This command shows the team members in your workspace. Use this when you want to see who already has access before inviting or removing someone, or to look up a member's ID.
```bash theme={"system"}
neetokb team-members list
neetokb team-members list --email oliver@example.com
```
| Flag | Type | Required | Default | Description |
| ------------- | -------- | -------- | ------- | ------------------------ |
| `--email` | `string` | | | Filter by email |
| `--page` | `int` | | `0` | Page number |
| `--page-size` | `int` | | `0` | Items per page (max 100) |
```json Sample output (--json) theme={"system"}
{
"data": [
{
"id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
"email": "oliver@example.com",
"first_name": "Oliver",
"last_name": "Smith",
"time_zone": "Asia/Kolkata",
"profile_image_url": null,
"active": true,
"organization_role": "Admin"
}
],
"breadcrumbs": [
{ "label": "Show", "command": "neetokb team-members show " },
{ "label": "Update", "command": "neetokb team-members update " },
{ "label": "Remove", "command": "neetokb team-members delete " }
],
"pagination": {
"total_records": 1,
"total_pages": 1,
"current_page_number": 1,
"page_size": 30
}
}
```
`--email` matches an address exactly; it does not search by partial address.
## Show a team member
This command shows details for one team member ID. Use this when you want to inspect a member's email, role, time zone, and active status after finding their ID from `team-members list`.
```bash theme={"system"}
neetokb team-members show aaaabbbb-cccc-dddd-eeee-ffff00001111
```
**Required arguments:**
* `` - Team member UUID
```json Sample output (--json) theme={"system"}
{
"data": {
"team_member": {
"id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
"email": "oliver@example.com",
"first_name": "Oliver",
"last_name": "Smith",
"time_zone": "Asia/Kolkata",
"profile_image_url": null,
"active": true,
"organization_role": "Admin"
}
}
}
```
## Invite team members
This command invites team members to your workspace. Use this when you want to add colleagues by email and assign an organization role without opening the Team Members page in NeetoKB.
```bash theme={"system"}
neetokb team-members create \
--emails oliver@example.com,sam@example.com \
--role Standard
```
| Flag | Type | Required | Default | Description |
| --------------- | ------------- | -------- | ------- | ------------------------------------------- |
| `--emails` | `stringSlice` | Yes | `[]` | Email addresses to invite (comma-separated) |
| `--role` | `string` | Yes | | Organization role |
| `--send-invite` | `bool` | | `true` | Send invitation email |
Invites one or more people in a single call. `--emails` takes a comma-separated list, and both it and `--role` are required. `--role` must name a role that already exists under **Settings → Roles**. Pass `--send-invite=false` to add them without sending an invitation email.
```json Sample output (--json) theme={"system"}
{
"data": {
"message": "Users added successfully"
},
"breadcrumbs": [
{ "label": "List team members", "command": "neetokb team-members list" }
]
}
```
The response confirms the request; it does not include a team member record. List the members afterwards to retrieve it.
## Update a team member
This command updates a team member's profile or role. Use this when correcting names, email, time zone, or organization role.
```bash theme={"system"}
neetokb team-members update aaaabbbb-cccc-dddd-eeee-ffff00001111 \
--first-name Oliver --role Admin
```
**Required arguments:**
* `` - Team member UUID
| Flag | Type | Required | Default | Description |
| -------------- | -------- | -------- | ------- | ----------------- |
| `--email` | `string` | | | New email address |
| `--first-name` | `string` | | | First name |
| `--last-name` | `string` | | | Last name |
| `--role` | `string` | | | Organization role |
| `--time-zone` | `string` | | | Time zone |
Only the flags you pass are changed. `--role` must name a role that already exists in the workspace.
```json Sample output (--json) theme={"system"}
{
"data": {
"team_member": {
"id": "aaaabbbb-cccc-dddd-eeee-ffff00001111",
"email": "oliver@example.com",
"first_name": "Oliver",
"last_name": "Smith",
"time_zone": "Asia/Kolkata",
"profile_image_url": null,
"active": true,
"organization_role": "Admin"
}
}
}
```
## Remove a team member
This command removes a team member from your workspace. Use this when someone should no longer have access.
```bash theme={"system"}
neetokb team-members delete aaaabbbb-cccc-dddd-eeee-ffff00001111
```
**Required arguments:**
* `` - Team member UUID
```text Sample output theme={"system"}
Team member removed.
```
With `--quiet`, this prints `success`.
# Utility commands
Source: https://apidocs.neetokb.com/cli-reference/utility
Authentication, diagnostics, versioning, updates, AI-assistant setup, and shell completion.
These commands manage the CLI itself rather than a NeetoKB resource.
## Authentication
### login
```bash theme={"system"}
neetokb login --subdomain your-workspace
```
Opens your browser to sign in and saves credentials for the workspace. Omit `--subdomain` to be prompted.
```text Sample output theme={"system"}
Authenticated as oliver@example.com on acme.neetokb.com.
```
### logout
```bash theme={"system"}
neetokb logout --subdomain your-workspace
neetokb logout --all
```
| Flag | Type | Required | Default | Description |
| ------- | ------ | -------- | ------- | --------------------------------- |
| `--all` | `bool` | | `false` | Sign out of every saved subdomain |
```text Sample output theme={"system"}
Signed out of acme.neetokb.com.
```
### whoami
```bash theme={"system"}
neetokb whoami
```
Lists each signed-in account and marks it `(default)` when only one is signed in. Pass `--subdomain ` to show one workspace.
```text Sample output theme={"system"}
Authenticated as oliver@example.com on acme.neetokb.com (default).
```
## Diagnostics
### doctor
```bash theme={"system"}
neetokb doctor
```
Checks authentication, API reachability, and the CLI version. See [Troubleshooting](/cli/troubleshooting). When several workspaces are signed in, pass `--subdomain `.
```text Sample output theme={"system"}
✓ Authentication: authenticated as oliver@example.com on acme.neetokb.com
✓ API connection: https://acme.neetokb.com (responding in 214ms)
✓ CLI version: 1.0.6
```
### version
```bash theme={"system"}
neetokb version
```
Prints the CLI version, commit hash, and build date.
```text Sample output theme={"system"}
neetokb 1.0.6 (commit: a1b2c3d, built: 2026-07-01)
```
### commands
```bash theme={"system"}
neetokb commands
```
Prints the complete command and flag catalog for the installed version as JSON. It is useful in scripts and with AI assistants.
```json Sample output theme={"system"}
[
{
"command": "neetokb articles",
"description": "Manage articles",
"subcommands": [
{
"command": "neetokb articles list",
"description": "List articles",
"flags": [
{ "name": "state", "type": "string", "description": "Filter by state (draft/published)" }
]
}
]
}
]
```
## Updates
### update
```bash theme={"system"}
neetokb update
```
Detects how the CLI was installed and runs the matching upgrade command: `brew upgrade` for a Homebrew install, the install script otherwise, and the PowerShell installer on Windows.
```text Sample output theme={"system"}
Detected Homebrew install.
Running: brew update && brew upgrade neetozone/tap/neetokb
```
## AI-assistant setup
Add NeetoKB instructions to your AI coding assistant. See [AI assistants](/cli/ai-assistants) for details.
```bash theme={"system"}
neetokb setup claude
neetokb setup cursor
neetokb setup windsurf
neetokb setup copilot
neetokb setup gemini
neetokb setup codex
```
```text Sample output theme={"system"}
NeetoKB plugin extracted to /Users/oliver/.config/neetokb/claude-plugin
To finish installation, open Claude Code and run these slash commands:
/plugin marketplace add /Users/oliver/.config/neetokb/claude-plugin
/plugin install neetokb@neetokb
(Claude Code installs plugins via interactive slash commands — there is no shell equivalent today.)
```
## Shell completion
Shell completion fills in command names, subcommands, and flags when you press `Tab`. It saves you from having to remember the full command tree or look up `--help`.
`neetokb completion ` installs completion for your shell. It writes a script under `~/.config/neetokb/completions` and configures your shell to load it the next time it starts.
```bash Zsh theme={"system"}
neetokb completion zsh
```
```bash Bash theme={"system"}
neetokb completion bash
```
```bash Fish theme={"system"}
neetokb completion fish
```
```powershell PowerShell theme={"system"}
neetokb completion powershell
```
Start a new shell (or run `source ~/.zshrc`) to enable it. After upgrading the CLI, run the command again to update the available completions. Re-running it replaces the existing script and configuration without adding duplicates.
To configure it yourself, pass `--print` to write the raw script to standard output instead of installing it:
```bash theme={"system"}
neetokb completion zsh --print
```
# Workspace
Source: https://apidocs.neetokb.com/cli-reference/workspace
View the settings of the knowledge base you are signed in to.
Workspace commands report the settings of the NeetoKB organization behind your current subdomain. For fields and response details, see the [API reference](/api-reference/settings/get).
Samples on this page show the `--json` envelope, which stays stable across terminals; the default pretty output picks columns to fit your terminal width. See [Output formats](/cli/output-formats).
## Show workspace information
This command shows your knowledge base's name and public URL. Use this to confirm which workspace a command will act on before running it, especially when several are signed in.
```bash theme={"system"}
neetokb workspace info
neetokb workspace info --subdomain acme
```
```json Sample output (--json) theme={"system"}
{
"data": {
"knowledge_base_name": "Spinkart Help Center",
"url": "https://spinkart.neetokb.com"
}
}
```
To check authentication and connectivity rather than workspace settings, run [`neetokb doctor`](/cli-reference/utility#doctor).
# AI assistants
Source: https://apidocs.neetokb.com/cli/ai-assistants
Set up NeetoKB for Claude, Cursor, Copilot, and other AI coding assistants.
Use the CLI with an AI coding assistant to manage NeetoKB in plain language. The `neetokb setup` commands add NeetoKB instructions for your assistant, while [`--toon`](/cli/output-formats) keeps command output compact for it to read.
## Set up your assistant
Run the subcommand for the tool you use:
| Command | What it does |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `neetokb setup claude` | Registers the NeetoKB plugin with Claude Code (plugin manifest, hooks, and skill). |
| `neetokb setup cursor` | Writes NeetoKB rules for the Cursor IDE. |
| `neetokb setup windsurf` | Writes NeetoKB rules for the Windsurf IDE. |
| `neetokb setup copilot` | Adds NeetoKB instructions for GitHub Copilot. |
| `neetokb setup gemini` | Adds NeetoKB instructions for the Gemini CLI. |
| `neetokb setup codex` | Adds NeetoKB instructions for OpenAI Codex. |
```bash theme={"system"}
neetokb setup claude
```
After setup, your assistant can check the commands and flags available in your installed CLI version:
```bash theme={"system"}
neetokb commands
```
The command prints the complete catalog as JSON.
## CLI or MCP?
Both surfaces let an assistant work with NeetoKB. The CLI runs on your machine and reuses your browser sign-in, so it suits coding assistants that already have a terminal. The [MCP server](/mcp/introduction) is hosted by NeetoKB and suits assistants without shell access; it connects with an OAuth grant scoped to you, or an API key scoped to the whole workspace.
## Tips for agent workflows
Prefer `--toon` when the assistant needs to read a list or record, and
`--quiet` when it needs to pipe an identifier into the next command. See
[Output formats](/cli/output-formats).
* Authenticate once with [`neetokb login`](/cli/authentication); the assistant reuses the stored credentials.
* When several workspaces are signed in, the assistant must pass `--subdomain ` on each command.
* Run [`neetokb doctor`](/cli/troubleshooting) first to confirm the assistant is authenticated and connected.
# Authentication
Source: https://apidocs.neetokb.com/cli/authentication
Sign in through the browser and manage credentials for one or more workspaces.
The CLI uses your browser to sign you in and securely saves your session, so you never need to enter an API key.
## Sign in
```bash theme={"system"}
neetokb login --subdomain your-workspace
```
Your browser opens to complete sign-in. Once you approve it, the CLI saves credentials for that subdomain. If you omit `--subdomain`, the CLI prompts for it.
Your subdomain is the first part of your workspace URL - for
`https://spinkart.neetokb.com`, the subdomain is `spinkart`. See [Workspace
subdomain](/getting-started/workspace-subdomain).
## Where credentials are stored
Credentials for every signed-in workspace live in a single file:
```
~/.config/neetokb/auth.json
```
Removing this file signs you out of every workspace, the same as `neetokb logout --all`.
## Check who you are
```bash theme={"system"}
neetokb whoami
```
Lists every signed-in account. When exactly one is signed in, it is marked `(default)`. Pass `--subdomain ` to show just one.
## Sign out
```bash theme={"system"}
neetokb logout --subdomain your-workspace # remove one workspace
neetokb logout --all # remove every workspace
neetokb logout # remove the only one, if a single workspace is signed in
```
## Working with multiple workspaces
You can sign in to several subdomains at once. To add another workspace, name its subdomain:
```bash theme={"system"}
neetokb login --subdomain globex
```
When more than one workspace is signed in, every command that talks to the API requires `--subdomain`. If you omit it, the CLI errors and lists the signed-in workspaces.
```bash theme={"system"}
neetokb articles list --subdomain acme
neetokb articles list --subdomain globex
```
With one signed-in workspace, it is the default and `--subdomain` stays optional.
## Troubleshooting
If sign-in or connection problems come up, run `neetokb doctor` first. See [Troubleshooting](/cli/troubleshooting) for common issues and fixes.
# Installation
Source: https://apidocs.neetokb.com/cli/installation
Install the neetokb CLI on macOS, Linux, or Windows.
Install the `neetokb` binary with the command for your platform, then [verify it](#verify-the-installation).
```bash macOS theme={"system"}
brew install neetozone/tap/neetokb
```
```bash Linux theme={"system"}
curl -fsSL https://neetokb.com/cli/install.sh | sh
```
```powershell Windows theme={"system"}
irm https://neetokb.com/cli/install.ps1 | iex
```
The shell and Windows installers download the latest release for your architecture (`amd64` or `arm64`), extract it, and add `neetokb` to your `PATH`.
## Other install methods
```bash theme={"system"}
curl -fsSL https://neetokb.com/cli/install.sh | sh
```
Installs to `/usr/local/bin` and may prompt for `sudo`. To update a Homebrew installation, run `brew upgrade neetokb`.
```cmd theme={"system"}
curl -fsSL https://neetokb.com/cli/install.cmd -o install.cmd && install.cmd
```
Extracts to `%LOCALAPPDATA%\Programs\neetokb` and adds it to your user `PATH`. This is equivalent to the PowerShell method.
## Verify the installation
Restart your terminal, then run:
```bash theme={"system"}
neetokb --help
```
You should see the list of available commands. To check the installed version:
```bash theme={"system"}
neetokb version
```
## Keep it up to date
`neetokb update` detects how the CLI was installed and runs the right upgrade command for you:
```bash theme={"system"}
neetokb update
```
Next, [sign in](/cli/authentication) to a workspace and run `neetokb doctor`
to confirm the CLI can reach NeetoKB.
# NeetoKB CLI
Source: https://apidocs.neetokb.com/cli/introduction
Manage articles, categories, authors, and team members from your terminal.
The **NeetoKB CLI** (`neetokb`) lets you manage NeetoKB from your terminal. It covers the [v2 REST API](/getting-started/introduction): list and search articles, create and publish content, browse the category tree, share unlisted links, and manage team members.
It is designed for people comfortable with a terminal or HTTP. You do not need to be a developer: run `neetokb setup` to connect an AI assistant such as Claude or Cursor, then describe the task in plain language.
## Why use the CLI?
Create and update articles from shell scripts, cron jobs, and content pipelines instead of the editor.
Search articles, list drafts, and pipe the results to `jq` to build one-off content reports.
Sign in to multiple workspaces at once and target any of them with a single flag - no browser switching.
Use token-efficient `--toon` output and one-command setup for Claude, Cursor, Copilot, and more.
## What you need
1. Access to one or more NeetoKB workspaces.
2. Permission to manage the resources you want to work with (articles, categories, team members, and so on).
3. The `neetokb` binary. See [Installation](/cli/installation).
Unlike the API, which authenticates with an `X-Api-Key` header, the CLI signs
you in through your browser and stores credentials locally. See
[Authentication](/cli/authentication).
# Output formats
Source: https://apidocs.neetokb.com/cli/output-formats
Pretty tables, JSON, quiet, and TOON - and when to use each.
Every command can return one of four output formats. In an interactive terminal, pretty output is the default. Use the flags below for machine-readable output.
| Format | Flag | Best for |
| ------ | ------------------------- | ----------------------------------------------------------------- |
| Pretty | *(default in a terminal)* | Reading a result yourself. |
| JSON | `--json` | Machine-readable payloads with pagination metadata. |
| Quiet | `--quiet` | Piping an identifier into another command or `jq`. |
| TOON | `--toon` | Feeding list/show output back to an LLM (fewer tokens than JSON). |
If more than one is set, precedence is `--toon` > `--quiet` > `--json` > pretty.
## Pretty
The default in a terminal: tables for lists and key-value pairs for a single record. It is intended for people, not scripts.
```bash theme={"system"}
neetokb articles list --state published
```
## JSON
JSON wraps the resource body with breadcrumbs and, for list commands, pagination details:
```json theme={"system"}
{
"data": [
{
"id": "a1b2c3d4-1111-2222-3333-444455556666",
"slug": "getting-started",
"title": "Getting Started Guide",
"state": "published"
}
],
"breadcrumbs": [{ "label": "Show", "command": "neetokb articles show " }],
"pagination": {
"total_records": 250,
"total_pages": 10,
"current_page_number": 1,
"page_size": 30
}
}
```
For list commands, `data` is the array of records; the CLI removes the API response's resource key. For `show`, `data` holds the API response body, such as `{ "article": { ... } }`.
`breadcrumbs` is omitted when empty, and `pagination` appears only on list commands. The CLI automatically uses JSON when output is piped (a non-TTY); use `--json` to force it.
## Quiet
`--quiet` returns only the `data` payload. For `create` and `update`, it prints the resource identifier; for `delete`, it prints `success`. This is useful in scripts:
```bash theme={"system"}
neetokb articles create \
--title "Getting Started" --category "Getting Started" \
--html-content "Welcome
" --state draft \
--quiet
# → prints the new article id
```
## TOON
`--toon` encodes the same data as TOON (Token-Optimized Output Notation). It keeps the JSON shape while compressing whitespace and keys, typically using 30–60% fewer tokens. Use it when giving list or show output to an AI assistant.
```bash theme={"system"}
neetokb search --search-term "billing" --toon
```
## Pagination
List commands return results in pages. The flags below control paging, and the JSON envelope's `pagination` block shows your position in the result set.
### Pagination Parameters
The page of results to retrieve, starting from 1.
The number of records to return per page (max 100).
### Example Usage
```bash theme={"system"}
neetokb articles list --page 2 --page-size 50
```
This returns the second page of articles, with 50 records per page.
### Response Structure
For list commands the JSON envelope carries a `pagination` block alongside the data:
```json theme={"system"}
{
"pagination": {
"total_records": 250,
"total_pages": 5,
"current_page_number": 2,
"page_size": 50
}
}
```
The total number of records across all pages.
The total number of pages available.
The page you are currently on.
The number of records returned per page.
### Default Behavior
If you omit both flags, the CLI lets the server use its defaults. Either flag overrides the defaults; `--page-size` accepts up to 100.
### Best Practices
* To retrieve every page, increment `--page` until `current_page_number == total_pages`.
* Use `--json` or `--toon` in scripts when you need the `pagination` block. `--quiet` removes the envelope, so it does not include pagination metadata.
* Check `total_records` before you begin to estimate the work involved.
# Troubleshooting
Source: https://apidocs.neetokb.com/cli/troubleshooting
Diagnose authentication and connectivity issues with neetokb doctor.
## Run the doctor
When something goes wrong, start with `neetokb doctor`. It checks your authentication, API connection, and CLI version.
```bash theme={"system"}
neetokb doctor
```
When multiple workspaces are signed in, name the one to check:
```bash theme={"system"}
neetokb doctor --subdomain your-workspace
```
## Common errors
When a command fails, it prints a one-line error message.
**Problem**: no workspace is signed in.
**Solution**: run [`neetokb login --subdomain `](/cli/authentication).
**Problem**: more than one workspace is signed in, so the target is ambiguous.
**Solution**: add `--subdomain ` to the command.
**Problem**: the `--subdomain` value doesn't match any signed-in workspace.
**Solution**: use one of the listed subdomains, or [sign in](/cli/authentication) to the new one.
**Problem**: a required flag was omitted.
**Solution**: check the command's [reference page](/cli-reference/overview) or run `neetokb --help` for the required flags.
**Problem**: the article is still a draft, so it has no public URL to share.
**Solution**: publish it with `neetokb articles update --state published`, then retry the [unlisted link command](/cli-reference/articles#unlisted-links).
**Problem**: the server rejected the request (for example, a validation error).
**Solution**: the CLI passes through the server's message. Check the JSON envelope (or `--quiet` payload) for `error`, `errors`, or `notice` and any suggestions from the API.
## Check the version
```bash theme={"system"}
neetokb version
```
Prints the CLI version, commit hash, and build date - useful when reporting an issue.
If you are behind the latest release, upgrade with:
```bash theme={"system"}
neetokb update
```
# Authentication
Source: https://apidocs.neetokb.com/getting-started/authentication
Learn how to authenticate your requests to the NeetoKB API using API keys.
### Generating an API Key
To use the NeetoKB APIs, you must first generate an API key.
[Learn how to generate your API key here.](https://help.neetokb.com/articles/api-keys)
### Making Authenticated API Requests
To authenticate your API requests, include a valid API key in the X-Api-Key header.
```shellscript theme={"system"}
curl https://spinkart.neetokb.com/api/external/v1/me \
-H 'X-Api-Key: your-api-key' \
-H 'Content-Type: application/json'
```
### Header Format
Include your API key in the `X-Api-Key` header of every request:
```http theme={"system"}
X-Api-Key: your_api_key_here
```
Generate separate API keys for different workspaces. An API key generated in
one workspace will not work in another.
API keys provide access to sensitive data. Treat them like passwords and
follow security best practices.
## Error Responses
### 401 Unauthorized
If your API key is missing, invalid, or expired, you'll receive a 401 error:
```json theme={"system"}
{
"error": "Could not authenticate, invalid API Key"
}
```
### Common Authentication Issues
**Problem**: API key is missing or invalid
**Solution**: Verify your API key is correct and hasn't been revoked/expired
**Problem**: Subdomain is left as the default value (**spinkart**) or incorrect
**Solution**: Verify your subdomain name is properly added in the request URL
# Getting the Article ID
Source: https://apidocs.neetokb.com/getting-started/getting-article-id
Understand how to retrieve article identifiers for use in your API calls.
## What is an article identifier?
Article identifiers are unique values used to reference specific articles in your knowledge base when making API requests. Understanding the different types of identifiers and how to find them is essential for working with the NeetoKB API.
NeetoKB supports three types of identifiers for articles, each serving different purposes:
* **ID (UUID)** - Permanent unique identifier.
Example: `285c4bab-3ca4-4a24-9288-73392a04554e`
* **Slug** - Human-readable URL identifier.
Example: `getting-started-guide`
* **Permalink** - Stable short identifier for updates.
Example: `a-d17829fc`
There are two main ways to get article identifiers:
* **Using the API** - Programmatically retrieve all articles and their identifiers.
* **From the URL** - Extract identifier directly from your browser's address bar.
Permalinks cannot be retrieved via the API or extracted from the URL. Refer to
the [help article](https://help.neetokb.com/articles/permalinks) for more information.
## Method 1: Using the API Endpoint
The [List all articles](/api-reference/articles/list) API endpoint allows you to retrieve a list of all articles in your workspace, including their identifiers. This is particularly useful when you need to programmatically access or retrieve the identifiers of all available articles.
### Step-by-Step Instructions
Send a `GET` request to the [List all articles](/api-reference/articles/list) API endpoint, including your API key in the request header.
The response will contain an array of articles, each with `id`, `slug`, and other fields.
Example:
```json theme={"system"}
{
"articles": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"slug": "getting-started",
"title": "Getting Started Guide",
"state": "published",
"unique_views_count": 123,
"category": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Tutorials"
}
},
// ... rest of the articles
],
"pagination": {
"total_records": 123,
"total_pages": 5,
"current_page_number": 1,
"page_size": 30
}
}
```
Here the article identifiers for the `Getting Started Guide` are:
* **ID**: `3c90c3cc-0d44-4b50-8888-8dd25736052a`
* **Slug**: `getting-started`
You can access the article identifiers in your code from the response using:
```javascript JavaScript theme={"system"}
// Get the first article's ID
const articleId = response.articles[0].id;
// Or iterate through all articles to find a specific one
const startedGuide = response.articles.find(article =>
article.title === "Getting Started Guide"
);
const startedGuideId = startedGuide.id;
const startedGuideSlug = startedGuide.slug;
```
```python Python theme={"system"}
# Get the first article's ID
article_id = response["articles"][0]["id"]
# Or iterate through all articles to find a specific one
for article in response["articles"]:
if article["title"] == "Getting Started Guide":
started_guide_id = article["id"]
started_guide_slug = article["slug"]
break
```
```bash Bash theme={"system"}
# Using jq to extract IDs from the response
curl -X GET "https://{workspace}.neetokb.com/api/external/v1/articles" \
-H 'X-Api-Key: your-api-key' | \
jq '.articles[0].id'
```
The `articles` array contains all articles in your workspace. If you have
multiple articles, you may want to filter by title or other properties to find
the specific article you need.
## Method 2: From the URL
Article identifiers appear in the URL when you view an article in your workspace. This method provides only the slug, not the article’s ID or permalink. For example, in the URL:
```
https://spinkart.neetokb.com/admin/categories/product-guides/articles/getting-started-guide/edit
```
The article slug is: **getting-started-guide**
### Step-by-Step Instructions
Log into your NeetoKB workspace and navigate to the article you want to work with.
Once you're viewing the article, look at your browser's address
bar. The URL will contain the
article identifier.
The article identifier is typically found in the URL path. Look for a pattern like:
```
https://your-subdomain.neetokb.com/admin/categories/product-guides/articles/{article-identifier}/edit
```
The `{article-identifier}` part is what you need.
### Examples
Here are some examples of how article identifiers appear in URLs & permalinks:
| URL Example | Article Identifier |
| ------------------------------------------------------------------------------------------------ | ----------------------- |
| `https://mycompany.neetokb.com/admin/categories/getting-started/articles/user-guide/edit` | `user-guide` |
| `https://support.neetokb.com/admin/categories/faq/articles/troubleshooting-tips/edit` | `troubleshooting-tips` |
| `https://docs.neetokb.com/admin/categories/developer-guides/articles/api-integration-guide/edit` | `api-integration-guide` |
| Permalink Example | Article Identifier |
| -------------------------------------------- | ------------------ |
| `https://mycompany.neetokb.com/p/a-84af178b` | a-84af178b |
| `https://support.neetokb.com/p/b-93cd289f` | b-93cd289f |
| `https://docs.neetokb.com/p/c-47de12ac` | c-47de12ac |
# Getting the Category ID
Source: https://apidocs.neetokb.com/getting-started/getting-category-id
Understand how to retrieve category IDs for use in your API calls.
## What is a category ID?
Category IDs are unique identifiers used to reference specific categories in your knowledge base when making API requests. To work effectively with the NeetoKB API, it’s important to know how to retrieve these IDs. You can do this programmatically by using the API to fetch all categories and their associated information.
## Using the API Endpoint
The [List all categories](/api-reference/categories/list) API endpoint allows you to retrieve a list of all categories in your workspace, including their IDs. This is particularly useful when you need to programmatically access or retrieve the IDs of all available categories.
### Step-by-Step Instructions
Send a `GET` request to the [List all categories](/api-reference/categories/list) API endpoint, including your API key in the request header.
The response will contain an array of categories with detailed information including `id`, `name`, count statistics, and nested subcategories.
Example:
```json theme={"system"}
{
"categories": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "Getting Started",
"description": "Essential guides to get you started",
"sequence": 1,
"parent_id": null,
"depth": 0,
"articles_count": 3,
"categories_count": 2,
"total_articles_count": 8,
"url": "https://example.neetokb.com/categories/getting-started",
"subcategories": [
{
"id": "b8e3d4f2-1a56-4c78-9012-345678901234",
"name": "Quick Setup",
"articles_count": 2,
"categories_count": 0,
"total_articles_count": 2
}
],
"ancestors": [],
"children": ["b8e3d4f2-1a56-4c78-9012-345678901234"],
"articles": [
{
"id": "f1a2b3c4-5d6e-7f8g-9h0i-1j2k3l4m5n6o",
"url": "https://example.neetokb.com/articles/welcome",
"title": "Welcome to NeetoKB",
"created_at": "2024-01-15T10:30:00Z",
"content": "Welcome to your knowledge base..."
}
]
},
// ... rest of the categories
],
"pagination": {
"total_records": 3,
"total_pages": 1,
"current_page_number": 1,
"page_size": 30
}
}
```
Here the category ID for the `Getting Started` category is:
* **ID**: `3c90c3cc-0d44-4b50-8888-8dd25736052a`
You can access the category information in your code from the response using:
```javascript JavaScript theme={"system"}
// Get the first category's ID and metadata
const category = response.categories[0];
const categoryId = category.id;
const articlesCount = category.articles_count;
const totalArticles = category.total_articles_count;
// Find a specific category by name
const gettingStartedCategory = response.categories.find(category =>
category.name === "Getting Started"
);
if (gettingStartedCategory) {
const id = gettingStartedCategory.id;
const subcategories = gettingStartedCategory.subcategories;
const articles = gettingStartedCategory.articles;
}
```
```python Python theme={"system"}
# Get the first category's ID and metadata
category = response["categories"][0]
category_id = category["id"]
articles_count = category["articles_count"]
total_articles = category["total_articles_count"]
# Find a specific category by name
for category in response["categories"]:
if category["name"] == "Getting Started":
getting_started_id = category["id"]
subcategories = category["subcategories"]
articles = category["articles"]
break
```
```bash Bash theme={"system"}
# Using jq to extract different fields from the response
curl -X GET "https://{workspace}.neetokb.com/api/external/v1/categories" \
-H 'X-Api-Key: your-api-key' | \
jq '.categories[0] | {id, name, articles_count, total_articles_count}'
```
The `categories` array contains all categories in your workspace with rich metadata:
* **Hierarchy**: `subcategories`, `ancestors`, `children`, `parent_id`, `depth` show the category structure
* **Statistics**: `articles_count`, `categories_count`, `total_articles_count` provide count information
* **Content**: `articles` array includes embedded article objects for each category
* **Identification**: UUID `id` is provided for referencing categories
If you have multiple categories, you may want to filter by name or other properties to find the specific category you need.
# Introduction
Source: https://apidocs.neetokb.com/getting-started/introduction
Welcome to the NeetoKB API documentation.
The NeetoKB API is organized around REST principles and uses standard HTTP response codes. All API endpoints return JSON responses and require authentication.
Before you start with NeetoKB APIs you will need the following:
1. [Workspace subdomain](/getting-started/workspace-subdomain).
2. [API key](/getting-started/authentication).
## Rate Limiting
API requests are subject to rate limiting to ensure fair use. If you exceed the rate limit, you'll receive a 429 response. If you encounter this error try again after some time.
## Need help?
Visit our [help center](https://help.neetokb.com), email us at [support@neetokb.com](mailto:support@neetokb.com), or join the [Neeto Community](https://neeto.com/community).
The community is powered by Slack and is the fastest way to get help directly from the developers, designers, and product folks building NeetoKB.
# Pagination
Source: https://apidocs.neetokb.com/getting-started/pagination
Learn how to handle paginated responses in the NeetoKB API.
## Pagination Parameters
You can control pagination using the following query parameters:
The page of results you want to retrieve (starting from 1)
The number of items to return per page
## Example Usage
Here's how to retrieve paginated results using cURL:
```bash cURL theme={"system"}
curl --request GET \
--url "https://{your-subdomain}.neetokb.com/api/external/v1/team_members?page_number=2&page_size=25" \
--header 'X-Api-Key: your-api-key'
```
```javascript JavaScript theme={"system"}
const response = await fetch('https://{your-subdomain}.neetokb.com/api/external/v1/team_members?page_number=2&page_size=25', {
method: 'GET',
headers: {
'X-Api-Key': 'your-api-key',
'Content-Type': 'application/json'
}
});
const data = await response.json();
console.log(data);
```
```python Python theme={"system"}
import requests
url = "https://{your-subdomain}.neetokb.com/api/external/v1/team_members"
params = {
"page_number": 2,
"page_size": 25
}
headers = {
"X-Api-Key": "your-api-key",
"Content-Type": "application/json"
}
response = requests.get(url, params=params, headers=headers)
data = response.json()
print(data)
```
This retrieves the second page of team members, with 25 results per page.
## Response Structure
Paginated responses include metadata about the pagination in JSON format:
```json Response Example theme={"system"}
{
"team_members": [
// ... array of team member objects
],
"pagination": {
"total_records": 150,
"total_pages": 6,
"current_page_number": 2,
"page_size": 25
}
}
```
The total number of items across all pages
The current page number (if pagination was used)
The total number of pages available (if pagination was used)
The number of items per page
## Default Behavior
If pagination parameters are not provided, default values will be applied:
* **page\_number**: 1 (first page)
* **page\_size**: 30 (30 items per page)
## Best Practices
1. **Start with reasonable page sizes**: Use page sizes between 10-100 items for optimal performance.
2. **Handle empty results**: Always check if the returned array is empty to detect the end of data.
3. **Use total\_records**: Use the `pagination.total_records` field to calculate the total number of pages needed.
4. **Implement error handling**: Handle cases where the requested page doesn't exist.
# HTTP Response Codes
Source: https://apidocs.neetokb.com/getting-started/response-codes
Learn about the HTTP status codes returned by the API.
## Success Codes
The request was successful and the server returned the requested data.
## Error codes
There was an issue with the request. This usually indicates malformed JSON,
missing required parameters, or invalid parameter values.
The request needs to be authenticated. This typically means: - Missing API key - Invalid API key - Expired API key
An operation was not allowed. This could mean: - Insufficient permissions for
the requested action - Attempting to access a resource you don't own - API key
doesn't have the required scope
The requested URL or resource was not found. This could indicate: - Incorrect
endpoint URL - Resource ID doesn't exist - Workspace subdomain is incorrect
The given request could not be processed by the server due to malformed
request. Check the request body once again.
Rate limit exceeded. Try again after some time.
An unexpected error occurred on the server. If this persists, please contact
support.
The server does not support the functionality required to fulfill the request.
## Error Response Format
When an error occurs, the API returns a JSON response with error details:
```json Error Response Example theme={"system"}
{
"message": "The provided API key is invalid or expired"
}
```
A human-readable error message
When debugging API issues, the HTTP status code often provides the first clue
about what went wrong. Start by checking the status code before diving into
the response body.
# Workspace subdomain
Source: https://apidocs.neetokb.com/getting-started/workspace-subdomain
Learn how to find your workspace subdomain.
## What is a Subdomain?
A subdomain is the part of your workspace URL that comes before the main domain. For example, in the URL:
```
https://spinkart.neetokb.com
```
**spinkart** is the subdomain.
This subdomain is crucial for making API requests, as it identifies your specific workspace within NeetoKB.
## Step-by-Step Instructions
You can usually find this in your browser's address bar when logged into your workspace.
Example:
```
https://your-subdomain.neetokb.com/admin/articles
```
Our main domain is: `neetokb.com`
Everything before `neetokb.com` is your subdomain.
**Example:**
* URL: `https://green-earth.neetokb.com`
* Subdomain: `green-earth`
## Using Your Subdomain in API Requests
Once you've identified your subdomain, you'll use it in all API requests. The base URL format is:
```
https://{your-subdomain}.neetokb.com/api/external/v1
```
For example, if your subdomain is `mycompany`, your API base URL would be:
```
https://mycompany.neetokb.com/api/external/v1
```
## Common Examples
Here are some common subdomain patterns:
| Type | Example URL | Subdomain |
| ---------- | --------------------------------------------------------- | ---------------- |
| Company | `https://acmecorp.neetokb.com/admin/articles` | `acmecorp` |
| Department | `https://marketing.neetokb.com/admin/reports/dashboard` | `marketing` |
| Project | `https://product-launch.neetokb.com/admin/my-preferences` | `product-launch` |
# Authentication
Source: https://apidocs.neetokb.com/mcp/authentication
Connect with OAuth for your own access, or an API key for the whole workspace.
The NeetoKB MCP server accepts two credentials, and the choice is a permissions boundary rather than a setup preference. Pick the one that matches how much of the knowledge base the assistant should reach.
| | OAuth | API key |
| ------------- | -------------------------- | -------------------------------- |
| **Scope** | The person who approved it | The whole workspace |
| **Identity** | A NeetoKB user | None |
| **Set up by** | Approving a sign-in prompt | Pasting a key into a config file |
## OAuth, scoped to you
An OAuth grant resolves to your NeetoKB user account, so every request runs under your permissions. Articles in categories you cannot see stay hidden, and an action you are not allowed to take is refused - the assistant sees exactly what you would see in the app.
The server publishes its metadata at `https://connect.neetokb.com/.well-known/oauth-authorization-server`:
| | |
| ----------------- | ------------------------------------------------- |
| **Authorization** | `https://connect.neetokb.com/mcp/oauth/authorize` |
| **Token** | `https://connect.neetokb.com/mcp/oauth/token` |
| **Registration** | `https://connect.neetokb.com/mcp/oauth/register` |
| **Revocation** | `https://connect.neetokb.com/mcp/oauth/revoke` |
| **Grant types** | `authorization_code`, `refresh_token` |
| **PKCE** | `S256` |
| **Scope** | `mcp` |
Clients register themselves, so there is no key to copy. You add the server URL, the assistant sends you to NeetoKB to approve it, and it refreshes the grant on its own from then on.
OAuth currently works with the assistants that sign in through a browser - **Claude** and **ChatGPT**. Assistants that complete sign-in on a local callback address are not able to register with this deployment yet, so they connect with an API key. See [Connect](/mcp/connect) for which is which.
To sign out, revoke the grant from your NeetoKB workspace or remove the server from the assistant.
## API key, scoped to the workspace
An API key carries no user identity. Requests made with it are not filtered by anyone's permissions, so the assistant can reach every article, category, and team member in the workspace, including drafts and private categories. Use it when you want a workspace-wide integration, or when your assistant cannot use OAuth.
It is the same key the [REST API](/getting-started/authentication) uses. [Learn how to generate one.](https://help.neetokb.com/articles/api-keys) Your assistant sends it on every request:
```http theme={"system"}
Authorization: Bearer
```
Set it once in the assistant's MCP configuration. [Connect](/mcp/connect) shows the right file and format for each one. Replace `YOUR_API_KEY` with your key, and the assistant sends the header for you.
Treat your API key like a password. Create a separate key for each workspace; a key only works in the workspace where you created it.
An API key gives access to the entire workspace, including unpublished drafts and team member records. Anyone who can read your assistant's configuration can use it. Do not commit it to a shared repository or paste it where others can see it.
## How each NeetoKB surface authenticates
| | How you authenticate |
| ------------ | ------------------------------------------------------------ |
| **REST API** | `X-Api-Key` header on every request |
| **CLI** | Sign in through your browser; credentials are stored locally |
| **MCP** | OAuth grant, or `Authorization: Bearer ` |
## When authentication fails
MCP does not expose a 401 error the way a direct API request does. A missing or invalid credential usually looks like one of these:
* The `neetokb` tools never appear in your assistant.
* A tool call fails, and the assistant reports it couldn't reach NeetoKB.
For an API key, that normally means the `Authorization` header is wrong: the key may be mistyped, belong to another workspace, or have been revoked. Verify or regenerate it in the [API Keys article](https://help.neetokb.com/articles/api-keys). For OAuth, the grant may have been revoked or the approval never completed - remove the server and add it again. Then follow [Troubleshooting](/mcp/troubleshooting).
# Connect
Source: https://apidocs.neetokb.com/mcp/connect
Point your AI assistant at the NeetoKB MCP server.
NeetoKB hosts the MCP server, so there is nothing to install or run locally. Add it to your assistant, then restart the assistant to make the `neetokb` tools available.
## Server details
| | |
| ------------------ | ------------------------------------------------------------------- |
| **Endpoint** | `https://connect.neetokb.com/mcp/messages` |
| **Transport** | HTTP |
| **Authentication** | An OAuth grant, or an `Authorization: Bearer ` header |
## Which method does your assistant use?
The credential decides what the assistant can reach, so read [Authentication](/mcp/authentication) before you pick.
| Assistant | Method | Where it is configured |
| ----------- | ------- | ------------------------------------- |
| Claude | OAuth | In-app, no config file |
| ChatGPT | OAuth | In-app, no config file |
| Claude Code | API key | `~/.claude.json` |
| Codex | API key | `~/.codex/config.toml` |
| Cursor | API key | `~/.cursor/mcp.json` |
| Gemini CLI | API key | `~/.gemini/settings.json` |
| VS Code | API key | `.vscode/mcp.json` |
| Windsurf | API key | `~/.codeium/windsurf/mcp_config.json` |
## OAuth assistants
Nothing to copy: add the server URL and approve the sign-in prompt.
Open **Settings → Connectors → Add → Add custom connector**, give it a **Name** such as `NeetoKB`, and paste the server URL:
```
https://connect.neetokb.com/mcp/messages
```
Save it, then click **Connect** on the new connector and approve the NeetoKB sign-in prompt. Works on claude.ai, the Claude desktop app, and Cowork.
Open **Settings → Security and login** and turn on **Developer mode**. Then go to **Plugins → Browse plugins → + → New Plugin** and paste the server URL:
```
https://connect.neetokb.com/mcp/messages
```
Approve the NeetoKB sign-in prompt when it appears.
## API key assistants
Replace `YOUR_API_KEY` with your [NeetoKB API key](/mcp/authentication) in each example below.
These files hold your API key in plain text, and some of them live inside a project you may share. Keep `.vscode/mcp.json` out of version control - add it to `.gitignore` before you commit - and never push any of these files to a public repository.
Add the server to `~/.claude.json`:
```json theme={"system"}
{
"mcpServers": {
"neetokb": {
"type": "http",
"url": "https://connect.neetokb.com/mcp/messages",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Or add it from the terminal:
```bash theme={"system"}
claude mcp add --transport http neetokb https://connect.neetokb.com/mcp/messages \
--header "Authorization: Bearer YOUR_API_KEY"
```
Save the file, then restart Claude Code.
Codex uses TOML, not JSON. Add the server to `~/.codex/config.toml`:
```toml theme={"system"}
[mcp_servers.neetokb]
url = "https://connect.neetokb.com/mcp/messages"
bearer_token_env_var = "NEETOKB_API_KEY"
```
`bearer_token_env_var` is the *name* of an environment variable, not the key itself. Export the key in your shell, then restart Codex:
```bash theme={"system"}
export NEETOKB_API_KEY=your-api-key
```
Create or edit `~/.cursor/mcp.json`:
```json theme={"system"}
{
"mcpServers": {
"neetokb": {
"url": "https://connect.neetokb.com/mcp/messages",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Save the file, then restart Cursor or reload its window from the command palette.
Add the server to `~/.gemini/settings.json`:
```json theme={"system"}
{
"mcpServers": {
"neetokb": {
"httpUrl": "https://connect.neetokb.com/mcp/messages",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Gemini CLI uses `httpUrl` for streamable HTTP servers; `url` means SSE and will not work here. Restart the CLI after saving.
Create `.vscode/mcp.json` in your workspace:
```json theme={"system"}
{
"servers": {
"neetokb": {
"type": "http",
"url": "https://connect.neetokb.com/mcp/messages",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
This requires VS Code 1.99 or later and GitHub Copilot Chat's **Agent** mode. VS Code uses `servers`, not `mcpServers`. Because this file lives in your repository, add it to `.gitignore` before committing.
Edit `~/.codeium/windsurf/mcp_config.json`:
```json theme={"system"}
{
"mcpServers": {
"neetokb": {
"serverUrl": "https://connect.neetokb.com/mcp/messages",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
Windsurf uses `serverUrl`, not `url`. Enable the server in **Settings → Cascade → MCP Servers**. Windsurf allows up to 100 MCP tools across all connected servers.
## Verify the connection
After your assistant reloads, confirm that `neetokb` is listed among its tools. Then try a prompt such as *"Search my NeetoKB articles for billing."* Find more in [Examples](/mcp/examples).
# Examples
Source: https://apidocs.neetokb.com/mcp/examples
Natural-language prompts for driving NeetoKB over MCP.
Once connected, you can ask your assistant directly. Try prompts like these:
## Look things up
* "Search my NeetoKB articles for billing."
* "Show me the Getting Started Guide article, including its HTML content."
* "List every draft article in my knowledge base."
* "What categories do I have, and how many articles are in each?"
## Write and publish
* "Draft a NeetoKB article called Refund policy under the Billing category."
* "Update the Getting Started Guide with this new intro paragraph."
* "Publish the Refund policy draft."
## Share and manage
* "Give me an unlisted link for the Refund policy article that expires in seven days."
* "Regenerate the unlisted link for Getting Started Guide - the old one leaked."
* "Invite [oliver@example.com](mailto:oliver@example.com) and [sam@example.com](mailto:sam@example.com) as Standard members."
* "Which articles does NeetoKB recommend for the /feedback page?"
Ask the assistant to confirm before it creates, publishes, or regenerates anything. MCP actions affect your live workspace, and regenerating an unlisted link breaks the previous URL immediately.
# NeetoKB MCP
Source: https://apidocs.neetokb.com/mcp/introduction
Manage your knowledge base from an AI assistant in plain language.
The NeetoKB **MCP server** lets your AI assistant work with your knowledge base from plain-language requests. Ask it to find an article, draft a new one, publish a change, share an unlisted link, or invite a teammate, and it works with your NeetoKB workspace for you.
[MCP](https://modelcontextprotocol.io) (Model Context Protocol) is an open standard that connects AI assistants to tools such as NeetoKB. You describe the task; the assistant uses the right tool.
## What you can do
Search and browse published articles and drafts, and read their full content.
Create articles in a category, revise them, and move them between draft and published.
Generate and regenerate unlisted links, with or without an expiry.
Browse the category tree, list authors and recommendations, and invite team members.
## What you need
1. A supported AI assistant - **Claude, ChatGPT, Claude Code, Codex, Cursor, Gemini CLI, VS Code (GitHub Copilot), or Windsurf**.
2. A way to authenticate. Claude and ChatGPT sign you in with OAuth, so there is nothing to copy. The others use a NeetoKB **API key** - [learn how to generate one](/mcp/authentication).
The two credentials differ in reach, not just in setup. An OAuth grant runs as **you**, so the assistant sees only what your permissions allow. An API key carries no identity and reaches the **whole workspace**, drafts and private categories included. [Authentication](/mcp/authentication) explains which to pick.
[Connect your assistant](/mcp/connect) to get started.
# Tools
Source: https://apidocs.neetokb.com/mcp/tools
The NeetoKB actions your AI assistant can perform over MCP.
The MCP server exposes NeetoKB's v2 resources as tools. You usually do not call a tool by name: describe the task and your assistant chooses one. The tools match the [REST API](/getting-started/introduction); each group below links to its API reference.
## Articles
Search and list articles, view one in full, and create or update them. Workspace tools cover drafts as well as published articles; a separate public tool reads a published article without workspace access. See [Articles](/api-reference/articles/list).
## Unlisted links
Fetch an article's unlisted share link, and regenerate it with an optional expiry. See [Get unlisted link](/api-reference/articles/get-unlisted-link) and [Regenerate unlisted link](/api-reference/articles/regenerate-unlisted-link).
## Categories
Browse the category hierarchy, including article counts and subcategories. See [Categories](/api-reference/categories/list).
## Authors
List the people credited on articles in your workspace. See [Authors](/api-reference/authors/list).
## Recommendations
Fetch the articles NeetoKB recommends for a page or URL. See [Recommendations](/api-reference/recommendations/get).
## Team members
List, view, invite, update, and remove team members. See [Team members](/api-reference/team-members/list).
## Workspace
Read the knowledge base's settings, such as its name and public URL. See [Settings](/api-reference/settings/get).
# Troubleshooting
Source: https://apidocs.neetokb.com/mcp/troubleshooting
Get the NeetoKB MCP server connected when the tools don't show up.
If the `neetokb` tools do not appear in your assistant, work through the checks for the way you connected. Each one corresponds to a [Connect](/mcp/connect) step.
## Every connection
Assistants read their MCP servers when they start. After adding the server or saving the configuration, restart the assistant or reload its window. The `neetokb` tools appear only after it reads the configuration again.
The endpoint must be exactly `https://connect.neetokb.com/mcp/messages`. A trailing slash or a missing `/messages` segment prevents the server from loading.
## OAuth assistants
These apply to **Claude** and **ChatGPT**.
Adding the connector does not sign you in. Claude needs you to click **Connect** on the connector afterwards; ChatGPT shows the prompt when you first use the plugin. If you dismissed it, remove the server and add it again.
The grant is bound to the workspace you picked while approving it. If the assistant reports finding no articles, you may have approved a different NeetoKB workspace - remove the connector, add it again, and choose the intended one.
An OAuth grant runs under your NeetoKB permissions, so articles in categories you cannot access stay hidden and restricted actions are refused. That is expected. For workspace-wide reach, connect with an [API key](/mcp/authentication) instead.
Custom MCP plugins are only available with **Developer mode** enabled under **Settings → Security and login**.
## API key assistants
These apply to **Claude Code, Codex, Cursor, Gemini CLI, VS Code, and Windsurf**.
One incorrect key prevents the server from loading. VS Code nests the server under `servers`, while the others use `mcpServers`. Windsurf uses `serverUrl` and Gemini CLI uses `httpUrl`; the rest use `url`. Codex uses TOML rather than JSON. Also check that the file parses: a trailing comma or missing brace stops it loading.
The `Authorization` header must contain `Bearer` followed by a valid NeetoKB API key. Generate or verify your key in the [API Keys article](https://help.neetokb.com/articles/api-keys). A key only works in the workspace where you created it.
`bearer_token_env_var` names an environment variable rather than holding the key. Confirm the variable is exported in the shell that launches Codex, and that the name matches the one in `config.toml`.
The NeetoKB server requires VS Code 1.99 or later and works in GitHub Copilot Chat's **Agent** mode. It is not available in Ask or Edit mode.
Enable the server in **Settings → Cascade → MCP Servers**. Windsurf allows up to 100 MCP tools across all connected servers. If you reach that limit, disable servers you are not using.
## Article errors
Unlisted links exist only for published articles. Ask the assistant to publish the article first, then request the link again.
If that does not resolve the issue, contact the team through the [help center](https://help.neetokb.com) or at [support@neetokb.com](mailto:support@neetokb.com).