{
  "openapi": "3.1.0",
  "info": {
    "title": "MazoCards Temporary Deck API",
    "version": "1.0.0",
    "summary": "Create a study-ready flashcard deck with one request",
    "description": "Preferred integration for AI assistants that generate flashcards. POST the complete deck, read the returned url, and give that link to the user. The user can study immediately without an account or file upload."
  },
  "servers": [
    {
      "url": "https://api.mazocards.com"
    }
  ],
  "externalDocs": {
    "description": "MazoCards guide for AI assistants",
    "url": "https://mazocards.com/agents"
  },
  "tags": [
    {
      "name": "Discovery",
      "description": "Learn how an AI assistant should use the API."
    },
    {
      "name": "Decks",
      "description": "Create and read temporary flashcard decks."
    }
  ],
  "paths": {
    "/": {
      "get": {
        "operationId": "getApiOverview",
        "tags": ["Discovery"],
        "summary": "Get agent integration instructions",
        "description": "Returns the preferred MazoCards workflow and links to the complete public documentation.",
        "security": [],
        "responses": {
          "200": {
            "description": "API overview"
          }
        }
      }
    },
    "/v1/decks": {
      "post": {
        "operationId": "createTemporaryDeck",
        "tags": ["Decks"],
        "summary": "Create a temporary study deck",
        "description": "Preferred action for AI assistants. Creates a deck with 1-100 cards. Return the response url to the user; it opens immediately and expires after six hours.",
        "x-openai-isConsequential": false,
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeck"
              },
              "examples": {
                "frenchTravel": {
                  "value": {
                    "name": "French travel basics",
                    "description": "Useful phrases for a first trip.",
                    "language": "fr-FR",
                    "tags": ["french", "travel"],
                    "cards": [
                      {
                        "front": "Où est la gare ?",
                        "back": "Where is the station?",
                        "context": "Asking for directions",
                        "tags": ["questions"]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deck created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateDeckResponse"
                },
                "example": {
                  "id": "0123456789abcdef0123456789abcdef",
                  "url": "https://mazocards.com/d/0123456789abcdef0123456789abcdef",
                  "expiresAt": "2026-06-13T18:00:00.000Z",
                  "deck": {
                    "name": "French travel basics",
                    "cardCount": 1
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid deck"
          },
          "429": {
            "description": "Creation rate limit exceeded"
          },
          "413": {
            "description": "Request body exceeds 256 KB"
          },
          "415": {
            "description": "Content-Type must be application/json"
          },
          "503": {
            "description": "Temporary deck service unavailable"
          }
        }
      }
    },
    "/v1/decks/{id}": {
      "get": {
        "operationId": "getTemporaryDeck",
        "tags": ["Decks"],
        "summary": "Read a temporary deck",
        "security": [],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-f0-9]{32}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Temporary deck"
          },
          "404": {
            "description": "Deck not found or expired"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Card": {
        "type": "object",
        "required": ["front", "back"],
        "properties": {
          "front": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          },
          "back": {
            "type": "string",
            "minLength": 1,
            "maxLength": 4000
          },
          "context": {
            "type": "string",
            "maxLength": 4000
          },
          "tags": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "string",
              "maxLength": 32
            }
          }
        }
      },
      "CreateDeck": {
        "type": "object",
        "required": ["name", "cards"],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "description": {
            "type": "string",
            "maxLength": 500
          },
          "language": {
            "type": "string",
            "description": "The TTS language for the deck. Use a single BCP-47 code for the back (e.g. 'fr-FR', defaults front to 'es-ES'), or use 'frontCode|backCode' to explicitly set both TTS voices (e.g. 'es-ES|fr-FR'). Supported codes: fr-FR, en-US, en-GB, es-ES, de-DE, it-IT, ja-JP, disabled."
          },
          "tags": {
            "type": "array",
            "maxItems": 20,
            "items": {
              "type": "string",
              "maxLength": 32
            }
          },
          "cards": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/Card"
            }
          }
        }
      },
      "CreateDeckResponse": {
        "type": "object",
        "required": ["id", "url", "expiresAt", "deck"],
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "deck": {
            "type": "object",
            "required": ["name", "cardCount"],
            "properties": {
              "name": {
                "type": "string"
              },
              "cardCount": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  }
}