Maia-analytics share API
The share API from Maia-analytics — 17 operation(s) for share.
OpenAPI Specification
openapi: 3.1.0
info:
title: MAIA Ah share API
description: API for MAIA application (migrated from Firebase)
version: 0.1.0
tags:
- name: share
paths:
/api/v1/share/{share_token}:
get:
tags:
- share
summary: Get Shared Project
description: "Get metadata for a shared project (read-only, no side effects).\n\nThis is the primary entry point for shared project access. Validates\nthe share token and returns project metadata. View count tracking is\nhandled separately via POST /{share_token}/view.\n\nArgs:\n share: Validated ProjectShare from token (injected by validate_share_token)\n share_service: ProjectShareService for fetching project data\n\nReturns:\n Shared project metadata (subset of full project data)\n\nRaises:\n HTTPException: 404 if project not found"
operationId: get_shared_project_api_v1_share__share_token__get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SharedProjectResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/view:
post:
tags:
- share
summary: Track Share View
description: "Increment the view count for a shared project.\n\nCalled by the frontend once per browser session to track views.\nSeparated from the GET endpoint to avoid double-counting from\nReact StrictMode's double-mount cycle.\n\nArgs:\n share: Validated ProjectShare from token\n share_service: ProjectShareService for view count operations\n\nReturns:\n Success confirmation"
operationId: track_share_view_api_v1_share__share_token__view_post
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ShareViewResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers:
get:
tags:
- share
summary: Get Shared Project Layers
description: "Get all layers for a shared project.\n\nArgs:\n share: Validated ProjectShare from token\n layer_service: Service for fetching layer data\n\nReturns:\n List of layers in API format (excludes soft-deleted and\n parcel-restricted layers)"
operationId: get_shared_project_layers_api_v1_share__share_token__layers_get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LayerModel'
title: Response Get Shared Project Layers Api V1 Share Share Token Layers Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/enrichments:
get:
tags:
- share
summary: Get Shared Project Enrichments
description: "Get enrichment metadata for a shared project (slim, read-only).\n\nReturns only the fields needed for column mapping (id, name, layer_id,\nis_data_source, dtype). Excludes sensitive fields like params, tool,\nand description. Enrichments on share-restricted (parcel) layers are\ndropped — the layer is hidden, so its enrichment metadata must be too.\n\nArgs:\n share: Validated ProjectShare from token\n enrichment_repo: Repository for fetching enrichment data\n layer_service: Service resolving which layers are share-restricted\n\nReturns:\n Slim enrichment metadata for visible enrichments on non-restricted layers"
operationId: get_shared_project_enrichments_api_v1_share__share_token__enrichments_get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SharedEnrichmentListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/filters:
post:
tags:
- share
summary: Create Shared Filter Spec
description: 'Share-mode twin of ``POST /filters`` — anonymous viewers create the
FilterSpec their tile / paginated / count requests will dereference.
Without this, share-mode clients had no path to a ``filter_id``: the
authed ``POST /filters`` blocks on Firebase auth that share viewers don''t
have, so polygon and column filters never synced to map tiles on shared
dashboards. ``favoritesOnly`` is rejected up front — share mode has no
user identity to resolve favorites against (matches
``_reject_favorites_in_share_mode``).'
operationId: create_shared_filter_spec_api_v1_share__share_token__filters_post
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FilterSpecRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FilterSpecResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/tiles/{z}/{x}/{y}.pbf:
get:
tags:
- share
summary: Get Shared Layer Mvt Tile
description: 'Serve an MVT tile for a layer in a shared project (anonymous access).
``filter_id`` references a server-side FilterSpec; when present, the
tile contains only matching rows. ``viz`` is the share-mode twin of the
authed tile endpoint''s param — it names a layer column to embed so
classed styling has values below the include-all zoom.'
operationId: get_shared_layer_mvt_tile_api_v1_share__share_token__layers__layer_id__tiles__z___x___y__pbf_get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: z
in: path
required: true
schema:
type: integer
title: Z
- name: x
in: path
required: true
schema:
type: integer
title: X
- name: y
in: path
required: true
schema:
type: integer
title: Y
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
- name: v
in: query
required: false
schema:
type: string
default: '0'
title: V
- name: filter_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Filter Id
- name: viz
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Viz
responses:
'200':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/agg-tiles/{z}/{x}/{y}.pbf:
get:
tags:
- share
summary: Get Shared Layer Mvt Agg Tile
description: 'Serve an aggregate MVT tile for a layer in a shared project.
``filter_id`` — share-mode twin of the auth-side agg-tile endpoint;
counts only matching rows when present.'
operationId: get_shared_layer_mvt_agg_tile_api_v1_share__share_token__layers__layer_id__agg_tiles__z___x___y__pbf_get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: z
in: path
required: true
schema:
type: integer
title: Z
- name: x
in: path
required: true
schema:
type: integer
title: X
- name: y
in: path
required: true
schema:
type: integer
title: Y
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
- name: v
in: query
required: false
schema:
type: string
default: '0'
title: V
- name: filter_id
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Filter Id
responses:
'200':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/viz-stats:
get:
tags:
- share
summary: Get Shared Layer Viz Stats
description: 'Share-mode twin of ``GET /map/{layer_id}/viz-stats``.
Shared views persist ``layerViz``, so anonymous viewers need the same
whole-layer quantile breaks that drive classed styling for the owner.'
operationId: get_shared_layer_viz_stats_api_v1_share__share_token__layers__layer_id__viz_stats_get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
- name: column
in: query
required: true
schema:
type: string
maxLength: 200
title: Column
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LayerVizStatsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/extent:
get:
tags:
- share
summary: Get Shared Layer Extent
description: Bounding box of a shared layer's features (anonymous access).
operationId: get_shared_layer_extent_api_v1_share__share_token__layers__layer_id__extent_get
parameters:
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: searchText
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Searchtext
- name: filterModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Filtermodel
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LayerExtentResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/feature/{feature_id}:
get:
tags:
- share
summary: Get Shared Feature Detail
description: Full properties + GeoJSON geometry for a single feature in a shared layer.
operationId: get_shared_feature_detail_api_v1_share__share_token__layers__layer_id__feature__feature_id__get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: feature_id
in: path
required: true
schema:
type: string
title: Feature Id
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/features/paginated:
get:
tags:
- share
summary: Get Shared Layer Features Paginated
description: 'Share-scoped AG Grid SSR paginated features. Mirrors the authenticated
path in ``table_handlers.get_layer_features_paginated`` but guards with the
share token + verifies the layer belongs to the shared project.'
operationId: get_shared_layer_features_paginated_api_v1_share__share_token__layers__layer_id__features_paginated_get
parameters:
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: startRow
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
default: 0
title: Startrow
- name: endRow
in: query
required: false
schema:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
default: 100
title: Endrow
- name: sortModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Sortmodel
- name: filterModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Filtermodel
- name: filterId
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Filterid
- name: groupKeys
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Groupkeys
- name: rowGroupCols
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Rowgroupcols
- name: searchText
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Searchtext
- name: geometry
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Geometry
- name: favoritesOnly
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
default: false
title: Favoritesonly
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedFeaturesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/features/filtered-ids:
get:
tags:
- share
summary: Get Shared Layer Filtered Ids
description: 'Share-scoped feature ids matching the current filter set.
Mirrors ``table_handlers.get_layer_filtered_ids`` but guards with the
share token + verifies the layer belongs to the shared project. Powers
map-filter sync and spatial polygon filtering on shared dashboards.'
operationId: get_shared_layer_filtered_ids_api_v1_share__share_token__layers__layer_id__features_filtered_ids_get
parameters:
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: enrichmentState
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 32
- type: 'null'
title: Enrichmentstate
- name: enrichmentName
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Enrichmentname
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500000
minimum: 1
default: 100000
title: Limit
- name: startRow
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
default: 0
title: Startrow
- name: endRow
in: query
required: false
schema:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
default: 100
title: Endrow
- name: sortModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Sortmodel
- name: filterModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Filtermodel
- name: filterId
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Filterid
- name: groupKeys
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Groupkeys
- name: rowGroupCols
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Rowgroupcols
- name: searchText
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Searchtext
- name: geometry
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Geometry
- name: favoritesOnly
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
default: false
title: Favoritesonly
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FilteredIdsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/features/filtered-count:
get:
tags:
- share
summary: Get Shared Layer Filtered Count
description: 'Share-scoped total row count matching the current filter set.
Mirrors ``table_handlers.get_layer_filtered_count`` but guards with the
share token + verifies the layer belongs to the shared project.'
operationId: get_shared_layer_filtered_count_api_v1_share__share_token__layers__layer_id__features_filtered_count_get
parameters:
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: enrichmentState
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 32
- type: 'null'
title: Enrichmentstate
- name: enrichmentName
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Enrichmentname
- name: startRow
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
default: 0
title: Startrow
- name: endRow
in: query
required: false
schema:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
default: 100
title: Endrow
- name: sortModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Sortmodel
- name: filterModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Filtermodel
- name: filterId
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Filterid
- name: groupKeys
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Groupkeys
- name: rowGroupCols
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Rowgroupcols
- name: searchText
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Searchtext
- name: geometry
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Geometry
- name: favoritesOnly
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
default: false
title: Favoritesonly
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FilteredCountResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/features/navigate:
get:
tags:
- share
summary: Get Shared Layer Navigate
description: 'Share-scoped prev/next cursor for shared dashboards. Mirrors
``table_handlers.navigate_layer_feature`` — single CTE per call,
cap-free up to whatever the filtered set contains.'
operationId: get_shared_layer_navigate_api_v1_share__share_token__layers__layer_id__features_navigate_get
parameters:
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: currentId
in: query
required: true
schema:
type: string
minLength: 1
title: Currentid
- name: wrap
in: query
required: false
schema:
type: boolean
default: true
title: Wrap
- name: enrichmentState
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 32
- type: 'null'
title: Enrichmentstate
- name: enrichmentName
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Enrichmentname
- name: startRow
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
default: 0
title: Startrow
- name: endRow
in: query
required: false
schema:
anyOf:
- type: integer
exclusiveMinimum: 0
- type: 'null'
default: 100
title: Endrow
- name: sortModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Sortmodel
- name: filterModel
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Filtermodel
- name: filterId
in: query
required: false
schema:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Filterid
- name: groupKeys
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Groupkeys
- name: rowGroupCols
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Rowgroupcols
- name: searchText
in: query
required: false
schema:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Searchtext
- name: geometry
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Geometry
- name: favoritesOnly
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
default: false
title: Favoritesonly
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/NavigateCursorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/layers/{layer_id}/columns:
get:
tags:
- share
summary: Get Shared Layer Columns Metadata
description: 'Share-scoped column metadata + aggregate stats. Mirrors
``table_handlers.get_layer_columns_metadata`` with a share-token guard.'
operationId: get_shared_layer_columns_metadata_api_v1_share__share_token__layers__layer_id__columns_get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
- name: layer_id
in: path
required: true
schema:
type: string
format: uuid
title: Layer Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ColumnsMetadataResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/views:
get:
tags:
- share
summary: Get Shared Project Views
description: "Get all views for a shared project.\n\nPer-view state is keyed by layer id (filters, column visibility/order,\nlayer visibility), so state for share-restricted (parcel) layers is\nstripped from each view — otherwise a shared view leaks the parcel\nlayer's column keys and the user's filter values even though the layer\nis omitted from the shared layer list.\n\nArgs:\n share: Validated ProjectShare from token\n share_service: ProjectShareService for fetching view data\n layer_service: Service resolving which layers are share-restricted\n\nReturns:\n List of views with filters converted to client display units\n\nRaises:\n HTTPException: 404 if project not found"
operationId: get_shared_project_views_api_v1_share__share_token__views_get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ViewsGetResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/share/{share_token}/chats:
get:
tags:
- share
summary: Get Shared Project Chats
description: "Get chat history for a shared project (read-only).\n\nStructured tool data IS stripped: tool-call and tool-return parts (e.g.\nquery_sql parcel rows persisted as ToolReturnParts) are removed before the\npayload reaches the anonymous share wire. Only prose is not stripped —\nassistant natural-language messages are preserved, because scanning free-form\nconversation for incidental parcel mentions would mean parsing LLM text,\nunreliable and out of this restriction's scope.\n\nArgs:\n share: Validated ProjectShare from token\n share_service: ProjectShareService for fetching chat data\n\nReturns:\n Chat history with system instructions stripped, or None if no chat exists"
operationId: get_shared_project_chats_api_v1_share__share_token__chats_get
parameters:
- name: share_token
in: path
required: true
schema:
type: string
title: Share Token
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatHistoryResponseSchema'
'422':
description: Validation E
# --- truncated at 32 KB (130 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maia-analytics/refs/heads/main/openapi/maia-analytics-share-api-openapi.yml