Recording links and inspections

Requesting from us

GET/v1/recording-link#

Call it when a task is created, or whenever you need the link. Idempotent for a task that passes the checks: the same task_id returns the same URL, so it is safe to call on create, on update, and on any render path.

This endpoint does not create properties. The property_id must already be present in the workspace's roster; the import that put it there also activated it, a few seconds after the import applied.

Treat recording_url as opaque: store and render it exactly as returned. Save it on your task and render it as a button the cleaner taps.

Note the two property ids. property_id in the response is ours, the uuid inside recording_url. external_property_id echoes yours, so a handler can match the response to the request without inferring which is which.

Sending the cleaner back to your app (return_url)

By default the cleaner's last screen says the recording is saved and that they can close the page. Pass return_url and that screen sends them back to you instead:

The response echoes it as "return_url": "conduit://rapideye/complete".

The allowlist. We only send a cleaner to a URL your integration is set up for, so the recording page can never be used to bounce someone to an arbitrary site. Each entry is a scheme for your app (conduit:// allows any URL under that scheme), or a web origin with an exact host (https://app.example.com; another host, a subdomain or a different port does not match). Email [email protected] to add one. Anything else is 400 invalid_request with detail.parameter set to return_url and detail.reason set to not_allowed (not on your list) or malformed (not an absolute scheme://host/path URL of at most 2,048 characters; it contains spaces, control characters, a backslash or a user@ part; or its host or port is one a browser cannot open, such as a port above 65535, a port with no host, or a host with characters other than letters, digits and . _ ~ -). This check runs with the other parameter checks, before the refusals below. If we cannot read your allowlist at that moment the answer is 503 service_unavailable; retrying is safe.

It is stored per task. A request that carries return_url sets it for that task_id. A request without it leaves the stored value as it is, so a render path that does not know about it never erases it. Send a new value to change it.

When the redirect fires. The cleaner goes through the whole finish flow exactly as they do today. Then, in this order:

1. Every part of the video has uploaded from the phone.

2. While we seal the walkthrough on our side, the screen reads "Finishing your upload. Keep this page open." Sealing takes about 30 seconds after the cleaner taps Done (90% within 70 seconds, almost all within 2.5 minutes).

3. Once it is sealed, the cleaner sees the usual "Recording uploaded" screen for 3 seconds, with a Return to {your name} button where the "you can close this page" line usually is.

4. The page navigates to your URL with two query parameters added (any query or fragment of your own is kept):

   TextCopy

   conduit://rapideye/complete?inspection_id=6a1d2c80-3f0e-4b3a-9d61-0c8f1b7e2a55&status=submitted
   

   Parameter	Value
   inspection_id	Our inspection id, the same one the webhooks and GET /v1/inspections carry
   status	Always submitted: the walkthrough is safely with us. Results follow on the usual webhooks

We never send the cleaner away before the walkthrough is sealed, because closing the browser while the video is still uploading loses footage. On a poor connection the phone's last request can reach us late or not at all; the screen then keeps waiting, up to the 5-minute limit. If it does not seal within 5 minutes, the cleaner gets today's screen and its "you can close this page" message, with no redirect; the inspection still finishes on our side, and your webhooks arrive as usual. If the upload itself fails, the cleaner sees the same error and retry screens as today, and nothing redirects.

How browsers handle the navigation. A redirect to an app scheme 30 seconds or more after the cleaner's last tap is treated differently by each way of opening the link. The Return to {your name} button is a plain link: a tap on it counts as the cleaner's own action, and that works where the automatic navigation is blocked.

What it refuses, and in what order

The checks run outermost first, so you are always told the largest thing that is wrong. Each one has a different remedy, which is why they are separate codes.

400 missing_parameter comes before all of them, with detail.parameter naming the parameter, for example "detail": { "parameter": "workspace_id" }. So does a refused return_url (400 invalid_request, see Sending the cleaner back to your app).

A task is bound to one property for its whole life. The recording, the report and your webhook all resolve through that binding, so re-pointing a task_id at a different property would attach a walkthrough to the wrong unit.

curl -sS -G https://api.rapideyeinspections.com/v1/recording-link \
  -H "Authorization: Bearer rapideye_pk_REPLACE_ME" \
  --data-urlencode "workspace_id=ws_123" \
  --data-urlencode "task_id=task_abc" \
  --data-urlencode "property_id=unit_42"

{
  "recording_url": "https://app.rapideyeinspections.com/record/...",
  "task_id": "task_abc",
  "property_id": "1f0a9c22-6b1e-4a77-9b0f-2d2b0c5f7a10",
  "external_property_id": "unit_42",
  "roster_revision": 4
}

curl -sS -G https://api.rapideyeinspections.com/v1/recording-link \
  -H "Authorization: Bearer rapideye_pk_REPLACE_ME" \
  --data-urlencode "workspace_id=ws_123" \
  --data-urlencode "task_id=task_abc" \
  --data-urlencode "property_id=unit_42" \
  --data-urlencode "return_url=conduit://rapideye/complete"

GET/v1/inspections?workspace_id=...&task_id=...#

Status poll; a fallback for the webhook and a way to backfill after downtime. The webhook is the primary signal. Poll no more than once per minute per task.

An inspection has two parts that finish at different times, and the response describes each as a block with its own status:

• checklist: the per-item results. Final minutes after the walkthrough. See Per-item checklist results below.
• report: the findings report. Ready hours later.

status is the inspection's overall lifecycle: pending, recording, processing, completed or failed. completed means the report is ready.

While the report is being produced:

Once it is ready:

media_expires_in comes with the checklist block: the lifetime of its image_url links, as on the findings response. Every read signs the links afresh, so this is where you get a new link for a picture whose 15 minutes have run out.

The report block:

report appears on processing and completed. It is omitted on pending and recording, where no report is under way yet, and on failed, where none is coming. checklist appears as soon as the walkthrough has any results, on any status, and is omitted for a home with no checklist.

inspection_id appears as soon as the cleaner opens the recording link. report_url and completed_at at the top level appear only on completed. They predate the report block and stay, so an integration built on them keeps working; new code should read report. Unknown task_id returns 404 task_not_found. Treat an unrecognized status, block status or stage as in-flight so we can add states without breaking you.

inspection_id is ours, and this is how you get it if you missed the webhook. It is what the findings endpoint below takes.

{
  "status": "processing",
  "inspection_id": "3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33",
  "report": { "status": "processing", "stage": "reviewing" },
  "media_expires_in": 900,
  "checklist": {
    "status": "complete",
    "counts": { "verified": 9, "missed": 2, "explained": 1, "not_checked": 0, "pending": 0 },
    "items": [
      { "id": "c1f0a2e4-...", "name": "Bedrooms: beds made, linens fresh", "state": "verified",
        "timestamp": 84.2, "image_url": "https://...signed..." }
    ]
  }
}

{
  "status": "completed",
  "inspection_id": "3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33",
  "report_url": "https://app.rapideyeinspections.com/reports/3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33",
  "completed_at": "2026-08-01T17:04:33Z",
  "report": {
    "status": "ready",
    "report_url": "https://app.rapideyeinspections.com/reports/3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33"
  },
  "media_expires_in": 900,
  "checklist": {
    "status": "complete",
    "counts": { "verified": 9, "missed": 2, "explained": 1, "not_checked": 0, "pending": 0 },
    "items": [
      { "id": "c1f0a2e4-...", "name": "Bedrooms: beds made, linens fresh", "state": "verified",
        "timestamp": 84.2, "image_url": "https://...signed..." }
    ]
  }
}

GET/v1/inspections/{inspection_id}/findings?workspace_id=...#

The findings behind a completed inspection, if you want the detail rather than the report link. Call it when inspection.completed arrives; the webhook carries both ids you need.

severity and category are closed sets: we will not send a value outside the three listed, so it is safe to branch on them exhaustively.

evidence has exactly two keys, before and after, each an array of media references. after is the state we found, what the finding is about. before is the same area on the previous visit, which is what makes a new problem legible as new; it is empty on a property's first inspection and anywhere we had no baseline, which is about a quarter of findings.

evidence is the one place we send an empty value rather than omitting the key, and it is deliberate. Elsewhere an optional field is omitted entirely when it does not apply, never null or "", because absence is the natural way to say "not applicable" about a single value, and testing for the key is the natural way to read it. For a list the useful guarantee is the other one: that iterating is always safe. So evidence, evidence.before and evidence.after are always there, and you can write for image in finding.evidence.before without a guard on any finding we will ever send you. Both lists are empty on a finding whose images we could not produce.

Every other optional field follows the omit rule, same as the error envelope. Test for the key.

There is no pagination. One call returns every finding for the inspection in one response, capped at 5000 findings (no real inspection approaches it). The order is stable between calls but carries no meaning; sort by severity or room if you need one.

workspace_id is a boundary, not a hint. Your key spans every workspace we have provisioned for you, so this parameter is what scopes a request to one of your customers. An inspection_id belonging to a different workspace answers 404 not_found, identical to an id that does not exist.

Media URLs are short-lived and are minted per request. A media reference is { "url": "..." }, a signed URL good for media_expires_in seconds from the moment we answered, and no longer. Fetch the bytes when the webhook arrives; do not store the URL. A stored URL is dead long before the task it is attached to is, and re-reading this endpoint is the supported way to get fresh ones. There is no permanent image URL to ask us for; the images live in a private bucket, which is the point. It is an image: fetch it with a plain GET and no auth header, and read the format from the response's Content-Type rather than the URL. Do not assume a particular file extension.

Only released reports. Until human review is finished the endpoint answers 409 report_not_ready, which is a "not yet", not a failure. The inspection is fine and inspection.completed is coming. We never expose findings that have not been through review, so a 409 is also the correct answer for an inspection whose analysis is still running. An unknown or out-of-workspace inspection_id is 404 not_found.

curl -sS -G "https://api.rapideyeinspections.com/v1/inspections/3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33/findings" \
  -H "Authorization: Bearer rapideye_pk_REPLACE_ME" \
  --data-urlencode "workspace_id=ws_123"

{
  "inspection_id": "3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33",
  "report_url": "https://app.rapideyeinspections.com/reports/3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33",
  "media_expires_in": 900,
  "checklist": {
    "status": "complete",
    "counts": { "verified": 1, "missed": 0, "explained": 0, "not_checked": 0, "pending": 0 },
    "items": [
      { "id": "c1f0a2e4-...", "name": "Bedrooms: beds made, linens fresh", "state": "verified" }
    ]
  },
  "findings": [
    {
      "id": "8c2d1f60-4a11-4de2-9b73-0e5a6c1d2f88",
      "description": "Burn mark on the arm of the sofa, roughly 3cm across.",
      "room": "Living Room",
      "severity": "MAJOR",
      "category": "damage",
      "video_timestamp_seconds": 128.4,
      "evidence": {
        "before": [ { "url": "https://...signed..." } ],
        "after": [ { "url": "https://...signed..." } ]
      }
    }
  ]
}

GET/v1/inspections/{inspection_id}/video?workspace_id=...#

A download link for the inspection's walkthrough video, so you can keep your own copy. It is the same video the report plays, one per inspection. Items a cleaner goes back to record from the checklist are already inside it.

Each call returns a fresh link good for media_expires_in seconds, the same 15 minutes as finding images. Start the download within that window. Do not store download_url. Store the file, or store this endpoint's URL together with the workspace_id, which never expire: the inspection.completed webhook carries the URL as video_url next to workspace_id, and calling it again is the supported way to get a new link. Read the format from content_type or the download's Content-Type header rather than from the URL.

The video is available before the report. The report waits for review; the video does not, because review never changes it. It is ready by the time inspection.recording_completed arrives, so you can fetch it from that event onward.

curl -sS -G "https://api.rapideyeinspections.com/v1/inspections/3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33/video" \
  -H "Authorization: Bearer rapideye_pk_REPLACE_ME" \
  --data-urlencode "workspace_id=ws_123"

{
  "inspection_id": "3b7f1a90-2c44-4b6d-9e01-7a5c2f8e1d33",
  "download_url": "https://...signed...",
  "expires_at": "2026-10-05T17:19:33Z",
  "media_expires_in": 900,
  "content_type": "video/mp4",
  "duration_seconds": 313,
  "size_bytes": 341087869,
  "recorded_at": "2026-10-05T17:01:12+00:00"
}