Reference: every value

This chapter is a set of lookup tables. Use it when you see a word, a badge, a colour, a status or a number in RAGGuard and want to know exactly what it means and what to do about it. It covers the issue types, severities, statuses, document states, vector classes, audit runs and their numbers, the health score, repair plans, connection states, test results, alert outcomes, settings, the HTTP API, limits, and a glossary. The explanations of whole pages are in the other chapters; this one is for looking things up. New to the vocabulary? Start with Concepts you need.

Colours below are the ones the interface uses. Green means good, amber means look at it, red means act, blue means in progress or informational, grey means neutral.

On this page

Issue types

There are eleven issue types. The label is what you see in the interface; the internal name is what appears in the API, in exports and in the Type filter's address.

LabelInternal nameSeverity and how it is decidedSystems involvedRecommended actionWhat it means and what to do
Missing embeddingsmissing_embeddingHigh. Critical when the manifest claims success (a success-like status, or an indexed chunk count above 0). Not raised while the document is inside the grace period.Amazon S3, QdrantFull reindexThe document exists in S3 but the index holds nothing for it, so users get no answer from it. Re-process the document. If the pipeline reported success, find out why it wrote nothing.
Partial indexpartial_indexHigh. Critical when the manifest claims success. Medium when only gaps in the chunk numbers suggest it ("suspected"). Skipped when the document is stale.Qdrant, PostgreSQLRe-embed missing chunksOnly some of the expected chunks are indexed, so answers can be silently incomplete. Expected chunks come from the chunk table if you configured one, otherwise from the manifest's expected chunk count, otherwise from gaps in the chunk numbers. Re-embed the missing chunks (a full rebuild is also safe).
Stale document versionstale_embeddingHigh. Medium when the source hash is a multipart ETag, which is not a real content hash. Not raised during the grace period.Amazon S3, QdrantFull reindexThe source changed but every indexed vector still describes the previous version. Also raised when the vectors carry no hash or version and the manifest's hash differs from the source's. Re-process the document.
Superseded vectors activesuperseded_activeMedium. High when a retrieval probe shows the old content is really returned.QdrantRemove old vectorsThe current version is indexed, but vectors of an older version or built with an older pipeline setup still answer queries and can outrank the new content. Remove them after the replacements are verified.
Orphan vectorsorphan_vectorHigh. Critical when a retrieval probe shows the content is returned for a matching query.Amazon S3, QdrantRemove old vectorsThe document was deleted at the source but its vectors are still searchable. It exists under no other tenant. Remove the vectors.
Duplicate chunksduplicate_chunkMediumQdrantRemove old vectorsThe same chunk is indexed more than once, typically after retried jobs. The first copy seen is kept and the rest are listed for removal.
Metadata mismatchmetadata_inconsistentThe highest severity among its problems (see Metadata problems)PostgreSQL, QdrantFix metadata. Needs a human for the collection-level variant.The source, the manifest and the vector payloads disagree on counts, versions, access-control hashes or required fields. One issue per document lists all its problems. Correct the manifest or the payload; no re-embedding is needed.
Pipeline driftpipeline_driftHigh when the embedding model, its version or the embedding dimensions differ. Medium when only the parser, chunking version, chunk size, chunk overlap or preprocessing differ. Critical for the collection-level size mismatch.PostgreSQL, QdrantFull reindex. Needs a human for the collection-level variant.Vectors were built with a different setup than your target pipeline (or the vectors of one document disagree among themselves). Mixed embedding spaces degrade retrieval in ways that are hard to see. Re-process the document with the target pipeline.
Empty embeddingsempty_embeddingHighQdrantFull reindexPoints exist whose vector is missing, empty or all zeros, so they can never match a query. Only checked when Detect empty embeddings is switched on for the Qdrant connection.
Tenant mismatchtenant_mismatchCriticalQdrantRemove old vectorsVectors are tagged with a tenant under which the document does not exist, while it does exist under another. A cross-customer leak risk. Treat it as a security incident.
Orphan manifest rowmanifest_orphanLowPostgreSQLNeeds a humanThe manifest lists a document that is gone from both the source and the index, and its status is not "deleted", "tombstoned" or "removed". Harmless to users, but it clutters your records. Retire the row in your pipeline.

Issue titles in the list

The Issue column shows a short title. This table maps each title to its type.

TitleType
Document has no embeddings in the index (the text " (pipeline claims success)" is added when the manifest claims success)Missing embeddings
Only part of the document is indexed (with the same optional text)Partial index
Embeddings are from an older version of the documentStale document version
Superseded vectors are still active next to the current onesSuperseded vectors active
Vectors remain for a document that no longer existsOrphan vectors
Duplicate active chunksDuplicate chunks
Metadata disagrees between systemsMetadata mismatch
Vectors without a document idMetadata mismatch, collection level
Indexed with an outdated pipeline configurationPipeline drift
Chunks of one document were built with different pipeline configsPipeline drift
Collection vector size does not match the target embedding modelPipeline drift, collection level
Points exist without a usable embeddingEmpty embeddings
Vectors are tagged with the wrong tenantTenant mismatch
Manifest row for a document that no longer existsOrphan manifest row

