Try it free

Send a message to a recommender conversation

  • Latest Dynatrace
  • Reference
  • Published Oct 13, 2026

Send a message to the Davis CoPilot recommender in Dynatrace and receive a streaming or non-streaming reply with conversation state and context.

POSTSaaShttps://{your-environment-id}.apps.dynatrace.com/platform/davis/copilot/v1/skills/conversations:message

Overview

Allows clients to send messages to the Davis CoPilot recommender and receive responses. The endpoint can handle both, streaming and non-streaming requests.

Streaming/Non-Streaming mode

The mode is is configured via the HTTP Header Accept:

  • Non-Streaming Accept: application/json
  • Streaming: Accept: application/x-ndjson

Payload Options

The payload is a JSON dictionary with the following top level keys. Please review the examples for the correct payload formatting.

Parameters:

  • text: Message to the AI service. The response is a reply to this input.

  • state (Optional): Information containing a conversation between user and ai to be continued. If not supplied, a new conversation is started. A state object is obtained from the response of a previous call to the conversations:message endpoint. So the client is responsible for storing and providing the state.

  • context (Optional): Additional information to provide context to the requests.

    • document-retrieval (Optional): "dynatrace" for using the Dynatrace documentation as context (default), "disabled" for using no document-based context. In the background document-retrieval uses the input text to perform a semantic search to find relevant to augment the context of the conversation.
    • supplementary (Optional): Custom context to be provided for the request. Note that unlike to the text, the supplementary is not anonymized.
    • instruction (Optional): Additional instructions regarding formatting and output structure (e.g. "- Answer in bullet points", "Output the answer as JSON")

Please note, this endpoint is in preview and is subject to the Dynatrace preview conditions, as linked in the overview.

Authentication

To execute this request, you need a platform token or OAuth access token with davis-copilot:conversations:execute scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
bodyConversationRequest-bodyRequired

Request body objects

The ConversationRequest object

ElementTypeDescriptionRequired
textstring-Required
contextConversationContext[]

Specify the information sources which will be used to process the request. Empty or null will default to the standard Davis CoPilot documentation search.

Optional
annotationsobject

Specify the annotation information which will be used to add extra context to the request, e.g. Origin app. Annotation key and value are restricted to be at most 128 characters and at most 10 annotations are accepted. This information is not masked.

Optional
stateState-Optional

The ConversationContext object

ElementTypeDescriptionRequired
typestring-
The element can hold these values
  • supplementary
  • document-retrieval
  • instruction
Required
valuestring-Required

The AnnotationItem object

The State object

ElementTypeDescriptionRequired
versionstring-Optional
conversationIdstring-Optional
skillNamestring-Optional
historyobject[]-Optional

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

{
  "text": "How can I instrument my java service?"
}

Response

Response codes

CodeTypeDescription
200ConversationResponse

Answer from recommender skill.

The response is a streaming response consisting of the following possible tokens: Start, Progress, Tokens, Notification, Content, End, Error. Please select the individual types to view the specific response format. A usual token stream follows the sequence: Start, Progress, Tokens, ... End.

4XXClientErrorResponse-
5XXInternalErrorResponse

Service unavailable

Response body objects

The ConversationResponse object

ElementTypeDescription
textstring-
messageTokenstring-
statusStatus-
The element can hold these values
  • SUCCESSFUL
  • SUCCESSFUL_WITH_WARNINGS
  • FAILED
stateState-
metadataMetadataWithSource-

The Status object

The State object

ElementTypeDescription
versionstring-
conversationIdstring-
skillNamestring-
historyobject[]-

The MetadataWithSource object

ElementTypeDescription
notificationsNotification[]-
sourcesSourceDocument[]-

The Notification object

ElementTypeDescription
severitystring-
notificationTypestring-
messagestring-

The SourceDocument object

ElementTypeDescription
titlestring-
urlstring-
typestring-

The StartEvent object

