TidySupport logo
TidySupport logo

  1. Home

    2. /

  2. Docs

    3. /

  3. API Reference

    4. /

  4. Knowledge Base

Knowledge Base API

Knowledge base articles power your AI support agent. When the agent receives a question, it searches these articles for relevant information to compose accurate responses. Use these endpoints to programmatically manage your knowledge base content.

Article Sources

Articles can be created from multiple sources:

  • MANUAL - Created manually via the API or dashboard
  • CRAWLER - Imported from a website crawl source
  • FILE_UPLOAD - Uploaded as a file (PDF, etc.)
  • CONVERSATION - Generated from a support conversation
  • REPLY_TEMPLATE - Derived from a reply template

Endpoints

GET/v1/workspaces/{workspaceId}/knowledge/articles

Lists all knowledge base articles in your workspace with offset pagination.

Request

curl "https://api.tidysupport.com/v1/workspaces/wrk_abc123/knowledge/articles?limit=10&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "articles": [
    {
      "id": "ka_abc123def456",
      "title": "How to reset your password",
      "contentText": "To reset your password, go to Settings > Security > Change Password...",
      "source": "MANUAL",
      "isPublished": true,
      "createdAt": "2025-02-01T10:00:00Z",
      "updatedAt": "2025-03-10T14:30:00Z"
    },
    {
      "id": "ka_xyz789ghi012",
      "title": "Billing FAQ",
      "contentText": "We offer monthly and annual billing. You can switch between plans...",
      "source": "CRAWLER",
      "sourceRef": "https://yoursite.com/help/billing",
      "isPublished": true,
      "createdAt": "2025-02-15T08:00:00Z",
      "updatedAt": "2025-02-15T08:00:00Z"
    }
  ],
  "total": 42
}

POST/v1/workspaces/{workspaceId}/knowledge/articles

Creates a new knowledge base article. The article content is automatically indexed for AI agent search after creation.

Request

curl -X POST "https://api.tidysupport.com/v1/workspaces/wrk_abc123/knowledge/articles" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How to reset your password",
    "contentText": "To reset your password:\n\n1. Go to Settings > Security\n2. Click Change Password\n3. Enter your current password\n4. Enter your new password\n5. Click Save\n\nIf you forgot your password, click Forgot Password on the login page to receive a reset link via email.",
    "isPublished": true
  }'

Response

{
  "article": {
    "id": "ka_new123abc456",
    "title": "How to reset your password",
    "contentText": "To reset your password:\n\n1. Go to Settings > Security...",
    "source": "MANUAL",
    "isPublished": true,
    "createdAt": "2025-03-13T10:00:00Z",
    "updatedAt": "2025-03-13T10:00:00Z"
  }
}

POST/v1/workspaces/{workspaceId}/knowledge/articles/{articleId}

Updates an existing knowledge base article. Only the fields you include in the request body are updated. The article is automatically re-indexed after changes.

Request

curl -X POST "https://api.tidysupport.com/v1/workspaces/wrk_abc123/knowledge/articles/ka_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How to reset your password (updated)",
    "contentText": "Updated instructions with new screenshots..."
  }'

Response

{
  "article": {
    "id": "ka_abc123def456",
    "title": "How to reset your password (updated)",
    "contentText": "Updated instructions with new screenshots...",
    "source": "MANUAL",
    "isPublished": true,
    "createdAt": "2025-02-01T10:00:00Z",
    "updatedAt": "2025-03-13T11:00:00Z"
  }
}

DELETE/v1/workspaces/{workspaceId}/knowledge/articles/{articleId}

Permanently deletes a knowledge base article. The article is immediately removed from the AI agent's search index.

Request

curl -X DELETE "https://api.tidysupport.com/v1/workspaces/wrk_abc123/knowledge/articles/ka_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true
}

Article Object

idstring
Unique identifier (prefixed with ka_)
titlestring
Article title
contentTextstring
Full article content in plain text
sourcestring
How the article was created (MANUAL, CRAWLER, FILE_UPLOAD, CONVERSATION, REPLY_TEMPLATE)
sourceRefstring | null
Source reference URL (for crawler-imported articles)
isPublishedboolean
Whether the article is searchable by the AI agent
createdAtstring
ISO 8601 timestamp when the article was created
updatedAtstring
ISO 8601 timestamp when the article was last updated

Best Practices

Write Focused Articles

Each article should cover a single topic or question. This helps the AI agent find the most relevant content and provide accurate answers. Avoid combining unrelated topics in one article.

Use Descriptive Titles

Article titles are used by the AI agent to match customer questions. Use clear, descriptive titles that match how customers would phrase their questions (e.g., “How to reset your password” rather than “Password Policy”).

Keep Content Up to Date

Outdated articles can cause the AI agent to give incorrect answers. Set up a regular review schedule and use the isPublished flag to temporarily hide articles that need updating.

Error Handling

400 - Invalid Content

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Title is required and must be between 1 and 500 characters."
}

404 - Article Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Article not found."
}