Send and Receive Messages

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

• Upload Files - Attach documents to your queries
• Review Chats - Manage your conversations