Knowledge

The knowledge base is the primary source Ogma searches when answering tickets and Playground questions.

What counts as knowledge

• Uploaded files (Markdown, plain text, HTML, JSON, CSV — not PDF)
• Pasted text blocks with an optional title
• Synced URLs that Ogma re-fetches on a schedule (public pages)
• Web scraper sources — Ogma POSTs to a URL you control; your server verifies the request and returns page content (for docs behind your auth gateway)

All content is chunked, embedded, and stored per server. Nothing is shared across servers.

Adding content

Upload

Drop one or more documents (max 5 MB each). Ogma extracts text and indexes it. Re-upload a file to refresh it.

Supported formats include .txt, .md, .markdown, .html, .htm, .json, and .csv (not PDF).

Paste

Paste documentation, answers, or notes directly. Give it a title so you can find it later. Good for internal runbooks or short procedures.

URL

Add a publicly accessible page. Ogma will fetch it and re-sync on a schedule based on your plan.

Plan	Minimum interval	Default for new URL sources	Max sources
Free	24 hours	24 hours	1
Plus	1 hour	3 hours	5
Enterprise	15 minutes	1 hour	50

You can set a custom refresh interval per source (minimum depends on plan).

If a URL fails to sync, the status column shows an error. Common causes:

• The page requires login or is behind a firewall.
• The site blocks scrapers or returns non-HTML content.
• The URL redirects through pages that require auth.

Fix the URL or visibility, then trigger Update now from the source detail view.

Web scraper

Use the Web scraper import when the page is not publicly fetchable, but you can expose an HTTPS endpoint that returns the document after verifying Ogma.

Ogma does not use HTTP basic auth. It uses the same webhook signing model as Agentic tools: your server checks Authorization and X-Ogma-Signature before returning content.

	URL import	Web scraper
HTTP method	GET (Ogma fetches the page directly)	POST (your server handles the request)
Authentication	None (page must be public)	Guild signing secret (+ optional custom headers)
Best for	Public docs, blogs, status pages	Internal docs, admin-only pages, auth gateways

Auto-sync intervals and per-plan source limits are the same as URL sources above.

How Ogma calls your endpoint

On import and on each scheduled refresh, Ogma sends:

