Get started

Authentication and errors

Partner keys, the error envelope, and every error code.

Authentication (you calling us)

Send your partner key as a bearer token on every request.

HTTP

GET /v1/workspaces HTTP/1.1
Host: api.rapideyeinspections.com
Authorization: Bearer rapideye_pk_...

One long-lived key, rapideye_pk_..., issued by RapidEye when we set you up.
Server-side secret only. Never ship it to a browser or mobile client.
401 invalid_key: the header is missing or malformed, or the key is unknown.
403 key_revoked: we turned the key off. Email support for a replacement.
A workspace key (rapideye_wk_...) is made in RapidEye Settings instead. See Building on your own account.
403 partner_disabled: we paused your integration. Not a problem with the key; rotating it does not fix it.

The error envelope

JSON

{ "error": { "code": "workspace_not_provisioned", "message": "..." } }

Every non-2xx response uses this envelope. Branch on error.code, never on the message text.
code and message are always present.
detail and next_steps are optional and omitted entirely when they do not apply, never sent as null or {}. Test for the key before reading it. workspace_not_provisioned above carries neither.
detail is an object holding that code's specifics: which parameter was missing, which limit was exceeded, which property id was not in the roster. Its keys vary by code.
Treat a code you do not recognize as a failure of its status class.

Key scopes

Every route needs one scope, except GET /v1/me, and your key carries the scopes we issued it with.
A request your key has no scope for answers 403 insufficient_scope, with detail.required_scope naming the scope it needed.
A task-system key carries every scope below except read:reservations.
A reservations key carries read:workspaces, read:properties and read:reservations. See Scopes for these routes.

Scope	Routes
`write:workspaces`	`POST /v1/workspaces`
`read:workspaces`	`GET /v1/workspaces`, `GET /v1/workspaces/{workspace_id}`
`write:roster`	`POST /v1/roster-imports`, `POST /v1/roster-syncs`
`read:roster`	`GET /v1/roster-imports/{import_id}`
`read:properties`	`GET /v1/properties`
`read:homes`	`GET` on a home's checklist and baseline photo imports
`write:homes`	`PUT` and `DELETE` on a home's checklist and Matterport tour, `POST` baseline photos
`write:recording_links`	`GET /v1/recording-link`
`read:inspections`	`GET /v1/inspections`, `GET /v1/inspections/{inspection_id}/findings`, `GET /v1/inspections/{inspection_id}/video`
`write:workspace_claims`	`POST /v1/workspace-claims`
`read:reservations`	`GET /v1/reservations` and the two routes under it

Error codes

Every code this API returns, with its status.