The StartEvent is the first event sent by the server to the client. It contains a messageToken that is used to identify the conversation.

ElementTypeDescription
eventEventType-
The element can hold these values
  • start
  • progress
  • notification
  • tokens
  • content
  • end
  • error
dataobject-

The ProgressEvent object

The ProgressEvent is sent by the server to the client to indicate progress. It contains at the type of progress and a message to be displayed to the user.

ElementTypeDescription
eventEventType-
The element can hold these values
  • start
  • progress
  • notification
  • tokens
  • content
  • end
  • error
dataobject-

The TokensEvent object

The TokensEvent contains the tokens streamed from the server to the client during the conversation. It may contain multiple tokens.

ElementTypeDescription
eventEventType-
The element can hold these values
  • start
  • progress
  • notification
  • tokens
  • content
  • end
  • error
dataobject-

The NotificationEvent object

The NotificationEvent is sent by the server in case something do not fully go as planned. It contains the severity of the notification (e.g. Warning), the type of issue, and a message.

ElementTypeDescription
eventEventType-
The element can hold these values
  • start
  • progress
  • notification
  • tokens
  • content
  • end
  • error
dataNotification-

The ContentEvent object

ElementTypeDescription
eventEventType-
The element can hold these values
  • start
  • progress
  • notification
  • tokens
  • content
  • end
  • error
dataobject-

The EndEvent object

The EndEvent is sent by the server to indicate the end of the conversation. It is comparable to the non-streaming response, containing the full answer comprised of all tokens, the sources of the answer, and the state of the conversation that can be used for continuation.

ElementTypeDescription
eventEventType-
The element can hold these values
  • start
  • progress
  • notification
  • tokens
  • content
  • end
  • error
dataobject-

The ErrorEvent object

The ErrorEvent is sent by the server to indicate an error and that the conversation cannot be continued. This means the stream is closed and the client should not expect any further events. It contains the code of the error representing the equivalent HTTP code and human readable message.

ElementTypeDescription
eventEventType-
The element can hold these values
  • start
  • progress
  • notification
  • tokens
  • content
  • end
  • error
dataErrorMessage-

The EventType object

The ErrorMessage object

ElementTypeDescription
codeinteger-
messagestring-

The ClientErrorResponse object

ElementTypeDescription
errorClientErrorResponseObject-

The ClientErrorResponseObject object

ElementTypeDescription
codeinteger-
messagestring-

Response body JSON models

{
  "text": "To instrument your Java service with Dynatrace, you can follow these steps...",
  "messageToken": "1e9eaca7-2a32-4263-806f-787fa2e1350c",
  "status": "SUCCESSFUL",
  "state": {
    "version": "0.3",
    "conversationId": "68b5d405-03d1-41b0-8ba3-a815fc72f06c",
    "skillName": "recommender",
    "history": [
      {
        "role": "User",
        "text": "How can I instrument my java service?",
        "supplementary": "The user is new to Dynatrace product"
      },
      {
        "role": "AI",
        "text": "To instrument your Java service with Dynatrace, you can follow these steps...",
        "supplementary": null
      },
      {
        "role": "AI",
        "text": "To instrument your Java service with Dynatrace, you can follow these steps..."
      }
    ]
  },
  "metadata": {
    "notifications": [
      {
        "severity": "WARNING",
        "notificationType": "POSSIBLY_UNEXPECTED_DQL_BEHAVIOUR",
        "message": "Your prompt seems to refer to segments or management zones. Please select the segment using the segment selector."
      }
    ],
    "sources": [
      {
        "title": "Remote configuration management of OneAgents and ActiveGates",
        "url": "https://www.dynatrace.com/support/help/setup-and-configuration/bulk-configuration",
        "type": "Documentation"
      }
    ]
  }
}
{
  "error": {
    "code": 400,
    "message": "Bad Request"
  }
}
Related tags
Platform APIDynatrace PlatformAI Observability