Back to Documentation

Send and Receive Messages

Complete guide to sending queries and receiving responses from the API

by Arkangel AI Team•1 min read

Learn how to send medical queries to the Arkangel AI API and process responses.

Main Endpoint

POST https://api.arkangelai.com/v1/chat

Sending a Message

Basic Request

curl -X POST https://api.arkangelai.com/v1/chat \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the symptoms of type 2 diabetes?"
  }'

Request Parameters

Parameter Type Required Description
message string Yes The message or query to send
conversation_id string No ID to continue an existing conversation
context object No Additional context for the query
language string No Response language (es, en, fr, pt)

Example with Context

const response = await fetch('https://api.arkangelai.com/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'What treatments are available?',
    conversation_id: 'conv_abc123',
    context: {
      patient_age: 45,
      condition: 'diabetes'
    },
    language: 'en'
  })
});

Response Format

{
  "id": "msg_xyz789",
  "conversation_id": "conv_abc123",
  "message": "Common symptoms of type 2 diabetes include...",
  "sources": [
    {
      "title": "ADA Diabetes Guide 2024",
      "url": "https://example.com/source",
      "relevance": 0.95
    }
  ],
  "created_at": "2026-01-19T10:30:00Z",
  "tokens_used": 150
}

Response Fields

Field Type Description
id string Unique message identifier
conversation_id string Conversation ID
message string AI-generated response
sources array Cited medical sources
created_at string Creation date and time (ISO 8601)
tokens_used number Tokens consumed in this request

Conversations

You can maintain context between messages using conversation_id:

// First message
const response1 = await sendMessage({
  message: 'What is hypertension?'
});

// Follow-up message
const response2 = await sendMessage({
  message: 'What are the risk factors?',
  conversation_id: response1.conversation_id
});

Response Streaming

For real-time responses, use the streaming endpoint:

const response = await fetch('https://api.arkangelai.com/v1/chat/stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    message: 'Explain the digestion process'
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value);
  console.log(chunk);
}

Error Handling

try {
  const response = await sendMessage({ message: 'My query' });

  if (!response.ok) {
    const error = await response.json();
    console.error('Error:', error.message);
  }
} catch (error) {
  console.error('Network error:', error);
}

Next Steps