Make your first request

This walkthrough takes a user from account creation through consultation completion and document retrieval. The API returns each consultation summary or SOAP note as an artifact.

Before you begin

You need an API Bearer token provisioned by Doctronic. Credential provisioning is currently manual. Contact your Doctronic business or implementation contact to request staging or production access. If you do not have a contact yet, email business@doctronic.ai. Do not send credentials or patient information by email.

Store the token server-side and never expose it in browser code, mobile binaries, logs, or analytics events.

export DOCTRONIC_API_URL="https://staging-partners.doctronic.ai/api/v1"
export DOCTRONIC_API_TOKEN="replace-with-your-token"
export DOCTRONIC_CREATE_USER_KEY="replace-with-a-unique-key"

1. Create a user

Create the Doctronic identity that corresponds to the patient in your system.

curl --request POST "$DOCTRONIC_API_URL/users/" \
  --header "Authorization: Bearer $DOCTRONIC_API_TOKEN" \
  --header "Idempotency-Key: $DOCTRONIC_CREATE_USER_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "firstName": "Avery",
    "lastName": "Chen",
    "dateOfBirth": "1990-06-15",
    "email": "avery@example.com",
    "phoneNumber": "+15555550100",
    "sex": "female"
  }'

Save the returned data.id. Pass it as X-Doctronic-User-ID for every user-scoped request.

2. Create a chat

export DOCTRONIC_USER_ID="user-id-from-step-one"
export DOCTRONIC_CREATE_CHAT_KEY="replace-with-a-different-unique-key"

curl --request POST "$DOCTRONIC_API_URL/chats/" \
  --header "Authorization: Bearer $DOCTRONIC_API_TOKEN" \
  --header "X-Doctronic-User-ID: $DOCTRONIC_USER_ID" \
  --header "Idempotency-Key: $DOCTRONIC_CREATE_CHAT_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "timezone": "America/New_York",
    "conversationPromptContext": "The user entered from the primary-care intake flow."
  }'

Save the returned data.id for each streaming request.

The create-user and create-chat operations retain an Idempotency-Key result for 24 hours. If a request times out before you receive a response, retry the same operation with the same body and key. Use a different key for a different user or chat.

3. Stream a turn

export DOCTRONIC_CHAT_ID="chat-id-from-step-two"

curl --no-buffer --request POST \
  "$DOCTRONIC_API_URL/chats/$DOCTRONIC_CHAT_ID/stream/" \
  --header "Authorization: Bearer $DOCTRONIC_API_TOKEN" \
  --header "X-Doctronic-User-ID: $DOCTRONIC_USER_ID" \
  --header "Content-Type: application/json" \
  --header "Accept: text/event-stream" \
  --data '{
    "userEvent": {
      "type": "user_message",
      "userInput": "I have had a sore throat and fever since yesterday."
    },
    "timezone": "America/New_York"
  }'

The response remains open for the assistant turn and emits Server-Sent Events such as message.start, message.content, and message.stop.

If a guardian event arrives, route it through the safety behavior approved for your integration. Pause any routine local flow that conflicts with that behavior, and keep the event's stable guardianId in your integration logs. Your approved behavior determines how and where the supplied message is presented.

4. Detect consultation completion

Continue sending user turns until the stream emits ai_consultation.complete. Its payload contains stable IDs for the consultation artifacts:

event: ai_consultation.complete
data: {"type":"ai_consultation.complete","artifacts":{"longSummary":"art_01K6JGGM2G2DB4Y9KB9H9MJJ6Q","shortSummary":"art_01K6JGGP7Q4R8S2T5V7W9X1Y3","soapNote":"art_01K6JGGR9Z6B2C4D6F8H0J2K4M"}}

Persist the artifact IDs with your consultation record. The completion event does not guarantee that every artifact is ready to retrieve. The end of an HTTP response only marks the end of that transport stream. It does not mean the consultation is complete.

5. Retrieve a consultation document

Use an artifact ID from the completion event:

export DOCTRONIC_ARTIFACT_ID="artifact-id-from-completion-event"

curl --request GET \
  "$DOCTRONIC_API_URL/artifacts/$DOCTRONIC_ARTIFACT_ID/" \
  --header "Authorization: Bearer $DOCTRONIC_API_TOKEN" \
  --header "X-Doctronic-User-ID: $DOCTRONIC_USER_ID"

A 200 response identifies the artifact with data.artifactType and provides its Markdown content in data.content.body. The type is long_summary, short_summary, or soap_note. If the API returns 202, the artifact is still being generated. Wait before requesting it again. Treat 404 as unavailable and 500 as a permanent generation failure.

Next steps