Analyses

An analysis is one floor plan image processed by Grihafy. This page covers sending one, reading it back, and managing it. Field-by-field schemas are in the API reference.

Submit a floor plan

POST /v1/analyses takes a multipart/form-data body and an Idempotency-Key header. It answers 202 with the new analysis in the queued status.

curl -X POST https://api.grihafy.com/v1/analyses \
  -H "Authorization: Bearer gfy_live_..." \
  -H "Idempotency-Key: 6f0c2a52-7e7e-4c53-9f6e-2d9d6d5b1a10" \
  -F "[email protected]" \
  -F "reviewMode=north_if_low_confidence" \
  -F "externalId=project-001" \
  -F 'metadata={"project":"Lakeview"}'

Field	Required	What it is for
`file`	Yes	The floor plan image. See the image rules below.
`reviewMode`	Yes	Whether Grihafy should pause to ask you about north or rooms. See Review flows.
`northAngle`	No	Which way north points in the image: degrees clockwise from the top, 0 to 359.99. Skips north detection.
`locale`	No	Report language: `en` (default), `hi` or `ar`.
`externalId`	No	Your own reference, up to 128 characters. Not required to be unique. You can filter by it when listing.
`metadata`	No	Up to 20 text values of up to 500 characters each, sent as JSON text. Returned unchanged.

Image rules

JPEG, PNG or WebP, up to 10 MB. The type is detected from the file contents.
One image per request. PDFs are not supported; export the page as an image first.
Grihafy re-encodes the image and shrinks it to fit within 2560 pixels. The input.width and input.height you get back describe that processed image.
An image that cannot be decoded, or that is larger than 40 megapixels, is rejected with 422 image_unreadable. No analysis is created and no credit is held.
An image that is readable but is not a floor plan is accepted and later ends as failed. The credit is returned.

Statuses

Status	Meaning	What you do
`queued`	Accepted and waiting to start.	Wait.
`processing`	Being analyzed.	Wait.
`review_required`	Paused until you answer a review step.	Answer the review
`completed`	Finished. The result is in the result field.	Read the result.
`failed`	The image could not be analyzed. The failure code is always internal.	Submit again if you think the cause was temporary. If it repeats, contact us with the analysis ID.
`expired`	A review step was not answered in time.	Submit the image again.

There is no fixed processing time. Wait for a webhook, or check the analysis every 5 to 10 seconds. Stay inside the rate limits.

Read the result

GET /v1/analyses/{id} returns the analysis. When it is completed, result holds the report:

score and potentialScore: 0 to 100, with a band label.
summary and categories: the overall picture.
rooms: each detected room with its direction and verdict.
findings and recommendations: what to look at and suggested changes.
unit, and sharedArea and unitLabel on rooms, when the image shows several flats. Each flat is its own analysis. See Review flows.

Every field is defined in the Analysis model. links.report is the hosted report page and requires signing in as a member of your organization. links.share is a link you can give to someone outside your organization. Share links do not expire and cannot be revoked yet.

Image links expire

input.imageUrl is a signed link that works for about 15 minutes. Read the analysis again for a fresh one. The link inside a webhook is fixed when the event is created and is not refreshed on retries.

List and filter

GET /v1/analyses returns your analyses newest first, 20 per page by default (limit up to 100). When more exist, nextCursor holds an opaque value to send back as cursor; it is null on the last page.

# Newest first, 20 per page by default
curl "https://api.grihafy.com/v1/analyses?status=completed&limit=20" \
  -H "Authorization: Bearer gfy_live_..."

# Next page: pass the nextCursor value from the previous response
curl "https://api.grihafy.com/v1/analyses?status=completed&limit=20&cursor=<nextCursor>" \
  -H "Authorization: Bearer gfy_live_..."

Filter	Matches
`status`	Analyses in one status.
`externalId`	Analyses with exactly this externalId.
`createdAfter`	Created after this time (exclusive). Use with `createdBefore` for a range; the start must be earlier than the end.
`archived`	Set to true to list only archived analyses.

Delete an analysis

DELETE /v1/analyses/{id} returns 204. You can delete an analysis in any status except processing, which returns 409 invalid_state; try again once it moves on. A credit held for an unfinished analysis is returned. A completed analysis keeps its credit spent. See Credits.

curl -X DELETE https://api.grihafy.com/v1/analyses/<id> \
  -H "Authorization: Bearer gfy_live_..."

Translated reports

Send locale=hi or locale=ar when submitting. The English report completes first and the translation follows. Until it is ready, reading the analysis returns English and its locale field says so. Asking for a specific language with ?locale=hi before it is ready returns 409 translation_pending with a Retry-After of 10 seconds. Webhooks always carry English.