# Tint Atlanta — Agent API Docs (Markdown)

_Generated: 2026-05-10T10:04:28+00:00 — schema_version: 1.0_

## What this is

Use this API to estimate window-tint jobs (automotive and flat glass), check appointment availability, submit quote requests, and book appointments. All quote endpoints are no-side-effect. Booking and quote-request endpoints create CRM leads — request user consent before calling them. Bookings require a registered API key (POST /api/v1/register).

**Base URL:** `https://tintatlanta.com/api/v1`

**Recommended base URL for AI agents:** `https://inspiring-tenderness-production.up.railway.app` (Railway proxy — bypasses Hostgator mod_security UA-blocking. Forwards everything else unchanged.)

## Discovery files

- `llms_txt` — <https://tintatlanta.com/llms.txt>
- `llms_full_txt` — <https://tintatlanta.com/llms-full.txt>
- `agents_json` — <https://tintatlanta.com/.well-known/agents.json>
- `agent_card` — <https://tintatlanta.com/.well-known/agent.json>
- `openapi_json` — <https://tintatlanta.com/.well-known/openapi.json>
- `ai_plugin_json` — <https://tintatlanta.com/.well-known/ai-plugin.json>
- `capabilities` — <https://tintatlanta.com/api/v1/capabilities>
- `docs` — <https://tintatlanta.com/api/v1/docs>
- `docs_md` — <https://tintatlanta.com/api/v1/docs-md>

## Auth

- Discovery, pricing, availability, lead-capture endpoints: **no auth required**.
- Bookings: **API key required** (`Authorization: Bearer <key>` or `X-API-Key: <key>`). Register one at `POST /api/v1/register` with `{name, email, use_case}`.

## Rate limits

- Anonymous: **60 req/min per IP**.
- Known agent UAs (ChatGPT-User, Claude-User, ClaudeBot, PerplexityBot, Google-Extended, Googlebot, Bingbot, etc.): **120 req/min per UA-class pool**.
- Registered API key: **300 req/min default** + bookings capped at **3 per 10 min per key**.
- Every response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers.

## Error semantics

All error responses share this JSON shape:

```json
{
  "success": false,
  "error_code": "MACHINE_READABLE_CODE",
  "message": "human readable",
  "recoverable": true,
  "method": "POST",                    // optional: hint of correct method
  "missing_fields": ["vehicle_year"],   // optional: which fields are missing
  "usage": {
    "content_type": "application/json",
    "sample_request": { /* concrete example */ }
  },
  "agent_instruction": "plain-language guidance for the runtime",
  "docs":    "/api/v1/docs",
  "openapi": "/.well-known/openapi.json"
}
```

Status codes follow standard semantics:

| Status | error_code (typical) | What the agent should do |
|---|---|---|
| 400 | `BAD_REQUEST`, `MISSING_FIELD`, `INVALID_JSON` | Ask the user for missing/corrected fields. Don't blind-retry. |
| 401 | `API_KEY_REQUIRED`, `INVALID_API_KEY` | Register a key (POST /api/v1/register), retry. |
| 403 | `FORBIDDEN` | Plan/geo blocked. Don't retry. |
| 404 | `SERVICE_NOT_FOUND`, `INVALID_VEHICLE_TYPE` | Use a different value or fall back to `quote-request`. |
| 405 | `METHOD_NOT_ALLOWED` | Read the `method` and `usage.sample_request` fields, then re-issue with the correct method. |
| 409 | `DATE_BLOCKED`, `SLOT_TAKEN`, `KEY_EXISTS` | Try alternate slot/value. |
| 422 | `OUT_OF_SERVICE_AREA` | Don't retry the same input. Fall back to `quote-request`. |
| 429 | `RATE_LIMITED` | Backoff per `Retry-After` header. |
| 500/503 | `BOOKING_FAILED`, `INTERNAL_ERROR` | Exponential backoff, then fall back to `quote-request`. |

## Endpoints

### `POST /api/v1/estimates` — `automotive_estimate`

Instant automotive window-tint price estimate with both Standard and Ceramic film options, GA tint-law shade legality checks, and add-on suggestions.

- `side_effect`: `none`
- `returns_price`: true
- `creates_lead`: false
- _also accepts `GET` with no parameters → returns default baseline matrix (Bet G)._

**Use when:**
- user wants automotive window tint pricing
- vehicle make/model is known or askable

**Avoid when:**
- request is for residential or commercial flat glass (use flat_glass_estimate)
- user only wants human follow-up (use quote_request)

**Required fields:**
- hard: `vehicle_type`
- soft: `vehicle_year`, `vehicle_make`, `vehicle_model`, `film_type`, `coverage`
- optional: `shade`, `windshield_shade`, `addons`

**Sample request body:**

```json
{
    "vehicle_type": "suv",
    "vehicle_year": 2026,
    "vehicle_make": "Tesla",
    "vehicle_model": "Model Y",
    "film_type": "ceramic",
    "coverage": "full"
}
```

---

### `POST /api/v1/flat-glass/estimate` — `flat_glass_estimate`

