Skip to main content

DIAL Deep Research API and request flow

Deep Research 0.4.0 serves DIAL Chat Completions, a property-schema endpoint, and an SDK health check. This reference is for platform engineers integrating clients or diagnosing requests. It assumes the backend and application instance are configured in Core.

Endpoints​

Clients call DIAL Core with the application instance ID, for example research-example. Core routes the request to the backend's fixed deployment, deep-research.

MethodBackend pathPurpose
POST/openai/deployments/deep-research/chat/completionsMain preparation and research workflow
POST/openai/deployments/deep-research/rateSDK rating route, registered with every chat completion; the backend does not override its no-op handler
GET/v1/configuration-support/application-schemaProperty JSON schema that Core downloads through dial:applicationTypeSchemaEndpoint
GET/healthSDK liveness response: {"status":"ok"}
POST/openai/deployments/deep-research-playground/chat/completionsTool-calling agent, only when ENABLE_PLAYGROUND_CHANNEL=true
POST/openai/deployments/deep-research-annotations-demo/chat/completionsFixed report citing two attached PDFs, only when ENABLE_ANNOTATIONS_DEMO=true

The backend registers these deployments and the schema handler. Its locked dependency is DIAL SDK 0.32.0. The SDK supplies the completion and rate routes, health route, and health response.

The health handler returns a fixed response. It does not check Core, model, or MCP connectivity. The schema handler returns property definitions without the root application-type identity. Core downloads the schema the first time it resolves the type, merges it with the registration, and caches the result; see ApplicationSchemaService.

Client request​

The first turn calls the instance through Core:

curl --no-buffer 'https://<DIAL_HOST>/openai/deployments/research-example/chat/completions?api-version=2025-04-01-preview' \
  -H 'api-key: <DIAL_API_KEY>' \
  -H 'Content-Type: application/json' \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "Compare the main risks described in the last two quarterly reports."
      }
    ],
    "stream": true
  }'

The model can ask clarification questions and propose a plan before research begins. Follow-up requests include the prior conversation messages, preserving each assistant message's custom_content.state. Approval arrives as another user turn; it is not a separate HTTP endpoint.

The backend loads and validates application properties, restores preparation state, fetches source descriptions, and runs preparation. Once the plan is approved and research starts, it runs the research graph in that same request. Source: turn coordinator and start-research tool.

Progress and report delivery​

With stream=true, the SDK returns text/event-stream. Heartbeat comments arrive at the configured interval, default five seconds. With stream=false, the SDK collects the result into a JSON response. Source: SDK response handling.

Research work and reviews appear as DIAL stages. Report drafts are withheld while reviews can still revise them; the final report is appended once after the graph finishes. The report is therefore not delivered token by token during research. Source: research runner contract.

Citation metadata is emitted in custom_content.annotations after report content. A client must preserve and render those annotations to display citation pills. Document citations depend on the configured file-sharing tool and metadata resource; dataset and query citations depend on StatGPT metadata. Sources: annotation payload and citation delivery.

Citation conversion or References construction can fail independently of the research turn. The delivery code logs these failures and retains the available report content. Missing citation links do not prove that retrieval failed; source configuration and citation-resolution logs distinguish the cases.

Conversation state​

The backend stores two internal values in each assistant message's custom_content.state:

ValuePurpose
messagesSerialized research/preparation history, including tool messages
preparationCurrent query, clarification, plan, approval, and research-start status

Clients carry the returned state forward unchanged with the corresponding assistant message. It is not a replacement for the visible conversation text. Preparation state comes from the latest assistant message with valid state; a fresh state is used only when no message has one. Missing usable message state falls back to visible assistant content. Sources: state and history serialization and preparation-state restoration.

Once the restored state has research_started=true, another turn raises a conflict asking for a new conversation. The service does not provide a separate resume/job API for a completed research. See the coordinator check and conflict condition.

Errors​

Turn failures use DIAL protocol errors, with user-facing text and an eight-character error reference for log correlation. A failure can produce a non-success HTTP response or an in-stream error chunk after streaming has begun. A 200 streaming response alone is not proof of success. Source: error delivery.

ConditionResult
Invalid application propertiesApplication-not-configured protocol error; administrators must correct the instance properties
Research already started in this conversationConflict condition, 409 on the HTTP error path
Research graph exceeds its step budgetProtocol error instructing the user to narrow the request and start a new conversation
Upstream authentication, permission, or missing deployment/resourceUser-facing service/model error; check the backend's correlated log record
Reached research iteration or report version limitThe graph proceeds to report delivery according to its budget rules; distinct from the graph-step failure limit

Sources: property validation, internal conditions, and graph routing.

Further reading​