Using Deskcite

Deskcite helps helpdesk workers find answers in their team's documentation. Ask a customer question, review the matching passages, and open the source before using an answer in your response. Search returns stored answers extracted from imported documents; it does not write a new customer reply.

Start with a customer question

1. Sign in with your username, password, and current six-digit authenticator code.
2. Select search in the sidebar, or press 1 when you are not typing in a field.
3. Enter a specific question, such as “How can a customer reset their authenticator after losing their phone?” Include the product or feature name when it helps distinguish similar procedures.
4. Click Ask or press Enter. Deskcite requests up to eight matching records and combines duplicate answer text into result cards.
5. Read the answer and click its card to open the source document beside the results. Check the surrounding section, prerequisites, and exceptions before responding to the customer.

Search works by meaning, so you can use the customer's own wording. If a question contains several problems, search for each one separately. If results are weak, include a specific error message or feature name and try again.

Dictate into a text field

Click the microphone beside an editable text field to dictate in English. On first use, Deskcite loads a speech model of about 142 MB from your Deskcite server and shows its progress. Allow microphone access when your browser asks. Speech recognition runs in your browser; microphone audio is not sent to a transcription service.

Text appears in the field as Whisper returns each streaming chunk, just as in the agent UI. The microphone stays on while you speak. In the search field, a break in transcript updates of about 1.2 seconds stops capture once queued transcription has caught up, flushes the final words, and starts an automatic search. Submitting a search stops recording and clears the field for your next question. Click the microphone to start dictating the next question. New words arriving during the request stay in the field; a failed search restores its question if the field is still empty. Non-speech markers such as [BLANK_AUDIO], (clicking), and other bracketed or parenthesized annotations are excluded from dictated input. Clicking Ask or pressing Enter while dictating also searches after the final words arrive. Click the microphone or press Escape to stop recording. Escape cancels any pending automatic search.

In other fields, click the microphone again or press Escape to stop, wait for the final words, and review the text before submitting. Clicking a submit control while recording stops dictation first; submit again after reviewing. Text is inserted at your cursor or replaces your selection. Passwords and authenticator codes have no microphone.

Switching views or hiding the tab stops recording. Dictation needs HTTPS with a trusted certificate (or localhost), microphone access, and a browser supporting WebAssembly threads and AudioWorklet. If the control reports missing speech assets, ask your administrator to install them with the Deskcite build. You can always type normally.

Understand a result

Each card shows an answer passage, a source path, a section number or heading, and a match percentage. The percentage is a ranking aid derived from search distance. It is not a probability that the answer is correct. A highly ranked passage may still describe a different version or customer situation.

Identical answer text can appear in multiple sections. Same answer in other sections lists those additional locations; the card opens the primary source. Select text to copy it without opening the document. There is no automatic send-to-customer action.

The source panel attempts to highlight the matching passage. Highlighting may not find an exact match, especially in PDFs or converted documents. Read or search within the source when needed. For mirrored web pages, see original opens the live source in a new tab. The imported copy can differ from the live page. Use close to return to the full result area.

Give feedback and revisit searches

Use ↑ Helpful when the answer fits the question and ↓ Not helpful when it does not. Click the selected rating again to clear it. Feedback changes later search ranking; rerun the search to see updated results.

Ratings are stored against the normalized query text and answer record, rather than a private per-user preference. They can affect your teammates' results. Down-votes penalize that answer's future matches; up-votes remove that query's down-vote penalty rather than guaranteeing first place.

recent searches lets you reopen previous results. Repeating a question refreshes its entry. The browser tab keeps up to 50 recent searches in session storage; this is not a shared ticket history. clear removes the displayed search history, not the indexed documentation or stored feedback.

Add documentation to the dataset

Select dataset or press 2. Import documents your team should use as answer sources.

Import from a URL

1. Paste the documentation URL into import from url.
2. Click Import.
3. Watch import activity for crawling, indexing, and completion or failure.
4. Once the import finishes, return to search and ask a question covered by the source.

URL import mirrors pages under the selected site and path, then extracts and stores Q&A pairs and embeddings. Start with the relevant documentation directory rather than a whole site. The server must be able to fetch the pages; signing in to a website in your own browser does not give the crawler that session.

Upload a document

1. Drop a file onto upload document, or click to browse.
2. Check the selected filename.
3. Click Upload & Import and follow import activity.

The file picker accepts HTML, Markdown, plain text, PDF, and RST files. The browser sends PDFs as base64 and other files as UTF-8 text. PDFs need extractable text; image-only scans may need OCR before upload.

“Queued for indexing” means the request was accepted, not that its answers are searchable. Wait for completion. A finished import with no useful answers may mean the document contained little extractable text. Import activity is cached in the current tab and expires after six hours; it is not a permanent job audit. Clearing activity does not cancel imports or delete knowledge.

Monitor work and schedule goals

