API Documentation

Integrate Zuro into your applications with our RESTful API

Quick Start

1. Get Your API Key

Navigate to your Account Settings → Security and create an API key.

2. Authenticate Requests

Include your API key in the request header:

X-API-Key: zuro_your_api_key_here

Or as a query parameter:

?api_key=zuro_your_api_key_here

3. Base URL

https://zuro.me/api/v1

Authentication

All API requests require authentication using an API key. Include your API key in one of the following ways:

Header (Recommended)

curl -H "X-API-Key: zuro_your_api_key_here" \
  https://zuro.me/api/v1/knowledge-bases

Query Parameter

curl https://zuro.me/api/v1/knowledge-bases?api_key=zuro_your_api_key_here

API Key Permissions

API keys have different permission levels based on your subscription tier:

Tier	Read	Write	Rate Limit
Starter			1,000 requests/month
Professional			5,000 requests/month
Enterprise			Unlimited

Note: Starter tier API keys are automatically set to read-only. Upgrade to Professional or Enterprise for write access.

API Endpoints

GET/knowledge-bases

Retrieve all knowledge bases for your account.

Example Request

curl -H "X-API-Key: zuro_your_api_key_here" \
  https://zuro.me/api/v1/knowledge-bases

Example Response

{
  "success": true,
  "data": {
    "knowledgeBases": [
      {
        "_id": "...",
        "name": "My Knowledge Base",
        "subdomain": "mykb",
        "createdAt": "2024-01-01T00:00:00.000Z"
      }
    ]
  }
}

GET/knowledge-bases/:subdomain/articles

Retrieve all approved articles for a specific knowledge base with optional pagination and filtering.

Query Parameters

limit (optional) - Number of results per page (default: 100, max: 1000)
skip (optional) - Number of results to skip for pagination (default: 0)
category (optional) - Filter by category name
tags (optional) - Filter by tags (comma-separated or array)

Example Request

curl -H "X-API-Key: zuro_your_api_key_here" \
  "https://zuro.me/api/v1/knowledge-bases/mykb/articles?limit=50&category=Getting%20Started&tags=api,docs"

Example Response

{
  "success": true,
  "data": {
    "articles": [
      {
        "_id": "...",
        "title": "Getting Started",
        "slug": "getting-started",
        "content": "...",
        "excerpt": "...",
        "category": "Getting Started",
        "tags": ["api", "docs"],
        "views": 150,
        "createdAt": "2024-01-01T00:00:00.000Z",
        "publishedAt": "2024-01-01T00:00:00.000Z"
      }
    ],
    "total": 25,
    "limit": 50,
    "skip": 0
  }
}

GET/articles/:id

Retrieve a specific article by ID.

Example Request

curl -H "X-API-Key: zuro_your_api_key_here" \
  https://zuro.me/api/v1/articles/507f1f77bcf86cd799439011

Example Response

