Collections API

The Collections API manages knowledge base article collections (categories/folders) for organizing help content.

Collection Object

{
  id: string;                    // UUID
  organization_id: string;       // UUID of the organization
  name: string;                  // Collection name
  slug: string;                  // URL-friendly identifier
  description?: string;          // Collection description
  icon?: string;                 // Icon identifier or emoji
  position: number;              // Display order
  article_count: number;         // Number of articles in collection
  created_at: string;            // ISO timestamp
  updated_at: string;            // ISO timestamp
}

List Collections

Retrieve all collections for the organization.

Procedure: collections.list

Authentication: None (public endpoint)

Input:

{
  organizationId?: string;   // Filter by organization UUID
}

Example:

curl -X GET "https://your-domain.com/api/trpc/collections.list"

Response:

{
  "result": {
    "data": {
      "json": [
        {
          "id": "uuid",
          "name": "Getting Started",
          "slug": "getting-started",
          "description": "Guides to help you get up and running",
          "icon": "rocket",
          "position": 0,
          "article_count": 8,
          "created_at": "2024-01-01T00:00:00.000Z"
        },
        {
          "id": "uuid-2",
          "name": "Account & Billing",
          "slug": "account-billing",
          "description": "Manage your account and payment settings",
          "icon": "credit-card",
          "position": 1,
          "article_count": 12,
          "created_at": "2024-01-01T00:00:00.000Z"
        },
        {
          "id": "uuid-3",
          "name": "Troubleshooting",
          "slug": "troubleshooting",
          "description": "Solutions to common problems",
          "icon": "wrench",
          "position": 2,
          "article_count": 15,
          "created_at": "2024-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

Notes:

• Results are sorted by position (ascending)
• Includes article count for each collection

Get Collection

Retrieve a single collection by ID or slug.

Procedure: collections.get

Authentication: None (public endpoint)

Input:

{
  id?: string;     // Collection UUID
  slug?: string;   // Collection slug (alternative to id)
}

Example by ID:

curl -X GET "https://your-domain.com/api/trpc/collections.get?input=%7B%22id%22:%22collection-uuid%22%7D"

Example by Slug:

curl -X GET "https://your-domain.com/api/trpc/collections.get?input=%7B%22slug%22:%22getting-started%22%7D"

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "Getting Started",
        "slug": "getting-started",
        "description": "Guides to help you get up and running",
        "icon": "rocket",
        "position": 0,
        "article_count": 8,
        "articles": [
          {
            "id": "article-uuid",
            "title": "Quick Start Guide",
            "slug": "quick-start",
            "excerpt": "Get started in 5 minutes",
            "view_count": 1250
          },
          {
            "id": "article-uuid-2",
            "title": "First Steps",
            "slug": "first-steps",
            "excerpt": "Your first steps after signing up",
            "view_count": 890
          }
        ],
        "created_at": "2024-01-01T00:00:00.000Z"
      }
    }
  }
}

Notes:

• Includes published articles within the collection
• Articles sorted by position within collection

Create Collection

Create a new collection. Admin/Agent only.

Procedure: collections.create

Authentication: Required

Input:

{
  name: string;           // 1-200 characters
  slug: string;           // 1-200 characters, URL-safe
  description?: string;   // Optional description
  icon?: string;          // Optional icon identifier
}

Example:

curl -X POST "https://your-domain.com/api/trpc/collections.create" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "name": "API Documentation",
      "slug": "api-docs",
      "description": "Technical documentation for developers",
      "icon": "code"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "API Documentation",
        "slug": "api-docs",
        "description": "Technical documentation for developers",
        "icon": "code",
        "position": 3,
        "article_count": 0,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
}

Notes:

• Slug must be unique within the organization
• Position is automatically assigned (appended to end)

Update Collection

Update an existing collection. Admin/Agent only.

Procedure: collections.update

Authentication: Required

Input:

{
  id: string;             // Required, collection UUID
  name?: string;          // 1-200 characters
  slug?: string;          // 1-200 characters, URL-safe
  description?: string;   // Description
  icon?: string;          // Icon identifier
}

Example:

curl -X POST "https://your-domain.com/api/trpc/collections.update" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "id": "collection-uuid",
      "name": "Developer Docs",
      "description": "API guides and technical documentation"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "name": "Developer Docs",
        "slug": "api-docs",
        "description": "API guides and technical documentation",
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Delete Collection

Delete a collection. Admin/Agent only.

Procedure: collections.delete

Authentication: Required

Input:

{
  id: string;  // Collection UUID
}

Example:

curl -X POST "https://your-domain.com/api/trpc/collections.delete" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"id":"collection-uuid"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Notes:

• Articles in the collection are not deleted
• Articles will have their collection_id set to null
• Consider reassigning articles before deleting

Reorder Collections

Update the display order of collections. Admin/Agent only.

Procedure: collections.reorder

Authentication: Required

Input:

{
  orderedIds: string[];  // Array of collection UUIDs in desired order
}

Example:

curl -X POST "https://your-domain.com/api/trpc/collections.reorder" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "orderedIds": ["uuid-3", "uuid-1", "uuid-2"]
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Icon Options

Collections support various icon identifiers:

You can also use emoji characters directly (e.g., "🚀", "📚").

Use Cases

Knowledge Base Navigation

// Fetch all collections for sidebar
const collections = await trpc.collections.list.query()

// Display with article counts
collections.forEach(col => {
  console.log(`${col.icon} ${col.name} (${col.article_count} articles)`)
})

Collection Page

// Fetch collection with articles
const collection = await trpc.collections.get.query({ slug: 'getting-started' })

// Display articles
collection.articles.forEach(article => {
  console.log(`- ${article.title}: ${article.excerpt}`)
})

Admin Management

// Create a new collection
const newCollection = await trpc.collections.create.mutate({
  name: 'Release Notes',
  slug: 'release-notes',
  description: 'Product updates and changelog',
  icon: 'star'
})

// Reorder collections
await trpc.collections.reorder.mutate({
  orderedIds: ['uuid-1', 'uuid-4', 'uuid-2', 'uuid-3']
})

Error Codes