API Documentation

Integrate Zuro into your applications with our RESTful API

Quick Start

1. Get Your API Key

Navigate to your Account Settings 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"
}

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.