Code	Status	Meaning
`missing_parameter`	400	A required parameter, field or header is absent or blank. `detail.parameter` names it.
`invalid_request`	400	A query parameter is malformed (a `limit` out of range, an `updated_since` without an offset, a `cursor` we did not issue), or the body is unusable, or a field is: malformed JSON, not a JSON object, wrong type, too long, an unknown field, or not yours to set. When one field is at fault `detail.parameter` names it, and a roster item problem also carries `detail.index`. A refused `return_url` also carries `detail.reason`: `not_allowed` or `malformed`.
`invalid_email`	400	The `email` on a workspace claim is not an address we can send to. Correct it and send again.
`invalid_key`	401	The `Authorization` header is missing, malformed, or carries a key we do not recognize. A configuration bug on your side; stop and check the key against the one we issued you. A workspace key: copy it again from Settings, Workspace, API, or make a new one there.
`key_revoked`	403	The key was valid and we turned it off. Not a configuration bug; email support for a replacement. A workspace key was revoked in Settings; make a new one there.
`partner_disabled`	403	Either the whole integration is paused on our side, or we hold no registry row for your slug at all. Your key is not the problem and a new one will not change the answer. Email support.
`insufficient_scope`	403	Your key, or the customer's connection, does not carry the scope this request needs. `detail.required_scope` names it. Nothing is wrong with the key; it was issued for less. See Key scopes.
`workspace_disabled`	403	This customer's connection to you is off (the customer disconnected you, or we switched it off), so its data is not readable and its events stop. The `workspace_id` stays the same if it connects again.
`plan_required`	403	A workspace key's workspace is not on a plan that includes the API. The key is kept and works again once the workspace is on Premium. Email [email protected] to change plans. See Building on your own account.
`not_available_to_workspace_keys`	403	A workspace key called a route that is for partners only. See Building on your own account for the routes it can call.
`reservation_not_found`	404	No reservation with that `reservation_id` in that workspace.
`not_found`	404	No such path on this API, or no such `inspection_id` or `import_id` in that workspace. Also what you get for a resource belonging to a different workspace; we do not distinguish the two.
`workspace_not_provisioned`	404	That workspace id is not provisioned for you. A task system creates it with `POST /v1/workspaces`; a partner reading reservations lists the customers it can read with `GET /v1/workspaces`.
`task_not_found`	404	No recording link has been issued for that `task_id` in that workspace. Call `GET /v1/recording-link` first.
`property_not_found`	404	That `property_id` is not in the workspace's roster. Send a roster that contains it. We do not create properties from a link request.
`method_not_allowed`	405	The path exists; the verb does not. `detail.allowed_methods` lists the ones that do.
`claim_requires_admin`	409	`POST /v1/workspace-claims` on a workspace your key did not create, or one that already has people in it. Ask RapidEye to nominate the owner.
`workspace_already_claimed`	409	The workspace already has an owner. They manage their own team from Settings; nothing for you to do.
`report_not_ready`	409	The inspection exists but has no released report yet, so it has no findings. Wait for `inspection.completed`; do not treat this as a permanent failure.
`video_not_ready`	409	The inspection's video is not recorded yet, still being processed, or being recorded again. Call again after `inspection.recording_completed` or `inspection.completed`. Not a permanent failure.
`video_not_available`	404	The inspection has no video to download: it was a photo inspection, or its recording could not be processed. This answer rarely changes, so do not poll for it.
`roster_required`	409	No roster has been confirmed for this workspace yet, so no recording links can be issued. Send one to `POST /v1/roster-imports`.
`property_inactive`	409	The property is in the roster but was not in the most recent snapshot you sent, so it is marked inactive. Include it in your next import to bring it back.
`property_not_activated`	409	The property is in the roster but is not switched on for inspections. Properties switch on a few seconds after an import applies, so if the import has only just applied, wait and retry. A property a person switched off in RapidEye stays off until a person switches it back on; an import does not change that. Otherwise send the roster again with a new `Idempotency-Key` (or trigger a sync with `POST /v1/roster-syncs` if you host a feed). If this persists, email support. `detail.reason` says which: `switched_off_in_rapideye` (a person switched it off; an import never changes that, so do not re-send for it) or `awaiting_activation` (send the roster again as above).
`workspace_not_enabled`	409	The account exists and inspections are not switched on for it: no roster import has applied yet, or we have paused the account (`service.state` on the workspace read tells you which). The account switches on when a roster import applies, so send the roster again with a new `Idempotency-Key` (or trigger a sync with `POST /v1/roster-syncs` if you host a feed). A paused account stays off until we set it back. If this persists, email support.
`task_property_conflict`	409	That `task_id` already has a link for a different property. A task is bound to one property for its whole life. Use a new `task_id`.
`property_managed_by_partner`	409	A workspace key asked for a recording link to a home a partner records through its own links. Use the partner's link.
`idempotency_conflict`	409	That `Idempotency-Key` was already used for a different roster. Reuse a key only to retry the identical request.
`roster_revision_conflict`	409	The import was built on a roster revision that is no longer current, because another import landed first. Re-read `GET /v1/properties` and send a fresh snapshot with a new `Idempotency-Key`. Appears on the run, in `error.code`.
`roster_empty_not_allowed`	409	The import carries no properties. An empty roster retires every door, so it is never implicit: re-send with `allow_empty: true` and a new `Idempotency-Key`. Appears on the run, in `error.code`.
`roster_confirmation_required`	409	The import would deactivate more than half of the present properties. Re-send with `acknowledge_inactive_count` set to the count in `detail` and a new `Idempotency-Key`. Appears on the run, in `error.code`.
`roster_duplicate_property`	409	A `property_id` appeared twice in one roster. Appears on the run, in `error.code`, for a feed we pulled. A pushed body gets `400 invalid_request` with the repeated ids in `detail.duplicate_property_ids`.
`pull_not_configured`	409	This workspace pushes its roster; there is no feed for us to poll.
`matterport_import_in_progress`	409	A Matterport tour is still importing for this home: a different tour on `PUT .../matterport` (`detail.importing` names it), or any tour on `POST .../baseline-photos`, because a home runs one import at a time. `detail.import_id` names the running import. Wait for `setup.matterport.state` to leave `importing`, then send again.
`baseline_import_in_progress`	409	A baseline photo import is still running for this home, yours or one its managers started, so a new photo batch or a new tour waits: a home runs one import at a time. When the running import is yours, `detail.import_id` names it; one a manager started has no id you can read. Send again once `setup.baseline_photos.state` leaves `importing`.
`payload_too_large`	413	The request body exceeds the endpoint's cap. `detail.limit_bytes` names it.
`too_many_requests`	429	Too many requests in a short window: more than 600 from one key in one 5-minute window of the clock (:00, :05, :10 and so on). Retry after the next window starts; nothing is lost. Provisioning, roster imports, claims and manual syncs each have their own tighter bound.
`internal_error`	500	Something broke on our side. The request was not processed; retrying is safe.
`service_unavailable`	503	A dependency of ours is failing, including the one that verifies your key. Not a problem with the key; never roll a key in response to this.