{
  "openapi": "3.1.0",
  "info": {
    "title": "tokentracker API",
    "version": "1.0.0",
    "description": "Public, keyless API for AI coding token usage by day, model, tool and machine. Reads are limited to 120 requests per minute per IP (edge-cached responses excluded); over the limit returns 429 with a Retry-After header.",
    "license": {
      "name": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://tokentracker.patrickbrown.dev/api/v1"
    }
  ],
  "paths": {
    "/users/{handle}": {
      "get": {
        "summary": "Profile summary",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bicrick"
            }
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "30d"
            },
            "description": "all | ytd | Nd (e.g. 30d) | YYYY"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive start day; overrides range"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive end day"
          },
          {
            "name": "tools",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "claude-code,codex"
            },
            "description": "Comma-separated tool ids"
          },
          {
            "name": "models",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "anthropic/claude-opus-5-5"
            },
            "description": "Comma-separated model ids"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Profile"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/users/{handle}/usage": {
      "get": {
        "summary": "Usage over time",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bicrick"
            }
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "30d"
            },
            "description": "all | ytd | Nd (e.g. 30d) | YYYY"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive start day; overrides range"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive end day"
          },
          {
            "name": "tools",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "claude-code,codex"
            },
            "description": "Comma-separated tool ids"
          },
          {
            "name": "models",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "anthropic/claude-opus-5-5"
            },
            "description": "Comma-separated model ids"
          },
          {
            "name": "group",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "week",
                "month",
                "year",
                "total"
              ],
              "default": "day"
            }
          },
          {
            "name": "split",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "tool",
                "model"
              ]
            }
          },
          {
            "name": "fill",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": true
            },
            "description": "Include empty days in daily series"
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/users/{handle}/models": {
      "get": {
        "summary": "Per-model totals",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bicrick"
            }
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "30d"
            },
            "description": "all | ytd | Nd (e.g. 30d) | YYYY"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive start day; overrides range"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive end day"
          },
          {
            "name": "tools",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "claude-code,codex"
            },
            "description": "Comma-separated tool ids"
          },
          {
            "name": "models",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "anthropic/claude-opus-5-5"
            },
            "description": "Comma-separated model ids"
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/users/{handle}/tools": {
      "get": {
        "summary": "Per-tool totals",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bicrick"
            }
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "30d"
            },
            "description": "all | ytd | Nd (e.g. 30d) | YYYY"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive start day; overrides range"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive end day"
          },
          {
            "name": "tools",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "claude-code,codex"
            },
            "description": "Comma-separated tool ids"
          },
          {
            "name": "models",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "anthropic/claude-opus-5-5"
            },
            "description": "Comma-separated model ids"
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ToolList"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/users/{handle}/heatmap": {
      "get": {
        "summary": "Calendar heatmap grid",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bicrick"
            }
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "30d"
            },
            "description": "all | ytd | Nd (e.g. 30d) | YYYY"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive start day; overrides range"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive end day"
          },
          {
            "name": "tools",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "claude-code,codex"
            },
            "description": "Comma-separated tool ids"
          },
          {
            "name": "models",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "anthropic/claude-opus-5-5"
            },
            "description": "Comma-separated model ids"
          },
          {
            "name": "levels",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 2,
              "maximum": 10,
              "default": 5
            }
          },
          {
            "name": "weekStart",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "sun",
                "mon"
              ],
              "default": "sun"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Heatmap"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/users/{handle}/stats": {
      "get": {
        "summary": "Summary statistics",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bicrick"
            }
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "30d"
            },
            "description": "all | ytd | Nd (e.g. 30d) | YYYY"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive start day; overrides range"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive end day"
          },
          {
            "name": "tools",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "claude-code,codex"
            },
            "description": "Comma-separated tool ids"
          },
          {
            "name": "models",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "anthropic/claude-opus-5-5"
            },
            "description": "Comma-separated model ids"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stats"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    },
    "/users/{handle}/devices": {
      "get": {
        "summary": "Per-machine totals",
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "bicrick"
            }
          },
          {
            "name": "range",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "30d"
            },
            "description": "all | ytd | Nd (e.g. 30d) | YYYY"
          },
          {
            "name": "from",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive start day; overrides range"
          },
          {
            "name": "to",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "description": "Inclusive end day"
          },
          {
            "name": "tools",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "claude-code,codex"
            },
            "description": "Comma-separated tool ids"
          },
          {
            "name": "models",
            "in": "query",
            "schema": {
              "type": "string",
              "example": "anthropic/claude-opus-5-5"
            },
            "description": "Comma-separated model ids"
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceList"
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "description": "Rate limited. Retry after the number of seconds in the Retry-After header."
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "Invalid parameter",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Unknown user or resource",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Totals": {
        "type": "object",
        "properties": {
          "tokens": {
            "type": "integer"
          },
          "input": {
            "type": "integer"
          },
          "output": {
            "type": "integer"
          },
          "reasoning": {
            "type": "integer"
          },
          "cacheRead": {
            "type": "integer"
          },
          "cacheWrite": {
            "type": "integer"
          },
          "responses": {
            "type": "integer"
          }
        }
      },
      "Profile": {
        "type": "object",
        "properties": {
          "handle": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "totals": {
            "$ref": "#/components/schemas/Totals"
          },
          "thisYear": {
            "$ref": "#/components/schemas/Totals"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "models": {
            "type": "integer"
          },
          "devices": {
            "type": "integer"
          },
          "firstDay": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "lastDay": {
            "type": [
              "string",
              "null"
            ],
            "format": "date"
          },
          "lastSync": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "links": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "UsageRow": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Totals"
          },
          {
            "type": "object",
            "properties": {
              "period": {
                "type": "string",
                "description": "YYYY-MM-DD (day/week start), YYYY-MM, YYYY or total"
              },
              "split": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer"
                }
              }
            }
          }
        ]
      },
      "Usage": {
        "type": "object",
        "properties": {
          "group": {
            "type": "string"
          },
          "split": {
            "type": [
              "string",
              "null"
            ]
          },
          "totals": {
            "$ref": "#/components/schemas/Totals"
          },
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/UsageRow"
            }
          }
        }
      },
      "Model": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Totals"
          },
          {
            "type": "object",
            "properties": {
              "model": {
                "type": "string"
              },
              "provider": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              },
              "tool": {
                "type": "string"
              },
              "share": {
                "type": "number"
              },
              "firstUsed": {
                "type": "string",
                "format": "date"
              },
              "lastUsed": {
                "type": "string",
                "format": "date"
              }
            }
          }
        ]
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          }
        }
      },
      "Tool": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Totals"
          },
          {
            "type": "object",
            "properties": {
              "tool": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "share": {
                "type": "number"
              },
              "models": {
                "type": "integer"
              },
              "firstUsed": {
                "type": "string",
                "format": "date"
              },
              "lastUsed": {
                "type": "string",
                "format": "date"
              }
            }
          }
        ]
      },
      "ToolList": {
        "type": "object",
        "properties": {
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Tool"
            }
          }
        }
      },
      "HeatmapDay": {
        "type": [
          "object",
          "null"
        ],
        "properties": {
          "date": {
            "type": "string",
            "format": "date"
          },
          "tokens": {
            "type": [
              "integer",
              "null"
            ]
          },
          "level": {
            "type": "integer"
          }
        }
      },
      "Heatmap": {
        "type": "object",
        "properties": {
          "range": {
            "type": "object",
            "properties": {
              "start": {
                "type": "string"
              },
              "end": {
                "type": "string"
              },
              "last": {
                "type": "string"
              }
            }
          },
          "levels": {
            "type": "integer"
          },
          "weekStart": {
            "type": "string"
          },
          "total": {
            "type": "integer"
          },
          "max": {
            "type": "integer"
          },
          "activeDays": {
            "type": "integer"
          },
          "months": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "week": {
                  "type": "integer"
                }
              }
            }
          },
          "weeks": {
            "type": "array",
            "items": {
              "type": "array",
              "minItems": 7,
              "maxItems": 7,
              "items": {
                "$ref": "#/components/schemas/HeatmapDay"
              }
            }
          }
        }
      },
      "Stats": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Totals"
          },
          {
            "type": "object",
            "properties": {
              "activeDays": {
                "type": "integer"
              },
              "firstDay": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "lastDay": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "busiestDay": {
                "type": [
                  "object",
                  "null"
                ],
                "properties": {
                  "date": {
                    "type": "string"
                  },
                  "tokens": {
                    "type": "integer"
                  }
                }
              },
              "longestStreak": {
                "type": "integer"
              },
              "currentStreak": {
                "type": "integer"
              },
              "averagePerActiveDay": {
                "type": "integer"
              },
              "today": {
                "type": "integer"
              },
              "thisMonth": {
                "type": "integer"
              },
              "topTool": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "topModel": {
                "type": [
                  "object",
                  "null"
                ]
              }
            }
          }
        ]
      },
      "Device": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Totals"
          },
          {
            "type": "object",
            "properties": {
              "device": {
                "type": "string"
              },
              "tools": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "lastSync": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "firstUsed": {
                "type": "string"
              },
              "lastUsed": {
                "type": "string"
              }
            }
          }
        ]
      },
      "DeviceList": {
        "type": "object",
        "properties": {
          "rows": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Device"
            }
          }
        }
      }
    }
  }
}
