# NiftyImages API LLM Context Bundle

Use this file when an LLM or agent needs enough context to plan an integration with the NiftyImages v2 API.

## Core endpoints

- Base URL: `https://dev.niftyimages.com/v2`
- OpenAPI: `https://dev.niftyimages.com/openapi/v1.json`
- API Reference: `https://dev.niftyimages.com/reference`
- MCP endpoint: `https://dev.niftyimages.com/store_mcp`
- MCP auth: `Authorization: Bearer <UI API key>` (not query string; optional host `NIFTY_API_KEY` fallback for local only)
- MCP human guide: `/docs/connect-ai.md`
- MCP connect guide: `/docs/workflows/connect-mcp.md`
- MCP tools (Data Store CRUD): `store_access`, `store_list`, `store_create`, `store_update`, `store_delete`, `store_query`, `store_get_record`, `store_upsert`, `store_patch_record`, `store_import_csv`, `store_delete_record`, `store_delete_records`

## Agent operating rules

- If the user asks you to call the API and no API key is available, ask the user for a NiftyImages API key before making `/v2` requests.
- Never invent, guess, log, or expose an API key. Treat it as a secret.
- Use `Authorization: Bearer {apiKey}` for authenticated API calls.
- If the user only asks for planning, code generation, or explanation, use these docs and OpenAPI without asking for an API key.
- Use OpenAPI for exact request and response schemas before writing integration code.
- Preserve returned ids and tokens exactly as returned: `storeId`, `conversationId`, `timerFrameId`, image ids, record ids, cursor tokens, preview URLs, and thumbnail URLs.
- Do not construct opaque URLs or tokens yourself. Use URLs returned by the API.
- Ask a clarifying question before destructive writes when user intent is ambiguous.
- When retrying unsafe writes, reuse the same `Idempotency-Key` only for the same logical write. Generate a new key for a new write.

## Authentication

Every `/v2` API request requires:

```http
Authorization: Bearer $NIFTYIMAGES_API_KEY
```

Do not place API keys in query strings. Do not use Basic auth or a custom API key header.

Regular API keys are account-scoped. Store API Keys start with `store-` and can access exactly one assigned store. For store workflows, call `GET /v2/stores/access` when scope or `storeId` is unknown. Store API Keys can read/write records under the assigned store, but cannot create stores, delete stores, change schemas, or access other stores.

## Primary guides

- Quickstart: `/docs/quickstart.md`
- Authentication: `/docs/authentication.md`
- Pagination: `/docs/pagination.md`
- Errors: `/docs/errors.md`
- Idempotency: `/docs/idempotency.md`
- Images: `/docs/images.md`
- Fonts: `/docs/fonts.md`
- Timer Frames: `/docs/timer-frames.md`
- Timers: `/docs/timers.md`
- Stores: `/docs/stores.md`
- Maps: `/docs/maps.md`
- Agent docs: `/docs/ai.md`

## Workflow packs

- Connect with AI (Store MCP): `/docs/connect-ai.md`
- Connect MCP (technical): `/docs/workflows/connect-mcp.md`
- Update store records (MCP north star): `/docs/workflows/update-store-records.md`
- Import CSV into a store: `/docs/workflows/import-csv-store.md`
- Search and export store records: `/docs/workflows/search-and-export-store.md`
- Create timer draft with an agent: `/docs/workflows/create-timer-with-agent.md`
- Browse images and thumbnails: `/docs/workflows/browse-images-and-thumbnails.md`

## Agent skills

Use these `SKILL.md` files when an agent harness supports skill-style procedural instructions:

- Store CSV import: `/docs/skills/store-csv-import/SKILL.md`
- Store query: `/docs/skills/store-query-export/SKILL.md`
- Store upsert: `/docs/skills/store-upsert/SKILL.md`
- Timer Frame draft: `/docs/skills/timer-frame-draft/SKILL.md`
- Timer target date: `/docs/skills/timer-target-date/SKILL.md`
- Image browser: `/docs/skills/image-browser/SKILL.md`
- Maps: `/docs/skills/maps/SKILL.md`

## Resource summary

Identity:
- `GET /v2/whoami`
- `GET /v2/image-types`

Images:
- `GET /v2/images`
- `GET /v2/images/{id}`
- `PATCH /v2/images/{id}`
- `DELETE /v2/images/{id}`
- `POST /v2/images/{id}/restore`
- `POST /v2/images/lookup`
- `GET /v2/image-thumbnails/{token}/{imageId}`

Fonts:
- `GET /v2/fonts`
- `POST /v2/fonts`
- `POST /v2/fonts/from-url`
- `DELETE /v2/fonts/{id}`

Timer Frames:
- `POST /v2/timer-frames`
- `GET /v2/timer-frames/{timerFrameId}?conversationId={conversationId}`
- `PATCH /v2/timer-frames/{timerFrameId}`
- `DELETE /v2/timer-frames/{timerFrameId}?conversationId={conversationId}`
- `POST /v2/timer-frames/{timerFrameId}/save`
- `GET /v2/timer-frame-previews/{token}/{conversationId}/{timerFrameId}`

Timers:
- `PATCH /v2/timers/{id}/target-date`

Stores:
- `GET /v2/stores`
- `GET /v2/stores/access`
- `GET /v2/stores/{storeId}`
- `POST /v2/stores`
- `PATCH /v2/stores/{storeId}`
- `DELETE /v2/stores/{storeId}`
- `POST /v2/stores/{storeId}/properties`
- `PATCH /v2/stores/{storeId}/properties/{propertyName}`
- `DELETE /v2/stores/{storeId}/properties/{propertyName}`

Store records:
- `GET /v2/stores/{storeId}/records`
- `GET /v2/stores/{storeId}/records/{recordId}`
- `POST /v2/stores/{storeId}/records`
- `POST /v2/stores/{storeId}/records/batch`
- `PATCH /v2/stores/{storeId}/records/{recordId}`
- `DELETE /v2/stores/{storeId}/records/{recordId}`
- `POST /v2/stores/{storeId}/records/delete-by-key`
- `POST /v2/stores/{storeId}/records/lookup`
- `POST /v2/stores/{storeId}/records/validate`
- `POST /v2/stores/{storeId}/records/search`
- `POST /v2/stores/{storeId}/records/count`
- `POST /v2/stores/{storeId}/records/aggregate`
- `POST /v2/stores/{storeId}/records/batch-delete`
- `GET /v2/stores/{storeId}/records/export`

Maps:
- `GET /v2/maps/{mapId}`
- `PATCH /v2/maps/{mapId}`
- `GET /v2/maps/{mapId}/locations`
- `GET /v2/maps/{mapId}/locations/{locationId}`
- `POST /v2/maps/{mapId}/locations`
- `PATCH /v2/maps/{mapId}/locations/{locationId}`
- `DELETE /v2/maps/{mapId}/locations/{locationId}`

## Agent guidance

- Prefer OpenAPI for exact schemas.
- Use guide Markdown for concepts and examples.
- Preserve returned ids such as `storeId`, `conversationId`, `timerFrameId`, image ids, record ids, and cursor tokens.
- When retrying unsafe writes, send an `Idempotency-Key`.
- For Timer Frames, keep `conversationId` and `timerFrameId` together across create, update, get, preview, save, and delete calls.
- For saved Timers, use `PATCH /v2/timers/{id}/target-date` to reschedule only the target date.
- For Stores, infer or inspect schema before writing records. Records must match property names and types.
- For Maps, discover `mapId` values with `GET /v2/images?type=map`; `mapId` is the image id, not the internal map GUID.