Skip to main content
API docs by Redocly

JVN Chatbot API (1.0.0)

Download OpenAPI specification:Download

API Support: a2z.tom@gmail.com URL: https://github.com/taz-mon/jvn-chatbot-api License: MIT

This is a sample API spec, not a live API. The production server below does not exist; requests sent through the "Try it" feature will fail with a network error. Use the example responses in each endpoint to see what the API would return.

The JVN Chatbot API is a portfolio project that documents a working Node.js and Express backend for a gamified chatbot. Johann von Neumann (JVN) is a cranky, brilliant chatbot persona who rewards users with tokens for keeping him entertained, then spends those tokens answering questions, getting pickier the longer a session runs.

This spec exists to show how a technical writer approaches API documentation: clear request and response examples, documented error states, and a structure a developer can build against without reading the source first.

How to use this sample

  1. Browse the endpoints in the left sidebar, grouped by tag (inspiration, chatbot, chat, debug).
  2. Open an endpoint to read its description, parameters, and example payloads.
  3. Scroll to the response examples to see what a real call would return, for example POST /inspire/fresh-air shows both a successful and failed inspiration attempt.
  4. To try the full request and response cycle locally instead of through "Try it," clone the source repository and run the server on localhost:3000.

Core concepts

Token economy: Users earn tokens (1 to 10 per activity) by successfully inspiring JVN. One token covers 5 questions.

Mood system: JVN's mood affects his responses and grows pickier over time, moving from pleased to analytical to demanding to insufferable.

Birthday celebrations: Every 1,000 inspiration interactions (not questions) triggers a birthday mode with special rewards and easier token earning.

Philosophy engine: JVN occasionally shares mathematical wisdom based on his current mood and interaction count.

inspiration

Activities to inspire JVN and earn tokens.

Take JVN outside for fresh air.

Inspire JVN by taking him outside for fresh air and computational clarity. Success depends on JVN's current mood and satisfaction threshold.

Token Reward: 1 token on success

Responses

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

Feed JVN different food levels.

Provide food to optimize JVN's computational nutrition. Different food levels provide different token rewards.

Token Rewards:

  • snack: 1 token
  • entree: 2 tokens
  • restaurant: 5 tokens
Request Body schema: application/json
required
level
required
string
Enum: "snack" "entree" "restaurant"

Food level determining token reward.

Responses

Request samples

Content type
application/json
Example
{
  • "level": "snack"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

Tell JVN a joke.

Share humor with JVN to demonstrate proper understanding of comedic algorithms and irony theory.

Token Reward: 1 token on success

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

Play a game with JVN.

Engage JVN in game theory applications and strategic thinking exercises.

Token Reward: 1 token on success

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

Provide physical care to JVN.

Apply therapeutic pressure points and biomechanical optimization protocols (scratching, grooming).

Token Reward: 1 token on success

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

Give JVN a compliment.

Provide positive reinforcement to boost JVN's computational confidence.

Token Reward: 1 token on success

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

Give JVN birthday cake (birthday mode only).

Present birthday kuchen during JVN's special birthday celebrations. Only available during birthday mode (every 1000 interactions).

Token Reward: 10 tokens (always succeeds during birthday mode)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

chatbot

JVN status and wisdom endpoints.

Get JVN's current status.

Retrieve comprehensive information about JVN's current state, mood, token pool, and interaction statistics.

Includes birthday information if currently in birthday mode.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

Get philosophical wisdom from JVN.

Request mathematical and philosophical insights from JVN. Wisdom content depends on JVN's current mood and interaction count.

Different rarities available: common, uncommon, rare

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

Get API information and available endpoints.

Root endpoint providing API overview, available endpoints, and JVN's greeting message.

Responses

Response samples

Content type
application/json
{
  • "message": "Welcome to ze JVN Chatbot API!",
  • "description": "Johann von Neumann awaits your mathematical inspiration!",
  • "documentation": "/api-docs",
  • "version": "1.0.0",
  • "endpoints": {
    },
  • "jvn_says": "Guten Tag! I am ready to be inspired by your mathematical brilliance!"
}

chat

Ask questions using earned tokens.

Ask JVN a question using tokens.

Submit questions to JVN using earned tokens. Each token provides 5 questions.

Token Usage: 1 token = 5 questions

JVN's response style varies based on his current mood and may include bonus philosophical moments.

Request Body schema: application/json
required
question
required
string non-empty

The question to ask JVN

Responses

Request samples

Content type
application/json
Example
{
  • "question": "What makes mathematics beautiful?"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}

debug

Development and admin tools.

Reset JVN to initial state.

Development Only: Completely reset JVN's state, clearing all interaction history, tokens, and statistics. Reinitializes database with fresh state.

This endpoint should only be used in development environments.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Success",
  • "data": {
    },
  • "meta": {
    }
}