POST <configured-url>
Content-Type: application/json
Accept: text/html, application/xhtml+xml, text/plain, application/json
Authorization: Bearer <guild-signing-secret>   (when webhook signing is enabled)
X-Ogma-Signature: t=<unix>,v1=<hmac-sha256-hex> (when webhook signing is enabled)
User-Agent: OgmaBot/1.0 (+https://github.com/ogma)

Any outgoing headers you configure in the dashboard are merged in (values are encrypted at rest and never shown again). You cannot override Authorization, X-Ogma-Signature, Content-Type, or Host.

Request body (JSON):

{
  "guildId": "123456789012345678",
  "url": "https://docs.example.com/internal/runbook",
  "timestamp": 1712345678
}

• guildId — Discord server ID for this Ogma workspace.
• url — Normalized source URL stored for this knowledge document (http/https only).
• timestamp — Unix seconds; also used in the signature header as t=.

When Webhook signing is enabled in the import dialog (default), Ogma uses the guild’s Agentic tools signing secret. If none exists yet, Ogma creates one automatically (same as creating your first agentic tool). Disable signing only for endpoints that do not require auth.

Verify the request on your server

Signature rules are identical to agentic tool webhooks. Ogma computes:

HMAC-SHA256(signing-secret, timestamp + "." + raw-json-body)

…and sends the hex digest in X-Ogma-Signature as t=<timestamp>,v1=<hex>.

Always verify using the raw request body string — do not re-serialize parsed JSON. Reject timestamps older than five minutes.

See Verify signatures for Node.js (@ogmasupport/webhook) and manual verification steps in other languages.

Minimal handler outline:

1. Read the raw POST body.
2. Verify Authorization: Bearer <secret> and/or X-Ogma-Signature.
3. Optionally confirm body.url matches the document you intend to serve.
4. Return the page as HTML or plain text with HTTP 2xx.

Ogma converts HTML to text (same pipeline as URL import), chunks it, and embeds it for search.

Response requirements

• HTTP 2xx with a non-empty body.
• Content-Type of HTML or plain text, or HTML that starts with < (detected automatically).
• Empty pages and non-text responses fail the sync with an error on the Knowledge page.

Optional custom headers

Add outbound headers in the import dialog when your gateway expects extra values (for example an API key header). Names must be letters, numbers, and hyphens. Values are encrypted at rest.

Troubleshooting scraper syncs

Symptom	Likely cause
401 / 403	Signature or Bearer token mismatch; clock skew; wrong signing secret
404	POST URL path wrong, or handler only accepts GET
Empty content	Response body has no readable text after HTML conversion
Signing secret unavailable	SECRETS_ENCRYPTION_KEY not configured on the Ogma API (see Agentic tools)

Use Update now on the source detail view after fixing your endpoint. Previous indexed content is kept until a refresh succeeds.

Source health

The Knowledge page surfaces source health — problems that cause bad answers before users hit them:

Status	Meaning
Healthy	Synced recently, no errors
Stale sync	Content may be outdated
Sync overdue	Scheduled refresh has not run
Sync failed	Last fetch or index failed
Never synced	URL added but not yet indexed
Never retrieved	Indexed but not used in recent ticket or Playground searches

The Overview page also shows a knowledge sync summary. Fix sync errors and stale sources proactively.

Freshness alerts

Sources flagged as stale or never retrieved in search appear under freshness alerts. These are candidates for update, removal, or Playground testing — content that exists but may not help users.

Duplicate and overlap detection

Ogma scans tips against knowledge docs to find:

• Tips that overlap long-form KB content
• Near-duplicate tips
• Conflicting answers between tips

Review overlaps periodically and merge or delete redundant tips. Last scan time and next available scan are shown on the Knowledge page.

The ingest command

Add short notes from Discord:

/ingest content:Your text here title:Optional title

Handy for capturing something from a live ticket. For larger content, use the dashboard.

Editing and version history

For pasted and uploaded documents, open Edit content on the Knowledge page to change title and body in a VS Code-style editor (Monaco) with syntax highlighting for Markdown, JSON, HTML, and plain text. Use the pencil icon in the folder sidebar to create a new document in the current folder. Each content change:

1. Snapshots the previous version (deduplicated by content hash — identical re-syncs skip new versions and re-embedding).
2. Re-chunks and re-embeds the updated text.

Use Version history in the editor to compare a past version against the current content and Revert when needed. Ogma keeps the last 50 versions per document. URL-, scraper-, and Git-managed docs sync through their normal pipelines; manual edits are for paste/upload sources.

Playground

Playground tests real support behavior:

• Type a question the way a user would.
• See the answer Ogma would give.
• See which chunks were retrieved and their scores.
• See agentic tool calls and results.

Use Playground to validate new docs, debug weak answers, and verify agentic tools. Do not use /ask or /ogma askgpt for this — those ignore your knowledge base.

On a free trial, the dashboard warns before Playground runs that consume AI quota beyond included limits.

Tips vs long-form knowledge

Knowledge is for reference material. Tips are for short, repeated answers. Both are searched together.

See Tips and Auto-learn.

Background jobs

URL syncs and tip backfill batch jobs appear on Background jobs while running. See Background jobs.

Keeping knowledge healthy

• Remove or update stale content when freshness alerts fire.
• Split very long documents when answers are weak.
• Watch Insights → Knowledge gaps for escalations with nothing to retrieve.
• Use Playground after every significant add or edit.

Related: Tips, Auto-learn, Insights, Commands (/ingest), Billing (indexing limits and overage).