> ## Documentation Index > Fetch the complete documentation index at: https://docs.mapxagent.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a project > Requires scope: session. ## OpenAPI ````yaml /openapi.json post /sessions openapi: 3.1.0 info: title: MapX SaaS API version: 1.0.0 description: >- Public REST API for MapX. Authenticate with a personal API key (Bearer mkx_...) created from the MapX account. All endpoints are scoped to the account that owns the key; each endpoint also enforces a capability scope (session, chat, files, layers, map, reports, remote, keys). Errors use a uniform envelope: {"error":{"code","message","details"}}. Rate limit: 300 requests per minute per key. The API resource is named `session` for historical reasons; it represents a persistent project in the product (a workspace with map state, layers, files, chat history, and reports). servers: - url: https://api.mapxagent.com/api/v1 description: Production - url: http://localhost:3001/api/v1 description: Local development security: - bearerAuth: [] tags: - name: Projects description: Project lifecycle and metadata. - name: Authentication description: API key validation. - name: Map description: Map state and actions. - name: Chat description: AI chat turns and question responses. - name: Files description: File listing, upload, and content access. - name: Layers description: Layer metadata, style, visibility, and ordering. - name: Reports description: HTML report generation and metadata. - name: API Keys description: Personal API key management. - name: Usage description: Current plan usage. - name: Meta description: API metadata. paths: /sessions: post: tags: - Projects summary: Create a project description: 'Requires scope: session.' operationId: createSession requestBody: required: true description: >- All fields are optional; an empty object creates a project with default title and map state. content: application/json: schema: type: object properties: title: description: >- Project title. Optional; defaults to "New Session" when omitted or empty. type: string maxLength: 200 mapState: type: object properties: center: description: Map center as [lng, lat]. minItems: 2 maxItems: 2 type: array items: type: number zoom: description: Map zoom level, 0-22. type: number minimum: 0 maximum: 22 bearing: description: Map rotation in degrees. type: number pitch: description: Map pitch in degrees, 0-85. type: number minimum: 0 maximum: 85 basemap: type: object properties: style: type: string description: >- Basemap style ID. Allowed values: positron (light), positronWithLabels (light with labels), dark (dark), darkWithLabels (dark with labels). categories: description: >- Basemap category overrides. Allowed keys: background, water, green, roads, buildings, aeroway, boundaries, labels. Omitted categories keep their built-in defaults. type: object additionalProperties: type: object properties: color: description: >- CSS color value, e.g. #1e3a5f or rgba(...). Setting a color makes the category visible. type: string visible: description: Whether the category is visible. type: boolean additionalProperties: false description: Per-category color and visibility override. required: - style additionalProperties: false description: Basemap style and per-category overrides. countryMask: description: >- Inverted-polygon mask that hides the basemap outside a country. Omitted or null means no country mask. anyOf: - type: object properties: countryCode: type: string description: ISO 3166-1 alpha-3 country code, e.g. CHN. countryName: type: string description: Country display name. visible: type: boolean description: Whether the country mask is shown. color: description: 'Mask color override (hex), e.g. #1e3a5f.' type: string required: - countryCode - countryName - visible additionalProperties: false - type: 'null' customMask: description: >- Custom polygon mask built from arbitrary GeoJSON. Omitted or null means no custom mask. anyOf: - type: object properties: geojson: type: string description: >- Raw GeoJSON string containing a Polygon or MultiPolygon geometry. color: description: 'Mask color override (hex), e.g. #1e3a5f.' type: string required: - geojson additionalProperties: false - type: 'null' additionalProperties: false description: >- Initial map state. All fields optional. Omitted center/zoom/bearing/pitch default to [0, 0], 2, 0, 0; omitted basemap defaults to { style: "positron", categories: {} }. additionalProperties: false example: title: 门店分析 mapState: center: - 0 - 0 zoom: 2 bearing: 0 pitch: 0 basemap: style: positron categories: water: visible: false responses: '201': description: Project created. content: application/json: schema: type: object properties: id: type: string description: Project UUID. title: type: string mapState: type: object properties: center: description: Map center as [lng, lat]. minItems: 2 maxItems: 2 type: array items: type: number zoom: description: Map zoom level, 0-22. type: number minimum: 0 maximum: 22 bearing: description: Map rotation in degrees. type: number pitch: description: Map pitch in degrees, 0-85. type: number minimum: 0 maximum: 85 basemap: type: object properties: style: type: string description: >- Basemap style ID. Allowed values: positron (light), positronWithLabels (light with labels), dark (dark), darkWithLabels (dark with labels). categories: description: >- Basemap category overrides. Allowed keys: background, water, green, roads, buildings, aeroway, boundaries, labels. Omitted categories keep their built-in defaults. type: object additionalProperties: type: object properties: color: description: >- CSS color value, e.g. #1e3a5f or rgba(...). Setting a color makes the category visible. type: string visible: description: Whether the category is visible. type: boolean additionalProperties: false description: Per-category color and visibility override. required: - style additionalProperties: false description: Basemap style and per-category overrides. countryMask: description: >- Inverted-polygon mask that hides the basemap outside a country. Omitted or null means no country mask. anyOf: - type: object properties: countryCode: type: string description: ISO 3166-1 alpha-3 country code, e.g. CHN. countryName: type: string description: Country display name. visible: type: boolean description: Whether the country mask is shown. color: description: 'Mask color override (hex), e.g. #1e3a5f.' type: string required: - countryCode - countryName - visible additionalProperties: false - type: 'null' customMask: description: >- Custom polygon mask built from arbitrary GeoJSON. Omitted or null means no custom mask. anyOf: - type: object properties: geojson: type: string description: >- Raw GeoJSON string containing a Polygon or MultiPolygon geometry. color: description: 'Mask color override (hex), e.g. #1e3a5f.' type: string required: - geojson additionalProperties: false - type: 'null' additionalProperties: false description: Current map viewport and basemap state. updatedAt: type: string format: date-time additionalProperties: true '400': description: Bad request — invalid or missing fields content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: MapX v1 error code. enum: - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited - usage_limit_exceeded - internal_error message: type: string details: description: Optional extra context. '401': description: Missing or invalid API key content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: MapX v1 error code. enum: - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited - usage_limit_exceeded - internal_error message: type: string details: description: Optional extra context. '403': description: Forbidden — insufficient scope or disabled account content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: MapX v1 error code. enum: - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited - usage_limit_exceeded - internal_error message: type: string details: description: Optional extra context. '404': description: Not found content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: MapX v1 error code. enum: - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited - usage_limit_exceeded - internal_error message: type: string details: description: Optional extra context. '409': description: Conflict — e.g. a chat turn is already in progress content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: MapX v1 error code. enum: - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited - usage_limit_exceeded - internal_error message: type: string details: description: Optional extra context. '429': description: Rate limited or usage limit reached content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: MapX v1 error code. enum: - bad_request - unauthorized - forbidden - not_found - conflict - rate_limited - usage_limit_exceeded - internal_error message: type: string details: description: Optional extra context. components: securitySchemes: bearerAuth: type: http scheme: bearer description: Personal API key (mkx_...) created from the MapX account. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.