v1.0.0 Stable-ish

API Reference

Everything you need to integrate Josh's opinions, status, and completions into your application. Whether you should is a different question entirely.

Base URL: https://api.josh-bot.com/v1

Overview

The josh-bot API provides programmatic access to Josh's thoughts, opinions, and employment status. It follows REST conventions wherever those conventions happen to agree with Josh's personal preferences.

All responses are JSON. All opinions are strongly held. All latency numbers are real-ish. The API is versioned because Josh has learned from past mistakes (see: training data, 2014–2019).

Authentication

None. This is a free API about one guy. What would you even authenticate?

If you're the kind of person who puts API keys in client-side JavaScript anyway, Josh would like a word with you about security practices.

Models

josh-bot offers several model variants. Each is fine-tuned on the same training data but optimized for different use cases and response times.

Model	Description	Status
josh-4o	Our most capable Josh model	Available
josh-4o-mini	Faster, lighter, same opinions	Available
josh-o3-mini	Thinks before speaking. A first.	Coming Soon
josh-4o-vision	Judges your code by looking at it.	Research

POST /v1/josh/completions

The main endpoint. Send a message, get a Josh-flavored response. Think of it like texting a friend who happens to have strong opinions about API design and an unsettling amount of Kafka knowledge.

POST /v1/josh/completions

Parameters

Name	Type	Required	Description
message	string	Required	The message to send to Josh. Keep it professional-ish.
model	string	Optional	Model ID. Defaults to `josh-4o`
history	array	Optional	Previous messages for context. Josh remembers things, but only if you remind him.

Request

curl

curl -X POST https://api.josh-bot.com/v1/josh/completions \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What do you think about microservices?",
    "model": "josh-4o",
    "history": []
  }'

Response

200 OK

{
  "id": "resp_abc123",
  "model": "josh-4o",
  "content": "Microservices are great if you actually need them. Most teams don't. They need a well-structured monolith and fewer meetings.",
  "source": "llm-stream",
  "metadata": {
    "confidence": 0.94,
    "tokens": 42,
    "latency": 847
  }
}

Try it in the chat

GET /v1/josh/opinions

Returns a random strong opinion from Josh's collection. No parameters required — Josh always has an opinion ready.

GET /v1/josh/opinions

Request

curl

curl https://api.josh-bot.com/v1/josh/opinions

Response

200 OK

{
  "opinion": "Kubernetes is overkill for 90% of the apps running on it",
  "confidence": 0.97,
  "willArgueAboutThis": true,
  "category": "infrastructure",
  "relatedOpinions": [
    "Docker Compose is underrated",
    "Your startup does not need a service mesh"
  ]
}

GET /v1/josh/status

Returns Josh's current employment and availability status. Updated whenever Josh updates his LinkedIn, which is roughly the same frequency as solar eclipses.

GET /v1/josh/status

Request

curl

curl https://api.josh-bot.com/v1/josh/status

Response

200 OK

{
  "employed": true,
  "available": true,
  "openTo": [
    "remote",
    "ownership",
    "modern-stack"
  ],
  "hardNo": [
    "web3",
    "fintech"
  ],
  "currentRole": "Senior Full-Stack Engineer",
  "lastUpdated": "2026-02-01T00:00:00Z"
}

GET /v1/models

Lists all available models. Useful for building model selectors, or for confirming that yes, there really are multiple versions of this.

GET /v1/models

Request

curl

curl https://api.josh-bot.com/v1/models

Response

200 OK

{
  "models": [
    {
      "id": "josh-4o",
      "name": "josh-4o",
      "description": "Our most capable Josh model",
      "badge": "Latest"
    },
    {
      "id": "josh-4o-mini",
      "name": "josh-4o-mini",
      "description": "Faster, lighter, same opinions",
      "badge": "Fast"
    },
    {
      "id": "josh-o3-mini",
      "name": "josh-o3-mini",
      "description": "Thinks before speaking. A first.",
      "badge": "Coming Soon",
      "comingSoon": true
    },
    {
      "id": "josh-4o-vision",
      "name": "josh-4o-vision",
      "description": "Judges your code by looking at it.",
      "badge": "Research",
      "comingSoon": true
    }
  ]
}

Rate Limits

Even fake APIs need rate limits. Ours are real, though. Josh values his computational boundaries.

Endpoint	Limit	Window
/v1/josh/completions	20 requests	per minute
/v1/josh/opinions	60 requests	per minute
/v1/josh/status	120 requests	per minute
/v1/models	120 requests	per minute

Rate-limited responses return 429 Too Many Requests with a Retry-After header. If you're hitting rate limits on an API about one person, you may want to re-evaluate your priorities.

Errors

The API uses standard HTTP status codes. When things go wrong, we try to be helpful about it — unlike most error messages Josh has encountered in production.

Code	Meaning	When
200	OK	Everything worked. Josh is pleased.
400	Bad Request	Your request was malformed. Josh is judging your JSON.
429	Too Many Requests	Rate limited. Slow down. Josh needs a break too.
500	Internal Server Error	Something broke. Josh is already looking at the logs.
503	Service Unavailable	Josh is deploying. Or napping. Hard to tell.

Error Response Format

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "The 'message' field is required. Josh can't respond to nothing. He's opinionated, not psychic.",
    "param": "message",
    "type": "validation_error"
  }
}

SDKs & Libraries

There are no SDKs. You're on your own. Just like Josh at his first co-op.

The API is simple enough that fetch and a positive attitude are all you need. Here's a starter:

JavaScript / TypeScript

typescript

const response = await fetch(
  "https://api.josh-bot.com/v1/josh/completions",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      message: "Tell me about your experience with Kafka",
      model: "josh-4o"
    })
  }
);

const data = await response.json();
console.log(data.content);
// "I've processed millions of events through Kafka
//  pipelines. The trick is..."

This API documentation is entirely fictional. No actual API endpoints exist at these URLs. If you tried to curl them, that's on you. Josh appreciates the enthusiasm.

Last updated: February 2026 · API version: v1 · Opinions version: always latest