> For the complete documentation index, see [llms.txt](https://cityweft.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cityweft.gitbook.io/docs/getting-started/api-reference.md).

# API Reference

Full interactive reference for the Cityweft API — explore every parameter and test requests with your own API key directly from this page.

Everything the `/v1/context` endpoint accepts and returns.

{% hint style="warning" %}
**Live testing requires an API key.** The **Test it** panel sends real requests to your account — each one generates a real model and counts toward your plan, exactly like any API call.

* Generate a key on the **API & Plugin Keys** page of the [Cityweft dashboard](https://app.cityweft.com) and paste it as the Bearer token.
* We recommend using a **development key** (not your production key) so experiments stay separate from your production usage.
* Keep test polygons small — a city block is plenty.
  {% endhint %}

## Generate 3D city context

> Generates the 3D model for a polygon area — buildings, ground surfaces, barriers, infrastructure instances, terrain and surface linework — returned as JSON geometry, or exported directly to a 3D file format with the \`export\` parameter. Maximum area per request is 10 km².

```json
{"openapi":"3.1.0","info":{"title":"Cityweft API","version":"1.0"},"servers":[{"url":"https://api.cityweft.com"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your Cityweft API key (starts with cw_), generated on the API & Plugin Keys page of the Cityweft dashboard."}},"schemas":{"Settings":{"type":"object","description":"Output customization options.","properties":{"geometry":{"type":"array","description":"Geometry groups to generate. `topography` is not included by default.","items":{"type":"string","enum":["buildings","surface","barriers","instances","infrastructure","topography"]},"default":["buildings","surface","barriers","instances"]},"surfaceTypes":{"type":"array","description":"Which representations of the ground surfaces to return: 'meshes' (the surface mesh group), 'centerlines' and/or 'outlines' (draped polylines in the surfaceLines response group). Any combination — without 'meshes', linework replaces the surface meshes.","items":{"type":"string","enum":["meshes","centerlines","outlines"]},"default":["meshes"]},"cropScene":{"type":"boolean","default":false,"description":"Slice the model precisely along the polygon boundary (adds ~10–20% processing time)."},"defaultRoofType":{"type":"string","enum":["flat","hipped","gabled","onion","dome","round","skillion","mansard","quadrupleSaltbox","saltbox","gambrel","pyramidal"],"default":"flat","description":"Roof type applied when the actual roof shape is unknown."},"defaultLevels":{"type":"number","default":1,"description":"Number of levels assumed when no height data exists."},"defaultLevelHeight":{"type":"number","default":4,"description":"Height of one level in meters, used to estimate building height when no data exists."},"buildingSources":{"type":"string","enum":["all","global"],"default":"all","description":"'all' uses the best building data available to your account; 'global' restricts the request to worldwide base data only."},"treeSource":{"type":"string","enum":["standard","hybrid","canopy"],"default":"standard","description":"Tree data source. `standard` uses surveyed points plus procedural forest fill; `hybrid` (recommended) detects individual trees from a 1-meter satellite canopy model with measured heights and crown diameters; `canopy` returns canopy-detected trees only."},"canopyMinHeight":{"type":"number","default":3,"description":"Shortest canopy counted as a tree, in meters (hybrid/canopy only)."},"canopyMinSpacing":{"type":"number","default":3,"description":"Minimum tree-to-tree spacing in meters for canopy detection."},"canopyMaxTrees":{"type":"number","default":40000,"description":"Hard cap on the number of detected trees."},"topographyModel":{"type":"boolean","default":false,"description":"Include the terrain model in the output (same as adding `topography` to `geometry`)."},"topographyReturnType":{"type":"string","enum":["meshes","elevationMap","both"],"default":"elevationMap","description":"How terrain is returned. Elevation maps are ~94% smaller than meshes."},"combineElevationMaps":{"type":"boolean","default":true,"description":"Merge per-tile elevation maps into a single grid covering the whole site."},"projectToTopography":{"type":"boolean","default":false,"description":"Project geometry onto real terrain elevations without returning terrain geometry."},"disableSurfaceProjection":{"type":"boolean","default":false,"description":"Keep surface geometry flat instead of draping it onto the terrain."},"crs":{"type":"string","enum":["local","EPSG:3857","UTM"],"default":"local","description":"Coordinate reference system of the returned coordinates."},"upAxis":{"type":"string","enum":["Y","Z"],"default":"Y","description":"Which axis represents \"up\" in the returned geometry."},"indexedMeshes":{"type":"boolean","default":false,"description":"Return indexed meshes — vertices are welded and every mesh gains an `indices` array, significantly reducing payload size (JSON responses only)."}}},"Export":{"type":"object","description":"Export directly to a 3D file format instead of receiving JSON geometry.","required":["format"],"properties":{"format":{"type":"string","enum":["obj","3dm","dxf","skp","glb","gltf","ifc","rvt","stl","ply","dae"],"description":"Target file format."},"crs":{"type":"string","description":"`local` (default, origin-relative meters) or a projected EPSG code (e.g. EPSG:27700) in meters, international feet, or US survey feet. Only valid when settings.crs is local."},"placement":{"type":"string","enum":["anchor","absolute"],"default":"anchor","description":"`anchor` keeps coordinates origin-relative with the format's native georeference anchor; `absolute` bakes real grid coordinates into the file for GIS workflows."},"units":{"type":"string","enum":["m","mm","ft","in"],"default":"m","description":"Model units for the exported file (ignored for formats with fixed units)."},"surfaceType":{"type":"string","enum":["meshes","centerlines","outlines"],"default":"meshes","description":"Deliver ground surfaces as meshes, or as centerline/outline curves instead."}}},"GeometryGroup":{"type":"object","properties":{"type":{"type":"string","description":"Geometry group name (buildings, surface, barriers, instances, topography, surfaceLines)."},"geometryType":{"type":"string","enum":["meshes","elevationMaps","nodes","polylines"]},"meshes":{"type":"array","items":{"$ref":"#/components/schemas/Mesh"}},"elevationMaps":{"type":"array","items":{"type":"object"}},"nodes":{"type":"array","items":{"type":"object"}},"polylines":{"type":"array","items":{"type":"object"}}}},"Mesh":{"type":"object","properties":{"vertices":{"type":"array","items":{"type":"number"},"description":"Flat triangle list — three coordinates per vertex, three vertices per triangle."},"indices":{"type":"array","items":{"type":"integer"},"description":"Present when settings.indexedMeshes is true."},"descriptor":{"type":"object","description":"Feature metadata (type, dimensions, materials, data tier).","additionalProperties":true}}},"SpatialReference":{"type":"object","properties":{"crs":{"type":"string"},"origin":{"type":"array","items":{"type":"number"}},"utmZoneEPSG":{"type":"string"},"zoneString":{"type":"string"},"hemisphere":{"type":"string"},"zone":{"type":"number"},"letter":{"type":"string"}}},"Attribution":{"type":"object","description":"Credit line for a data source that contributed to the scene.","properties":{"id":{"type":"string"},"name":{"type":"string"},"text":{"type":"string","description":"Credit line to render verbatim when displaying or redistributing the output."},"license":{"type":"string"},"url":{"type":"string"},"required":{"type":"boolean"}}}}},"paths":{"/v1/context":{"post":{"operationId":"getContext","summary":"Generate 3D city context","description":"Generates the 3D model for a polygon area — buildings, ground surfaces, barriers, infrastructure instances, terrain and surface linework — returned as JSON geometry, or exported directly to a 3D file format with the `export` parameter. Maximum area per request is 10 km².","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["polygon"],"properties":{"polygon":{"type":"array","minItems":4,"description":"The area to generate, as [latitude, longitude] pairs. Must be closed — first and last points identical. Maximum area 10 km².","items":{"type":"array","minItems":2,"maxItems":2,"items":{"type":"number"}}},"origin":{"type":"array","minItems":2,"maxItems":2,"description":"Optional [latitude, longitude] origin for local coordinates (defaults to the first polygon vertex).","items":{"type":"number"}},"settings":{"$ref":"#/components/schemas/Settings"},"export":{"$ref":"#/components/schemas/Export"}}}}}},"responses":{"200":{"description":"Generated geometry (or a download URL when `export` was provided).","content":{"application/json":{"schema":{"oneOf":[{"title":"Geometry response","type":"object","properties":{"origin":{"type":"array","items":{"type":"number"},"description":"[latitude, longitude] origin of the local coordinate frame."},"geometry":{"type":"array","items":{"$ref":"#/components/schemas/GeometryGroup"}},"spatialReference":{"$ref":"#/components/schemas/SpatialReference"},"attributions":{"type":"array","items":{"$ref":"#/components/schemas/Attribution"}},"dataAccess":{"type":"object","description":"Reports when premium country data was unavailable to your plan and the response fell back to worldwide data.","properties":{"granted":{"type":"string","enum":["full","global"]},"suppressedCountries":{"type":"array","items":{"type":"string"}},"reason":{"type":["string","null"]}}}}},{"title":"Export response","type":"object","properties":{"downloadUrl":{"type":"string","description":"Direct URL to download the exported file (stored temporarily)."},"spatialReference":{"$ref":"#/components/schemas/SpatialReference"}}}]}}}},"400":{"description":"Invalid request — malformed polygon, unclosed polygon, or area larger than 10 km²."},"401":{"description":"Missing or invalid API key."},"402":{"description":"No active subscription or remaining balance for this request."},"503":{"description":"Server busy — retry shortly (Retry-After header included)."}}}}}}
```