YapHub

Appearance

API Reference ​

Last Updated: 2026-05-08

The Yappa Knowledge Hub exposes 18 RESTful JSON API endpoints across 6 controllers. All endpoints require bearer token authentication (ROLE_ADMIN).

Authentication ​

All endpoints under /api/* require a valid bearer token:

Authorization: Bearer <token>

Configured via ACCESS_TOKEN environment variable.

Category Endpoints ​

POST /api/categories ​

Create a new category.

Request Body:

json
{
  "name": "Development",
  "description": "Development resources",
  "icon": ":computer:",
  "isActive": true,
  "sortOrder": 1,
  "targetGroups": ["developers"]
}

Response: 201 Created with category:read serialization group.

GET /api/categories ​

List all categories.

Response: 200 OK

json
{
  "success": true,
  "data": [...],
  "count": 10
}

Category Settings Endpoints ​

GET /api/categories/{id}/settings/digest ​

Get digest configuration for a category.

Response: 200 OK

json
{
  "enabled": true,
  "frequency": "weekly",
  "day": 5,
  "time": "16:00",
  "subscriberCount": 8,
  "lastDigestDate": "2026-05-01T16:00:00Z",
  "totalDigests": 12
}

PUT /api/categories/{id}/settings/digest ​

Update digest configuration.

Request Body:

json
{
  "enabled": true,
  "frequency": "biweekly",
  "day": 1,
  "time": "09:00"
}

Knowledge Endpoints ​

POST /api/knowledge ​

Create a new knowledge item.

Request Body:

json
{
  "title": "Kubernetes Best Practices",
  "content": "Article about K8s patterns",
  "categoryId": 3,
  "tags": ["kubernetes", "devops"],
  "url": "https://example.com/k8s-guide",
  "userId": "U01234567",
  "targetGroups": ["developers"]
}

Response: 201 Created with knowledge:read serialization group.

GET /api/knowledge ​

List knowledge items. Optional query param ?category=string to filter by category.

Response: 200 OK

json
{
  "success": true,
  "data": [...],
  "count": 42
}

Digest Endpoints ​

POST /api/digests/generate ​

Generate an AI-powered digest.

Request Body:

json
{
  "categoryId": 3,
  "preset": "7 days",
  "limit": 20,
  "distributeNow": false,
  "initiatorUserId": "U01234567"
}

Response: 200 OK with digest:read serialization group.

POST /api/digests/{id}/distribute ​

Distribute a digest to category subscribers.

Request Body:

json
{
  "initiatorUserId": "U01234567"
}

GET /api/digests/{id}/delivery-status ​

Get delivery status for a digest.

POST /api/digests/{id}/retry-failed ​

Retry failed deliveries for a digest.

GET /api/digests/category/ ​

List all digests for a category.

Notion Sync Endpoints ​

POST /api/notion/sync/from-notion ​

Sync knowledge items FROM Notion into local DB.

Query Params: ?force=true to overwrite local changes.

POST /api/notion/sync/categories-from-notion ​

Sync categories FROM Notion.

POST /api/notion/sync/to-notion ​

Push local knowledge items TO Notion.

Query Params: ?limit=100

Response:

json
{
  "status": "success",
  "synced": 15,
  "failed": 0,
  "totalProcessed": 15
}

Subscription Endpoints ​

POST /api/subscriptions/subscribe ​

Subscribe a user to a category.

Request Body:

json
{
  "userId": "U01234567",
  "categoryId": 3,
  "userName": "John Doe"
}

POST /api/subscriptions/unsubscribe ​

Unsubscribe a user (soft-delete).

GET /api/subscriptions/user/ ​

List all active subscriptions for a user.

GET /api/subscriptions/category/{categoryId}/subscribers ​

List subscriber user IDs for a category.

Technical Details ​

  • Base URL: http://localhost:8000/api
  • Content-Type: application/json
  • Auth: Bearer token (ROLE_ADMIN required on all endpoints)
  • Errors: Standard HTTP codes (400, 404, 500) with descriptive JSON body