Omni AI

Omni is Clear Street’s proprietary financial copilot for the Clear Street trading platform. It can help you with:

• Market research - Look up stocks, analyze price movements, find news and catalysts
• Portfolio insights - View your positions, balances, and performance history
• Trade execution - Place orders for US equities, ETFs, and equity options
• Options analysis - Price options, calculate Greeks, and estimate probabilities
• Order management - Query, track, and cancel your orders

Omni has access to real-time market data, your account information, and research tools to help you make informed trading decisions.The following section covers the available endpoints.

Entitlements

Before Omni can provide personalized portfolio and trade insight, you need to grant Omni access to your account data via an entitlement agreement. Note that this still does not allow Omni to take any actions on your behalf without confirmation. Omni’s list of entitlement agreements can be found via the GET /v1/omni-ai/entitlement-agreements. If you want to provide Omni access you can take the agreement_key and entitlement_codes and pass those along with the account id in the body of POST /v1/omni-ai/entitlements request as shown below.

{
  "agreement_id": "01JZ0000000000000000000000",
  "requested_entitlement_codes": ["omni.account_data"],
  "trading_account_ids": ["{account_id}", "{account_id}"]
}

If done properly you will see the relevant agreements and entitlements returned back in the response of GET /v1/omni-ai/entitlements

Note that you can remove the entitlement at any time by using theDELETE /v1/omni-ai/entitlements/{entitlement_id}

Conversations with Omni

There are 3 key terms to understand when interacting with Omni APIs which are threads, messages and responses.

• Threads - holds the full conversation history and has a title and timestamps. It does not contain content directly but rather is the container that groups messages together.
• Messages - A message is a finalized immutable record in a thread. It can be a USER message or an ASSISTANT (produced by Omni) message. A message only exists here after a terminal state is reached — you cannot see a message while Omni is still generating it.
• Responses - The live, poll-able view into Omni’s response to a user’s message. It has a lifecycle status like queued, running, succeeded, failed, or canceled. While it is being generated, it may include partial text and thinking content. Once it reaches a terminal state, the assistant output becomes available as a finalized message in the thread.

In summary, the Response is what you watch while waiting for Omni to produce a finalized message. The Message is the permanent record you read back when replaying history and messages are contained within threads. Next, let’s dive into a typical Omni workflow.

Omni Workflow

1. User creates a thread with a prompt via create threads endpoint POST /v1/omni-ai/threads
2. API response returns thread_id, user_message_id, and response_id
3. User polls the response by id endpoint GET /v1/omni-ai/responses/{response_id} using response_id to get updates .
   1. Note additionally there is a thread response endpoint GET /v1/omni-ai/threads/{thread_id}/response which is a convenience endpoint that can be used to look up the current active response for a thread without knowing the response_id. This is useful when reloading a thread whose last finalized message is a USER message — this indicates an assistant turn is likely in progress.
4. When the response succeeds, Omni’s answer appears as a finalized message in that thread. Note that as long as a message has not reached a terminal state you can cancel a response by using the cancel response endpoint DELETE /v1/omni-ai/responses/{response_id}
5. User can read messages in a thread using the get messages endpoint GET /v1/omni-ai/threads/{thread_id}/messages
   1. For any of the messages marked with a role of ASSISTANT (Omni’s messages), users have the ability to provide feedback using the submit feedback endpoint POST /v1/omni-ai/messages/{message_id}/feedback
6. User can create a new thread or continue a conversation by responding back to Omni’s message by using create message endpointPOST /v1/omni-ai/threads/{thread_id}/messages
7. Additionally a user can navigate to another thread by looking up all threads using get threads endpoint GET v1/omni-ai/threads and getting the messages for that thread

Defining Capabilities

When you create a new thread or a new message as part of the request body a user is able to define which types of structured output Omni is permitted to emit in a response. This is done through the capabilities field. This is important to note because Omni can return more than just plain text and capabilities keep Omni from sending actions the client cannot render or safely support. Below is a list of current capabilities Omni supports:

Capability	What it unlocks
PREFILL_ORDER	Omni may suggest order tickets (symbol, side, quantity, price) for the user to review and confirm
OPEN_CHART	Omni may emit inline charts and open_chart actions directing the UI to display a symbol chart
OPEN_SCREENER	Omni may emit open_screener actions with pre-configured filters, sort, and field selection
OPEN_ENTITLEMENT_CONSENT	Omni may prompt the user to grant account-data access when it needs consent to proceed

For API users, the practical rule is:

• If you only want text answers, omit capabilities or send an empty array.
• If your app can render charts, send OPEN_CHART.
• If your app can show a user-reviewed order ticket, send PREFILL_ORDER.
• If your app supports saved/symbol screeners, send OPEN_SCREENER.
• If your app can present Omni account-data consent, send OPEN_ENTITLEMENT_CONSENT.

Response Status Definitions

Status	Description	Terminal
Queued	Accepted, but Omni’s work has not started.	No
Running	Omni’s work is in progress. Content may be partial.	No
Succeeded	Omni’s response completed successfully	Yes
Failed	Omni’s response failed. Check error.	Yes
Canceled	Omni’s response was canceled	Yes

Once terminal, the finalized assistant message is available through the message endpoints.

Messages Outcome Definitions

Outcome	Description
Completed	Finalized successfully
Errored	Failed during execution
Canceled	Canceled before completion

Additional endpoints

Action	Method	Path	Description
Get Message by ID	GET	/v1/omni-ai/messages/{message_id}	Getting a specific message by id
Get Thread by ID	GET	/v1/omni-ai/threads/{thread_id}	Getting a specific thread by id, note it does not include the messages

• Omni AI is provided by Clear Street Technology LLC.

---