Integrations And API

Public API

Base URL:

https://app.knowlu.me/api/public/v1

OpenAPI:

https://app.knowlu.me/api/public/v1/docs
https://app.knowlu.me/api/public/v1/redoc
https://app.knowlu.me/api/public/v1/openapi.json

Authentication:

Authorization: Bearer kn_...

Source submission also requires:

Idempotency-Key: <unique-key-per-submit-attempt>

Public API Flow

The current API is source-scoped. It is designed for integrations that submit one URL, wait for completion, then consume fragments or an export.

Step	Endpoint
List projects	GET /projects
Submit one URL source	POST /sources
Poll source status	GET /sources/{source_id}
Read fragments	GET /sources/{source_id}/fragments
Queue Markdown export	POST /sources/{source_id}/export
Poll export	GET /exports/{export_id}

Submit A Source

curl -i https://app.knowlu.me/api/public/v1/sources \
  -H "Authorization: Bearer $KNOWLUME_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/article",
    "title": "Optional title",
    "project_slug": "inbox"
  }'

A successful request returns 202 Accepted and a source_id.

Poll Status

curl -sS https://app.knowlu.me/api/public/v1/sources/$SOURCE_ID \
  -H "Authorization: Bearer $KNOWLUME_API_KEY"

Terminal statuses are succeeded and failed.

Fetch Filtered Fragments

curl -sS "https://app.knowlu.me/api/public/v1/sources/$SOURCE_ID/fragments?reproducibility_min=7&originality_min=6&sourcesness_min=5&limit=50" \
  -H "Authorization: Bearer $KNOWLUME_API_KEY"

Score filters are inclusive. sourcesness keeps the existing public spelling.

Queue A Markdown Export

curl -sS -X POST "https://app.knowlu.me/api/public/v1/sources/$SOURCE_ID/export" \
  -H "Authorization: Bearer $KNOWLUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "markdown",
    "reproducibility_min": 7,
    "originality_min": 6,
    "sourcesness_min": 5
  }'

Then poll:

curl -sS "https://app.knowlu.me/api/public/v1/exports/$EXPORT_ID" \
  -H "Authorization: Bearer $KNOWLUME_API_KEY"

MCP

MCP endpoint:

https://app.knowlu.me/mcp/

Authentication:

Authorization: Bearer kn_...

Claude Code example:

claude mcp add --transport http knowlume https://app.knowlu.me/mcp/ \
  --header "Authorization: Bearer kn_..."

MCP is for agent clients that need direct access to Knowlume sources, fragments, and exports.

Export Webhooks

Users configure Integration Webhook in app settings.

The webhook payload is sent after successful Markdown export. It includes:

• event name;
• export id;
• source metadata;
• selected fragment Markdown;
• file URL when file delivery is enabled;
• API key metadata prefix.

The webhook is not a source-submission callback URL. It is a user-level export delivery setting.

Integration Design Rules

Use idempotency keys for source submission retries.

Poll source status before reading fragments.

Read Retry-After on retryable responses.

Avoid logging bearer tokens, source text, webhook payload bodies, or full exported content.

Keep external clients source-scoped until they need a project-wide query model.

For user-facing export behavior, see Fragments, Scores, And Export. For common request failures, see Troubleshooting.