Select agents or press 3 to inspect running work, task counts, schedules, and recent runs. Use refresh to request the latest state. The view also refreshes while open. If the agent service is unavailable, ask your administrator to check it.

To schedule a goal, enter a name and goal, then choose Recurring / crontab or One-off. Recurring schedules use five standard cron fields. One-off schedules use the date and time entered in your browser. Check the calendar's displayed timezone when reviewing occurrences.

You can describe timing in words and click Translate. Translation fills a proposal for review; it does not automatically enable it. Review the proposed timing, select Enable automatic scheduling when ready, and click Save schedule. Check the synchronization status and calendar. You can edit or enable/disable saved schedules. If another edit causes a conflict, reload the schedules before retrying.

Canceling queued tasks affects pending work and does not stop an import already running. Coordinate with your team before using this control.

Accounts and recovery

If signup is available, choose Sign up, complete the account fields, add the provided authenticator setup to your authenticator app, and confirm with a current code. Save the recovery codes before opening the workspace. Keep them somewhere you can access if you lose your authenticator.

Use the recovery option on the sign-in screen if you cannot provide an authenticator code. Follow the prompts to set up replacement access. If you have neither the authenticator nor recovery codes, contact your administrator. Sign out ends the current login session.

Troubleshooting

Keyboard shortcuts outside text fields: 1 search, 2 dataset, 3 agents, 4 documentation, j / ↓ next view, k / ↑ previous view, and ? shortcut help.

Integrating with Deskcite

Use the HTTPS JSON API to search stored answers, submit feedback, retrieve Q&A records, and import sources. The app uses these same routes. Examples below use a fictional customer question and illustrative response values.

Connect and authenticate

Set BASE to the origin of your Deskcite instance, without /deskcite. The default local HTTPS port is 4433; the supplied Docker host mapping uses 6433. Use your deployment's trusted TLS certificate or supply its CA with curl's --cacert option.

export BASE='https://localhost:6433'

Obtain a session from POST /auth/login using an existing account's user, password, and current otp. Its successful JSON response includes access_token. Send that value as Authorization: Bearer TOKEN on protected requests. For example, the login body is:

{"user":"worker@example.com","password":"YOUR_PASSWORD","otp":"123456"}

# Set TOKEN to the access_token returned by your login client.
export TOKEN='YOUR_ACCESS_TOKEN'
curl --fail-with-body "$BASE/deskcite/similar" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"text":"How do I reset an authenticator?","n":8}'

The supplied configuration makes /deskcite (status), /deskcite/ui, and selected shell assets public. Search, imports, agent operations, and source documents require credentials unless the deployment explicitly configures otherwise. Login sessions and routing grants have different authorization semantics; grants must cover the requested path. Do not assume anonymous access from older API examples.

POST /auth/refresh refreshes a session and POST /auth/logout ends it; both take bearer authorization. Handle expiry by obtaining fresh credentials. Do not automatically replay login or other authenticator-consuming requests with a used code. Account enrollment, recovery, and grant administration are supplied by mesgd; this guide focuses on Deskcite's product API.

Search for answers

POST /deskcite/similar

Send text (a nonempty string) and optional n (an integer from 1 to 100, default 8). question is accepted as an alias for text.

{
  "ok": true,
  "rows": [{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "question": "How do I reset an authenticator?",
    "answer": "Follow your organization's account recovery procedure.",
    "path": "/deskcite/documents/recovery.md",
    "segment": 2,
    "headings": "Account recovery",
    "distance": 0.18,
    "vote": null
  }]
}

id identifies the stored question record; keep it for feedback or retrieval. path, segment, and headings identify the source location. distance is the feedback-adjusted semantic distance; smaller values rank better. vote is up, down, or null for this query/record. An empty result is 200 with rows: [].

The UI groups identical answer text and displays a match percentage computed as round(max(0, 1 - distance) * 100). API clients receive individual rows. Scores are ranking signals, not calibrated confidence. The first request can take longer while the embedding model starts.

POST /deskcite/ask

Send {"text":"How do I reset an authenticator?"}. This returns the single nearest stored row with ok: true, rather than a rows array. It does not synthesize a new answer. No match returns 404 with {"ok":false,"error":"no matching answer"}.

Full-text and graph search

GET /deskcite/search?q=recovery calls the separate erag document pipeline, rather than the Q&A table used by similar and ask. Optional types is a comma-separated filter such as document,section,image; document restricts the document path. Blank q produces empty results. text and question are aliases for q.

GET /deskcite/search/graph?q=recovery&mode=subgraph&hop=1 requests the graph pipeline. Both routes also accept POST bodies with these fields. Their returned data is supplied by erag; do not treat it as the semantic answer-row schema. Availability and content depend on the deployment's erag index and configuration.

Record feedback

POST /deskcite/rate

Send the result's question id, the original search text, and vote as up, down, or clear.

