Maia-analytics workspaces API
The workspaces API from Maia-analytics — 18 operation(s) for workspaces.
The workspaces API from Maia-analytics — 18 operation(s) for workspaces.
openapi: 3.1.0
info:
title: MAIA Ah workspaces API
description: API for MAIA application (migrated from Firebase)
version: 0.1.0
tags:
- name: workspaces
paths:
/api/v1/internal/workspaces/:
get:
tags:
- workspaces
summary: List Workspaces
description: List all workspaces with member counts and credit info.
operationId: list_workspaces_api_v1_internal_workspaces__get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceListResponse'
security:
- FirebaseAuthMiddleware: []
/api/v1/internal/workspaces/available-counties:
get:
tags:
- workspaces
summary: List All Available Counties
description: 'Return every coverage-supported county in GCS (workspace-agnostic).
Source for the create-workspace picker, which runs before a workspace
exists. The per-workspace `GET /{workspace_id}/available-counties` reuses
the same gate minus already-loaded counties.'
operationId: list_all_available_counties_api_v1_internal_workspaces_available_counties_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/AvailableCountyResponse'
type: array
title: Response List All Available Counties Api V1 Internal Workspaces Available Counties Get
security:
- FirebaseAuthMiddleware: []
/api/v1/internal/workspaces/provision:
post:
tags:
- workspaces
summary: Provision Workspace
description: 'Provision a new workspace end-to-end with a Neon sandbox + counties.
Replaces the legacy bare-create `POST /`. A workspace with no loaded
counties has zero geographic query access, so provisioning is the only
sanctioned create path. Seeds the `workspace_counties` rows as `loading`
and fires the `stand_up_workspace` Dagster job. Returns once the rows
are persisted (5-15s for Neon create); county data loads asynchronously
thereafter.'
operationId: provision_workspace_api_v1_internal_workspaces_provision_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceProvisionRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- FirebaseAuthMiddleware: []
/api/v1/internal/workspaces/{workspace_id}:
get:
tags:
- workspaces
summary: Get Workspace Detail
description: Get detailed workspace information including members.
operationId: get_workspace_detail_api_v1_internal_workspaces__workspace_id__get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- workspaces
summary: Update Workspace
description: Update workspace fields.
operationId: update_workspace_api_v1_internal_workspaces__workspace_id__patch
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceUpdateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/projects:
get:
tags:
- workspaces
summary: List Workspace Projects
description: List all created projects in a workspace, annotated with lock status.
operationId: list_workspace_projects_api_v1_internal_workspaces__workspace_id__projects_get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminProjectListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/credits:
get:
tags:
- workspaces
summary: Get Workspace Credits
description: Get credit summary with per-user breakdown.
operationId: get_workspace_credits_api_v1_internal_workspaces__workspace_id__credits_get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminCreditsSummaryResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/credits/add:
post:
tags:
- workspaces
summary: Add Workspace Credits
description: Add enrichment credits to a workspace.
operationId: add_workspace_credits_api_v1_internal_workspaces__workspace_id__credits_add_post
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdminAddCreditsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/credits/set:
post:
tags:
- workspaces
summary: Set Workspace Credits
description: Set available enrichment credits to an exact value.
operationId: set_workspace_credits_api_v1_internal_workspaces__workspace_id__credits_set_post
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AdminSetCreditsRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/credits/reset:
post:
tags:
- workspaces
summary: Reset Workspace Credits
description: Reset used enrichment credits for workspace and all members.
operationId: reset_workspace_credits_api_v1_internal_workspaces__workspace_id__credits_reset_post
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/suspend:
post:
tags:
- workspaces
summary: Suspend Workspace
description: Suspend a workspace, blocking all members from logging in.
operationId: suspend_workspace_api_v1_internal_workspaces__workspace_id__suspend_post
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/unsuspend:
post:
tags:
- workspaces
summary: Unsuspend Workspace
description: Restore login access for a suspended workspace.
operationId: unsuspend_workspace_api_v1_internal_workspaces__workspace_id__unsuspend_post
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminWorkspaceDetailResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/credits/history:
get:
tags:
- workspaces
summary: Get Workspace Credits History
description: Get credit change history from the audit log.
operationId: get_workspace_credits_history_api_v1_internal_workspaces__workspace_id__credits_history_get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: limit
in: query
required: false
schema:
type: integer
maximum: 100
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdminAuditLogListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/retell-config:
get:
tags:
- workspaces
summary: Get Retell Config
description: 'Read the workspace''s Retell config + auto-dial gate.
Secrets returned masked (last 4 only). Internal admin only — workspace
admins do not manage Retell config themselves; MAIA staff onboard a
workspace by setting agent IDs/creds + flipping `auto_dial_enabled`.'
operationId: get_retell_config_api_v1_internal_workspaces__workspace_id__retell_config_get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RetellConfigResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- workspaces
summary: Update Retell Config
description: 'Update Retell config and/or flip the auto-dial gate. Admin-only,
audit-logged. Pass an explicit `null` to clear an override; omit a
field to leave it untouched.'
operationId: update_retell_config_api_v1_internal_workspaces__workspace_id__retell_config_patch
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RetellConfigUpdateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RetellConfigResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/feature-toggles:
get:
tags:
- workspaces
summary: Get Feature Toggles
description: 'List every governable feature toggle with its effective state, override
flag, and inherited global default for the workspace. Internal admin only.'
operationId: get_feature_toggles_api_v1_internal_workspaces__workspace_id__feature_toggles_get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureTogglesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
patch:
tags:
- workspaces
summary: Update Feature Toggle
description: 'Set one per-workspace override. Admin-only, audit-logged.
An unregistered key is rejected with 422.'
operationId: update_feature_toggle_api_v1_internal_workspaces__workspace_id__feature_toggles_patch
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureToggleUpdateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureTogglesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/feature-toggles/{key}:
delete:
tags:
- workspaces
summary: Clear Feature Toggle Override
description: 'Clear one per-workspace override so it inherits the global default.
Admin-only, audit-logged. An unregistered key is rejected with 422.'
operationId: clear_feature_toggle_override_api_v1_internal_workspaces__workspace_id__feature_toggles__key__delete
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: key
in: path
required: true
schema:
type: string
title: Key
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FeatureTogglesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/counties:
get:
tags:
- workspaces
summary: List Workspace Counties
description: Return per-county sandbox load state for the workspace.
operationId: list_workspace_counties_api_v1_internal_workspaces__workspace_id__counties_get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/WorkspaceCountyResponse'
title: Response List Workspace Counties Api V1 Internal Workspaces Workspace Id Counties Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
tags:
- workspaces
summary: Append Workspace County
description: 'Insert a single pending `workspace_counties` row.
The env-matched `workspace_county_pickup_{staging,prod}` Dagster sensor
picks the row up on its next tick (≤30s typical), registers the
partition, launches `sandbox_load`, and the run-status callbacks stamp
completion back. `workspace_counties` is the single source of truth for
workspace RBAC — `WorkspaceCountyRepository.get_loaded_fips` reads it
directly.'
operationId: append_workspace_county_api_v1_internal_workspaces__workspace_id__counties_post
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AppendCountyRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WorkspaceCountyResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/available-counties:
get:
tags:
- workspaces
summary: List Available Counties
description: Return GCS-known counties not yet loaded for this workspace.
operationId: list_available_counties_api_v1_internal_workspaces__workspace_id__available_counties_get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AvailableCountyResponse'
title: Response List Available Counties Api V1 Internal Workspaces Workspace Id Available Counties Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/internal/workspaces/{workspace_id}/counties/{county_id}:
delete:
tags:
- workspaces
summary: Remove Workspace County
description: 'Revoke RBAC access to a county and remove its tracker row.
Does NOT drop the loaded sandbox data — the partition stays in the
workspace''s Neon branch so a re-add is idempotent (re-add still runs
the loader from scratch, the sandbox infra just doesn''t need to be
re-provisioned).'
operationId: remove_workspace_county_api_v1_internal_workspaces__workspace_id__counties__county_id__delete
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: county_id
in: path
required: true
schema:
type: string
format: uuid
title: County Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
WorkspaceCountySelection:
properties:
state_fips:
type: string
maxLength: 2
minLength: 2
pattern: ^\d{2}$
title: State Fips
county_fips:
type: string
maxLength: 3
minLength: 3
pattern: ^\d{3}$
title: County Fips
additionalProperties: false
type: object
required:
- state_fips
- county_fips
title: WorkspaceCountySelection
description: 'One county selection — FIPS-shape only.
Used by the append-county and workspace-provisioning request bodies.
Callers supply ``state_fips`` (2-digit) + ``county_fips`` (3-digit) only.
``extra="forbid"`` rejects callers still constructing slug-shape kwargs
with 422 rather than silently dropping the slug pair.
The handler resolves the FIPS pair to a USPS state code before calling
the service (the ``workspace_counties.state`` column is USPS, not
numeric FIPS).'
AdminWorkspaceDetailResponse:
properties:
id:
type: string
format: uuid
title: Id
name:
type: string
title: Name
avatar_color:
anyOf:
- type: string
- type: 'null'
title: Avatar Color
available_enrichment_credits:
type: integer
title: Available Enrichment Credits
used_enrichment_credits:
type: integer
title: Used Enrichment Credits
remaining_credits:
type: integer
title: Remaining Credits
is_suspended:
type: boolean
title: Is Suspended
member_count:
type: integer
title: Member Count
project_count:
type: integer
title: Project Count
members:
items:
$ref: '#/components/schemas/AdminWorkspaceMemberItem'
type: array
title: Members
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
type: object
required:
- id
- name
- avatar_color
- available_enrichment_credits
- used_enrichment_credits
- remaining_credits
- is_suspended
- member_count
- project_count
- members
- created_at
- updated_at
title: AdminWorkspaceDetailResponse
description: Full workspace detail response for admin view.
AdminCreditUserUsageItem:
properties:
user_id:
type: string
format: uuid
title: User Id
display_name:
anyOf:
- type: string
- type: 'null'
title: Display Name
email:
type: string
title: Email
used_enrichment_credits:
type: integer
title: Used Enrichment Credits
type: object
required:
- user_id
- display_name
- email
- used_enrichment_credits
title: AdminCreditUserUsageItem
description: Per-user credit usage in a workspace.
AdminAuditLogResponse:
properties:
id:
type: string
format: uuid
title: Id
admin_user_id:
type: string
format: uuid
title: Admin User Id
admin_email:
anyOf:
- type: string
- type: 'null'
title: Admin Email
action:
type: string
title: Action
target_type:
type: string
title: Target Type
target_id:
type: string
format: uuid
title: Target Id
target_display_name:
anyOf:
- type: string
- type: 'null'
title: Target Display Name
before_value:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Before Value
after_value:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: After Value
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
created_at:
type: string
format: date-time
title: Created At
type: object
required:
- id
- admin_user_id
- admin_email
- action
- target_type
- target_id
- target_display_name
- before_value
- after_value
- metadata
- created_at
title: AdminAuditLogResponse
description: Response schema for a single audit log entry.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
AdminWorkspaceProvisionRequest:
properties:
name:
type: string
maxLength: 255
minLength: 1
title: Name
counties:
items:
$ref: '#/components/schemas/WorkspaceCountySelection'
type: array
title: Counties
initial_credits:
type: integer
minimum: 0.0
title: Initial Credits
default: 5000
region_id:
anyOf:
- type: string
- type: 'null'
title: Region Id
additionalProperties: false
type: object
required:
- name
- counties
title: AdminWorkspaceProvisionRequest
description: 'Request body for provisioning a new workspace end-to-end.
Wraps `AdminWorkspaceService.provision_workspace_with_counties`: creates
the Neon sandbox and seeds `workspace_counties` rows. At least one county
is mandatory — a workspace with no loaded counties has zero geographic
query access. Rejects unknown fields with 422.
`counties` non-emptiness and in-list duplicates are validated in the
service (400) rather than here, so the same guard covers the script caller
(`scripts/provision_prod_admin_workspace.py`) and the error is a 400, not a
422, matching the rest of the provisioning contract.'
AppendCountyRequest:
properties:
state_fips:
type: string
maxLength: 2
minLength: 2
pattern: ^\d{2}$
title: State Fips
county_fips:
type: string
maxLength: 3
minLength: 3
pattern: ^\d{3}$
title: County Fips
additionalProperties: false
type: object
required:
- state_fips
- county_fips
title: AppendCountyRequest
description: Request body for appending one county to an existing workspace sandbox.
FeatureToggleUpdateRequest:
properties:
key:
type: string
minLength: 1
title: Key
enabled:
type: boolean
title: Enabled
additionalProperties: false
type: object
required:
- key
- enabled
title: FeatureToggleUpdateRequest
description: Request to flip a single feature toggle for a workspace.
AdminProjectListItem:
properties:
id:
type: string
format: uuid
title: Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
status:
type: string
title: Status
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
owner_display_name:
anyOf:
- type: string
- type: 'null'
title: Owner Display Name
is_locked:
type: boolean
title: Is Locked
default: false
locked_by_display_name:
anyOf:
- type: string
- type: 'null'
title: Locked By Display Name
type: object
required:
- id
- name
- status
- created_at
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maia-analytics/refs/heads/main/openapi/maia-analytics-workspaces-api-openapi.yml