Lore Scanner

Automatically extract lore from your game’s existing data files.

Overview

Most games already have lore scattered across dialogue scripts, data files, and configuration. The Lore Scanner uses AI to discover and structure this content into Lore Documents — no manual rewriting needed.

What it does:

1. You upload your game files (dialogue scripts, data files, configs)
2. An AI agent reads through them and identifies lore content
3. You review the extractions and approve what to keep
4. Approved extractions become Lore Documents, ready for NPC interactions

Prerequisites

• An Editor Key (sk_editor_*) — create one in Projects  → your project → API Keys (see Authentication)
• A way to ZIP your files and compute SHA-256 content hashes — the submit flow requires both
• Credits available for the scan — see Credit Costs below

Supported File Formats

The scanner accepts 29 game development file formats:

How It Works

The scanner uses an archive-based flow: you describe your files in a manifest, upload them as a single ZIP archive, then confirm to start processing.

1. Estimate Cost

Before uploading, send file metadata to get a cost estimate:

curl -X POST https://loremind.peekgames.dev/api/loremind/v1/scanner/estimate \
  -H "Authorization: Bearer sk_editor_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      { "filename": "story.ink", "sizeBytes": 45000 },
      { "filename": "npcs.json", "sizeBytes": 12000 }
    ]
  }'

2. Submit the Archive Manifest

Describe the files you’re going to upload. The response includes a jobId and a signed uploadUrl:

curl -X POST https://loremind.peekgames.dev/api/loremind/v1/scanner/submit-archive \
  -H "Authorization: Bearer sk_editor_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      { "filename": "story.ink", "relativePath": "story.ink", "sizeBytes": 45000, "contentHash": "sha256_of_file" },
      { "filename": "npcs.json", "relativePath": "data/npcs.json", "sizeBytes": 12000, "contentHash": "sha256_of_file" }
    ],
    "totalSizeBytes": 57000,
    "userContext": "A fantasy RPG set in the kingdom of Eldrath"
  }'

3. Upload the ZIP and Confirm

Zip your files, PUT the archive to the signed uploadUrl, then confirm to queue the job. Credits are reserved at confirm time:

curl -X PUT "SIGNED_UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @lore-files.zip
 
curl -X POST https://loremind.peekgames.dev/api/loremind/v1/scanner/submit-archive/confirm \
  -H "Authorization: Bearer sk_editor_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "jobId": "job_abc123" }'

4. Poll for Results

Check the job status until processing completes:

curl https://loremind.peekgames.dev/api/loremind/v1/scanner/jobs/job_abc123 \
  -H "Authorization: Bearer sk_editor_your_key"

When status is COMPLETED, the response includes extracted lore items with titles, tags, confidence scores, and content previews.

5. Review and Commit

Approve the extractions you want to keep. Each approved extraction becomes a Lore Document:

curl -X POST https://loremind.peekgames.dev/api/loremind/v1/scanner/commit \
  -H "Authorization: Bearer sk_editor_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jobId": "job_abc123",
    "extractionIds": ["ext_1", "ext_2", "ext_5"]
  }'

Committed documents are automatically processed through the embedding pipeline and become available for NPC interactions.

Re-scanning (True-Up)

When your game files change, use the rescan endpoint to identify what’s different:

curl -X POST https://loremind.peekgames.dev/api/loremind/v1/scanner/rescan \
  -H "Authorization: Bearer sk_editor_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      { "filename": "story.ink", "contentHash": "sha256_of_current_file" },
      { "filename": "npcs.json", "contentHash": "sha256_of_current_file" },
      { "filename": "new_quest.ink", "contentHash": "sha256_of_new_file" }
    ]
  }'

The response tells you which files are changed, added, deleted, or unchanged compared to the last scan. You can then re-submit only the changed and added files.

If a Step Fails

Each scanner endpoint returns specific errors — 400 for manifest problems, 402 when credits are below the reservation, 409 when a job is in the wrong state. The per-endpoint error tables are in the Lore Scanner API reference, and common failures (401, 402, 429) are explained in Errors & Rate Limits.

Limits

Oversized files inside the archive are skipped (listed in the job’s skipped content). Jobs expire 24 hours after confirmation; after expiry, reserved credits are refunded and scan results are no longer available for commit.

Credit Costs

The Lore Scanner is more expensive per-operation than manual document upload because it uses an AI agent to read, interpret, and extract lore from raw game files.

Costs are billed from the AI agent’s actual processing work. Cost factors:

• Total file size — Larger files require more AI processing
• File count — Each file is analyzed individually
• Content complexity — Dense narrative files may produce more extractions

Use the /scanner/estimate endpoint to get a cost estimate before uploading. Credits are reserved when you confirm the upload (above the estimate, to cover variance) and the difference is refunded once the job completes.

Access

The scanner is accessible from:

• Dashboard — Intelligence > Scanner  for visual upload and review
• Editor API Key — all scanner endpoints accept sk_editor_* keys for Unity Editor integration

See the Lore Scanner API reference for complete endpoint documentation.

Next Steps

• Lore Scanner API reference — Full endpoint documentation with request/response schemas
• Lore Documents — How extracted lore is stored and used
• Credits & Billing — Scanner cost details