Residential or commercial flat-glass window-film estimate. Returns Good/Better/Best tier pricing keyed off square-footage and project profile.

- `side_effect`: `none`
- `returns_price`: true
- `creates_lead`: false

**Use when:**
- user wants residential or commercial window film
- square footage and property type are known

**Avoid when:**
- job is automotive (use automotive_estimate)

**Required fields:**
- hard: `total_sqft`, `site_type`
- soft: `primary_concern`
- optional: `floors`, `needs_ladder`, `film_goals`

**Sample request body:**

```json
{
    "total_sqft": 850,
    "site_type": "residential",
    "primary_concern": "heat",
    "floors": 2
}
```

---

### `POST /api/v1/quote-request` — `quote_request`

Lead-capture endpoint for commercial / residential / security work that needs a custom quote with a site visit. Creates a CRM lead and triggers a follow-up workflow.

- `side_effect`: `creates_lead`
- `returns_price`: false
- `creates_lead`: true
- **requires user consent before calling**

**Use when:**
- user wants Tint Atlanta to follow up by phone/email
- pricing endpoint cannot return a confident estimate
- job is custom enough to require a site assessment

**Required fields:**
- hard: `first_name`, `phone`, `email`, `service_type`
- soft: `last_name`, `company_name`, `property_info`, `message`
- optional: `building_type`, `square_footage`, `address`

**Sample request body:**

```json
{
    "first_name": "Jane",
    "phone": "404-555-0100",
    "email": "jane@example.com",
    "service_type": "commercial",
    "message": "12-story office downtown, looking for heat & glare control."
}
```

---

### `GET /api/v1/availability` — `check_availability`

Check open appointment time slots for a specific date and service type, or scan the next N days.

- `side_effect`: `none`
- `returns_price`: false
- `creates_lead`: false

**Use when:**
- user wants to know when they can come in for service
- before suggesting a booking

**Required fields:**
- hard: `(none)`
- soft: `date`, `service`
- optional: `days`

**Sample request body:**

```json
{
    "query_params": {
        "date": "2026-05-10",
        "service": 1
    }
}
```

---

### `POST /api/v1/bookings` — `book_appointment`

Book a confirmed automotive tinting appointment. Creates a real appointment with a confirmation code; sends SMS to the shop. Requires a registered API key.

- `side_effect`: `books_appointment`
- `returns_price`: false
- `creates_lead`: true
- **requires user consent before calling**
- **auth**: `api_key` — register at `/api/v1/register`

**Use when:**
- user has accepted an estimate and chosen a slot
- user has explicitly consented to schedule with Tint Atlanta

**Required fields:**
- hard: `date`, `time`, `customer_name`, `customer_phone`, `customer_email`
- soft: `vehicle_year`, `vehicle_make`, `vehicle_model`, `vehicle_type`, `coverage`, `film_type`
- optional: `special_requests`

**Sample request body:**

```json
{
    "date": "2026-05-15",
    "time": "14:00",
    "service_type": "automotive",
    "customer_name": "Jane Doe",
    "customer_phone": "404-555-0100",
    "customer_email": "jane@example.com",
    "vehicle_year": 2026,
    "vehicle_make": "Tesla",
    "vehicle_model": "Model Y",
    "vehicle_type": "suv",
    "coverage": "full",
    "film_type": "ceramic"
}
```

---

### `POST /api/v1/register` — `register_api_key`

Issue an API key (one per email). Required for transactional endpoints (currently: bookings).

- `side_effect`: `none`
- `returns_price`: false
- `creates_lead`: false

**Required fields:**
- hard: `name`, `email`
- soft: `use_case`
- optional: `(none)`

**Sample request body:**

```json
{
    "name": "Acme AI Concierge",
    "email": "integrations@acme.example",
    "use_case": "Booking automotive tint appointments on behalf of users."
}
```

---

### `GET /api/v1/services` — `list_services`

Full service catalog with pricing tiers, film products, and add-ons.

- `side_effect`: `none`
- `returns_price`: true
- `creates_lead`: false

**Required fields:**
- hard: `(none)`
- soft: `(none)`
- optional: `(none)`

---

### `GET /api/v1/location` — `business_location`

Business address, hours, coordinates, and service area.

- `side_effect`: `none`
- `returns_price`: false
- `creates_lead`: false

**Required fields:**
- hard: `(none)`
- soft: `(none)`
- optional: `(none)`

---

### `GET /api/v1/faq` — `list_faq`

Frequently asked questions, optionally filtered by category.

- `side_effect`: `none`
- `returns_price`: false
- `creates_lead`: false

**Required fields:**
- hard: `(none)`
- soft: `(none)`
- optional: `category`

---

## OpenAPI 3.0 spec

Full machine-readable spec at <https://tintatlanta.com/.well-known/openapi.json>. The `operationId` strings are MCP-friendly tool names (e.g. `estimate_price`, `check_availability`).

## Contact

- **Phone:** (678) 439-8468
- **Email:** info@tintatlanta.com
- **Website:** https://tintatlanta.com
- **Address:** 9585 Main St, Woodstock, GA 30188