Thankly developer documentation

REST API

Two tokens, two headers — the distinction most integrations get wrong first.

# 1 — exchange client credentials for an org access token
curl -sS https://api.thankly.ai/auth/token \
  -H 'Content-Type: application/json' \
  -d '{"clientId":"$THANKLY_CLIENT_ID","clientSecret":"$THANKLY_CLIENT_SECRET"}'
# → { "accessToken": "…", "tokenType": "bearer", "expiresIn": 3600 }

# 2 — create an experience, server-side, with X-Authorization
curl -sS https://api.thankly.ai/experiences \
  -H 'Content-Type: application/json' \
  -H "X-Authorization: Bearer $ORG_ACCESS_TOKEN" \
  -d '{
        "tag_id": "your-tag",
        "context": { "topic": { "topic": "weekend in Lisbon",
                                 "questions": ["Where should we eat?"] } },
        "capabilities": [ { "type": "restaurants" } ]
      }'
# → { "experienceId": "…", "accessToken": "…" }

# 3 — poll until ready, with the per-experience token and plain Authorization
curl -sS "https://api.thankly.ai/experiences/$EXPERIENCE_ID" \
  -H "Authorization: Bearer $EXPERIENCE_ACCESS_TOKEN"

Full REST reference →

JavaScript SDK

The same flow, with token refresh and polling handled for you.

// Server-side — holds the clientSecret, sends X-Authorization
import { createThanklyServer } from '@thankly/sdk-server'

const thankly = createThanklyServer({
  apiHost: 'https://api.thankly.ai',
  clientId: process.env.THANKLY_CLIENT_ID,
  clientSecret: process.env.THANKLY_CLIENT_SECRET,
  secretTokenKey: 'thankly.token',
})

const { experienceId, accessToken } = await thankly.createExperience({
  tag_id: 'your-tag',
  context: { topic: { topic: 'weekend in Lisbon', questions: ['Where should we eat?'] } },
  capabilities: [{ type: 'restaurants' }],
})

// Browser — receives only the per-experience token, never the secret
import { createThanklyClient } from '@thankly/sdk-client'

const client = createThanklyClient({ apiHost: 'https://api.thankly.ai' })
const experience = await client.fetchExperience(experienceId, accessToken)

Full JavaScript reference →

JVM SDK

Kotlin, coroutines throughout. recommend creates and awaits in one call.

import ai.thankly.sdk.*
import kotlinx.coroutines.runBlocking

// Backends only: clientCredentials holds the secret. On Android, take a token
// your own backend vends instead — see the reference.
val config = ThanklyConfig(
    apiHost = "https://api.thankly.ai",
    tokenProvider = TokenProvider.clientCredentials(
        clientId = System.getenv("THANKLY_CLIENT_ID"),
        clientSecret = System.getenv("THANKLY_CLIENT_SECRET"),
        apiHost = "https://api.thankly.ai",
    ),
)

val result = runBlocking {
    ThanklyClient(config).recommend(
        context = Topic(
            topic = "weekend in Lisbon",
            questions = listOf("Where should we eat?"),
        ),
        capabilities = listOf(CapabilityRequest(type = "restaurants")),
        tagId = "your-tag",
    )
}

Full JVM reference →

Installing