> ## 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. # Upload a file > Requires scope: files. Multipart upload. Supported extensions: .csv, .geojson, .json, .xlsx, .xls, .txt, .md, .docx, .doc, .pdf, .tif, .tiff. GeoJSON/JSON are added as layers directly; CSV/Excel are converted to GeoJSON layers; TIFF is converted to a COG image layer; text/document files are stored as plain files. Max size: 50MB (configurable via UPLOAD_MAX_SIZE_MB). ## OpenAPI ````yaml /openapi.json post /sessions/{id}/files 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/{id}/files: post: tags: - Files summary: Upload a file description: >- Requires scope: files. Multipart upload. Supported extensions: .csv, .geojson, .json, .xlsx, .xls, .txt, .md, .docx, .doc, .pdf, .tif, .tiff. GeoJSON/JSON are added as layers directly; CSV/Excel are converted to GeoJSON layers; TIFF is converted to a COG image layer; text/document files are stored as plain files. Max size: 50MB (configurable via UPLOAD_MAX_SIZE_MB). operationId: uploadFile parameters: - name: id in: path required: true description: Project UUID. schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object required: - file properties: file: type: string format: binary description: >- File to upload. Supported extensions: .csv, .geojson, .json, .xlsx, .xls, .txt, .md, .docx, .doc, .pdf, .tif, .tiff. responses: '200': description: Uploaded file record. content: application/json: schema: type: object properties: id: type: string description: Layer id created for GeoJSON uploads. label: type: string description: Display name. fileId: type: string description: Uploaded file id. addedToMap: type: boolean description: Whether the file was automatically added as a layer. featureCount: type: integer description: Feature count for GeoJSON uploads. geometryType: type: string description: >- Detected geometry type (circle/line/fill) for GeoJSON uploads. style: type: object additionalProperties: true description: Layer style applied to the new layer. additionalProperties: false '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.