Felt Maps API

openapi: 3.0.0
info:
  description: Felt REST API v2.0
  title: Felt Comments Maps API
  version: '2.0'
servers:
- url: https://felt.com
  variables: {}
security: []
tags:
- description: 'Maps are the centerpiece of Felt.


    With these APIs, you can create, retrieve, update, delete, move, and duplicate maps programmatically.

    '
  name: Maps
  x-page-description: APIs for building maps
  x-page-icon: map-location
paths:
  /api/v2/maps/{map_id}/move:
    post:
      callbacks: {}
      description: Move a map to a different project or folder within the same workspace. Project IDs and Folder IDs can be found inside map settings.
      operationId: move_map
      parameters:
      - description: ''
        in: path
        name: map_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapMoveParams'
        description: Map move params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Map'
          description: Map
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Move map
      tags:
      - Maps
  /api/v2/maps/{map_id}/duplicate:
    post:
      callbacks: {}
      description: Create a copy of a map with all its layers, elements, and configuration.
      operationId: duplicate_map
      parameters:
      - description: The ID of the map to duplicate
        in: path
        name: map_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapDuplicateParams'
        description: Map duplicate params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Map'
          description: Duplicated Map
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Duplicate map
      tags:
      - Maps
  /api/v2/maps:
    post:
      callbacks: {}
      description: 'Create a new map with optional customization options.


        Several aspects can be customized when creating a new map, including:


        * Title

        * Initial location (latitude, longitude and zoom level)

        * Sharing permissions (defaults to viewing and commenting for users with the map URL)

        * An array of URLs to import on map creation

        '
      operationId: create_map
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapCreateParams'
        description: Map create params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Map'
          description: Map
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Create map
      tags:
      - Maps
      x-sort-order: 0
  /api/v2/maps/{map_id}/update:
    post:
      callbacks: {}
      description: Update map properties including title, description, and access permissions.
      operationId: update_map
      parameters:
      - description: The ID of the map to update
        in: path
        name: map_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MapUpdateParams'
        description: Map update params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Map'
          description: Map
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Update map
      tags:
      - Maps
  /api/v2/maps/{map_id}:
    delete:
      callbacks: {}
      description: 'Permanently delete a map and all its associated data.


        {% hint style="warning" %}

        This action cannot be undone. The map and all its layers, elements, and comments will be permanently removed.

        {% endhint %}

        '
      operationId: delete_map
      parameters:
      - description: The ID of the map to delete
        in: path
        name: map_id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Delete map
      tags:
      - Maps
    get:
      callbacks: {}
      description: Retrieve a map with its metadata including title, URL, thumbnail, and timestamps.
      operationId: show_map
      parameters:
      - description: ''
        in: path
        name: map_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Map'
          description: Map
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
          description: UnauthorizedError
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: NotFoundError
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: InternalServerError
      security:
      - bearerAuth: []
      summary: Get map
      tags:
      - Maps
