{
    "openapi": "3.1.0",
    "info": {
        "title": "MyTokenTracker API",
        "version": "1.1.0",
        "description": "Report LLM usage and cost for any provider (authenticated), and read the free, CC BY 4.0 open data (no auth): the AI Cost Index, community usage, and the model price catalog, as JSON or CSV.",
        "contact": {
            "url": "https://mytokentracker.io/docs"
        }
    },
    "servers": [
        {
            "url": "https://mytokentracker.io"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/api/v1/events": {
            "post": {
                "summary": "Report one usage event or a batch",
                "operationId": "createEvents",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "oneOf": [
                                    {
                                        "$ref": "#/components/schemas/Event"
                                    },
                                    {
                                        "type": "object",
                                        "required": [
                                            "events"
                                        ],
                                        "properties": {
                                            "events": {
                                                "type": "array",
                                                "maxItems": 500,
                                                "items": {
                                                    "$ref": "#/components/schemas/Event"
                                                }
                                            }
                                        }
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Created",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "created": {
                                            "type": "integer"
                                        },
                                        "total_cost": {
                                            "type": "number"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid or missing API token"
                    },
                    "422": {
                        "description": "Validation failed"
                    },
                    "429": {
                        "description": "Daily log limit reached"
                    }
                }
            }
        },
        "/api/v1/data": {
            "get": {
                "summary": "Discover open datasets, row counts, and freshness",
                "operationId": "dataIndex",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/api/v1/data/schema": {
            "get": {
                "summary": "Field dictionary for every open dataset",
                "operationId": "dataSchema",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/api/v1/data/cost-index": {
            "get": {
                "summary": "AI Cost Index series (JSON or CSV)",
                "operationId": "dataCostIndex",
                "security": [],
                "parameters": [
                    {
                        "name": "index",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "frontier",
                                "budget",
                                "all"
                            ]
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "json",
                                "csv"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/api/v1/data/community": {
            "get": {
                "summary": "Anonymized community usage rollup (JSON or CSV)",
                "operationId": "dataCommunity",
                "security": [],
                "parameters": [
                    {
                        "name": "dimension",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "total",
                                "provider",
                                "model",
                                "platform",
                                "use_case"
                            ]
                        }
                    },
                    {
                        "name": "from",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "to",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "json",
                                "csv"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/api/v1/data/models": {
            "get": {
                "summary": "Model price catalog (JSON or CSV)",
                "operationId": "dataModels",
                "security": [],
                "parameters": [
                    {
                        "name": "provider",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "active",
                        "in": "query",
                        "schema": {
                            "type": "boolean"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "format",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "json",
                                "csv"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "description": "Your API token from https://mytokentracker.io/settings (format: mtt_...)."
            }
        },
        "schemas": {
            "Event": {
                "type": "object",
                "required": [
                    "provider",
                    "model",
                    "input_tokens",
                    "output_tokens"
                ],
                "properties": {
                    "provider": {
                        "type": "string",
                        "example": "openai",
                        "description": "Provider slug, e.g. anthropic, openai, google, mistral."
                    },
                    "model": {
                        "type": "string",
                        "example": "gpt-4o"
                    },
                    "input_tokens": {
                        "type": "integer",
                        "minimum": 0,
                        "example": 1200
                    },
                    "output_tokens": {
                        "type": "integer",
                        "minimum": 0,
                        "example": 350
                    },
                    "cache_read_tokens": {
                        "type": "integer",
                        "minimum": 0,
                        "nullable": true
                    },
                    "cache_write_tokens": {
                        "type": "integer",
                        "minimum": 0,
                        "nullable": true
                    },
                    "reasoning_tokens": {
                        "type": "integer",
                        "minimum": 0,
                        "nullable": true
                    },
                    "total_cost": {
                        "type": "number",
                        "nullable": true,
                        "description": "If supplied, stored as the actual cost. Omit to have it estimated from the price catalog."
                    },
                    "latency_ms": {
                        "type": "integer",
                        "nullable": true,
                        "description": "Response latency in milliseconds (powers speed comparisons)."
                    },
                    "success": {
                        "type": "boolean",
                        "nullable": true,
                        "description": "Did the call/task succeed? Powers cost-per-success and value-for-money views."
                    },
                    "quality_score": {
                        "type": "number",
                        "nullable": true,
                        "description": "Optional quality/eval score (your scale, e.g. 0..1 or 0..100). Enables quality-adjusted comparisons."
                    },
                    "status": {
                        "type": "string",
                        "nullable": true,
                        "description": "ok | error | timeout | ... (reliability)."
                    },
                    "currency": {
                        "type": "string",
                        "default": "USD"
                    },
                    "platform": {
                        "type": "string",
                        "example": "openai-api",
                        "description": "Tool/SDK that produced the usage, e.g. claude-code, cursor, openai-api."
                    },
                    "use_case": {
                        "type": "string",
                        "example": "chat",
                        "description": "coding, chat, agent, rag, batch, ..."
                    },
                    "session_id": {
                        "type": "string",
                        "nullable": true
                    },
                    "project": {
                        "type": "string",
                        "nullable": true
                    },
                    "occurred_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                    },
                    "metadata": {
                        "type": "object",
                        "nullable": true,
                        "additionalProperties": true
                    }
                }
            }
        }
    }
}