API documentation

Integrate Dedox 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: dedox_your_api_key_here

3. Base URL

https://api.dedox.ai/v1

Source files for AI drafts are uploaded in the app, not through this API. Dedox reads PDF, Word, Markdown, text, PowerPoint, Excel, CSV, OpenDocument, RTF, EPUB, HTML and ZIP files, up to 25MB each (50MB for a ZIP). A public page address works too, including a public Google Docs or Sheets link.

Authentication

All API requests require authentication using an API key in the X-API-Key header.

Example

curl -H "X-API-Key: dedox_your_api_key_here" \
  https://api.dedox.ai/v1/knowledge-bases

API key permissions

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

TierReadWriteRate Limit
Starter1,000 requests/month
Team5,000 requests/month
Professional10,000 requests/month
EnterpriseUnlimited

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

API endpoints

GET/knowledge-bases

Retrieve all knowledge bases for your account.

Example request

curl -H "X-API-Key: dedox_your_api_key_here" \
  https://api.dedox.ai/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

NameRequiredDescription
limitNoNumber of results per page (default: 100, max: 1000)
skipNoNumber of results to skip for pagination (default: 0)
categoryNoFilter by category name
tagsNoFilter by tags (comma-separated or array)

Example request

curl -H "X-API-Key: dedox_your_api_key_here" \
  "https://api.dedox.ai/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: dedox_your_api_key_here" \
  https://api.dedox.ai/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": "editor@example.com",
        "displayName": "Help Team"
      },
      "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

NameRequiredDescription
qNoSearch query string
categoryNoFilter by category
tagsNoFilter by tags (comma-separated or array)
authorNoFilter by author ID
dateFromNoFilter articles published after this date (ISO format)
dateToNoFilter articles published before this date (ISO format)
limitNoNumber of results (default: 20, max: 100)
skipNoNumber of results to skip (default: 0)
sortByNoSort order: "relevance", "date", or "views" (default: "relevance")

Example request

curl -H "X-API-Key: dedox_your_api_key_here" \
  "https://api.dedox.ai/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

NameRequiredDescription
qYesSearch query (minimum 2 characters)
limitNoNumber of suggestions (default: 10, max: 20)

Example request

curl -H "X-API-Key: dedox_your_api_key_here" \
  "https://api.dedox.ai/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: dedox_your_api_key_here" \
  https://api.dedox.ai/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: dedox_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Article",
    "content": "Article content here...",
    "knowledgeBase": "507f1f77bcf86cd799439011",
    "status": "draft"
  }' \
  https://api.dedox.ai/v1/articles

Request body

NameRequiredDescription
titleYesArticle title
contentYesArticle content (markdown supported)
knowledgeBaseYesKnowledge base ID
slugNoURL-friendly identifier (auto-generated from title if not provided)
excerptNoShort description
statusNo"draft" or "approved" (default: "draft")
categoryNoCategory name
tagsNoArray of tag strings
seoNoSEO 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: dedox_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "content": "Updated content...",
    "status": "approved"
  }' \
  https://api.dedox.ai/v1/articles/507f1f77bcf86cd799439011

Request body

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

NameDescription
titleArticle title
contentArticle content
slugURL-friendly identifier
excerptShort description
categoryCategory name
tagsArray of tag strings
status"draft" or "approved"
seoSEO metadata object
DELETE/articles/:idWRITE

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

Example request

curl -X DELETE -H "X-API-Key: dedox_your_api_key_here" \
  https://api.dedox.ai/v1/articles/507f1f77bcf86cd799439011
POST/knowledge-basesWRITE

Create a new knowledge base. Requires write permissions.

Example request

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

Request body

NameRequiredDescription
nameYesKnowledge base name
subdomainNoCustom subdomain (requires Professional/Enterprise plan)
settingsNoSettings object
brandingNoBranding configuration
PUT/knowledge-bases/:idWRITE

Update a knowledge base. Requires write permissions.

Example request

curl -X PUT -H "X-API-Key: dedox_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name"
  }' \
  https://api.dedox.ai/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: dedox_your_api_key_here" \
  https://api.dedox.ai/v1/knowledge-bases/507f1f77bcf86cd799439011

Rate limiting

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

  • Starter: 1,000 requests per month
  • Team: 5,000 requests per month
  • Professional: 10,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 CodeDescription
200Success
401Unauthorised. Invalid or missing API key
403Forbidden: insufficient permissions
404Not found. The resource does not exist.
429Too many requests: rate limit exceeded
500Internal Server Error

Error response format

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

Model Context Protocol (MCP)

Professional+

Experimental feature

The MCP section on this page is experimental. Expect bugs and missing features, and review any tool call before you run it. The REST API above is the supported way to read and write your knowledge base.

What is MCP?

Model Context Protocol (MCP) enables AI assistants like Claude Desktop, Cursor IDE, and ChatGPT to interact with your Dedox 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 Dedox 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": {
    "dedox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.dedox.ai/mcp",
        "--header",
        "X-MCP-Key:YOUR_MCP_KEY_HERE"
      ]
    }
  }
}
Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "dedox": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.dedox.ai/mcp",
        "--header",
        "X-MCP-Key:YOUR_MCP_KEY_HERE"
      ]
    }
  }
}

3. MCP Endpoint

The MCP endpoint for direct API calls:

POST https://api.dedox.ai/mcp

Send your MCP key in the request header (recommended): X-MCP-Key: dedox_mcp_your_key_here
Query parameter ?key= is deprecated and disabled in production unless your operator enables MCP_ALLOW_QUERY_KEY=true.

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

Initialise 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

NameDescription
list_articlesList articles with filters
get_articleGet article details
create_articleCreate new article
update_articleUpdate article
delete_articleDelete article
list_article_versionsList article versions
restore_article_versionRestore to version

Knowledge base management

NameDescription
list_knowledge_basesList all KBs
get_knowledge_baseGet KB details
create_knowledge_baseCreate new KB
update_knowledge_baseUpdate KB
delete_knowledge_baseDelete KB

Category management

NameDescription
get_article_categoriesGet all categories
create_categoryCreate category
update_categoryRename category
delete_categoryDelete category

Analytics

NameDescription
get_knowledge_base_analyticsKB analytics
get_article_analyticsArticle analytics

Search & Comments

NameDescription
search_articlesFull-text search
get_article_tagsGet tags
list_commentsList comments
approve_commentApprove comment
reject_commentReject comment
delete_commentDelete comment

Example: creating an article

Note: The content field accepts Markdown format. Dedox 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 Dedox",
      "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: Unlimited

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

Error codes

CodeMessageDescription
-32600Invalid RequestJSON-RPC format error
-32601Method not foundUnknown method or tool
-32602Invalid paramsMissing or invalid parameters
-32000Tool execution errorError during tool execution
-32001Subscription requiredProfessional+ tier required
-32002Rate limit exceededToo many requests
-32003Permission deniedMCP 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.