# Dune API Skill For OpenClaw Agents

You are working with the Dune API, a Node.js Express service that imports Dune: Awakening data from Questlog into MongoDB and exposes it through REST endpoints for OpenClaw.

## Primary Goal

Help OpenClaw retrieve complete Dune: Awakening records with the least guesswork. Prefer the detailed singular datasets for client-facing lookups and search.

## Public Base URL

Use this production API base URL:

```text
https://dune.api.coppnic.cc
```

Swagger/OpenAPI is available here:

```text
https://dune.api.coppnic.cc/openapi.json
https://ui.dune.api.coppnic.cc/docs
```

## Best Endpoints For OpenClaw

Prefer singular datasets because they contain full Questlog single-record payloads in `raw`:

```text
GET /api/item
GET /api/item/{id}
GET /api/skill
GET /api/skill/{id}
GET /api/recipe
GET /api/recipe/{id}
GET /api/placeable
GET /api/placeable/{id}
GET /api/npc
GET /api/npc/{id}
```

Useful examples:

```text
GET /api/item/LongRifle_Unique_Poison_03?language=en
GET /api/item/Bloodsack_02?language=en
GET /api/skill/skills_ability_poisonmine?language=en
GET /api/recipe/Bloodsack_2_Recipe?language=en
GET /api/placeable/Atre_Banner_Placeable?language=en
GET /api/npc/bs43q?language=en
```

For text search:

```text
GET /api/search?q=rifle&datasets=item&language=en
GET /api/search?q=poison&datasets=item,skill,recipe&language=en
```

Supported languages are `en` and `de`.

## Dataset Rules

Detailed singular datasets:

| Dataset     | Mongo collection | Questlog detail method  |
| ----------- | ---------------- | ----------------------- |
| `item`      | `item`           | `database.getItem`      |
| `skill`     | `skill`          | `database.getSkill`     |
| `recipe`    | `recipe`         | `database.getRecipe`    |
| `placeable` | `placeable`      | `database.getPlaceable` |
| `npc`       | `npc`            | `database.getNpc`       |

Summary plural datasets:

| Dataset      | Mongo collection | Questlog page method     |
| ------------ | ---------------- | ------------------------ |
| `items`      | `items`          | `database.getItems`      |
| `skills`     | `skills`         | `database.getSkills`     |
| `recipes`    | `recipes`        | `database.getRecipes`    |
| `placeables` | `placeables`     | `database.getPlaceables` |
| `npcs`       | `npcs`           | `database.getNpcs`       |

Use plural datasets only when a compact Questlog page-summary record is enough. If a plural lookup includes an id, for example `/api/items/LongRifle_Unique_Poison_03`, the API checks the matching singular collection first and falls back to the plural summary collection.

## Response Shape

Stored documents have normalized metadata and the original Questlog payload:

```json
{
	"dataset": "item",
	"language": "en",
	"source": "questlog.gg",
	"sourceMethod": "database.getItem",
	"sourceId": "LongRifle_Unique_Poison_03",
	"name": "Assassin's Rifle",
	"raw": {}
}
```

For OpenClaw, inspect `raw` for domain-specific fields:

- Items: `raw.stats`, `raw.mainCategory`, `raw.subCategory`, recipe relationships, wearable/equip fields.
- Skills: `raw.levels`, `raw.connections`, grid position, bonuses.
- Recipes: `raw.recipeInputItems`, `raw.recipeOutputItems`, crafting requirements, crafting stations.
- Placeables: production types, power/water fields, craftable recipe relationships.
- NPCs: `raw.description`, `raw.npcTags`, category metadata.

## Discord Output Contract

When OpenClaw asks for an answer intended for Discord, return Discord embed JSON instead of plain text. The bot should be able to send the returned payload directly.

Use this shape:

```json
{
	"embeds": [
		{
			"title": "Assassin's Rifle",
			"url": "https://dune.api.coppnic.cc/api/item/LongRifle_Unique_Poison_03?language=en",
			"description": "Short useful summary for Discord.",
			"color": 15198183,
			"fields": [
				{ "name": "Dataset", "value": "item", "inline": true },
				{ "name": "Language", "value": "en", "inline": true },
				{
					"name": "Source ID",
					"value": "LongRifle_Unique_Poison_03",
					"inline": false
				}
			],
			"footer": { "text": "Dune API" }
		}
	]
}
```

Embed rules:

- Use `name` or `raw.name` as the embed title.
- Use the matching Dune API URL as the embed URL.
- Keep descriptions short; do not dump the full `raw` object.
- Put compact facts in fields and omit empty fields.
- Return at most 5 embeds for search results.
- Keep field values below Discord limits.
- Use decimal colors: item `15198183`, skill `3447003`, recipe `5763719`, placeable `15844367`, npc `10181046`.

Dataset field ideas:

- `item`: grade, category, subcategory, weapon stats, armor stats, fillable stats.
- `skill`: category, subcategory, max skill level, level bonuses.
- `recipe`: output items, input items, crafting time, required stations.
- `placeable`: category, power, water, supported production types.
- `npc`: category, tags, description.

## Repository Map

Look here when changing behavior:

```text
src/datasets.js                 Dataset keys, collections, Questlog methods, API allowlists.
src/importer/questlogClient.js   Questlog URL building and TRPC response extraction.
src/importer/importer.js         Import orchestration, detail fetches, Mongo upserts.
src/db/indexes.js                Mongo indexes for summary and singular collections.
src/routes/api.js                REST API routes, search, dataset lookup behavior.
src/swagger/openapi.js           OpenAPI/Swagger documentation.
src/app.js                       Express middleware and public top-level routes.
scripts/import.js                CLI import entry point.
```

## Validation

Useful endpoint checks:

```text
GET /health
GET /api/datasets
GET /api/item/LongRifle_Unique_Poison_03?language=en
GET /api/search?q=poison&datasets=item,skill,recipe&language=en
GET /SKILL.md
```

## Important Constraints

- Do not expose secrets in public documentation or API responses.
- Keep `.env` values private; production configuration comes from environment variables.
- Keep the singular datasets first-class for OpenClaw.
- Keep changes small and consistent with the existing CommonJS/Express style.