{
  "success": true,
  "data": {
    "article": {
      "_id": "507f1f77bcf86cd799439011",
      "title": "Getting Started",
      "slug": "getting-started",
      "content": "...",
      "excerpt": "...",
      "category": "Getting Started",
      "tags": ["api", "docs"],
      "views": 150,
      "author": {
        "email": "user@example.com",
        "displayName": "John Doe"
      },
      "knowledgeBase": {
        "subdomain": "mykb",
        "owner": "..."
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "publishedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

GET/knowledge-bases/:subdomain/search

Search articles with full-text search, filters, and sorting options.

Query Parameters

q (optional) - Search query string
category (optional) - Filter by category
tags (optional) - Filter by tags (comma-separated or array)
author (optional) - Filter by author ID
dateFrom (optional) - Filter articles published after this date (ISO format)
dateTo (optional) - Filter articles published before this date (ISO format)
limit (optional) - Number of results (default: 20, max: 100)
skip (optional) - Number of results to skip (default: 0)
sortBy (optional) - Sort order: "relevance", "date", or "views" (default: "relevance")

Example Request

curl -H "X-API-Key: zuro_your_api_key_here" \
  "https://zuro.me/api/v1/knowledge-bases/mykb/search?q=getting%20started&category=Getting%20Started&sortBy=date&limit=20"

Example Response

{
  "success": true,
  "data": {
    "articles": [
      {
        "_id": "...",
        "title": "Getting Started",
        "slug": "getting-started",
        "excerpt": "...",
        "category": "Getting Started",
        "tags": ["api", "docs"],
        "views": 150,
        "publishedAt": "2024-01-01T00:00:00.000Z",
        "relevanceScore": 95
      }
    ],
    "total": 5,
    "query": "getting started",
    "filters": {
      "category": "Getting Started",
      "tags": []
    }
  }
}

GET/knowledge-bases/:subdomain/search/suggestions

Get search suggestions/autocomplete for a query. Returns matching titles, categories, and tags.

Query Parameters

q (required) - Search query (minimum 2 characters)
limit (optional) - Number of suggestions (default: 10, max: 20)

Example Request

curl -H "X-API-Key: zuro_your_api_key_here" \
  "https://zuro.me/api/v1/knowledge-bases/mykb/search/suggestions?q=get"

Example Response

{
  "success": true,
  "data": {
    "suggestions": [
      "Getting Started",
      "Getting Started with API",
      "Getting Started Guide"
    ]
  }
}

GET/knowledge-bases/:subdomain/articles/:slug/ratings

Get rating and feedback statistics for an article. Use this to display engagement metrics in your custom portal.

Example Request

curl -H "X-API-Key: zuro_your_api_key_here" \
  https://zuro.me/api/v1/knowledge-bases/mykb/articles/getting-started/ratings

Example Response

{
  "success": true,
  "data": {
    "stats": {
      "averageRating": 4.5,
      "totalRatings": 20,
      "helpfulCount": 45,
      "notHelpfulCount": 5,
      "ratingDistribution": {
        "1": 0,
        "2": 1,
        "3": 2,
        "4": 7,
        "5": 10
      }
    }
  }
}

Note: To allow end users to submit feedback, point your frontend to the public endpoints at /api/public/knowledge-bases/:subdomain/articles/:slug/feedback (no API key required).

POST/articlesWRITE

Create a new article. Requires write permissions.

Example Request

curl -X POST -H "X-API-Key: zuro_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Article",
    "content": "Article content here...",
    "knowledgeBase": "507f1f77bcf86cd799439011",
    "status": "draft"
  }' \
  https://zuro.me/api/v1/articles

Request Body

title (required) - Article title
content (required) - Article content (markdown supported)
knowledgeBase (required) - Knowledge base ID
slug (optional) - URL-friendly identifier (auto-generated from title if not provided)
excerpt (optional) - Short description
status (optional) - "draft" or "approved" (default: "draft")
category (optional) - Category name
tags (optional) - Array of tag strings
seo (optional) - SEO metadata object with metaTitle, metaDescription, keywords, etc.

PUT/articles/:idWRITE

Update an existing article. Requires write permissions.

Example Request

curl -X PUT -H "X-API-Key: zuro_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "content": "Updated content...",
    "status": "approved"
  }' \
  https://zuro.me/api/v1/articles/507f1f77bcf86cd799439011

Request Body

All fields are optional. Only include fields you want to update:

title - Article title
content - Article content
slug - URL-friendly identifier
excerpt - Short description
category - Category name
tags - Array of tag strings
status - "draft" or "approved"
seo - SEO metadata object

DELETE/articles/:idWRITE

Delete an article (soft delete). Requires write permissions.

Example Request

curl -X DELETE -H "X-API-Key: zuro_your_api_key_here" \
  https://zuro.me/api/v1/articles/507f1f77bcf86cd799439011

POST/knowledge-basesWRITE

Create a new knowledge base. Requires write permissions.

Example Request

curl -X POST -H "X-API-Key: zuro_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Knowledge Base",
    "subdomain": "mykb"
  }' \
  https://zuro.me/api/v1/knowledge-bases

Request Body

name (required) - Knowledge base name
subdomain (optional) - Custom subdomain (requires Professional/Enterprise plan)
settings (optional) - Settings object
branding (optional) - Branding configuration

PUT/knowledge-bases/:idWRITE

Update a knowledge base. Requires write permissions.

Example Request

curl -X PUT -H "X-API-Key: zuro_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name"
  }' \
  https://zuro.me/api/v1/knowledge-bases/507f1f77bcf86cd799439011

DELETE/knowledge-bases/:idWRITE

Delete a knowledge base (soft delete). Requires write permissions.

Example Request

curl -X DELETE -H "X-API-Key: zuro_your_api_key_here" \
  https://zuro.me/api/v1/knowledge-bases/507f1f77bcf86cd799439011

Rate Limiting

API requests are rate-limited based on your subscription tier:

Starter: 1,000 requests per month
Professional: 5,000 requests per month
Enterprise: Unlimited

When you exceed your rate limit, you'll receive a 429 Too Many Requests response.

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

Status Code	Description
200	Success
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "success": false,
  "error": "Error message here"
}