Metadata problems

A Metadata mismatch issue lists one or more of these problems under Problems found in its evidence.

CodeSeverityMeaning
missing_payload_fieldsMediumVector payloads lack fields you require (by default document_id, source_hash, and tenant_id once there is more than one tenant)
untracked_in_manifestMediumVectors exist for a current document but the manifest has no row for it
manifest_count_mismatchMediumThe manifest says N chunks are indexed and the index holds a different number. Hidden when a partial index already explains it.
acl_mismatchHighVectors carry a different access-control hash than the manifest, so permissions may be wrong at query time
manifest_lags_indexLowThe index is current but the manifest still records an older source hash
manifest_version_mismatchLowThe manifest's indexed version differs from the source version although the content hashes agree
status_failed_but_indexedLowThe manifest status says failed although the document is indexed
unattributed_vectorsHighCollection level: points that carry no document id. See below.

Collection-level findings

Two findings belong to a whole Qdrant collection, not to one document. In lists the document column reads "Whole collection" (or "Whole tenant" in some run lists). They cannot become repair plans. Fix them in your own systems, then audit again.

FindingTypeSeverityMeaning
Vectors without a document idMetadata mismatchHighN points in a collection carry no document id, so they cannot be matched to any document
Collection vector size does not match the target embedding modelPipeline driftCriticalThe vector size of a collection differs from Embedding dimensions in Settings, Pipeline, so queries embedded with the target model cannot match it

Repair actions

Internal nameLabel shownWhat it means
reindex_fullFull reindexRe-process the whole document from the latest source: parse, chunk, embed and write, then update the manifest
reindex_chunksRe-embed missing chunksRe-embed only the missing chunks (a full rebuild is also safe)
cleanup_vectorsRemove old vectorsRemove the listed vectors, only after the replacements are verified and an operator approves
fix_metadataFix metadataCorrect the manifest or the payload; no re-embedding
investigateNeeds a humanNo automatic repair exists; someone has to look

How a repair plan chooses actions for one document:

  • Missing, stale, drifted or empty-embedding issues give Full reindex.
  • Otherwise, a partial index gives Re-embed missing chunks.
  • A metadata mismatch adds Fix metadata only when there is no Full reindex (a full reindex already rewrites the manifest).
  • Superseded, duplicate, orphan and tenant-mismatch issues set the "remove old vectors" flag, which becomes Remove old vectors after verification.
  • An orphan manifest row and any collection-level finding give no automatic action (Needs a human).

Severities and badge colours

SeverityBadge colourRankNotes
CriticalRed4Act now
HighAmber3Fix soon
MediumBlue2Plan to fix
LowGrey1Housekeeping
InfoGrey0Exists in the data model, but none of the current checks raises it

The severity chips on the Issues tab show the four levels from critical to low, with the number of open issues of each. The colour tones used for badges everywhere are: green (good, completed), amber (warning, look at it), red (critical, failed), blue (information, in progress) and grey (neutral).

Issue statuses

StatusBadgeMeaningHow it changes
OpenAmberThe audit found it and it has not been fixed or ignoredBecomes Resolved when an audit that covers the document no longer finds it. Becomes Ignored when you ignore it.
ResolvedGreenAn audit no longer finds itBecomes Open again (its "Reopened" count goes up) if a later audit finds it again
IgnoredGreyYou decided to accept it and, optionally, said whyStays Ignored, even if later audits still find it, until you click Reopen

An issue keeps one identity across audits: the same problem on the same document is the same row, and its Seen number counts the audits that saw it. A scoped audit only resolves issues inside its own scope.

Issue event names

Each issue has a timeline of events.

EventIssue timeline textActivity log labelWhen it is recorded
openedDetected by an auditIssue openedThe first time an audit finds the problem
reopenedCame back after it was resolvedIssue reopenedAn audit finds a problem that was Resolved
resolvedResolved: the index now matches the sourceIssue resolvedAn audit that covers the document no longer finds it
severity_changedSeverity changed from X to YSeverity changedAn audit finds an open issue at a different severity (higher or lower)
ignoredIgnored, with "Reason: ..." when you gave oneIssue ignoredYou click Ignore
unignoredReopened by a userIssue unignoredYou click Reopen (on an Ignored or a Resolved issue)

The Activity log can also show the label "Issue escalated". The product records an escalation as severity_changed, and counts it as Escalated in the change counters.

Document statuses

The audit gives every document one of five statuses. They are shown under Document status on Overview, in the Status filter on Documents, and as the tabs of the Reconciliation documents table.

StatusColour (Overview bar)MeaningHow it is decided
HealthyGreenSource, manifest and index agreeNo findings
DegradedAmberSearchable, with minor issuesThe worst finding is medium or low
BrokenRedSerious issues foundAt least one critical or high finding
PendingBlueStill being processedChanged or in flight within the grace period and no findings. Not judged yet.
OrphanedGreyDeleted at the source, vectors remainNot in the source, but vectors exist

