Detect rooms
Room detection · model room-detector
POST
/v1/drawings/detection/roomsDetects rooms in an architectural floor plan PDF. This is an async job — it returns immediately with a job ID and you poll for the detections. Returns bounding boxes, polygons, and, when available, the room number and label extracted from nearby plan text. Detections are in PDF coordinate space.
- Returns
- A job to check202 Accepted
- Usage
- Element detectionper sheet
- Results in
- A list of roomsresult.rooms
- Auth
- API keyX-API-Key header
How it runs
- Send a
document_id - Get a
job_id - Check your results or receive a webhook
Request
This endpoint requires a
document_id. Upload your PDF first.Auth via X-API-Key header (or a bearer token). Body is JSON — this endpoint does not accept file uploads directly.
| Field | Description |
|---|---|
document_idstring · UUIDRequired | UUID of a document uploaded via POST /v1/documents. Must belong to this account and not be expired. |
page_numbersarray of integersOptional | 1-based page numbers to scan. Omit to scan the whole document. |
webhook_urlstring · URLOptional | URL to notify when the job finishes. |
confidence_minnumberOptional | Minimum detection confidence, from 0 to 1. Defaults to 0.3. |
apply_ocrbooleanOptional | Read room labels from the drawing text to name rooms and recover rooms the model missed. |
Any other field is rejected with 422 VALIDATION_ERROR (Unknown field.).
| Header | Description |
|---|---|
X-API-KeyRequired | Your API key (or a bearer token). A missing or invalid key returns 401. |
Content-TypeRequired | application/json |
Responses
The job is enqueued immediately. Poll GET /v1/jobs/{job_id} until status is complete or failed.
| Field | Description |
|---|---|
job_idstring · UUID | Use this to poll for results. |
statusstring | Always queued on this response. |
poll_urlstring | Path only — prepend https://api.anchorgrid.ai to build the full URL. |
When status is complete, the result field on the job (fetched via GET /v1/jobs/{job_id}) contains:
| Field | Description |
|---|---|
document_idstring | UUID of the source document. |
rooms_foundinteger | Total number of rooms detected. |
pages_analyzedinteger | Number of pages that were scanned. |
model_versionstring | Version of the room-detector model used. |
processing_time_msinteger | Wall-clock processing time, in milliseconds. |
roomsarray | One entry per detected room. |
rooms[].idstring | Stable room identifier. |
rooms[].pageinteger | 1-based PDF page index where the room was detected. |
rooms[].bboxobject | Axis-aligned bounding box in PDF point coordinates: x1, y1, x2, y2. |
rooms[].polygon[number, number][] | Room outline as an ordered list of [x, y] points, in PDF point coordinates. |
rooms[].confidencenumber | Detection confidence score. |
rooms[].class_labelstring | Detector class, e.g. "room". |
rooms[].room_numberstring | null | Room number extracted from nearby plan text, when available. |
rooms[].labelstring | null | Room name/label extracted from nearby plan text, when available. |
rooms[].areanumber | Room area in square PDF points (1/72 in), computed from the polygon when available, otherwise from the bbox. |
total_areanumber | Sum of rooms[].area across all detected rooms, in square PDF points. |
Errors
| Status | What it means |
|---|---|
| 401 | Missing or invalid X-API-Key. |
| 404 | document_id not found or expired. |
| 422 | Validation error — malformed UUID or invalid body. |
| 503 | Task queue unavailable — retry. |