{
  "openapi": "3.1.0",
  "info": {
    "title": "Speconaut API",
    "version": "0.0.0-draft",
    "description": "Draft-only API contract for future Speconaut product question answering, sessions, product memory, and authentication. No public API endpoint is available yet."
  },
  "servers": [
    {
      "url": "https://api.speconaut.com",
      "description": "Future production API placeholder"
    }
  ],
  "paths": {
    "/v1/ask": {
      "post": {
        "summary": "Ask a product question",
        "description": "Planned endpoint for product questions, comparisons, and follow-up context grounded in Speconaut product memory.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AskRequest"
              }
            }
          }
        },
        "responses": {
          "501": {
            "description": "Not implemented"
          }
        }
      }
    },
    "/v1/products/search": {
      "post": {
        "summary": "Search product memory",
        "description": "Planned endpoint for matching products by name, model number, alias, category, and source trace.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductSearchRequest"
              }
            }
          }
        },
        "responses": {
          "501": {
            "description": "Not implemented"
          }
        }
      }
    },
    "/v1/products/{id}": {
      "get": {
        "summary": "Get product memory",
        "description": "Planned endpoint for normalized product identity, variants, specifications, and source traces.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "501": {
            "description": "Not implemented"
          }
        }
      }
    },
    "/v1/sessions": {
      "post": {
        "summary": "Create a conversation session",
        "description": "Planned endpoint for creating web, retail, device, or partner sessions.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionCreateRequest"
              }
            }
          }
        },
        "responses": {
          "501": {
            "description": "Not implemented"
          }
        }
      }
    },
    "/v1/auth/sms/request": {
      "post": {
        "summary": "Request an SMS verification code",
        "description": "Planned placeholder. No SMS provider is connected.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsRequest"
              }
            }
          }
        },
        "responses": {
          "501": {
            "description": "Not implemented"
          }
        }
      }
    },
    "/v1/auth/sms/verify": {
      "post": {
        "summary": "Verify an SMS code",
        "description": "Planned placeholder for binding a verified phone number to a Speconaut account.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SmsVerifyRequest"
              }
            }
          }
        },
        "responses": {
          "501": {
            "description": "Not implemented"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AskRequest": {
        "type": "object",
        "required": ["question"],
        "properties": {
          "question": {
            "type": "string"
          },
          "locale": {
            "type": "string",
            "default": "en-US"
          },
          "session_id": {
            "type": "string"
          },
          "context": {
            "type": "object",
            "properties": {
              "source": {
                "type": "string",
                "default": "specifications.global"
              },
              "product_ids": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "previous": {
                "type": "string"
              }
            },
            "additionalProperties": true
          },
          "answer_format": {
            "type": "string",
            "enum": ["markdown", "json", "plain_text"],
            "default": "markdown"
          }
        },
        "additionalProperties": false
      },
      "ProductSearchRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10
          }
        },
        "additionalProperties": false
      },
      "SessionCreateRequest": {
        "type": "object",
        "properties": {
          "client_type": {
            "type": "string",
            "enum": ["web", "retail", "device", "partner"],
            "default": "web"
          },
          "locale": {
            "type": "string",
            "default": "en-US"
          }
        },
        "additionalProperties": false
      },
      "SmsRequest": {
        "type": "object",
        "required": ["phone_number"],
        "properties": {
          "phone_number": {
            "type": "string"
          },
          "channel": {
            "type": "string",
            "enum": ["sms"],
            "default": "sms"
          }
        },
        "additionalProperties": false
      },
      "SmsVerifyRequest": {
        "type": "object",
        "required": ["phone_number", "code"],
        "properties": {
          "phone_number": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  }
}