Model Context Protocol (MCP)

Professional+

🚨

Experimental Feature

The Zuro MCP Server is highly experimental. Expect bugs and missing features. While destructive operations are intentionally excluded, you should still carefully review any tool executions before running them.

What is MCP?

Model Context Protocol (MCP) enables AI assistants like Claude Desktop, Cursor IDE, and ChatGPT to interact with your Zuro knowledge bases. Instead of using REST API calls, you can have natural language conversations with your AI assistant to manage content.

MCP is available on Professional and Enterprise plans.Learn more about MCP.

Getting Started

1. Create an MCP Key

Go to your Account Settings → Security and create an MCP key. Select the specific permissions you want to grant:

articles:read, articles:write, articles:delete
knowledgebases:read, knowledgebases:write, knowledgebases:delete
categories:write, categories:delete
analytics:read
comments:read, comments:moderate
search:read

2. Configure Your AI Assistant

Add the Zuro MCP server to your AI assistant configuration. For Cursor IDE, you can use the one-click install:

Cursor IDE

Add to Cursor

Or manually edit .cursor/mcp.json:

⚠️ Important: After clicking "Add to Cursor", you'll need to replace YOUR_MCP_KEY_HERE with your actual MCP key from your account settings.

{
  "mcpServers": {
    "zuro": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.zuro.me/api/mcp?key=YOUR_MCP_KEY_HERE"
      ]
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zuro": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.zuro.me/api/mcp?key=YOUR_MCP_KEY_HERE"
      ]
    }
  }
}

3. MCP Endpoint

The MCP endpoint for direct API calls:

POST https://api.zuro.me/api/mcp

Include your MCP key as a query parameter: ?key=YOUR_MCP_KEY
Or in the request header: X-MCP-Key: zuro_mcp_your_key_here

MCP Protocol

MCP uses JSON-RPC 2.0 format. All requests must include:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1"
    }
  }
}

Available MCP Methods

initialize

Initialize the MCP connection and get server capabilities

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

tools/list

List all available tools (filtered by your MCP key permissions)

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

tools/call

Execute a tool with parameters

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_articles",
    "arguments": {
      "knowledgeBaseId": "507f1f77bcf86cd799439011",
      "limit": 10
    }
  }
}

resources/list

List available resources (currently returns empty array as resources are not yet implemented)

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/list",
  "params": {}
}

Available Tools

Article Management

• list_articles - List articles with filters
• get_article - Get article details
• create_article - Create new article
• update_article - Update article
• delete_article - Delete article
• list_article_versions - List article versions
• restore_article_version - Restore to version

Knowledge Base Management

• list_knowledge_bases - List all KBs
• get_knowledge_base - Get KB details
• create_knowledge_base - Create new KB
• update_knowledge_base - Update KB
• delete_knowledge_base - Delete KB

Category Management

• get_article_categories - Get all categories
• create_category - Create category
• update_category - Rename category
• delete_category - Delete category

Analytics

• get_knowledge_base_analytics - KB analytics
• get_article_analytics - Article analytics

Search & Comments

• search_articles - Full-text search
• get_article_tags - Get tags
• list_comments - List comments
• approve_comment - Approve comment
• reject_comment - Reject comment
• delete_comment - Delete comment

Example: Creating an Article

Note: The content field accepts Markdown format. Zuro will automatically convert it to HTML.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_article",
    "arguments": {
      "knowledgeBaseId": "507f1f77bcf86cd799439011",
      "title": "Getting Started with Zuro",
      "content": "# Welcome\n\nThis is your first article.\n\n## Features\n\n- Easy to use\n- Markdown support\n- Beautiful formatting",
      "status": "draft"
    }
  }
}

Rate Limits

• Professional: 1,000 requests per hour per key
• Enterprise: 5,000 requests per hour per key

Rate limit headers are included in responses: X-RateLimit-Limit,X-RateLimit-Remaining,X-RateLimit-Reset

Error Codes

Code	Message	Description
-32600	Invalid Request	JSON-RPC format error
-32601	Method not found	Unknown method or tool
-32602	Invalid params	Missing or invalid parameters
-32000	Tool execution error	Error during tool execution
-32001	Subscription required	Professional+ tier required
-32002	Rate limit exceeded	Too many requests
-32003	Permission denied	MCP key lacks required permission

Note: For detailed tool documentation, parameter descriptions, and more examples, see the tools/list response which includes full schemas for each tool.

Need Help?

If you have questions or need assistance with the API, please contact our support team.

For account management and API key creation, visit your Account Settings → Security.