> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sitevisit.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get an API key and make your first call in under five minutes.

## 1. Generate an API key

Sign in to [sitevisit.app](https://sitevisit.app), open **Settings → Developers**, give the key a name (e.g. `local-dev`), and click **Generate key**.

<Warning>
  The full key is shown **exactly once**. Copy it now and store it in your secret manager — we keep only a hash, so we can't show it again. If you lose it, revoke it and generate a new one.
</Warning>

Keys look like:

```
sv_live_e059b3544b7fa4b93c7e26933aeba781
```

The `sv_live_` prefix identifies the environment; the random tail is hashed at rest.

## 2. Make your first call

List your properties:

```bash theme={null}
curl https://sitevisit.app/api/v1/properties \
  -H "Authorization: Bearer sv_live_..."
```

A successful response looks like:

```json theme={null}
{
  "data": [
    {
      "id": "clx0...",
      "name": "Happy Apartments",
      "address": "123 Main St, Sample City",
      "icon_emoji": "🏢",
      "cover_image_url": "https://...",
      "is_sample": true,
      "visit_count": 2,
      "open_item_count": 3,
      "created_at": "2026-05-01T15:32:11.000Z",
      "updated_at": "2026-06-04T09:01:44.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## 3. Drill into a visit

Grab a property `id` from the response above, then list its visits:

```bash theme={null}
curl "https://sitevisit.app/api/v1/site-visits?property_id=clx0..." \
  -H "Authorization: Bearer sv_live_..."
```

Then list the action items for that visit:

```bash theme={null}
curl "https://sitevisit.app/api/v1/action-items?site_visit_id=cly5..." \
  -H "Authorization: Bearer sv_live_..."
```

Each action item includes its priority, status, transcript quote, timestamp into the original video, and links to the evidence photos.

## 4. Create your first action item

Now a write. Pick a `site_visit_id` from step 3 above and POST:

```bash theme={null}
curl -X POST https://sitevisit.app/api/v1/action-items \
  -H "Authorization: Bearer sv_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-write-001" \
  -d '{
    "site_visit_id": "cly5...",
    "title": "Replace bulb at front entrance",
    "priority": "HIGH",
    "location": "Front lobby"
  }'
```

Response (`HTTP/2 201`):

```json theme={null}
{
  "id": "cmq0...",
  "siteVisitId": "cly5...",
  "title": "Replace bulb at front entrance",
  "priority": "HIGH",
  "status": "OPEN",
  "location": "Front lobby",
  "createdAt": "2026-06-05T13:53:53.644Z",
  "..."
}
```

A few things to notice:

* **The `Idempotency-Key` header is optional but recommended.** If your network blips and you retry, the second call returns the exact same response without creating a duplicate item. See [Idempotency](/idempotency) for the full pattern.
* **Plan limits surface inline.** If you're on the Free plan and have used your visit cap, the response is `HTTP/2 402 plan_limit_exceeded` with an `upgrade_url` field — your client can branch on the code and surface the upgrade flow.
* **Same data shape on read.** Run a `GET /action-items?site_visit_id=cly5...` and the new item appears in the list immediately.

## 5. Page through results

Lists return up to 25 rows by default (100 max). To fetch the next page, pass the previous response's `next_cursor` as `starting_after`:

```bash theme={null}
curl "https://sitevisit.app/api/v1/site-visits?starting_after=cly5...&limit=50" \
  -H "Authorization: Bearer sv_live_..."
```

When `has_more` is `false`, you've reached the end. Full details in [Pagination](/pagination).

## What's next

* **Browse the [API reference](/api-reference)** for every parameter and field.
* **Read [Idempotency](/idempotency)** before shipping any write code to production.
* **Read [Errors](/errors)** to understand what each status code means.
* If you're building an AI agent or workflow, the [MCP server](/mcp) wraps these endpoints as natural-language tools — including the QR-to-phone capture flow for attaching evidence photos.