"Needs attention" on Documents and Reconciliation means Degraded plus Broken. A document's status comes from what the audit finds, not from your Ignore decisions.

Document states

The Embedding status column on Documents (and the Status column in the Reconciliation documents table) is a simpler label derived from the status and the issue types, checked in this order.

StateColourHow it is derived
ProcessingBlueThe document status is Pending
Missing embeddingsRedThe document has a Missing embeddings issue
StaleAmberThe document has a Stale document version issue, or its status is Degraded
HealthyGreenThe status is Healthy
FailedRedThe status is Broken or Orphaned (and neither of the two rules above applied)

"Failed" does not mean a pipeline job failed. It means the audit found serious problems with the document, or that the document is an orphan. A Broken document with only, for example, a tenant mismatch shows as Failed.

Vector classes

While the index is scanned, RAGGuard gives every vector one class by comparing it with the live source and your target pipeline. You see the classes on the Chunks tab of a document after Inspect live.

ClassColourMeaningHow it is decided
FreshGreenMatches the current source and the pipelineIts hash (or, if it has none, its version) matches the source, and it does not conflict with the target pipeline
StaleAmberBuilt from an older version of the documentIts hash (or version) differs from the source's
OutdatedAmberCurrent content, built with an older pipeline setupHash matches, but a value it records conflicts with the target pipeline
UnknownGreyThe index does not say which version it isThe payload carries no hash and no version, so freshness cannot be established
OrphanRedThe document no longer exists at the sourceThe document is not in the source

Fresh and Unknown vectors count as live. The checks run in this order: Orphan, then Stale, then Outdated, then Fresh or Unknown.

Audit runs: kinds, statuses and triggers

These are the Type, Status and Trigger values in Audit history.