components:
  schemas:
    GeoJSON:
      properties:
        features:
          items:
            properties:
              geometry:
                properties:
                  felt:id:
                    $ref: '#/components/schemas/FeltID'
                  felt:parentId:
                    example: luCHyMruTQ6ozGk3gPJfEB
                    format: felt_id
                    nullable: true
                    type: string
                type: object
              properties:
                type: object
              type:
                enum:
                - Feature
                type: string
            type: object
          type: array
        type:
          enum:
          - FeatureCollection
          type: string
      required:
      - type
      - features
      title: GeoJSON
      type: object
    MapMoveParams:
      oneOf:
      - properties:
          project_id:
            $ref: '#/components/schemas/FeltID'
        required:
        - project_id
        title: MoveMapProjectParams
        type: object
      - properties:
          folder_id:
            $ref: '#/components/schemas/FeltID'
        required:
        - folder_id
        title: MoveMapFolderParams
        type: object
      title: MapMoveParams
      type: object
    FeltID:
      example: luCHyMruTQ6ozGk3gPJfEB
      format: felt_id
      nullable: false
      title: FeltID
      type: string
    MapCreateParams:
      additionalProperties: false
      properties:
        basemap:
          description: 'The basemap to use for the new map. Defaults to "default". Valid values are "default", "light", "dark", "satellite", a valid raster tile URL with {x}, {y}, and {z} parameters, or a hex color string like #ff0000.'
          type: string
        description:
          description: A description to display in the map legend
          type: string
        lat:
          description: If no data has been uploaded to the map, the initial latitude to center the map display on.
          type: number
        layer_urls:
          description: An array of urls to use to create layers in the map. Only tile URLs for raster layers are supported at the moment.
          items:
            type: string
          type: array
        lon:
          description: If no data has been uploaded to the map, the initial longitude to center the map display on.
          type: number
        public_access:
          description: The level of access to grant to the map. Defaults to "view_only".
          enum:
          - private
          - view_only
          - view_and_comment
          - view_comment_and_edit
          type: string
        title:
          description: The title to be used for the map. Defaults to "Untitled Map"
          type: string
        workspace_id:
          description: The workspace to create the map in. Defaults to the latest used workspace
          type: string
        zoom:
          description: If no data has been uploaded to the map, the initial zoom level for the map to display.
          type: number
      title: MapCreateParams
      type: object
    MapViewerPermissions:
      additionalProperties: false
      properties:
        can_duplicate_map:
          description: Whether viewers can duplicate the map and data
          type: boolean
        can_export_data:
          description: Whether viewers can export map data
          type: boolean
        can_see_map_presence:
          description: Whether viewers can see who else is viewing the map
          type: boolean
      title: MapViewerPermissions
      type: object
    UnauthorizedError:
      properties:
        errors:
          items:
            properties:
              detail:
                type: string
              source:
                properties:
                  header:
                    enum:
                    - authorization
                    type: string
                type: object
              title:
                type: string
            type: object
          type: array
      title: UnauthorizedError
      type: object
    MapTableSettings:
      additionalProperties: false
      properties:
        default_table_layer_id:
          example: luCHyMruTQ6ozGk3gPJfEB
          format: felt_id
          nullable: true
          type: string
        viewers_can_open_table:
          description: Whether viewers can open the data table
          type: boolean
      title: MapTableSettings
      type: object
    MapDuplicateParams:
      additionalProperties: false
      properties:
        destination:
          oneOf:
          - additionalProperties: false
            properties:
              project_id:
                $ref: '#/components/schemas/FeltID'
            required:
            - project_id
            type: object
          - additionalProperties: false
            properties:
              folder_id:
                $ref: '#/components/schemas/FeltID'
            required:
            - folder_id
            type: object
          type: object
        title:
          description: Title for the duplicated map. If not provided, will default to '[Original Title] (copy)'
          type: string
      title: MapDuplicateParams
      type: object
    InternalServerError:
      properties:
        errors:
          items:
            properties:
              detail:
                type: string
              source:
                properties:
                  parameter:
                    type: string
                type: object
              title:
                type: string
            type: object
          type: array
      title: InternalServerError
      type: object
    Map:
      additionalProperties: false
      properties:
        basemap:
          type: string
        created_at:
          example: '2024-05-25T15:51:34'
          format: date_time
          type: string
        element_groups:
          items:
            properties:
              elements:
                $ref: '#/components/schemas/GeoJSON'
              id:
                $ref: '#/components/schemas/FeltID'
              name:
                nullable: true
                type: string
            type: object
          type: array
        elements:
          $ref: '#/components/schemas/GeoJSON'
        folder_id:
          nullable: true
          type: string
        id:
          $ref: '#/components/schemas/FeltID'
        layer_groups:
          items:
            $ref: '#/components/schemas/LayerGroup'
          type: array
        layers:
          items:
            $ref: '#/components/schemas/Layer'
          type: array
        links:
          properties:
            self:
              example: https://felt.com/api/v2/maps/V0dnOMOuTd9B9BOsL9C0UjmqC
              type: string
          type: object
        project_id:
          nullable: false
          type: string
        public_access:
          enum:
          - private
          - view_only
          - view_and_comment
          - view_comment_and_edit
          type: string
        table_settings:
          $ref: '#/components/schemas/MapTableSettings'
        thumbnail_url:
          description: A static thumbnail image of the map
          nullable: true
          type: string
        title:
          type: string
        type:
          enum:
          - map
          type: string
        url:
          type: string
        viewer_permissions:
          $ref: '#/components/schemas/MapViewerPermissions'
        visited_at:
          format: date_time
          nullable: true
          type: string
      required:
      - id
      - type
      - url
      - title
      - thumbnail_url
      - created_at
      - visited_at
      - layers
      - layer_groups
      - elements
      - element_groups
      - project_id
      - public_access
      title: Map
      type: object
    LayerMetadata:
      additionalProperties: false
      properties:
        attribution_text:
          nullable: true
          type: string
        attribution_url:
          nullable: true
          type: string
        description:
          nullable: true
          type: string
        license:
          nullable: true
          type: string
        source_abbreviation:
          nullable: true
          type: string
        source_name:
          nullable: true
          type: string
        source_url:
          nullable: true
          type: string
        updated_at:
          example: '2025-03-24'
          format: date
          nullable: true
          type: string
      title: LayerMetadata
      type: object
    Layer:
      additionalProperties: false
      properties:
        attributes:
          description: List of the attributes on the layer
          items:
            properties:
              name:
                description: The name of the attribute
                type: string
              type:
                description: The type of the attribute
                enum:
                - INTEGER
                - REAL
                - TEXT
                - BOOLEAN
                - DATE
                - DATETIME
                - GEOMETRY
                type: string
            required:
            - name
            type: object
          nullable: true
          type: array
        caption:
          nullable: true
          type: string
        geometry_type:
          enum:
          - Line
          - Point
          - Polygon
          - Raster
          nullable: true
          type: string
        hide_from_legend:
          nullable: false
          type: boolean
        id:
          $ref: '#/components/schemas/FeltID'
        is_spreadsheet:
          nullable: true
          type: boolean
        last_refreshed_at:
          description: ISO 8601 timestamp of when the layer's data was last updated. This includes scheduled refreshes, manual refreshes, and direct feature edits.
          format: date-time
          nullable: true
          type: string
        legend_display:
          description: Controls how the layer is displayed in the legend.
          enum:
          - default
          - name_only
          nullable: true
          type: string
        legend_visibility:
          description: Controls whether or not the layer is displayed in the legend. Defaults to "show".
          enum:
          - hide
          - show
          nullable: true
          type: string
        links:
          properties:
            self:
              example: https://felt.com/api/v2/maps/V0dnOMOuTd9B9BOsL9C0UjmqC/layers/k441enUxQUOnZqc1ZvNsDA
              type: string
          type: object
        metadata:
          $ref: '#/components/schemas/LayerMetadata'
        name:
          nullable: false
          type: string
        next_refresh_at:
          description: ISO 8601 timestamp of when the next scheduled refresh will occur. Null if refresh is disabled or paused.
          format: date-time
          nullable: true
          type: string
        ordering_key:
          description: A sort order key used for ordering layers and layer groups in the legend
          nullable: true
          type: integer
        paused_reason:
          description: Why the layer's refresh is paused. Null when not paused.
          enum:
          - consecutive_failures
          nullable: true
          type: string
        progress:
          format: float
          nullable: false
          type: number
        refresh_period:
          enum:
          - 15 min
          - 30 min
          - hour
          - 3 hours
          - 6 hours
          - 12 hours
          - day
          - week
          - month
          - disabled
          type: string
        refresh_status:
          description: Whether scheduled refresh is active, paused (due to failures), or disabled
          enum:
          - active
          - paused
          - disabled
          type: string
        status:
          enum:
          - uploading
          - processing
          - failed
          - completed
          nullable: false
          type: string
        style:
          description: The Felt Style Language style for the layer
          type: object
        subtitle:
          deprecated: true
          description: 'Deprecated: use `caption` instead.'
          nullable: true
          type: string
        tile_url:
          description: The tile URL for this layer
          nullable: true
          type: string
        type:
          enum:
          - layer
          type: string
      required:
      - id
      - type
      - hide_from_legend
      - status
      - caption
      - name
      - progress
      - geometry_type
      - style
      - refresh_period
      - refresh_status
      title: Layer
      type: object
    NotFoundError:
      properties:
        errors:
          items:
            properties:
              detail:
                type: string
              source:
                properties:
                  parameter:
                    type: string
                type: object
              title:
                type: string
            type: object
          type: array
      title: NotFoundError
      type: object
    MapUpdateParams:
      additionalProperties: false
      properties:
        basemap:
          description: 'The basemap to use for the map. Defaults to "default". Valid values are "default", "light", "dark", "satellite", a valid raster tile URL with {x}, {y}, and {z} parameters, or a hex color string like #ff0000.'
          type: string
        description:
          description: A description to display in the map legend
          type: string
        public_access:
          description: The level of access to grant to the map. Defaults to "view_only".
          enum:
          - private
          - view_only
          - view_and_comment
          - view_comment_and_edit
          type: string
        table_settings:
          $ref: '#/components/schemas/MapTableSettings'
        title:
          description: The new title for the map
          type: string
        viewer_permissions:
          $ref: '#/components/schemas/MapViewerPermissions'
      title: MapUpdateParams
      type: object
    JsonErrorResponse:
      properties:
        errors:
          items:
            properties:
              detail:
                example: null value where string expected
                type: string
              source:
                properties:
                  pointer:
                    example: /data/attributes/petName
                    type: string
                required:
                - pointer
                type: object
              title:
                example: Invalid value
                type: string
            required:
            - title
            - source
            - detail
            type: object
          type: array
      required:
      - errors
      title: JsonErrorResponse
      type: object
    LayerGroup:
      additionalProperties: false
      properties:
        caption:
          nullable: true
          type: string
        id:
          $ref: '#/components/schemas/FeltID'
        layers:
          items:
            $ref: '#/components/schemas/Layer'
          type: array
        legend_visibility:
          description: Controls how the layer group is displayed in the legend. Defaults to "show".
          enum:
          - hide
          - show
          nullable: true
          type: string
        links:
          properties:
            self:
              example: https://felt.com/api/v2/maps/V0dnOMOuTd9B9BOsL9C0UjmqC/layer_groups/v13k4Ae9BRjCHHdPP5Fcm6D
              type: string
          type: object
        name:
          nullable: false
          type: string
        ordering_key:
          description: A sort order key used for ordering layers and layer groups in the legend
          nullable: false
          type: integer
        subtitle:
          deprecated: true
          description: 'Deprecated: use `caption` instead.'
          nullable: true
          type: string
        type:
          enum:
          - layer_group
          type: string
        visibility_interaction:
          description: Controls how the layer group is displayed in the legend. Defaults to `"default"`.
          enum:
          - default
          - slider
          - select
          - multi_select
          nullable: false
          type: string
      required:
      - id
      - type
      - name
      - caption
      - visibility_interaction
      - layers
      title: LayerGroup
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: YOUR_API_KEY
      scheme: bearer
      type: http