---
title: "Toggle Favorite"
method: POST
path: "/api/v1/favorite/{project_id}/{feature_id}"
tags: ["favorite"]
---

# Toggle Favorite

`POST /api/v1/favorite/{project_id}/{feature_id}`

Toggle a row favorite. Returns the new favorited state.

The body is optional, and must stay so: ``deploy-full`` ships the client
before the API and a loaded tab keeps its old bundle indefinitely, so a
required body would 422 every favorite click in that tab until the user
happens to reload. It carries analytics context only and must never feed an
authorization decision — this route admits ``AccessLevel.READ`` callers.

## Path parameters

- `feature_id` string, required

## Request body

- FavoriteToggleContext — The exact first-party list context at the time of a favorite action.
  - `layer_id` string, uuid, nullable
  - `visible_feature_ids` string[], nullable
  - `row_position` integer, nullable
  - `position_source` 'grid_viewport' | 'server_cursor' | 'map_stack'
  - `total_rows` integer, nullable
  - `is_grouped` boolean, nullable
  - `sort_model` SortEntry[], nullable
    - `colId` string, required
    - `sort` 'asc' | 'desc', required
    - `sortMode` 'default' | 'null_push' | 'count', nullable
  - `filter_model` object, nullable
  - `show_favorites_only` boolean, nullable
  - `search_text` string, nullable
  - `geometry` GeoJSONPolygon — Narrow GeoJSON subset — matches the spatial-filter payload the frontend draws. Accept Polygon and MultiPolygon only; reject Point / LineString / feature collections, which ``ST_Intersects`` with a bbox wouldn't produce meaningful results against.
    - `type` 'Polygon' | 'MultiPolygon', required
    - `coordinates` unknown[], required
      - unknown
  - `comparison_scope` 'table_viewport' | 'map_stack' | 'navigation_neighbors' | 'unavailable'
  - `source` 'table_cell' | 'table_shortcut' | 'detail_panel', required
  - `session_id` string, nullable

## Response `200`

Successful Response

- FavoriteToggleResponse — The favorited state after the toggle.
  - `favorited` boolean, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-14** `ab171f3fcfbe` — 2 info
  - added optional request body
  - added the required property `favorited` to the response with the `200` status

[Change history](https://skmtc.dev/maia-analytics/apis/maia-api/changes/api/v1/favorite/:project_id/:feature_id/post.md)

---

[API](https://skmtc.dev/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.dev/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/maia-analytics/maia-api/revisions/4c1b045ef2af/schema)