> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.
# List AI-generated suggestions
>
This endpoint requires **Organization Admin** permissions.
Lists AI-generated suggestions for a shared model. Suggestions can be filtered by status and are returned with keyset-based pagination.
Suggestions are sorted by priority, creation date, and ID for stable pagination.
## OpenAPI
````yaml /api/openapi.yaml get /v1/models/{modelId}/suggestions
openapi: 3.1.0
info:
title: Omni API
description: >
The Omni REST API provides programmatic access to your Omni instance for
managing users, documents, queries, schedules, and more.
version: 1.0.0
contact:
name: Omni Support
url: https://docs.omni.co
servers:
- url: https://{instance}.omniapp.co/api
description: Production
variables:
instance:
default: blobsrus
description: Your production Omni instance subdomain
- url: https://{instance}.playground.exploreomni.dev/api
description: Playground
variables:
instance:
default: blobsrus
description: Your playground Omni instance subdomain
security:
- bearerAuth: []
- orgApiKey: []
tags:
- name: Who Am I
description: Inspect your own user permissions
- name: AI
description: AI-powered query generation
- name: AI Credit Controls
description: Manage organization-level AI credit usage
- name: AI Eval
description: >-
AI evaluation: manage prompt sets and runs used to score AI quality
against curated prompt suites.
- name: AI Model Suggestions
description: Manage AI-generated suggestions for shared models
- name: AI Routines
description: >-
Manage AI Routines: schedule recurring AI-powered tasks to run
automatically on your data.
- name: Documents v2
description: >
A draft-based workflow for creating and editing documents: create a
document, patch a draft, then publish. Replaces the one-shot `PUT`/`PATCH`
v1 document write endpoints.
- name: Documents
description: Create, retrieve, and manage documents
- name: API Tokens
description: >-
Manage API tokens (Organization keys, Personal Access Tokens, MCP OAuth
grants)
- name: Connections
description: Manage database connections
- name: Connection environments
description: Manage connection environments database connections
- name: Content
description: Unified content retrieval (documents and folders)
- name: Content migration
description: Export and import dashboards
- name: Content validator
description: Validate content against models and perform find/replace operations
- name: Dashboard downloads
description: Download dashboards and tiles as PDF, PNG, XLSX, CSV, or JSON files
- name: Dashboard filters and controls
description: Read and update dashboard filter and control default values
- name: dbt
description: Manage dbt configuration for connections
- name: Document favorites
description: Favorite and unfavorite documents
- name: Document labels
description: Apply and manage labels on documents
- name: Document permissions
description: Manage document-level access
- name: Labels
description: >
Manage labels in an organization. Labels can be applied to documents and
folders to help organize and categorize content.
**Label types:**
- **Basic labels**: Can be created and managed by any user
- **Verified labels**: Indicate curated or officially sanctioned content.
Admin-only.
- **Homepage labels**: Appear on the organization homepage. Admin-only.
- name: Folders
description: Create and organize content folders
- name: Folder permissions
description: Manage folder-level access
- name: Jobs
description: Check status of asynchronous jobs
- name: Models
description: Create and manage data models
- name: Model branches
description: Manage model branches and merge changes
- name: Model git configuration
description: Manage git configuration for shared models
- name: Queries
description: Execute workbook queries
- name: Schedules
description: Create and manage scheduled tasks
- name: Schedule recipients
description: Manage schedule recipients
- name: Schema refresh schedules
description: Manage automated schema refresh schedules for connections
- name: Topics
description: Retrieve topic information from models
- name: Uploads
description: Manage file uploads
- name: Users
description: Manage users
- name: User attributes
description: Manage user attribute definitions
- name: User groups
description: Manage user groups
- name: User model roles
description: Manage model and connection role assignments for users
- name: User group model roles
description: Manage model and connection role assignments for user groups
- name: Uploads
description: Manage CSV and spreadsheet uploads
paths:
/v1/models/{modelId}/suggestions:
get:
tags:
- AI Model Suggestions
summary: List AI-generated suggestions
description: >
This endpoint requires **Organization Admin** permissions.
Lists AI-generated suggestions for a shared model. Suggestions can be
filtered by status and are returned with keyset-based pagination.
Suggestions are sorted by priority, creation date, and ID for stable
pagination.
operationId: listModelSuggestions
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: The ID of the shared model to list suggestions for.
- name: status
in: query
schema:
type: string
enum:
- active
- ignored
- all
default: active
description: |
Filter suggestions by status:
- `active` - Only active suggestions (default)
- `ignored` - Only ignored suggestions
- `all` - All suggestions regardless of status
- name: cursor
in: query
schema:
type: string
description: >-
Cursor for keyset-based pagination. Use the `id` from the last
suggestion in the previous page.
- name: pageSize
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 25
description: >-
Number of suggestions to return per page. Defaults to 25, maximum
100.
responses:
'200':
description: List of suggestions for the model
content:
application/json:
schema:
type: object
required:
- records
- pageInfo
properties:
records:
type: array
description: List of AI-generated suggestions
items:
$ref: '#/components/schemas/ModelSuggestion'
pageInfo:
$ref: '#/components/schemas/PageInfo'
example:
records:
- id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
category: missing_context
title: Document the orders view
rationale: >-
Users frequently ask what `status` means; documenting the
view in ai_context improves AI answers.
priority: 1
proposedChanges:
kind: context_edits
edits:
- field: ai_context
target: views.orders
value: The orders view contains one row per customer order.
evidence:
- type: ai_chat
chatAiSessionId: a1b2c3d4-5717-4562-b3fc-2c963f66afa6
capturedAt: '2026-06-24T09:12:33Z'
ignoreReason: null
ignoredAt: null
ignoredBy: null
aiModifiedAt: '2026-06-25T16:10:58Z'
createdAt: '2026-06-25T16:10:58Z'
updatedAt: '2026-06-25T16:10:58Z'
- id: b2c3d4e5-6717-4562-b3fc-2c963f66afa6
category: missing_context
title: Clarify the revenue measure
rationale: >-
The revenue measure lacks a description, leading to
ambiguous AI responses.
priority: 3
proposedChanges:
kind: context_edits
edits:
- field: ai_context
target: views.orders.fields.revenue
value: >-
Revenue is recognized at order completion, net of
refunds.
evidence: []
ignoreReason: null
ignoredAt: null
ignoredBy: null
aiModifiedAt: '2026-06-24T11:05:00Z'
createdAt: '2026-06-24T11:05:00Z'
updatedAt: '2026-06-24T11:05:00Z'
pageInfo:
hasNextPage: true
nextCursor: b2c3d4e5-6717-4562-b3fc-2c963f66afa6
pageSize: 25
totalRecords: 47
'400':
description: |
Bad Request
Possible error messages:
- `Invalid cursor value`
- `modelId: Invalid UUID`
- `pageSize must be between 1 and 100`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: 'Bad Request: Invalid cursor value'
status: 400
'401':
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: |
Forbidden. Possible causes:
- Requesting user lacks Organization Admin permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: 'Forbidden: Organization admin permission required'
status: 403
'404':
description: |
Not Found
Possible error messages:
- `Shared model with id does not exist`
- `Model not found or not accessible`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: >-
Shared model with id 550e8400-e29b-41d4-a716-446655440000 does
not exist
status: 404
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- bearerAuth: []
components:
schemas:
ModelSuggestion:
type: object
required:
- id
- category
- title
- rationale
- priority
- proposedChanges
- evidence
- ignoreReason
- ignoredAt
- ignoredBy
- aiModifiedAt
- createdAt
- updatedAt
properties:
id:
type: string
format: uuid
description: Unique identifier for the suggestion.
category:
type: string
description: Suggestion category, e.g. `missing_context`.
example: missing_context
title:
type: string
description: Short human-readable title.
rationale:
type: string
description: Explanation of why the suggestion was made.
priority:
type: integer
minimum: 1
maximum: 10
description: Priority from 1 (highest) to 10 (lowest).
example: 1
proposedChanges:
$ref: '#/components/schemas/SuggestionProposedChanges'
evidence:
type: array
nullable: true
description: >-
Source evidence for the suggestion. `null` for rows created before
evidence was tracked; `[]` when none was cited.
items:
$ref: '#/components/schemas/SuggestionEvidenceItem'
ignoreReason:
type: string
nullable: true
description: >-
Optional free-text reason recorded when the suggestion was
dismissed.
ignoredAt:
type: string
format: date-time
nullable: true
description: ISO 8601 timestamp of dismissal, or `null` if active.
ignoredBy:
type: string
format: uuid
nullable: true
description: User ID that dismissed the suggestion, or `null` if active.
aiModifiedAt:
type: string
format: date-time
description: >-
ISO 8601 timestamp of the last AI write (create or AI update).
Unaffected by dismiss/restore.
createdAt:
type: string
format: date-time
description: ISO 8601 timestamp of when the suggestion was created.
updatedAt:
type: string
format: date-time
description: >-
ISO 8601 timestamp of the last write of any kind, including
dismiss/restore.
PageInfo:
type: object
description: Pagination information for paginated responses.
properties:
hasNextPage:
type: boolean
description: Indicates if there are more records available.
nextCursor:
type: string
nullable: true
description: Cursor for the next page of results. `null` if no more results.
pageSize:
type: integer
description: Number of records per page.
totalRecords:
type: integer
description: Total number of records matching the query.
Error:
type: object
properties:
error:
type: string
description: HTTP response code for the error
example:
message:
type: string
description: Detailed error description
example:
SuggestionProposedChanges:
type: object
description: The change(s) the suggestion would apply to the model.
required:
- kind
- edits
properties:
kind:
type: string
enum:
- context_edits
description: The kind of change. Currently always `context_edits`.
edits:
type: array
items:
$ref: '#/components/schemas/SuggestionContextEdit'
SuggestionEvidenceItem:
type: object
required:
- type
- chatAiSessionId
- capturedAt
properties:
type:
type: string
enum:
- ai_chat
description: The kind of evidence. Currently always `ai_chat`.
chatAiSessionId:
type: string
format: uuid
description: Chat session that motivated the suggestion.
capturedAt:
type: string
description: ISO 8601 timestamp of when the evidence was captured.
SuggestionContextEdit:
type: object
required:
- field
- target
- value
properties:
field:
type: string
description: The model field being edited (e.g. `ai_context`).
example: ai_context
target:
type: string
description: >-
Dot-path identifying what the edit applies to, e.g.
`views.orders.fields.status`.
example: views.orders
value:
anyOf:
- type: string
- type: array
items:
type: string
description: The proposed value for the field.
responses:
TooManyRequests:
description: Too Many Requests - Rate limit exceeded (60 requests/minute)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Can be either an [Organization API
Key](/api/authentication#organization-api-keys) or [Personal Access
Token (PAT)](/api/authentication#personal-access-tokens-pat).
Include in the `Authorization` header as: `Bearer YOUR_TOKEN`
orgApiKey:
type: http
scheme: bearer
bearerFormat: JWT
description: >
Requires an [Organization API
Key](/api/authentication#organization-api-keys). Personal Access Tokens
(PATs) are not supported for this endpoint.
Include in the `Authorization` header as: `Bearer ORGANIZATION_API_KEY`
````