TypeMeaning
FullThe whole corpus. Only full completed audits feed the Health over time chart and the three-way comparison on Reconciliation.
ScopedOne tenant (Scoped audit), or specific documents (Re-audit document, or the API's documents list)
VerifyA scoped audit run by a repair plan, to check its documents (Verify now) or to prepare the removal list (Approve cleanup)
StatusBadgeMeaning
RunningBlueStarted and not yet finished
CompletedGreenFinished and recorded
FailedRedStopped with an error, shown on the run's page. A run that was cut off (for example a hosting function that was killed) is marked Failed with "abandoned: the process running it stopped", plus the last step it reached.
TriggerWhat started it
ApiA request to the HTTP API. This includes the Run audit, Run full audit, Scoped audit and Re-audit document buttons of the web interface (which use the API), and calls made with an API key. You cannot tell the two apart by this value.
Repair verifyVerify now on a repair plan (or your worker's callback)
Cleanup prepApprove cleanup, which first audits the plan's documents again to get the exact list of vectors to remove
CliThe ragi audit command
ScheduleThe built-in scheduler of a single-user server (not available in the hosted app)
BootstrapThe first audit that the demo server runs by itself
ManualThe default name when code starts an audit without giving a trigger. You will rarely see it.

The Scope column reads All, a tenant name, or "N documents".

Audit stats fields

Every finished run records these numbers. Some appear only when they apply. The run page shows the tiles Documents, Source documents, Manifest rows, Index vectors, Retrieval probes and Health score.

FieldMeaningShown as
source_documentsDocuments found in S3 (after the key prefix and key pattern)Source documents ("in Amazon S3"), and Source documents on Reconciliation
manifest_rowsRows read from the manifest (when Only audit documents found in the source (S3) is on, only rows for documents found in S3)Manifest rows ("in PostgreSQL")
index_pointsVectors read from Qdrant in this audit, including orphans and vectors with no document idIndex vectors ("in Qdrant")
documents_totalDocuments compared in total (the union of what the three systems hold, within the scope)Documents ("compared in total")
documents_by_statusDocuments per status (Healthy, Degraded, Broken, Pending, Orphaned)API only
findings_totalNumber of findings (issues found)Findings; the Issues column of the runs table
findings_by_severityFindings per severityBy severity
findings_by_typeFindings per typeBy type
health_score(Healthy + Pending documents) divided by all documents, as a percentage. 100 when there are no documents.Health score; the Health column
retrieval_probesHow many probe searches were sent to the index. Present only when probes are on and the audit found something.Retrieval probes ("queries sent to the index")
diffThe change countersChanges in this audit; the Changes column
scopeThe tenant or number of documents audited, empty for a full auditScope
duration_secondsHow long the audit tookDuration
alertsWhat happened to the alert: sent (0 or 1), issues, reason, errorAlert delivery card; Recent deliveries
required_payload_fieldsThe fields every vector had to carry in this auditAPI only
source_documents_onlyTrue when the "only audit documents found in the source" switch was onAPI only
isolationThe tenant isolation picture (overall result, tenants and five checks), including how many leaks were searched live (leaks_tested_by_search) and how many a search returned (leaks_confirmed_reachable). Recorded only by full audits.The Isolation page
progressWhile running, the current step and seconds elapsed. The steps are "listing the source documents (S3)", "reading the processing manifest", "looking up the files the manifest names (S3)", "reading the vector index (Qdrant)" and "comparing the three lists".Shown in the failure message of an abandoned run

Change counters

These five numbers describe what an audit changed compared with the audit before it. You see them as Since the previous audit on Reconciliation, as Last audit on Overview and as Changes in this audit on the run page. In the runs table the Changes column shows "N opened" and "N resolved".

CounterMeaningColour when above zero
OpenedNew issues, found for the first timeAmber
ReopenedIssues that had been Resolved and came backAmber
EscalatedOpen issues whose severity went upAmber
ResolvedOpen issues that this audit no longer foundGreen
UnchangedOpen issues seen again. An issue that is also counted as Escalated is counted here too.Default

Ignored issues that are seen again appear in none of the counters.

Health score

Health score is the share of documents that are healthy, as a percentage: (Healthy documents + Pending documents) divided by all documents, rounded to one decimal place. Pending documents count as healthy because they are probably still being ingested.

ScoreBadge colour
90% and aboveGreen
70% up to just under 90%Amber
Below 70%Red
No score yetGrey, with a dash

Where it appears: the first card on Overview (from the latest state of all documents, so a scoped or verification audit that refreshes some documents can move it), the Health over time chart (one point per completed full audit), the Health column in Audit history, the run page, Tenant health (per tenant) and the Reconciliation comparison. A scoped audit's own score covers only its scope. The score is never changed by ignoring an issue.

Repair plans

Plan statuses

StatusBadgeMeaningButtons you get
DraftGreyCreated, nothing sent.Trigger repair
TriggeredBlueThe repair request was sent to your workerVerify now
PartialAmberSome documents are fixed and some are notSend repair again, Verify now
FailedRedThe index still has the problemsSend repair again, Verify now
Cleanup pendingAmberReplacements are verified, removal of old vectors needs your approvalApprove cleanup
Cleanup triggeredBlueThe removal request was sent to your workerVerify now
CompletedGreenEvery repair is verifiednone

View payload is available in every status. In the API, Approve cleanup is also accepted for a Partial plan (it then covers only the documents that already passed).

How Verify now decides the plan status: when every document is Completed, the plan is Completed. When every document is Completed, Replacements verified or Waiting for cleanup (and at least one is not Completed), the plan is Cleanup pending. When some documents are Not fixed yet and the others are in any other status, the plan is Partial. When every document is Not fixed yet, the plan is Failed.

Item statuses

Item statusLabel shownColourMeaning
plannedPlannedGreyNot yet checked
reindexedReplacements verifiedAmberThe new vectors are in place; old ones await cleanup
awaiting_cleanupWaiting for cleanupAmberThe document needs only removal of vectors and is ready for it
completedCompletedGreenAll five checks pass
failedNot fixed yetRedAt least one of the first four checks fails. The line "Still found: ..." names what remains.

Verification checks

After a repair, a scoped audit of the plan's documents runs, and each document gets these five checks.

LabelInternal namePasses when the verification audit finds none of
All chunks presentexpected_chunks_presentMissing embeddings, Partial index
Embeddings presentembeddings_presentEmpty embeddings, Missing embeddings
Latest version indexedlatest_version_indexedStale document version
Metadata correctmetadata_correctMetadata mismatch, Pipeline drift
Old vectors removedold_vectors_inactiveSuperseded vectors active, Duplicate chunks, Orphan vectors, Tenant mismatch

A document is Completed when all five pass. It is Replacements verified (or Waiting for cleanup) when the first four pass and the fifth does not. Otherwise it is Not fixed yet.

Plan events

EventTitle in the plan's HistoryLabel in the Activity log
createdPlan createdRepair plan created
reindex_triggeredRepair sent to your workerRe-index requested
worker_callbackYour worker reported backWorker callback received
verifiedOne of: "Verified: every repair is in place"; "Verified: replacements are in place, old vectors await approval"; "Verified: some documents still have issues"; "Verified: the repairs are not in place yet"Repair verified
cleanup_triggeredCleanup sent to your workerVector cleanup requested

Connection states

StateBadgeWhereMeaning
ConnectedGreenData sources cards, IntegrationsConfigured, and the live check passed
ErrorRedData sources cardsConfigured, but the live check failed. The card's line shows the error.
Not connectedGreyData sources cardsNot configured yet
CheckingBlueData sources cardsThe live check is running
Status unavailableAmberData sources cardsConfigured, but the live status could not be read just now
Configured / Not configuredGreen / GreyRepair webhook cardWhether the repair webhook has any saved value

On Overview, Connection health shows a green dot for a system that answers and a red dot for one that does not, with the response time in milliseconds. A system counts as configured only when its required fields are present: the S3 bucket and both access keys, the manifest connection string, and the Qdrant URL.

Test check statuses

Test connection (and Test on a card) returns one line per check. The overall verdict is Test failed if any check is red, Test passed with warnings if any is amber, and Test passed otherwise. Check settings (repair webhook, alerts) only validates values and shows one line.

Check statusIconMeaning
okGreen tickThe check passed
warnAmber triangleIt works, but something will limit the audit. Read it.
failRed crossIt does not work. The message says what to change.
SystemChecks, in order
Amazon S3Bucket reachable, Documents found (only when empty), Key pattern, Object metadata (only on failure), Content hashes
PostgreSQLDatabase reachable, Manifest table, Columns used for checks (only when columns are missing), Rows, Role is read-only, Chunk manifest
QdrantQdrant reachable, Collections, Collection NAME and Payload of NAME (for up to the first five collections)
AnythingConfiguration (a problem with a required field or a setting), Connection (an unexpected error)

Alert delivery outcomes

On Alerts, Recent deliveries lists what happened after each of the latest 50 audits.

OutcomeBadgeDetail textMeaning
DeliveredGreen"Sent to the alert webhook."One message was sent and the webhook accepted it
FailedRedThe error, for example the name of an HTTP errorA message was due but the webhook did not accept it (one attempt, 10-second wait, no retry). The audit itself is not affected.
Not sentGrey"No alert webhook was configured." or "No new issues at or above the minimum severity."Nothing was due, or nowhere to send it

The Show filter offers "Delivered or failed" (the default), "Every audit", "Delivered", "Failed" and "Not sent". An alert is due only for issues that are new, reopened or escalated, and at or above the Minimum severity.

Manifest status values

RAGGuard reads the manifest's processing_status column (or whichever column you map to it). Matching ignores capital letters and spaces at the ends. Any other value is treated as unknown: neither success, nor in flight, nor failed.

GroupValues it recognisesEffect
Successsuccess, succeeded, indexed, completed, complete, done, ready, ok, processed, trueThe pipeline "claims success". A document with no vectors then gets Critical instead of High. (true lets you map a true/false column such as is_indexed.) An indexed chunk count above 0 also counts as claiming success for a missing document.
In flightpending, queued, processing, running, in_progress, indexing, parsing, embeddingA document in one of these states that was updated within the grace period is Pending, not broken. A document stuck in one of them for longer is flagged, and the issue text says since when.
Failedfailed, error, errored, failureExplains a missing document ("marked ... and never retried successfully"). A document that is indexed although the manifest says failed gets the low problem status_failed_but_indexed.
Deleteddeleted, tombstoned, removedA manifest row with one of these for a document that is gone does not raise an Orphan manifest row issue

Settings groups and fields

There are seven settings groups. The detailed fields, help and examples are in the chapters linked in the first column. Secret fields are encrypted when stored, are write-only (after saving, the form says "A value is saved" and never shows the value), and can be left empty to keep the stored value. Optional text fields that you leave empty use the default. Text fields have length limits (for example 255 characters for Bucket and 4,000 for the JSON fields), and a message tells you when you exceed one.

Every address you enter (S3 endpoint, Qdrant URL, database host, repair webhook, alert webhook) must be a public one in hosted mode.

Source documents (S3)

Where: Data sources, Amazon S3 card, Configure or Edit. Detail: Data sources.

LabelInternal keyTypeRequiredSecretDefault
BucketbuckettextYesNonone
Key prefixprefixtextNoNoempty (whole bucket)
RegionregiontextNoNonone
Custom endpointendpoint_urladdressNoNonone (AWS)
Access key IDaccess_key_idtextYesYesnone
Secret access keysecret_access_keytextYesYesnone
Content hashhash_modemetadata, compute, etagNoNometadata
SHA-256 metadata keysha256_metadata_keytextNoNosha256
Key pattern (regex)key_patternpattern with a (?P<document_id>...) groupNoNo^(?P<tenant_id>[^/]+)/(?P<document_id>.+)$
Default tenantdefault_tenanttextNoNodefault (used when the key pattern has no tenant group)
Look up files from the manifest (skip listing the bucket)lookup_from_manifestswitchNoNooff

Processing manifest (PostgreSQL / Supabase)

Where: Data sources, PostgreSQL card. Detail: Data sources.

LabelInternal keyTypeRequiredSecretDefault
Connection stringdatabase_urlpostgresql://...YesYesnone
Schemaschemaidentifier (letters, digits, underscores)NoNopublic
Document tabletableidentifierNoNorag_document_manifest
Chunk table (optional)chunk_tableidentifierNoNonone
Column map (JSON)column_mapJSON object of text valuesNoNoempty
Chunk column map (JSON)chunk_column_mapJSON object of text valuesNoNoempty

The manifest columns RAGGuard knows are: tenant_id, document_id (the only mandatory one), source_uri, source_version, source_hash, parsed_hash, parser_version, chunking_version, chunk_size, chunk_overlap, embedding_model, embedding_model_version, embedding_dim, preprocessing, expected_chunk_count, indexed_chunk_count, indexed_version, processing_status, last_verified_at, updated_at, acl_hash (21 in all). The chunk table columns are tenant_id, document_id (required), chunk_id (required), chunk_index, chunk_hash.

Vector index (Qdrant)

Where: Data sources, Qdrant card. Detail: Data sources.

LabelInternal keyTypeRequiredSecretDefault
URLurladdressYesNonone
API keyapi_keytextNoYesnone
Collectionscollectionscomma-separated namesNoNoempty (every collection)
Payload field map (JSON)payload_mapJSON object of text values; dotted paths reach nested fieldsNoNoempty
Named vectorvector_nametextNoNonone
Detect empty embeddingscheck_vectorsswitchNoNooff

The payload fields RAGGuard reads are tenant_id, document_id, chunk_id, chunk_index, chunk_hash, source_hash, source_version, parser_version, chunking_version, chunk_size, chunk_overlap, embedding_model, embedding_model_version, embedding_dim, preprocessing and acl_hash.

Target pipeline

Where: Settings, Pipeline tab, card "Expected pipeline". All fields are optional and empty by default. Detail: Settings.

LabelInternal keyType and range
Parser versionparser_versiontext
Chunking versionchunking_versiontext
Chunk sizechunk_sizewhole number, 1 to 1,000,000
Chunk overlapchunk_overlapwhole number, 0 to 1,000,000
Embedding modelembedding_modeltext
Embedding model versionembedding_model_versiontext
Embedding dimensionsembedding_dimwhole number, 1 to 65,536. Also compared with every collection's vector size.
Preprocessingpreprocessingtext

Repair worker

Where: Integrations, Repair webhook card. Detail: Integrations.

LabelInternal keyTypeRequiredSecretDefault
Webhook URLwebhook_urladdressNoNonone
Signing secretwebhook_secrettextNo (but nothing is sent without it)Yesnone
Vector removalcleanup_policymanual, autoNoNomanual

Alerts

Where: Alerts, Alert webhook card. Detail: Alerts.

LabelInternal keyTypeSecretDefault
Webhook URLwebhook_urladdress (a Slack-compatible incoming webhook)Yesnone
Minimum severitymin_severitycritical, high, medium, lowNohigh

Email

Where: Integrations, Email card. Detail: Integrations.

LabelInternal keyTypeRequiredSecretDefault
SMTP serverhosthost nameYesNonone
Portportwhole number, 1 to 65,535NoNo587
Connection securitysecuritystarttls, ssl, noneNoNostarttls
UsernameusernametextNoNonone
PasswordpasswordtextNoYesnone
From addressfrom_addressemail addressYesNonone

Audit policy

Where: Settings, Policy tab, card "Audit policy". Detail: Settings.

LabelInternal keyType and rangeDefault
Grace period (minutes)grace_minuteswhole number, 0 to 1,44010
Default tenantdefault_tenanttext. Assumed when a manifest row or a vector names no tenant.default
Required payload fieldsrequired_payload_fieldscomma-separated namesempty (meaning document_id and source_hash, plus tenant_id once there is more than one tenant)
Only audit documents found in the source (S3)source_documents_onlyswitchoff
Embedding price (USD per 1M tokens)embedding_price_per_mtoknumber, 0 to 10,0000.13
Tokens per chunk (for estimates)chunk_size_tokenswhole number, 1 to 100,000512

The two fields named Default tenant are different. The S3 one is used when the key pattern has no tenant group; the Policy one is used when a manifest row or a vector has no tenant.

API keys are a separate list on Integrations, not a settings group. See API roles and endpoints.

API roles and endpoints

Every web-interface action is also an API call. The technical reference lists every endpoint (GUIDE.md section 9), and the server's interactive reference is at /docs on your RAGGuard address (the interface does not link to it).

RoleHow you prove itCan do
PublicNothingLoad the web interface, check /healthz, read the session status, sign up and sign in (rate limited)
Browser sessionThe ragi_session cookie set when you sign inEverything in the interface, including settings, API keys and password
API keyAuthorization: Bearer ragi_...Run audits and read results, work with issues, documents, reports, isolation results and the isolation drill, recommendations, impact analysis, history and repair plans (including creating, triggering, verifying and approving cleanup), and send retrieval logs. It cannot read or change settings, test connections, list, create or revoke keys, or change a password. A key works only inside its own workspace.
Signed callbackAn HMAC signature header, not a loginYour repair worker tells RAGGuard it has finished
MethodPathAccessWhat it does
GET/PublicThe web interface. Any other page address outside /api, /static, /docs and /redoc returns it too, so deep links work.
GET/healthzPublicWhether the server is up, its version and mode, whether the ledger is reachable and whether set-up is still required
GET/api/sessionPublicWho you are, whether sign-up is open, whether set-up is required, whether your workspace is ready
POST/api/auth/registerPublic, 5 per hour per networkCreate an account and sign in
POST/api/auth/loginPublic, 8 per account and 30 per network per 15 minutesSign in
POST/api/auth/logoutBrowser sessionEnd this session
POST/api/auth/passwordSession only, 10 per 15 minutesChange the password and sign out other sessions
GET/api/settingsSession onlyEvery settings group with its fields (never secrets)
PUT/api/settings/{kind}Session onlySave one group: s3, manifest, qdrant, pipeline, repair, alerts or policy
POST/api/settings/{kind}/testSession only, 30 per 10 minutesRun the real check; with a body, test unsaved values
GET, POST/api/keysSession onlyList API keys, create one (token shown once)
DELETE/api/keys/{key_id}Session onlyRevoke a key
GET/api/overviewSession or keyHealth, counts, trend, latest runs
GET/api/connectionsSession or keyLive status of each connection
POST/api/auditsSession or keyStart an audit. Body fields: tenant, documents (list of tenant_id and document_id), probe, wait (true to wait for the result)
GET/api/auditsSession or keyRecent runs (limit 1 to 200, default 30)
GET/api/audits/{run_id}Session or keyOne run
GET/api/issuesSession or keyIssues. Filters: status (open, resolved, ignored, all; default open), severity, type, tenant, q, limit (1 to 500, default 100), offset. The answer has total and items.
GET/api/issues/{issue_id}Session or keyOne issue with its events
POST/api/issues/{issue_id}/ignoreSession or keyIgnore, with an optional reason (up to 500 characters)
POST/api/issues/{issue_id}/reopenSession or keyReopen
GET/api/documentsSession or keyDocuments. Filters: status, tenant, q, limit (1 to 500), offset
GET/api/documentSession or keyOne document (tenant, document_id); live=true adds the live three-way view
GET/api/reportSession or keyThe integrity report: format (json, md, csv), include_healthy, tenant
GET/api/isolationSession or keyThe tenant isolation picture of the latest full audit: overall and per-tenant status, five checks, and the issues open right now (findings_live, with findings_changed_since_audit set when they no longer match the audit). available is false before the first full audit. See Isolation.
GET/api/isolation/reportSession or keyThe isolation evidence report: format (json, the default, or md)
POST/api/isolation/drillSession or keyThe read-only isolation drill on one document. Optional body: tenant and document_id, both or neither. It changes nothing and sends nothing; would_alert holds the real alert message an audit would post, with sent set to false.
GET/api/recommendationsSession or keyRecommended work and cost; optional min_severity
POST/api/blast-radiusSession or keyImpact analysis
POST/api/setup-checkSession or key, 20 per 10 minutes per workspaceThe setup check: do S3, the manifest and Qdrant call the same documents by the same ID? No body. Read-only, stores nothing, can take up to about two minutes. Always answers 200, even when a connection is missing (then the verdict is not_ready)
POST/api/query-logSession or keySend retrieval logs (up to 5,000 rows per call)
GET/api/historySession or keyThe merged activity trail (limit 1 to 500, default 100)
POST, GET/api/repairsSession or keyCreate a plan, list plans
GET/api/repairs/{plan_id}Session or keyOne plan with its events
GET/api/repairs/{plan_id}/payloadSession or keyThe request that would be sent to your worker
POST/api/repairs/{plan_id}/triggerSession or keySend the re-index request to your worker
POST/api/repairs/{plan_id}/verifySession or keyVerify the plan's documents
POST/api/repairs/{plan_id}/approve-cleanupSession or keyAsk your worker to remove the old vectors
POST/api/repairs/{plan_id}/callbackSigned callbackYour worker reports it has finished; this starts verification

HTTP status codes you may see from the API: 400 the request could not be carried out (the message says why, for example the isolation drill needs both tenant and document_id, or neither); 401 sign in or a valid key is needed; 403 not allowed (for example a key used for settings); 404 not found; 409 set-up incomplete or an audit already running; 422 a value was rejected (the message names the field); 429 rate limited; 502 your infrastructure refused or failed (the message explains); 503 the connection or the deployment is not set up; 504 the audit ran out of time.

Limits and rate limits

LimitValueWhere it applies and what you see
Password length10 to 128 charactersSign-up and Change password
Sign-in attempts8 per account and 30 per network per 15 minutes"Too many sign-in attempts. Wait a few minutes and try again." A successful sign-in clears the per-account count.
Sign-ups5 per network per hour"Too many sign-ups from your network. Try again later."
Password changes10 per account per 15 minutes"Too many attempts. Try again later."
Connection tests30 per workspace per 10 minutes"Too many connection tests. Try again in a few minutes."
Session lifetime7 days, renewed as you use the app (set by the server operator)You are sent back to sign in when it ends
WorkspacesOne per account
API keys20 per workspace"You can have at most 20 API keys. Revoke one first."
API key name80 charactersThe field says "Use at most 80 characters."
API key "Last used"Updated at most once every 10 minutes
Concurrent auditsOne per workspace"An audit is already running."
Audit time budget, hosted270 seconds (the hosting function stops at 300)The audit stops with a message saying which step was running
Audit time budget, other serversNone unless the operator sets one
One Qdrant request, hosted auditUp to 60 secondsA slow filter fails with a clear "timed out" message
Connection test timeoutsS3: 4 seconds to connect, 10 to read, no retries. Qdrant: 8 seconds. Manifest: 10 seconds to connect.
Manifest query time45 seconds per statement
Abandoned-run clean-upA run still Running after the time budget plus 90 seconds (360 seconds on hosted servers) is marked Failed. Without a time budget the wait is 15 minutes.The Run audit button is enabled again
Retrieval probesUp to 25 per audit, each reading the top 10 resultsOnly for orphan, tenant-mismatch, stale and superseded findings
Scoped audit by documents (API)Up to 5,000 documents; tenant up to 256 characters; document id up to 2,048
Ids in evidenceUp to 50 chunk or point names listed; up to 5,000 point ids per collection in a removal listMarked as truncated when capped
Repair plan creationUp to 5,000 issue ids and 20 types
Repair webhookOne attempt, 30-second wait; signature accepted within 5 minutes"Repair webhook delivery failed: ..."
Alert webhookOne attempt, 10-second wait, no retry; up to 10 issues in the text and 25 in the listRecorded on the run
Retrieval logUp to 5,000 rows per call, up to 100 document ids per row; searches from the last 14 days count
Lists in the interfaceThe first 500 issues and 500 documents are loaded (sorted and paged in the browser, 25 rows per page by default); the 100 most recent audits; the 200 most recent activity events; the latest 50 audits for Recent deliveries; the 50 most recent repair plans; the most severe 200 documents in the Recommended work preview (a plan includes all); the first 500 chunks in a live inspectionA note under the table says when more exist
Impact analysisA sample of 25 affected documents; the top 8 documents in Query impact
TestsS3 lists up to 200 keys and reads details of 5; manifest counts up to 100,000+ rows; Qdrant checks the first 5 collections and samples 20 points
Ignore reason500 characters

Glossary

TermMeaning
Access-control hash (ACL hash)A fingerprint of a document's permissions. RAGGuard compares the one in the manifest with the one on the vectors.
API keyA token (ragi_...) for scripts and CI. Shown once, stored only as a hash, works inside one workspace.
AuditOne comparison of source, manifest and index. It produces issues, document statuses and a health score.
ChunkA piece of a document that is turned into one vector
CollectionA named set of vectors inside Qdrant
Collection-level findingA finding about a whole collection, not about one document
Document idThe stable identity of a document, taken from the S3 key (after the prefix and key pattern), the manifest document_id column and the payload document_id field. It must be written the same way in all three.
Embedding / vectorThe list of numbers that represents a chunk for similarity search
ETagAn identifier S3 gives each object. For objects uploaded in several parts it is not a content hash, so RAGGuard flags it as unreliable.
EvidenceThe values an audit read from your systems when it raised an issue
FingerprintThe setup used to build a document's vectors: parser, chunking, embedding model and preprocessing
Grace periodHow long a recently changed or still-processing document is allowed to be Pending before it is judged. Default 10 minutes.
Health scoreThe share of healthy (and pending) documents, as a percentage
HMACA signature computed with a shared secret. RAGGuard signs each request to your worker, and your worker signs its callback.
IndexThe vector database your application searches (Qdrant)
IssueOne recorded disagreement, with a type, a severity, evidence and a recommended fix
Issue ledgerRAGGuard's own database of runs, issues, document states and plans. It never stores document contents.
Key patternThe regular expression that turns an S3 key into a tenant and a document id
Key prefixOnly keys under this prefix are audited
ManifestThe table where your pipeline records what it processed
OrphanSomething that no longer has an owner: vectors for a deleted document, or a manifest row for one
PayloadThe metadata stored with each vector (document id, hash, chunk id, and so on)
PendingA document that changed or is being processed within the grace period, so it is not judged yet
Pipeline driftVectors built with a different setup than your target pipeline
PointOne stored vector with its payload, in Qdrant
Probe (retrieval probe)A search against the live index, using one affected chunk's own vector, to show whether bad content can really be returned
Public addressA host that is reachable from the internet. Hosted mode refuses private network and localhost addresses.
RAGRetrieval-augmented generation: answers are written from documents retrieved from a vector index
Read-onlyRAGGuard only lists, reads and queries your systems. It never writes or deletes.
Repair planA set of documents with the smallest safe action for each, which RAGGuard hands to your worker and then verifies
ScopeThe part of the corpus an audit covers: everything, one tenant, or specific documents
SessionYour signed-in browser connection, kept in a cookie
source_hashThe SHA-256 of a document as your pipeline last processed it. RAGGuard compares it with the hash read from S3.
SourceThe documents in S3 that should be searchable
Target pipelineThe setup you expect documents to have been processed with, set in Settings
TenantA customer or business unit whose documents must stay separate
WebhookAn address that receives an automatic HTTP request. RAGGuard uses one for repairs and one for alerts.
WorkerYour own program that re-indexes documents when RAGGuard asks
WorkspaceOne account's private area: its connections, issues, history and plans