# I'm In The Book — Developer Resources & API

A public, read-only REST API for prices, art styles, story scenes and gift occasions.

## Overview

I'm In The Book makes personalized keepsake storybooks starring a grandchild and their
grandparents. This page documents our public REST API, which exposes the catalog data
behind the store: current prices, the illustration styles a book can be drawn in, the
story scenes a customer chooses from, and the gift-occasion pages we publish.

The API is read-only and built for programmatic access — scripts, integrations and AI
agents alike. Every endpoint is a `GET`, every response is JSON, and the whole surface is
described by a published OpenAPI 3 schema. No personal data, order data or internal
identifiers are exposed. Creating and buying a book stays a human web flow at
<https://iminthebook.com>.

## Base URL & Versioning

All endpoints live under:

```
https://iminthebook.com/api/v1/
```

The API is versioned in the URL path. The current contract version is **1.0.0**, served at
`/api/v1/`.

### Deprecation policy

- Backwards-incompatible changes are never made in place. A breaking change ships as a new
  version path (for example `/api/v2/`) while the previous version keeps working.
- Any endpoint or version scheduled for removal is announced **at least 6 months in
  advance**.
- Deprecated responses carry the `Deprecation` and `Sunset` response headers giving the
  deprecation date and the retirement date.
- Retirement dates are also published on this page, so a client can watch either the
  headers or <https://iminthebook.com/developers>.
- Additive changes (new endpoints, new optional response fields) can happen at any time
  within a version. Clients should ignore unknown JSON fields rather than failing on them.

## Authentication

None. Version 1 requires no API key, token or signup — it serves public read-only catalog
data. Ordering, checkout and anything touching a customer's photos or book remain on the
human web flows and are not part of this API.

## Endpoints

| Endpoint | What it returns |
| --- | --- |
| `GET https://iminthebook.com/api/v1/status` | Service name, health indicator, API version and links to the docs, the OpenAPI schema and the website. |
| `GET https://iminthebook.com/api/v1/pricing` | Current price list: hardcover book, digital book, gift wrap add-on, additional hardcover copy, and multi-book pricing. |
| `GET https://iminthebook.com/api/v1/pricing/quote` | Itemized quote for one book. Query params: `format_type` (`hardcover` or `digital`) and `gift_wrap` (`true`/`false`). |
| `GET https://iminthebook.com/api/v1/art-styles` | The six illustration styles a book can be drawn in, with ids and descriptions. |
| `GET https://iminthebook.com/api/v1/scenes` | The selectable story scenes. Optional `category` filter: `activity`, `food`, `funny` or `sweet`. |
| `GET https://iminthebook.com/api/v1/occasions` | Gift occasions with dedicated landing pages, each with a title, summary and absolute URL. |

### Example: price quote

```bash
curl "https://iminthebook.com/api/v1/pricing/quote?format_type=hardcover&gift_wrap=true"
```

```json
{
  "currency": "USD",
  "base_price": 74.99,
  "gift_wrap": 7.99,
  "discount": 0.0,
  "total": 82.98
}
```

### Example: art styles

```bash
curl https://iminthebook.com/api/v1/art-styles
```

```json
{
  "count": 6,
  "art_styles": [
    {
      "id": "classic_storybook",
      "name": "Classic Storybook",
      "description": "Warm, traditional illustration with soft lighting and rich colors"
    },
    {
      "id": "dreamy_watercolor",
      "name": "Dreamy Watercolor",
      "description": "Soft, ethereal pastel tones with gentle brushstrokes"
    }
  ]
}
```

### Example: scenes in one category

```bash
curl "https://iminthebook.com/api/v1/scenes?category=food"
```

```json
{
  "count": 9,
  "scenes": [
    {
      "id": "food_ice_cream_square",
      "label": "Ice cream at the town square",
      "category": "food"
    }
  ]
}
```

## Rate Limits

Requests are limited to **60 requests per minute per IP address**. Every response under
`/api/v1/` carries rate limit headers in the RFC *RateLimit header fields for HTTP*
syntax:

```
RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=59;t=42
```

- `q` — the quota (requests allowed per window)
- `w` — the window length in seconds
- `r` — requests remaining in the current window
- `t` — seconds until the current window resets

Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header (whole
seconds to wait) and a JSON body:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 18
RateLimit-Policy: "default";q=60;w=60
RateLimit: "default";r=0;t=18

{"detail": "Rate limit exceeded. Retry after 18 seconds."}
```

Please back off until the window resets rather than retrying immediately. If you need a
higher limit for a legitimate integration, email us.

## Machine-Readable Resources

- <https://iminthebook.com/openapi.json> — OpenAPI 3 specification covering every public endpoint.
- <https://iminthebook.com/docs> — interactive API reference generated from that specification.
- <https://iminthebook.com/llms.txt> — a plain-text summary of the site for language models and agents.
- <https://iminthebook.com/sitemap.xml> — the full list of public pages.

Public pages also support content negotiation: send `Accept: text/markdown` to get a
Markdown rendering of a page instead of HTML, or append a `.md` suffix to the path (for
example <https://iminthebook.com/about.md> or <https://iminthebook.com/developers.md>).

## Contact

Questions, bug reports or a request for a higher rate limit: email
<help@iminthebook.com>. A human reads every message.