YapHub

Appearance

API Reference ​

Last Updated: 2026-03-09 Version: 2.0 (Consolidated)

The Yappa Knowledge Hub exposes a RESTful JSON API for interacting with captured knowledge, categories, and AI summaries.

🏮 Knowledge Endpoints ​

POST /api/knowledge Creates a new internal knowledge item and triggers a sync to Notion.

  • Fields: title (req), content, url, tags (array), roleNames (array), categoryId.
  • Note: Triggers asynchronous AI summary generation for each specified role.

GET /api/knowledge Lists all local knowledge items.

  • Query Params: search, categoryId, status.

GET /api/knowledge/{id} Retrieves a single item including its versioned AI summaries and metadata.

🤖 AI Summary Endpoints ​

POST /api/ai-summary/regenerate Forces a new AI generation for a specific role and knowledge item.

  • Payload: knowledgeId, roleName.

PATCH /api/ai-summary/{id} Allows manual editing of an AI-generated summary. This marks the summary as isEdited = true to prevent future AI overwrites.

📘 Category (Thematic List) Endpoints ​

GET /api/categories Returns all active thematic lists, including their icons and default target roles.

POST /api/categories/sync Manually triggers a pull from the Notion Categories database to refresh the local cache.

🔄 Sync & Webhooks ​

POST /api/notion/sync Triggers a full bidirectional sync cycle between SQLite and Notion.

POST /api/notion/webhook Receives real-time updates from Notion (configured via Notion Integration settings).

Technical Details ​

  • Base URL: http://localhost:8000/api
  • Content-Type: application/json
  • Errors: Returns standard HTTP codes (400, 404, 500) with a { "error": "..." } body.

TIP

For local development, use the Local Knowledge Endpoints to bypass Notion network latency. // Update knowledge item const updateKnowledge = async (id, data) => { const response = await api.put(/knowledge/${id}, data); return response.data; };


### PHP (Guzzle)

```php
use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'http://localhost:8000/api',
    'headers' => [
        'Content-Type' => 'application/json',
    ],
]);

// Create knowledge item
$response = $client->post('/knowledge', [
    'json' => [
        'title' => 'My Knowledge',
        'content' => 'Content...',
        'tags' => ['tag1', 'tag2'],
    ],
]);
$knowledge = json_decode($response->getBody(), true);

// List knowledge items
$response = $client->get('/knowledge');
$items = json_decode($response->getBody(), true);

Python (Requests) ​

python
import requests

BASE_URL = 'http://localhost:8000/api'

# Create knowledge item
def create_knowledge(data):
    response = requests.post(
        f'{BASE_URL}/knowledge',
        json=data,
        headers={'Content-Type': 'application/json'}
    )
    return response.json()

# List knowledge items
def list_knowledge():
    response = requests.get(f'{BASE_URL}/knowledge')
    return response.json()

# Usage
knowledge = create_knowledge({
    'title': 'My Knowledge',
    'content': 'Content...',
    'tags': ['tag1', 'tag2']
})

OpenAPI/Swagger Documentation ​

Future Enhancement: Generate OpenAPI specification for interactive API documentation.

Proposed Tools:

  • NelmioApiDocBundle for Symfony
  • Swagger UI for interactive documentation
  • Postman collection export

Versioning ​

Currently, the API is unversioned.

Future Enhancement: Add API versioning:

/api/v1/knowledge
/api/v2/knowledge

Or via headers:

Accept: application/vnd.yappa.v1+json