Omni AI Model Suggestions API
Manage AI-generated suggestions for shared models
OpenAPI Specification
openapi: 3.1.0
info:
title: Omni AI AI Model Suggestions API
description: "The Omni REST API provides programmatic access to your Omni instance for managing users, documents, queries, schedules, and more. \n"
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: AI Model Suggestions
description: Manage AI-generated suggestions for shared models
paths:
/v1/models/{modelId}/suggestions:
get:
tags:
- AI Model Suggestions
summary: List AI-generated suggestions
description: "<Note>\n This endpoint requires **Organization Admin** permissions.\n</Note>\n\nLists AI-generated suggestions for a shared model. Suggestions can be filtered by status and are returned with keyset-based pagination.\n\nSuggestions are sorted by priority, creation date, and ID for stable pagination.\n"
security:
- bearerAuth: []
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 <modelId> 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'
/v1/models/{modelId}/suggestions/{suggestionId}:
delete:
description: "<Note>\n **Organization Admin** permissions are required to use this endpoint.\n</Note>\n\nPermanently deletes an AI Model suggestion.\n"
operationId: modelSuggestionsDelete
summary: Delete a suggestion
tags:
- AI Model Suggestions
parameters:
- name: modelId
in: path
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
required: true
description: UUID of the shared model the suggestion belongs to
- name: suggestionId
in: path
schema:
type: string
format: uuid
example: b2c3d4e5-f6a7-8901-bcde-f12345678901
required: true
description: UUID of the suggestion
responses:
'200':
description: The suggestion was deleted
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Malformed ID
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError401'
'403':
description: AI disabled for organization, model is not a shared model, or caller lacks Organization Admin permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: Suggestion or model not found in this organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/models/{modelId}/suggestions/runs/latest:
get:
summary: Get the latest generation run
description: "<Note>\n **Organization Admin** permissions are required to use this endpoint.\n</Note>\n\nRetrieve the most recent generation run for the shared model (the active run if one is in flight, otherwise the last terminal run), or `null` if none exists.\n"
operationId: modelSuggestionsRunLatest
security:
- bearerAuth: []
tags:
- AI Model Suggestions
parameters:
- name: modelId
in: path
required: true
description: UUID of the shared model the suggestions belong to
schema:
type: string
format: uuid
description: UUID of the shared model the suggestions belong to
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
responses:
'200':
description: The latest generation run, or null
content:
application/json:
schema:
type: object
description: The most recent generation run or `null` if no runs exist.
required:
- run
properties:
run:
allOf:
- $ref: '#/components/schemas/SuggestionRun'
- type: object
nullable: true
description: The most recent run for this model or `null` if none exists.
examples:
withRun:
summary: Model has runs
value:
run:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
status: complete
triggerSource: manual
triggeredBy:
userId: b2c3d4e5-f6a7-8901-bcde-f12345678901
name: Blob Ross
createdAt: '2026-07-15T14:30:00Z'
executionStartedAt: '2026-07-15T14:30:05Z'
completedAt: '2026-07-15T14:32:30Z'
error: null
noRuns:
summary: Model has never had a run
value:
run: null
'400':
description: Malformed `modelId`
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError401'
'403':
description: Feature not enabled, AI disabled, model is not a shared model, or caller lacks Organization Admin permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: Model not found in this organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/models/{modelId}/suggestions/runs/{runId}:
get:
summary: Get status for a generation run
description: "<Note>\n **Organization Admin** permissions are required to use this endpoint.\n</Note>\n\nRetrieve the status of a specific generation run. Poll until `status` is terminal (`complete` or `failed`), then re-fetch the suggestions list.\n"
operationId: modelSuggestionsRunGet
security:
- bearerAuth: []
tags:
- AI Model Suggestions
parameters:
- name: modelId
in: path
required: true
description: UUID of the shared model the run belongs to
schema:
type: string
format: uuid
description: UUID of the shared model the run belongs to
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
- name: runId
in: path
required: true
description: UUID of the generation run
schema:
type: string
format: uuid
description: UUID of the generation run
example: b2c3d4e5-f6a7-8901-bcde-f12345678901
responses:
'200':
description: The generation run
content:
application/json:
schema:
$ref: '#/components/schemas/SuggestionRun'
examples:
completed:
summary: Completed run
value:
id: b2c3d4e5-f6a7-8901-bcde-f12345678901
status: complete
triggerSource: manual
triggeredBy:
userId: c3d4e5f6-a7b8-9012-cdef-123456789012
name: Blob Ross
createdAt: '2026-07-15T14:30:00Z'
executionStartedAt: '2026-07-15T14:30:05Z'
completedAt: '2026-07-15T14:32:30Z'
error: null
running:
summary: Run in progress
value:
id: b2c3d4e5-f6a7-8901-bcde-f12345678901
status: running
triggerSource: scheduled
triggeredBy:
userId: c3d4e5f6-a7b8-9012-cdef-123456789012
name: Blob Ross
createdAt: '2026-07-15T14:30:00Z'
executionStartedAt: '2026-07-15T14:30:05Z'
completedAt: null
error: null
'400':
description: Malformed `modelId` or `runId`
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError401'
'403':
description: Feature not enabled, AI disabled, model is not a shared model, or caller lacks Organization Admin permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: Run not found, does not belong to this model, or does not belong to this organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'405':
description: Method not allowed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/models/{modelId}/suggestions/generate:
post:
tags:
- AI Model Suggestions
summary: Generate model suggestions
description: "<Note>\n This endpoint requires **Organization Admin** permissions.\n</Note>\n\nTrigger an AI suggestion generation run for the shared model and enqueue the async job. Poll the [Get status for a generation run endpoint](/api/ai-model-suggestions/get-status-for-a-generation-run) for status.\n\nA model can have one active run at a time and a cooldown period is enforced after a successful run. See the `Retry-After` header in the response for more information.\n"
security:
- bearerAuth: []
operationId: modelSuggestionsGenerate
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: UUID of the shared model the suggestions belong to
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
responses:
'202':
description: Generation run enqueued
content:
application/json:
schema:
type: object
required:
- runId
- status
properties:
runId:
type: string
format: uuid
description: 'The ID of the created generation run. Poll the [Get status for a generation run endpoint](/api/ai-model-suggestions/get-status-for-a-generation-run) for status.
'
status:
type: string
enum:
- queued
description: The status of the run. Generation runs asynchronously.
example:
runId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
status: queued
'400':
description: 'Bad Request
Possible error messages:
- `modelId: Invalid UUID` - The model ID is not a valid UUID format
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Authentication required
'403':
description: 'Forbidden
Possible error messages:
- `Permission denied` - User is not an Organization Admin
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: Model not found in this organization
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'405':
description: Method not allowed
'409':
description: A generation run is already active for this model
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError409'
example:
detail: A generation run is already active for this model
status: 409
'429':
description: A run completed recently; retry after the cooldown (see the `Retry-After` header)
headers:
Retry-After:
schema:
type: integer
description: Number of seconds to wait before retrying
content:
application/json:
schema:
type: object
required:
- runId
- status
properties:
runId:
type: string
format: uuid
description: 'The ID of the created generation run. Poll the [Get status for a generation run endpoint](/api/ai-model-suggestions/get-status-for-a-generation-run) for status.
'
status:
type: string
enum:
- queued
description: The status of the run. Generation runs asynchronously.
example:
detail: A run completed recently. Please wait before triggering another run.
lastCompletedAt: '2026-07-20T10:30:00.000Z'
retryAfterSeconds: 300
status: 429
'500':
description: Failed to enqueue the generation job
/v1/models/{modelId}/suggestions/schedule:
put:
tags:
- AI Model Suggestions
summary: Enable model AI suggestions schedule
description: "<Note>\n This endpoint requires **Organization Admin** permissions.\n</Note>\n\nEnable the daily generation schedule for AI model suggestions on a shared model. Suggestions are generated daily at midnight in the specified timezone.\n\nThis operation is idempotent: calling it multiple times returns the persisted schedule.\n"
security:
- bearerAuth: []
operationId: modelSuggestionsScheduleEnable
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
description: The unique identifier of the model.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
timezone:
type: string
description: 'IANA timezone string (e.g., `America/New_York`, `Europe/London`, `UTC`). Determines when the daily suggestion generation runs. Defaults to `UTC` if not provided.
'
additionalProperties: false
examples:
withTimezone:
summary: Enable with specific timezone
value:
timezone: America/New_York
defaultTimezone:
summary: Enable with default UTC timezone
value: {}
responses:
'200':
description: Schedule enabled successfully. Returns the current state of the schedule, or the same state if already enabled.
content:
application/json:
schema:
type: object
required:
- id
- sharedModelId
- status
- timezone
properties:
id:
type: string
format: uuid
description: Unique identifier for the schedule.
sharedModelId:
type: string
format: uuid
description: The shared model the schedule generates suggestions for.
status:
type: string
enum:
- enabled
timezone:
type: string
description: IANA timezone the schedule runs in.
example: America/New_York
example:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
sharedModelId: f1e2d3c4-b5a6-7890-abcd-ef9876543210
status: enabled
timezone: America/New_York
'400':
description: 'Bad Request
Possible error messages:
- `modelId: Invalid UUID` - The model ID is not a valid UUID format
- `timezone: Invalid timezone` - The provided timezone is not a valid IANA timezone format
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'403':
description: 'Forbidden
Possible error messages:
- `Permission denied` - User is not an organization admin
- `AI is not enabled for this organization` - Organization does not have AI features enabled
- `Model must be shared` - The model is not a shared model
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: 'Not Found
Possible error messages:
- `Model with id <modelId> does not exist`
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'429':
$ref: '#/components/responses/TooManyRequests'
delete:
tags:
- AI Model Suggestions
summary: Disable model AI suggestions schedule
description: "<Note>\n This endpoint requires **Organization Admin** permissions.\n</Note>\n\nDisable the daily generation schedule for AI model suggestions on a shared model.\n\nThis operation is idempotent: calling it multiple times returns success even if the schedule is already disabled.\n"
security:
- bearerAuth: []
operationId: modelSuggestionsScheduleDisable
parameters:
- schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
required: true
description: UUID of the shared model the suggestions belong to
name: modelId
in: path
responses:
'200':
description: Schedule disabled successfully. Returns confirmation even if the schedule was already disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
example:
success: true
message: AI suggestions schedule disabled
'400':
description: 'Bad Request
Possible error messages:
- `modelId: Invalid UUID` - The model ID is not a valid UUID format
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'403':
description: 'Forbidden
Possible error messages:
- `Permission denied` - User is not an Organization Admin
- `AI is not enabled for this organization` - Organization does not have AI features enabled
- `Model must be shared` - The model is not a shared model
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: 'Not Found
Possible error messages:
- `Model with id <modelId> does not exist`
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'405':
description: Method not allowed
'429':
$ref: '#/components/responses/TooManyRequests'
/v1/models/{modelId}/suggestions/{suggestionId}/ignore:
post:
tags:
- AI Model Suggestions
summary: Dismiss a suggestion
description: "<Note>\n This endpoint requires **Organization Admin** permissions.\n</Note>\n\nDismisses a suggestion, removing it from the active list. Dismissed suggestions can be restored using the [restore endpoint](/api/ai-model-suggestions/restore-a-dismissed-suggestion).\n"
security:
- bearerAuth: []
operationId: modelSuggestionsIgnore
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
description: The unique identifier of the model.
- name: suggestionId
in: path
required: true
schema:
type: string
format: uuid
example: b2c3d4e5-f6a7-8901-bcde-f12345678901
description: The unique identifier of the suggestion to dismiss.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
type: string
maxLength: 4000
description: Optional free-text reason for dismissing the suggestion.
example: Already covered by an existing field description.
additionalProperties: false
responses:
'200':
description: Suggestion dismissed successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Indicates the request was successful
example: true
'400':
description: Invalid body or malformed ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Missing or invalid authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError401'
'403':
description: 'Feature not enabled, AI disabled, model is not a shared model, or caller lacks Organization Admin permissions
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError403'
'404':
description: 'Not Found
Possible error messages:
- `Model not found`
- `Suggestion not found`
- Cross-organization suggestion access denied
'
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError404'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/models/{modelId}/suggestions/{suggestionId}/restore:
post:
tags:
- AI Model Suggestions
summary: Restore a dismissed suggestion
description: "<Note>\n This endpoint requires **Organization Admin** permissions.\n</Note>\n\nRestores a previously dismissed suggestion back to the active list.\n"
security:
- bearerAuth: []
operationId: modelSuggestionsRestore
parameters:
- name: modelId
in: path
required: true
schema:
type: string
format: uuid
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
description: UUID of the shared model the suggestion belongs to.
- name: suggestionId
in: path
required: true
schema:
type: string
format: uuid
example: b2c3d4e5-f6a7-8901-bcde-f12345678901
description: The unique identifier of the suggestion to restore.
responses:
'200':
description: Suggestion restored successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Indicates the request was successful
example: true
'400':
description: Malformed ID.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError400'
'401':
description: Missing or invalid authentication.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError401'
'403':
description: 'Feature not enabled, AI disabled, model is not a shared model, or caller lacks organization admin permissions
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'Not Found
Possible error messages:
- `Model not found`
- `Suggestion not found`
- Cross-organization suggestion access denied
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
SuggestionContextE
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/omni/refs/heads/main/openapi/omni-ai-model-suggestions-api-openapi.yml