TuringMate
API v1

Messages & Chat

Send messages to characters and receive AI-powered responses. The chat endpoint supports both synchronous and asynchronous modes.

POST
/api/v1/chat

Send message, get AI response

GET
/api/v1/conversations/:id

Get conversation history

GET
/api/v1/updates

Poll for responses

Send Message (Sync)

The default sync mode waits for the AI response before returning. Typical response time: 2-10 seconds.

Request
curl -X POST https://www.turingmate.com/api/v1/chat \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "abc123",
    "message": "What do you think about space exploration?",
    "mode": "sync"
  }'
Response
{
  "sessionId": "session_xyz",
  "message": {
    "id": "msg_123",
    "content": "Space exploration is fascinating! I think...",
    "sentAt": "2024-01-15T10:30:00Z"
  },
  "credits": {
    "used": 1,
    "remaining": 99
  }
}

Send Message (Async)

Use async mode for webhooks, serverless environments (timeout concerns), or high-volume applications. Returns immediately with a poll URL.

Request
{
  "characterId": "abc123",
  "message": "Tell me a story",
  "mode": "async"
}
Response (immediate)
{
  "status": "processing",
  "pollUrl": "/api/v1/updates?sessionId=session_xyz",
  "credits": { "used": 1 }
}

Request Parameters

FieldTypeRequiredDescription
characterIdstringYesCharacter to chat with
messagestring*Text message (* message or imageUrl required)
imageUrlstring*Image URL to attach
sessionIdstringNoContinue existing conversation
mode"sync" | "async"NoResponse mode (default: sync)

Conversation History

Retrieve the message history for a conversation session with pagination support.

Request
curl "https://www.turingmate.com/api/v1/conversations/session_xyz?limit=20" \
  -H "x-api-key: your_api_key"
Response
{
  "sessionId": "session_xyz",
  "characterId": "abc123",
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "content": "Hello!",
      "timestamp": "2024-01-15T10:00:00Z"
    },
    {
      "id": "msg_2",
      "role": "assistant",
      "content": "Hey there! How's it going?",
      "timestamp": "2024-01-15T10:00:05Z"
    }
  ],
  "hasMore": false
}

Polling for Updates

Poll for new messages (useful for async mode and proactive messages).

Request
curl "https://www.turingmate.com/api/v1/updates?since=2024-01-15T10:00:00Z" \
  -H "x-api-key: your_api_key"