{"components":{"securitySchemes":{"bearer":{"scheme":"bearer","type":"http"}}},"info":{"description":"Administration of one org. Authenticate with an **account-org-level** service-account credential (made for one org): request a token with the `client_credentials` grant at `https://api.mapped.com/oauth/token`, then send it as `Authorization: Bearer`. Every route is for the credential's own org: `orgId` must be that org and `accountId` the account that holds it, otherwise the call is refused (403) and nothing is read or changed. A batch is for many buildings of that one org. Account-level credentials and signed-in users' tokens are not accepted (403).","title":"Mapped admin API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/v1/accounts/{accountId}/orgs/{orgId}/batches/{batchId}":{"get":{"description":"Per-item results are kept for 3 days; after that the items of a finished batch are omitted and counted in `counts.unreported`. A batch of another org or account, or an id this API did not issue, returns 404.","operationId":"getBatch","parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"in":"path","name":"orgId","required":true,"schema":{"type":"string"}},{"in":"path","name":"batchId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"batchId":"0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e","completedAt":"2026-11-05T10:00:04.000Z","counts":{"error":1,"ok":1,"pending":0,"total":2,"unreported":0},"createdAt":"2026-11-05T10:00:00.000Z","items":[{"buildingId":"bld_1","orgId":"org_1","status":"ok"},{"buildingId":"bld_2","error":"building_not_found","orgId":"org_1","status":"error"}],"status":"completed"},"success":true},"schema":{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"batchId":{"type":"string"},"completedAt":{"type":"string"},"counts":{"additionalProperties":false,"properties":{"error":{"maximum":9007199254740991,"minimum":-9007199254740991,"type":"integer"},"ok":{"maximum":9007199254740991,"minimum":-9007199254740991,"type":"integer"},"pending":{"maximum":9007199254740991,"minimum":-9007199254740991,"type":"integer"},"total":{"maximum":9007199254740991,"minimum":-9007199254740991,"type":"integer"},"unreported":{"description":"Finished items whose per-item result is no longer available.","maximum":9007199254740991,"minimum":-9007199254740991,"type":"integer"}},"required":["total","ok","error","pending","unreported"],"type":"object"},"createdAt":{"type":"string"},"items":{"items":{"additionalProperties":false,"properties":{"buildingId":{"type":"string"},"error":{"description":"For example building_not_found, connector_required, missing_postal_identity, invalid_gross_area, upstream_error, job_failed (the job did not complete; some of its items may already have been applied).","type":"string"},"orgId":{"type":"string"},"status":{"enum":["pending","ok","error"],"type":"string"}},"required":["orgId","buildingId","status"],"type":"object"},"type":"array"},"status":{"enum":["queued","running","completed"],"type":"string"}},"required":["batchId","status","counts","createdAt","items"],"type":"object"},"success":{"const":true,"type":"boolean"}},"required":["success","data"],"type":"object"}}},"description":"Per-item results are kept for 3 days; after that the items of a finished batch are omitted and counted in `counts.unreported`. A batch of another org or account, or an id this API did not issue, returns 404."},"401":{"content":{"application/json":{"example":{"code":"invalid_token","error":"Invalid bearer token","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"No valid bearer token: `missing_token` (no `Authorization: Bearer` header), `invalid_token` or `token_expired`."},"403":{"content":{"application/json":{"example":{"code":"forbidden","error":"Org does not belong to this account","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Not a credential for this org and account, or not an account-org-level service-account credential. Nothing was read or changed."},"404":{"content":{"application/json":{"example":{"code":"not_found","error":"Batch not found","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Batch not found."},"429":{"content":{"application/json":{"example":{"code":"rate_limited","error":"Too many requests","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Too many requests; see `Retry-After`."},"503":{"content":{"application/json":{"example":{"code":"results_unavailable","error":"Per-item results are temporarily unavailable; try again shortly","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Per-item results (`results_unavailable`) or the batch (`jobs_unavailable`, `batches_unavailable`) cannot be read right now, or a check this API depends on is unavailable (`upstream_unavailable`); retry."}},"security":[{"bearer":[]}],"summary":"Batch status and per-item results","x-docs":{"audience":"org-service-account"}}},"/v1/accounts/{accountId}/orgs/{orgId}/buildings":{"get":{"description":"Only buildings with a postal address are returned, since the others cannot be updated. The list can lag an update by up to a minute.","operationId":"listBuildings","parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"in":"path","name":"orgId","required":true,"schema":{"type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"description":"An integer from 1 to 100; 50 when absent.","pattern":"^\\d+$","type":"string"}},{"in":"query","name":"cursor","required":false,"schema":{"description":"Opaque; pass the `nextCursor` of the previous page.","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":{"items":[{"grossArea":52000,"id":"bld_1","name":"Head Office"},{"grossArea":null,"id":"bld_2","name":"Warehouse"}],"nextCursor":"eyJ2IjoxLCJhZnRlciI6ImJsZF8yIn0"},"success":true},"schema":{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"items":{"items":{"additionalProperties":false,"properties":{"grossArea":{"description":"Square feet.","type":["number","null"]},"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name","grossArea"],"type":"object"},"type":"array"},"nextCursor":{"type":"string"}},"required":["items"],"type":"object"},"success":{"const":true,"type":"boolean"}},"required":["success","data"],"type":"object"}}},"description":"Only buildings with a postal address are returned, since the others cannot be updated. The list can lag an update by up to a minute."},"400":{"content":{"application/json":{"example":{"code":"invalid_limit","error":"limit must be an integer between 1 and 100","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"`limit` is not an integer from 1 to 100 (`invalid_limit`), or `cursor` is not one this API gave you (`invalid_cursor`)."},"401":{"content":{"application/json":{"example":{"code":"invalid_token","error":"Invalid bearer token","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"No valid bearer token: `missing_token` (no `Authorization: Bearer` header), `invalid_token` or `token_expired`."},"403":{"content":{"application/json":{"example":{"code":"forbidden","error":"Org does not belong to this account","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Not a credential for this org and account, or not an account-org-level service-account credential. Nothing was read or changed."},"429":{"content":{"application/json":{"example":{"code":"rate_limited","error":"Too many requests","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Too many requests; see `Retry-After`."},"503":{"content":{"application/json":{"example":{"code":"upstream_unavailable","error":"Authorization service unavailable","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"A check this API depends on is unavailable; retry."}},"security":[{"bearer":[]}],"summary":"List the buildings of an org","x-docs":{"audience":"org-service-account"}}},"/v1/accounts/{accountId}/orgs/{orgId}/buildings/gross-area:batch":{"post":{"description":"Accepts 1 to 1,000 buildings of the org in the path and returns immediately. Poll the returned `statusUrl` (also the `Location` header). Each `buildingId` may appear once, and an item names no org (the org is the path's). One background job is started for the org.","operationId":"startGrossAreaBatch","parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"in":"path","name":"orgId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"items":[{"buildingId":"bld_1","grossArea":52000},{"buildingId":"bld_2","grossArea":18500}]},"schema":{"properties":{"createConnector":{"default":false,"description":"Allow creating the admin-center connector if the org has none.","type":"boolean"},"items":{"items":{"properties":{"buildingId":{"pattern":"^[A-Za-z0-9_.-]{1,128}$","type":"string"},"grossArea":{"description":"Square feet. 0 is valid.","minimum":0,"type":"number"},"orgId":{"description":"Not allowed: the org is the path's.","not":{}}},"required":["buildingId","grossArea"],"type":"object"},"maxItems":1000,"minItems":1,"type":"array"}},"required":["items"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"example":{"data":{"batchId":"0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e","statusUrl":"/v1/accounts/ACCOUNT_ID/orgs/ORG_ID/batches/0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e"},"success":true},"schema":{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"batchId":{"type":"string"},"statusUrl":{"type":"string"}},"required":["batchId","statusUrl"],"type":"object"},"success":{"const":true,"type":"boolean"}},"required":["success","data"],"type":"object"}}},"description":"Accepts 1 to 1,000 buildings of the org in the path and returns immediately. Poll the returned `statusUrl` (also the `Location` header). Each `buildingId` may appear once, and an item names no org (the org is the path's). One background job is started for the org."},"400":{"content":{"application/json":{"example":{"code":"invalid_items","error":"items must be an array of 1 to 1000 entries","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Nothing was started: `items` is not an array of 1 to 1,000 (`invalid_items`), an item is malformed or names an `orgId` (`invalid_item`), a `buildingId` repeats (`duplicate_item`), `createConnector` is not a boolean (`invalid_create_connector`), or the body is not a JSON object, is malformed, or is not `application/json` (`bad_request`)."},"401":{"content":{"application/json":{"example":{"code":"invalid_token","error":"Invalid bearer token","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"No valid bearer token: `missing_token` (no `Authorization: Bearer` header), `invalid_token` or `token_expired`."},"403":{"content":{"application/json":{"example":{"code":"forbidden","error":"Org does not belong to this account","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Not a credential for this org and account, or not an account-org-level service-account credential. Nothing was read or changed."},"413":{"content":{"application/json":{"example":{"code":"bad_request","error":"Bad request","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"A JSON body over 1,000,000 bytes is `bad_request` in this envelope. A body over 1 MiB (1,048,576 bytes) is refused earlier by the server, in its own shape (`{ \"code\": \"PAYLOAD_TOO_LARGE\", ... }`)."},"429":{"content":{"application/json":{"example":{"code":"rate_limited","error":"Too many batches started; try again shortly","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Too many requests, or too many batches or updates started; see `Retry-After`."},"502":{"content":{"application/json":{"example":{"code":"jobs_unavailable","error":"The batch could not be started and was cancelled; some updates may already have been applied","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"The job could not be started and was cancelled; some updates may already have been applied."},"503":{"content":{"application/json":{"example":{"code":"batches_unavailable","error":"Batches are temporarily unavailable; try again shortly","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Batches and updates are not available right now (`batches_unavailable`, `jobs_unavailable`), or a check this API depends on is unavailable (`upstream_unavailable`); retry."}},"security":[{"bearer":[]}],"summary":"Set gross area for many buildings, asynchronously","x-docs":{"audience":"org-service-account"}}},"/v1/accounts/{accountId}/orgs/{orgId}/buildings/{buildingId}/gross-area":{"put":{"description":"Starts a background job (a batch of one) and returns immediately. Poll the returned `statusUrl` (also the `Location` header); the result of the update, including a building that is not found, is its item. Idempotent; setting the same value twice is harmless.","operationId":"setBuildingGrossArea","parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string"}},{"in":"path","name":"orgId","required":true,"schema":{"type":"string"}},{"in":"path","name":"buildingId","required":true,"schema":{"pattern":"^[A-Za-z0-9_.-]{1,128}$","type":"string"}}],"requestBody":{"content":{"application/json":{"example":{"grossArea":52000},"schema":{"properties":{"createConnector":{"default":false,"description":"Allow creating the admin-center connector if the org has none.","type":"boolean"},"grossArea":{"description":"Square feet. 0 is valid.","minimum":0,"type":"number"}},"required":["grossArea"],"type":"object"}}},"required":true},"responses":{"202":{"content":{"application/json":{"example":{"data":{"batchId":"0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e","statusUrl":"/v1/accounts/ACCOUNT_ID/orgs/ORG_ID/batches/0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e"},"success":true},"schema":{"additionalProperties":false,"properties":{"data":{"additionalProperties":false,"properties":{"batchId":{"type":"string"},"statusUrl":{"type":"string"}},"required":["batchId","statusUrl"],"type":"object"},"success":{"const":true,"type":"boolean"}},"required":["success","data"],"type":"object"}}},"description":"Starts a background job (a batch of one) and returns immediately. Poll the returned `statusUrl` (also the `Location` header); the result of the update, including a building that is not found, is its item. Idempotent; setting the same value twice is harmless."},"400":{"content":{"application/json":{"example":{"code":"invalid_gross_area","error":"grossArea must be a finite number >= 0","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Nothing was started: `grossArea` is missing, not a number, or below 0 (`invalid_gross_area`); `createConnector` is not a boolean (`invalid_create_connector`); `buildingId` does not match the pattern (`invalid_building_id`); or the body is not a JSON object, is malformed, or is not `application/json` (`bad_request`)."},"401":{"content":{"application/json":{"example":{"code":"invalid_token","error":"Invalid bearer token","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"No valid bearer token: `missing_token` (no `Authorization: Bearer` header), `invalid_token` or `token_expired`."},"403":{"content":{"application/json":{"example":{"code":"forbidden","error":"Org does not belong to this account","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Not a credential for this org and account, or not an account-org-level service-account credential. Nothing was read or changed."},"413":{"content":{"application/json":{"example":{"code":"bad_request","error":"Bad request","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"A JSON body over 1,000,000 bytes is `bad_request` in this envelope. A body over 1 MiB (1,048,576 bytes) is refused earlier by the server, in its own shape (`{ \"code\": \"PAYLOAD_TOO_LARGE\", ... }`)."},"429":{"content":{"application/json":{"example":{"code":"rate_limited","error":"Too many batches started; try again shortly","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Too many requests, or too many batches or updates started; see `Retry-After`."},"502":{"content":{"application/json":{"example":{"code":"jobs_unavailable","error":"The batch could not be started and was cancelled; some updates may already have been applied","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"The job could not be started and was cancelled; some updates may already have been applied."},"503":{"content":{"application/json":{"example":{"code":"batches_unavailable","error":"Batches are temporarily unavailable; try again shortly","success":false},"schema":{"additionalProperties":false,"properties":{"code":{"description":"Stable and machine-readable.","type":"string"},"error":{"type":"string"},"success":{"const":false,"type":"boolean"}},"required":["success","error","code"],"type":"object"}}},"description":"Batches and updates are not available right now (`batches_unavailable`, `jobs_unavailable`), or a check this API depends on is unavailable (`upstream_unavailable`); retry."}},"security":[{"bearer":[]}],"summary":"Set a building's gross area (square feet), asynchronously","x-docs":{"audience":"org-service-account"}}}},"servers":[{"url":"https://api.mapped.com"}]}