openapi: 3.0.0
info:
  description: Felt REST API v2.0
  title: Felt Comments Layer Library API
  version: '2.0'
servers:
- url: https://felt.com
  variables: {}
security: []
tags:
- description: 'With these APIs, you can publish your layers to your workspace library.

    '
  name: Layer Library
  x-page-description: APIs to publish layers
  x-page-icon: layer-group
  x-parent: Layers
paths:
  /api/v2/maps/{map_id}/layers/{layer_id}/publish:
    post:
      callbacks: {}
      description: Make a layer available in the workspace library for reuse by team members.
      operationId: publish_map_layer
      parameters:
      - description: The ID of the map where the layer is located
        in: path
        name: map_id
        required: true
        schema:
          type: string
      - description: The ID of the layer to publish
        in: path
        name: layer_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishLayerParams'
        description: Publish layer params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Layer'
          description: Publish layer response
        '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: Publish map layer
      tags:
      - Layer Library
  /api/v2/maps/{map_id}/layer_groups/{layer_group_id}/publish:
    post:
      callbacks: {}
      description: Make a layer group available in the workspace library for reuse by team members.
      operationId: publish_map_layer_group
      parameters:
      - description: The ID of the map where the layer group is located
        in: path
        name: map_id
        required: true
        schema:
          type: string
      - description: The ID of the layer group to publish
        in: path
        name: layer_group_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishLayerGroupParams'
        description: Publish layer group params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayerGroup'
          description: Publish layer group response
        '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: Publish map layer group
      tags:
      - Layer Library
  /api/v2/library:
    get:
      callbacks: {}
      description: 'List all layers in your workspace''s library, or the felt layer library.


        You can add a layer from the library to a map by using the "Duplicate layers" API endpoint (`POST /api/v2/duplicate_layers`) and the layer `id` provided by this endpoint.

        '
      operationId: list_library_layers
      parameters:
      - description: ''
        in: query
        name: source
        required: false
        schema:
          default: workspace
          description: Defaults to listing library layers for your "workspace". Use "felt" to list layers from the Felt data library. Use "all" to list layers from both sources.
          enum:
          - workspace
          - felt
          - all
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LayerLibrary'
          description: LayerLibrary
        '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: List library layers
      tags:
      - Layer Library
components:
  schemas:
    PublishLayerGroupParams:
      additionalProperties: false
      properties:
        name:
          description: The name to publish the layer group under
          example: My Layer
          type: string
      title: PublishLayerGroupParams
      type: object
    FeltID:
      example: luCHyMruTQ6ozGk3gPJfEB
      format: felt_id
      nullable: false
      title: FeltID
      type: string
    PublishLayerParams:
      additionalProperties: false
      properties:
        name:
          description: The name to publish the layer under
          example: My Layer
          type: string
      title: PublishLayerParams
      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
    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
    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
    LayerLibrary:
      properties:
        layer_groups:
          items:
            $ref: '#/components/schemas/LayerGroup'
          type: array
        layers:
          items:
            $ref: '#/components/schemas/Layer'
          type: array
        type:
          enum:
          - layer_library
          type: string
      required:
      - type
      - layers
      - layer_groups
      title: LayerLibrary
      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