curl --fail-with-body "$BASE/deskcite/rate" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","text":"How do I reset an authenticator?","vote":"up"}'

Success returns 200 with {"ok":true,"id":"…","vote":"up"}. Clearing returns vote: null. An unknown record returns 404.

A new rating replaces the previous mark for the same normalized query and record. These marks are shared rather than scoped to the caller. A down-vote reduces that answer's match by a factor of four in later semantic queries; distinct query texts can add further penalties. Up or clear removes that query's negative mark. Rerun a search to observe the new ranking.

Retrieve and create knowledge

GET /deskcite/question/UUID

Returns ok, id, question, answer, path, segment, and headings. Unlike search results, this response has no distance or vote. Invalid UUIDs return 400; missing records return 404.

POST /deskcite/question

Required nonempty strings: question, answer, and path. Optional segment is an integer (default 0); headings defaults to an empty value.

{
  "question": "Where is the recovery procedure?",
  "answer": "Open the account recovery guide.",
  "path": "/deskcite/documents/recovery.md",
  "segment": 0,
  "headings": "Recovery"
}

Success is 201 with ok: true, id, and answer_id. Creation inserts a pair; it does not upload the source file. Do not assume this call also completes embedding. The normal document import workflow performs extraction and embedding; verify search availability if you insert pairs directly. Repeating a create request can insert another record.

GET /deskcite/documents/PATH

Fetches an original uploaded or mirrored source as bytes with the appropriate content type. Send bearer authorization. The server applies configured folder restrictions and returns 403 for denied access or 404 for missing files. Use the source path returned by the service when it refers to this route; do not append it to /deskcite again.

Import documentation

POST /deskcite/import

For a URL, send {"url":"https://docs.example.com/guide/"}. For a text file, send:

{"name":"recovery.md","content":"# Recovery\nFollow the account recovery procedure."}

For binary content such as PDF, set encoding to base64 and supply valid base64 in content. The optional folder string selects a storage subfolder for file imports. Text defaults to utf8. Supply either the URL form or the file form; if both are present the URL form wins.

The response is 202, for example:

{"ok":true,"status":"queued","source":"recovery.md"}

This acknowledges submission, not completion or successful indexing. There is no durable job ID or per-job polling endpoint in this handler. Submitting again may repeat work. Observe the app's import activity or service events and verify that expected answers become searchable.

POST /deskcite/embed

No request body. Queues one pass of faqerl_embed:backfill/0, which fills vectors for stored questions that do not have one yet. POST /deskcite/question inserts a pair and does not embed it; call this afterwards so similar and ask can find the new row.

The response is 202 with {"ok":true,"status":"queued"}, or "status":"running" when a pass is already in progress. This acknowledges the queue, not a finished embedding. A second call while a pass is running does not start another. Check GET /deskcite and compare questions with embedded, or search for the new text.

The app subscribes to wss://HOST/deskcite/events using WebSocket subprotocols json and the bearer token as a second protocol value. Import events include type, source, and ts; progress, completion, and failure can include msg. Types are import.start, import.progress, import.done, and import.error. Correlate by source; identical concurrent sources are ambiguous. This stream is live, with no replay guarantee.

Agent operations

These routes expose shared operational state and scheduling controls. Use them only when your integration needs to manage team work.

Save a recurring schedule with action: "save", name, objective, kind: "cron", five-field cron, and boolean enabled. For a one-off use kind: "once" and an ISO 8601 run_at timestamp instead of cron. To edit, include the existing id and version. The UI submits the full schedule for toggles as well. A stale version returns 409; reload before retrying. Check the returned cron_status to confirm synchronization.

{"action":"propose","prompt":"Every weekday at 9am"} asks the model to suggest timing. Review the proposal before saving and enabling. The result may ask a clarifying question instead of returning a complete proposal. {"action":"calendar","start":1792972800,"end":1793577600} requests occurrences for a range expressed in Unix seconds, with end greater than start and a maximum span of 43 days. Model or agent unavailability can return 503; invalid proposals can return 502.

Status, dispatch, and failures

GET /deskcite returns {"ok":true,"questions":1420,"answers":1402,"embedded":1398} with current counts. Counts indicate stored state, not the success of a particular import.

POST /deskcite also supports JSON dispatch using op: status, similar, ask, rate, question, search, or search_graph. Use dedicated routes in new clients for clarity. PUT aliases POST for forwarded Q&A routes; Deskcite-specific import and agent actions are POST routes. DELETE does not delete knowledge and returns method-not-allowed for recognized forwarded routes.

Deskcite handlers generally return {"ok":false,"error":"…"} for errors. Authentication middleware can return a different shape. Check HTTP status before parsing success fields and tolerate error bodies that are not JSON. Avoid blind retries of imports, record creation, or credential-consuming operations. Search and document access have separate authorization checks; integrations must enforce their own customer-facing disclosure policy before presenting results.