Getting Started: Using the Fluency API

This guide shows you how to build a learning application or game on top of the Fluency API.

What the API Provides

Building an effective learning system requires deep expertise in cognitive science: spaced repetition algorithms, diagnostic assessment, error pattern analysis, and adaptive intervention selection. The Fluency API handles all of this complexity for you.

You focus on building an engaging game or app. We provide the adaptive learning engine that determines which question to ask next, when to review previous material, and how to remediate errors. Whether you're building a 3D runner, a mobile quiz app, or a web-based practice tool, you get research-backed learning science without implementing any of it yourself.

The API provides two learning modes (Speedrun for diagnostic assessment, Practice for adaptive training), targeted interventions for incorrect answers, and built-in progress tracking with XP and leaderboards.

Environments

We provide two environments for development and production:

Integration (Testing)

API URL: https://api-integration.trashcat.rp.devfactory.com
User Pool ID: us-east-1_cfmKouGuW
User Pool Domain: trashcat-integration-userauth.auth.us-east-1.amazoncognito.com
Region: us-east-1

Production

API URL: https://api.trashcat.learnwith.ai
User Pool ID: us-east-1_NBNupqDm5
User Pool Domain: trashcat-production-userauth.auth.us-east-1.amazoncognito.com
Region: us-east-1

Step 1: Choose Your Authentication Model

Option 1: Client Credentials

Use this if:

You have your own backend server
You have your own user authentication system
You want full control over user management

How it works:

Contact trashcat@trilogy.com to request client credentials (Client ID + Client Secret)
Your backend authenticates users using your own auth system

Your backend exchanges client credentials for an access token via Cognito OAuth endpoints:

POST https://{USER_POOL_DOMAIN}/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id={CLIENT_ID}&
client_secret={CLIENT_SECRET}

Your backend makes API requests with:
- Authorization: Bearer {access_token} header
- X-User-Email: {user_email} header (to identify which user)

Advantages:

Full control over user management
Can integrate with existing auth systems
Centralized token management

Option 2: Use Our Authorization Server

Use this if:

You're building a frontend-only game (web, Unity WebGL, mobile)
You want to minimize backend infrastructure
You want us to handle user management

How it works:

Contact trashcat@trilogy.com to request an App Client ID and provide your redirect URLs
Integrate AWS Amplify or implement OAuth 2.0 flow in your game
Users sign in via our Cognito User Pool (supports email/password, Google SSO, magic links)
Your game receives an ID token and uses it for all API calls

Example using AWS Amplify:

import { Amplify } from 'aws-amplify';
import { fetchAuthSession, signIn } from 'aws-amplify/auth';

// Configure Amplify
const currentOrigin = window.location.origin;

Amplify.configure({
  Auth: {
    Cognito: {
      userPoolId: 'us-east-1_cfmKouGuW',
      userPoolClientId: '<client ID obtained from us>',
      loginWith: {
        oauth: {
          domain: 'trashcat-integration-userauth.auth.us-east-1.amazoncognito.com',
          scopes: ['openid', 'email', 'profile'],
          redirectSignIn: [`${currentOrigin}/`],
          redirectSignOut: [`${currentOrigin}/`],
          responseType: 'code',
        },
      },
    },
  },
});

// Sign in
await signIn({ username: email, password });

// Get ID token for API calls
const session = await fetchAuthSession();
const idToken = session.tokens?.idToken?.toString();

Advantages:

No backend required
User management handled automatically
Token refresh handled by auth library

Step 2: Make API Requests

Once you have a token, include it in all API requests:

Authorization: Bearer {id_token}

For client credentials flow, also include:

X-User-Email: {user_email}

Example API call:

const response = await fetch('https://api-integration.trashcat.rp.devfactory.com/learning/v1/skills', {
  headers: {
    Authorization: `Bearer ${idToken}`,
    'Content-Type': 'application/json',
  },
});

const { skills } = await response.json();

Step 3: Explore the API

The API Reference documents all available endpoints with request/response schemas. You can make live requests directly from the interactive playground in your browser.

Alternative tools:

Postman/Insomnia: Import the OpenAPI spec from https://docs.trashcat.learnwith.ai/openapi.json.
LLM integration: Use https://docs.trashcat.learnwith.ai/llms.txt for AI-friendly documentation

Example: Basic Learning Loop

This example demonstrates the core request/response flow: fetch a question, display it to the user, submit their answer, and show feedback.

// 1. Get available skills
const skillsRes = await fetch(`${API_URL}/learning/v1/skills`, {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { skills } = await skillsRes.json();

// 2. Initialize session
const sessionId = crypto.randomUUID();

// 3. Get a question
const questionRes = await fetch(`${API_URL}/learning/v1/skills/${skills[0].id}/algorithms/practice/questions`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${idToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ sessionId }),
});
const { question } = await questionRes.json();

// 4. Display question to user
console.log(question.text); // "7 × 8 = ?"
console.log(question.choices); // [{ id: "1", value: 56, label: "56" }, ...]

// 5. Submit answer (after user selects)
const answerRes = await fetch(
  `${API_URL}/learning/v1/skills/${skills[0].id}/algorithms/practice/questions/${question.id}/answers`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${idToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      sessionId,
      answer: { choiceId: selectedChoiceId },
      timeTookToAnswerMs: 3000,
      state: 'Answered',
      capabilities: { intervention: false }, // Disable interventions for MVP
      activeSessionDurationSec: 60,
    }),
  },
);
const feedback = await answerRes.json();

// 6. Show feedback
console.log(feedback.answerType); // "CORRECT" or "INCORRECT"
console.log(feedback.correctAnswer); // { value: 56 }

Error Handling

If a request fails, the API returns standard HTTP error codes with descriptive messages:

// Example error response (401 Unauthorized)
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Invalid or expired token"
}

// Example error response (400 Bad Request)
{
  "statusCode": 400,
  "message": "Bad Request",
  "error": "sessionId is required"
}

Always check the HTTP status code before parsing the response. For production error handling patterns, see the Complete Example guide.