# NiftyImages API developer docs

Base URL: https://dev.niftyimages.com/v2
Auth: Send `Authorization: Bearer $NIFTYIMAGES_API_KEY` on v2 API calls.
Store API Keys start with `store-` and can access exactly one store. Use `GET /v2/stores/access` to discover the assigned store before store record workflows.
OpenAPI: https://dev.niftyimages.com/openapi/v1.json
Interactive reference: https://dev.niftyimages.com/reference
MCP endpoint: https://dev.niftyimages.com/store_mcp
MCP auth: Authorization: Bearer <UI API key> (account or store- key). Do not put keys in the URL.
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
MCP human guide: https://dev.niftyimages.com/docs/connect-ai.md
MCP connect guide: https://dev.niftyimages.com/docs/workflows/connect-mcp.md

NiftyImages v2 is a clean-slate REST API for current NiftyImages product surfaces. It is designed for agents, CLIs, generated SDKs, and MCP-compatible tooling. Store MCP at /store_mcp covers store lifecycle and records; use OpenAPI for images, timers, maps.

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, you can use these docs and OpenAPI without 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.

High-value guide Markdown:
- https://dev.niftyimages.com/docs/quickstart.md
- https://dev.niftyimages.com/docs/authentication.md
- https://dev.niftyimages.com/docs/images.md
- https://dev.niftyimages.com/docs/fonts.md
- https://dev.niftyimages.com/docs/timer-frames.md
- https://dev.niftyimages.com/docs/timers.md
- https://dev.niftyimages.com/docs/stores.md
- https://dev.niftyimages.com/docs/maps.md
- https://dev.niftyimages.com/docs/errors.md
- https://dev.niftyimages.com/docs/pagination.md
- https://dev.niftyimages.com/docs/idempotency.md
- https://dev.niftyimages.com/docs/ai.md

Agent workflow packs:
- https://dev.niftyimages.com/docs/connect-ai.md
- https://dev.niftyimages.com/docs/workflows/update-store-records.md
- https://dev.niftyimages.com/docs/workflows/connect-mcp.md
- https://dev.niftyimages.com/docs/workflows/import-csv-store.md
- https://dev.niftyimages.com/docs/workflows/search-and-export-store.md
- https://dev.niftyimages.com/docs/workflows/create-timer-with-agent.md
- https://dev.niftyimages.com/docs/workflows/browse-images-and-thumbnails.md

Agent skills:
- https://dev.niftyimages.com/docs/skills/store-csv-import/SKILL.md
- https://dev.niftyimages.com/docs/skills/store-query-export/SKILL.md
- https://dev.niftyimages.com/docs/skills/store-upsert/SKILL.md
- https://dev.niftyimages.com/docs/skills/timer-frame-draft/SKILL.md
- https://dev.niftyimages.com/docs/skills/timer-target-date/SKILL.md
- https://dev.niftyimages.com/docs/skills/image-browser/SKILL.md
- https://dev.niftyimages.com/docs/skills/maps/SKILL.md

Important behavior:
- v2 uses Bearer API keys only. Do not use query string auth, Basic auth, or a custom ApiKey header.
- Regular API keys are account-scoped. Store API Keys are store-scoped: they can read/write records for their assigned store, but cannot create stores, delete stores, change schemas, or access other stores.
- List endpoints use cursor pagination where available.
- Errors use Problem Details.
- Unsafe writes should send an `Idempotency-Key` when retrying is possible.
- Timer Frames are temporary drafts scoped by API key plus `conversationId`.
- Saved Timers can update only their target date with `PATCH /v2/timers/{id}/target-date`.
- Store records are dynamic JSON objects validated against each store schema.