1. Generate an API key
Sign in to sitevisit.app, open Settings → Developers, give the key a name (e.g. local-dev), and click Generate key.
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.
sv_live_ prefix identifies the environment; the random tail is hashed at rest.
2. Make your first call
List your properties:
A successful response looks like:
3. Drill into a visit
Grab a property id from the response above, then list its visits:
Then list the action items for that visit:
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:
Response (HTTP/2 201):
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 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:
When has_more is false, you’ve reached the end. Full details in Pagination.
What’s next
- Browse the API reference for every parameter and field.
- Read Idempotency before shipping any write code to production.
- Read Errors to understand what each status code means.
- If you’re building an AI agent or workflow, the MCP server wraps these endpoints as natural-language tools — including the QR-to-phone capture flow for attaching evidence photos.
