Maia-analytics enrichment API
The enrichment API from Maia-analytics — 17 operation(s) for enrichment.
OpenAPI Specification
openapi: 3.1.0
info:
title: MAIA Ah enrichment API
description: API for MAIA application (migrated from Firebase)
version: 0.1.0
tags:
- name: enrichment
paths:
/api/v1/enrichment/limits:
get:
tags:
- enrichment
summary: Get Enrichment Limits
description: 'Per-batch limits for column-wide bulk enrichment.
Returns the canonical server values backing the column-header Enrich
submenu''s clamps and confirm gates. The FE should fetch these once and
cache; never carry its own copy of these constants.'
operationId: get_enrichment_limits_api_v1_enrichment_limits_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentLimitsResponse'
/api/v1/enrichment/all:
get:
tags:
- enrichment
summary: Get All Enrichments
description: "Get all custom enrichments.\nRequires authentication. Allows read access to owned or example projects.\n\nArgs:\n request: The request object containing project_id (pre-validated)\n enrichment_service: Service for handling enrichment operations\n\nReturns:\n List of all enrichments"
operationId: get_all_enrichments_api_v1_enrichment_all_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentListResponse'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/create:
post:
tags:
- enrichment
summary: Create Enrichment
description: "Create a new enrichment with default values. Requires layer ownership.\n\nArgs:\n request: The request object containing layer_id (pre-validated)\n enrichment_service: Service for handling enrichment operations\n\nReturns:\n Dictionary containing enrichment data"
operationId: create_enrichment_api_v1_enrichment_create_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEnrichmentRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/enrich_async/status_batch:
post:
tags:
- enrichment
summary: Get Enrichment Status Batch
description: Get the status of multiple enrichment workflows.
operationId: get_enrichment_status_batch_api_v1_enrichment_enrich_async_status_batch_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentStatusBatchRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentStatusListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/enrich_async/{enrichment_id}:
post:
tags:
- enrichment
summary: Enrich Row Async
description: "Enrich rows in the dataset asynchronously.\n\nSupports two selection modes (exactly one per request, enforced by\n``EnrichRowRequest`` validator):\n\n- ``feature_ids`` — explicit ids; legacy path, unchanged.\n- ``selection`` — filter spec + fingerprint + expected count. The\n server validates the fingerprint (400 on mismatch), recomputes the\n live count (409 on drift), and resolves the matching ids\n server-side before enqueueing — no wire-payload of large id\n arrays."
operationId: enrich_row_async_api_v1_enrichment_enrich_async__enrichment_id__post
security:
- FirebaseAuthMiddleware: []
parameters:
- name: token
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Firebase ID token for MVT authentication
title: Token
description: Firebase ID token for MVT authentication
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichRowRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentBatchStartResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/enrichment/{enrichment_id}:
put:
tags:
- enrichment
summary: Update Enrichment
description: "Update an enrichment. Requires ownership of the project containing the enrichment.\n\nThe mortgage entitlement check fetches the user profile lazily — only a\nretarget onto the mortgage tool pays the profile DB round-trip.\n\nArgs:\n enrichment_id: The ID of the enrichment to update (pre-validated)\n request: The request object containing updated fields\n enrichment_service: Service for handling enrichment operations\n\nReturns:\n Dictionary containing enrichment data"
operationId: update_enrichment_api_v1_enrichment__enrichment_id__put
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEnrichmentRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/delete:
post:
tags:
- enrichment
summary: Delete Enrichment
description: "Delete an enrichment. Requires ownership of the project containing the enrichment.\n\nArgs:\n request: The request object containing enrichment_id and project_id (pre-validated)\n enrichment_service: Service for handling enrichment operations\n\nReturns:\n Dict with success status and message"
operationId: delete_enrichment_api_v1_enrichment_delete_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentDelete'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentDeleteResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/workflow/status/{workflow_id}:
get:
tags:
- enrichment
summary: Get Enrichment Status
description: Get the status of a single enrichment workflow.
operationId: get_enrichment_status_api_v1_enrichment_workflow_status__workflow_id__get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workflow_id
in: path
required: true
schema:
type: string
title: Workflow Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/enrichment/agent_workflow/status/{workflow_id}:
get:
tags:
- enrichment
summary: Get Enrichment Agent Task Status
description: Get the status of an enrichment agent (creation/update) workflow.
operationId: get_enrichment_agent_task_status_api_v1_enrichment_agent_workflow_status__workflow_id__get
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workflow_id
in: path
required: true
schema:
type: string
title: Workflow Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentAgentStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/enrichment/all_user:
get:
tags:
- enrichment
summary: Get All User Enrichments
description: 'Get all enrichments.
Requires authentication.'
operationId: get_all_user_enrichments_api_v1_enrichment_all_user_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AllUserEnrichmentsResponse'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/add_to_layer:
post:
tags:
- enrichment
summary: Add Enrichment To Layer
description: "Add an enrichment to a layer. Requires ownership of the project containing the layer.\n\nArgs:\n request: The request object containing enrichment_id and layer_id (pre-validated)\n enrichment_service: Service for handling enrichment operations\n\nReturns:\n message with success status"
operationId: add_enrichment_to_layer_api_v1_enrichment_add_to_layer_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddEnrichmentToLayerRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AddEnrichmentToLayerResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/delete_from_library:
post:
tags:
- enrichment
summary: Delete Enrichment From Library
description: "Delete an enrichment.\nRequires authentication.\n\nArgs:\n request: The request object containing enrichment_id\n enrichment_service: Service for handling enrichment operations\n\nReturns:\n Dict with success status and message"
operationId: delete_enrichment_from_library_api_v1_enrichment_delete_from_library_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentDeleteFromLibraryRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentDeleteFromLibraryResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/credits:
get:
tags:
- enrichment
summary: Get Enrichment Credits
description: Get the number of enrichments credits available for this user.
operationId: get_enrichment_credits_api_v1_enrichment_credits_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EnrichmentCreditsResponse'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/in-flight/{project_id}:
get:
tags:
- enrichment
summary: Get In Flight Tasks
description: 'Get all in-flight enrichment workflows for a project.
Queries DBOS workflow status filtered to non-terminal row-enrichment
workflows and aggregates per-field for the polling UI.'
operationId: get_in_flight_tasks_api_v1_enrichment_in_flight__project_id__get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InFlightTasksResponse'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/in-flight:
get:
tags:
- enrichment
summary: Get All In Flight Tasks
description: Get all in-flight enrichment workflows across the user's projects.
operationId: get_all_in_flight_tasks_api_v1_enrichment_in_flight_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AllInFlightTasksResponse'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/cancel/bulk:
post:
tags:
- enrichment
summary: Cancel Enrichment Workflows Bulk
description: 'Bulk-cancel in-flight DBOS enrichment workflows.
Best-effort + idempotent, matching the single-cancel contract. Returns
204 unconditionally — workflows the caller doesn''t own, workflows
without a reservation row, and workflows already in a terminal state
are silently skipped. The FE''s column-level cancel sends every
workflow_id it tracked and relies on polling to converge each one to
REVOKED.'
operationId: cancel_enrichment_workflows_bulk_api_v1_enrichment_cancel_bulk_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkCancelEnrichmentRequest'
required: true
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- FirebaseAuthMiddleware: []
/api/v1/enrichment/cancel/{workflow_id}:
post:
tags:
- enrichment
summary: Cancel Enrichment Workflow
description: 'Cancel an in-flight DBOS enrichment workflow + refund any unsettled credits [MAIA-1468].
Returns 204 on success (idempotent on terminal states). 404 if the
workflow has no reservation row (Celery-routed enrichment or unknown ID)
or if the user doesn''t own the workspace it belongs to. Cross-workspace
access is 404 not 403 to avoid leaking workflow existence.
The ``_current_user`` Depends enforces authn; workspace authz is resolved
inside the service via the request-scoped ``UserService`` (already bound
to the current user via DI).'
operationId: cancel_enrichment_workflow_api_v1_enrichment_cancel__workflow_id__post
security:
- FirebaseAuthMiddleware: []
parameters:
- name: workflow_id
in: path
required: true
schema:
type: string
title: Workflow Id
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
InFlightTasksResponse:
properties:
tasks:
items:
$ref: '#/components/schemas/InFlightTaskResponse'
type: array
title: Tasks
description: List of in-flight tasks for the project
count:
type: integer
title: Count
description: Total number of in-flight tasks
batches:
items:
$ref: '#/components/schemas/BatchEnrichmentInfo'
type: array
title: Batches
description: Run-scoped progress per enrichment action (MAIA-2116)
totals_by_field:
additionalProperties:
type: integer
type: object
title: Totals By Field
description: 'DEPRECATED (MAIA-2116): rolling per-field totals; use `batches`'
field_info:
additionalProperties:
$ref: '#/components/schemas/FieldEnrichmentInfo'
type: object
title: Field Info
description: 'DEPRECATED (MAIA-2116): rolling per-field info; use `batches`'
type: object
required:
- tasks
- count
title: InFlightTasksResponse
description: Response schema for listing in-flight enrichment tasks.
AgeRange:
properties:
min:
anyOf:
- type: integer
- type: 'null'
title: Min
max:
anyOf:
- type: integer
- type: 'null'
title: Max
is_approximate:
type: boolean
title: Is Approximate
default: true
reasoning:
anyOf:
- type: string
- type: 'null'
title: Reasoning
description: The reasoning for the age range.
sources:
items:
type: string
type: array
title: Sources
description: The sources for the age range.
type: object
title: AgeRange
description: Age range from PDL. Can represent exact age (min == max) or range.
ResourceReference:
properties:
resource_type:
$ref: '#/components/schemas/ResourceType'
description: The type of resource
operation:
$ref: '#/components/schemas/ResourceOperation'
description: The operation that was performed on the resource
resource_id:
type: string
title: Resource Id
description: The ID of the resource
display_name:
type: string
title: Display Name
description: Display name for the resource
created_at:
anyOf:
- type: string
- type: 'null'
title: Created At
description: ISO timestamp when resource was created in this chat
feature_count:
anyOf:
- type: integer
- type: 'null'
title: Feature Count
description: Number of features in the created resource
task_id:
anyOf:
- type: string
- type: 'null'
title: Task Id
description: Celery task ID for async operations like deep research
type: object
required:
- resource_type
- operation
- resource_id
- display_name
title: ResourceReference
description: Reference to a resource created or modified during chat.
EnrichmentUpdates:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
description:
anyOf:
- type: string
- type: 'null'
title: Description
tool:
anyOf:
- type: string
- type: 'null'
title: Tool
params:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Params
dtype:
anyOf:
- type: string
enum:
- string
- float
- boolean
- list[str]
- jsonb
- int
- url
- type: string
const: categorical
- type: string
enum:
- ContactModel
- TenantLeaseConcise
- OwnerResidentialMailingAddress
- MortgageProfile
- type: 'null'
title: Dtype
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
type: object
title: EnrichmentUpdates
description: 'Schema for enrichment update fields.
This provides a structured representation of fields that can be updated.
Add specific fields here instead of using a generic Dict[str, Any].'
EnrichmentDeleteFromLibraryRequest:
properties:
enrichment_id:
type: string
format: uuid
title: Enrichment Id
examples:
- 00000000-0000-0000-0000-000000000001
type: object
required:
- enrichment_id
title: EnrichmentDeleteFromLibraryRequest
description: "Request schema for deleting an enrichment from the library.\n\nAttributes:\n enrichment_id: Unique identifier for the enrichment to delete"
EnrichmentStatusListResponse:
properties:
statuses:
items:
$ref: '#/components/schemas/EnrichmentStatusResponse'
type: array
title: Statuses
type: object
required:
- statuses
title: EnrichmentStatusListResponse
description: Response model for returning a list of enrichment task statuses.
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
OccupancyStatus:
type: string
enum:
- leased
- vacant
- owner_occupied
- partially_leased
- unknown
title: OccupancyStatus
PDLCompany:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
size:
anyOf:
- type: string
- type: 'null'
title: Size
id:
anyOf:
- type: string
- type: 'null'
title: Id
founded:
anyOf:
- type: integer
- type: 'null'
title: Founded
industry:
anyOf:
- type: string
- type: 'null'
title: Industry
location:
anyOf:
- $ref: '#/components/schemas/PDLLocation'
- type: 'null'
linkedin_url:
anyOf:
- type: string
- type: 'null'
title: Linkedin Url
linkedin_id:
anyOf:
- type: string
- type: 'null'
title: Linkedin Id
facebook_url:
anyOf:
- type: string
- type: 'null'
title: Facebook Url
twitter_url:
anyOf:
- type: string
- type: 'null'
title: Twitter Url
website:
anyOf:
- type: string
- type: 'null'
title: Website
type: object
title: PDLCompany
description: Company information from PDL.
PDLEducation:
properties:
school:
anyOf:
- $ref: '#/components/schemas/PDLSchool'
- type: 'null'
degrees:
items:
type: string
type: array
title: Degrees
majors:
items:
type: string
type: array
title: Majors
minors:
items:
type: string
type: array
title: Minors
start_date:
anyOf:
- type: string
- type: 'null'
title: Start Date
end_date:
anyOf:
- type: string
- type: 'null'
title: End Date
gpa:
anyOf:
- type: number
- type: 'null'
title: Gpa
type: object
title: PDLEducation
description: Education information from PDL.
TenantLeaseConcise:
properties:
tenant_legal_name:
anyOf:
- type: string
- type: 'null'
title: Tenant Legal Name
description: Tenant legal name or primary occupant name.
lease_start_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Lease Start Date
description: Lease commencement / tenant move-in date (if known).
lease_end_date:
anyOf:
- type: string
format: date
- type: 'null'
title: Lease End Date
description: Lease expiration date for the current in-place term.
in_place_rent_psf_yr:
anyOf:
- type: string
pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- type: 'null'
title: In Place Rent Psf Yr
description: $ / SF / Year current in-place base rent (net of abatements if possible).
expense_structure:
anyOf:
- $ref: '#/components/schemas/ExpenseStructure'
- type: 'null'
description: Expense pass-through structure (NNN, modified gross, etc.).
escalation_type:
anyOf:
- $ref: '#/components/schemas/LeaseEscalationType'
- type: 'null'
description: How base rent escalates (fixed %, CPI, hybrid, none).
occupancy_status:
anyOf:
- $ref: '#/components/schemas/OccupancyStatus'
- type: 'null'
description: Leased / Vacant / Owner-occupied / Partial / Unknown — good single filter.
num_tenants:
anyOf:
- type: integer
- type: 'null'
title: Num Tenants
description: Number of distinct tenants in the building (1 = single-tenant).
delinquency_status:
anyOf:
- type: string
- type: 'null'
title: Delinquency Status
description: Description of the tenant's delinquency status.
as_of:
type: string
format: date-time
title: As Of
description: UTC timestamp when this record was compiled/last updated.
type: object
title: TenantLeaseConcise
description: 'Concise tenant / lease model optimized for REIT screens.
Includes a small set of critical fields and computed helpers
(lease duration, months remaining, rent delta). Use `to_dict()`
to include derived values in output.'
EnrichmentAgentTaskPayload:
properties:
status:
type: string
title: Status
output_type:
type: string
title: Output Type
message:
anyOf:
- type: string
- type: 'null'
title: Message
resources:
anyOf:
- items:
$ref: '#/components/schemas/ResourceReference'
type: array
- type: 'null'
title: Resources
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
output:
anyOf:
- {}
- type: 'null'
title: Output
deep_research_timed_out:
type: boolean
title: Deep Research Timed Out
default: false
type: object
required:
- status
- output_type
title: EnrichmentAgentTaskPayload
description: Payload returned by the enrichment agent background task.
SSRTableQueryParams:
properties:
startRow:
type: integer
minimum: 0.0
title: Startrow
default: 0
endRow:
type: integer
exclusiveMinimum: 0.0
title: Endrow
default: 100
sortModel:
anyOf:
- items:
$ref: '#/components/schemas/SortEntry'
type: array
- type: 'null'
title: Sortmodel
filterModel:
anyOf:
- additionalProperties:
oneOf:
- $ref: '#/components/schemas/CompoundFilter-Input'
- oneOf:
- $ref: '#/components/schemas/TextCondition'
- $ref: '#/components/schemas/NumberCondition'
- $ref: '#/components/schemas/SetCondition'
- $ref: '#/components/schemas/DateCondition'
- $ref: '#/components/schemas/BooleanCondition'
discriminator:
propertyName: filterType
mapping:
boolean: '#/components/schemas/BooleanCondition'
date: '#/components/schemas/DateCondition'
number: '#/components/schemas/NumberCondition'
set: '#/components/schemas/SetCondition'
text: '#/components/schemas/TextCondition'
type: object
- type: 'null'
title: Filtermodel
filterId:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Filterid
groupKeys:
anyOf:
- items:
anyOf:
- type: string
- type: integer
- type: number
- type: boolean
- type: 'null'
type: array
- type: 'null'
title: Groupkeys
rowGroupCols:
anyOf:
- items:
$ref: '#/components/schemas/RowGroupCol'
type: array
- type: 'null'
title: Rowgroupcols
searchText:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Searchtext
geometry:
anyOf:
- $ref: '#/components/schemas/GeoJSONPolygon'
- type: 'null'
favoritesOnly:
type: boolean
title: Favoritesonly
default: false
type: object
title: SSRTableQueryParams
description: 'Combined query-param shape for the 5 AG-Grid SSR endpoints.
Aliases match AG Grid''s camelCase wire format (``startRow``, ``filterModel``, …)
so the client contract is unchanged. Handlers parse JSON-encoded query
strings into this model via the ``parse_ssr_query_params`` dep; any
validation failure surfaces as 422 with a field path.'
TextCondition:
properties:
filterType:
type: string
const: text
title: Filtertype
default: text
type:
type: string
enum:
- contains
- notContains
- equals
- notEqual
- startsWith
- endsWith
- blank
- notBlank
- unavailable
title: Type
filter:
anyOf:
- type: string
- type: 'null'
title: Filter
type: object
required:
- type
title: TextCondition
PDLSchool:
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
type:
anyOf:
- type: string
- type: 'null'
title: Type
id:
anyOf:
- type: string
- type: 'null'
title: Id
location:
anyOf:
- $ref: '#/components/schemas/PDLLocation'
- type: 'null'
linkedin_url:
anyOf:
- type: string
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/maia-analytics/refs/heads/main/openapi/maia-analytics-enrichment-api-openapi.yml