{
  "openapi": "3.1.0",
  "info": {
    "title": "SnowLeopard API",
    "description": "Natural language querying capabilities over structured data",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.snowleopard.ai",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/datafiles/{datafile_id}/retrieve": {
      "post": {
        "summary": "Retrieve complete query results",
        "description": "Execute a natural language query against a Playground datafile and return the retrieved data.",
        "operationId": "retrieve",
        "x-codeSamples": [
          {
            "lang": "Python",
            "label": "Asynchronous",
            "source": "from snowleopard import AsyncSnowLeopardClient\n\nasync def main():\n    client = AsyncSnowLeopardClient(api_key=\"{api_key}\")\n    response = await client.retrieve(\n        datafile_id=\"{datafile_id}\",\n        user_query=\"How many superheroes are there?\"\n    )\n    print(response.data)"
          },
          {
            "lang": "Python",
            "label": "Synchronous",
            "source": "from snowleopard import SnowLeopardClient\n\nclient = SnowLeopardClient(api_key=\"{api_key}\")\nresponse = client.retrieve(\n    datafile_id=\"{datafile_id}\",\n    user_query=\"How many superheroes are there?\"\n)\nprint(response.data)"
          },
          {
            "lang": "TypeScript",
            "label": "TypeScript",
            "source": "import { SnowLeopardClient } from '@snowleopard-ai/client';\n\nconst client = new SnowLeopardClient({\n    apiKey: 'your-api-key'\n});\n\nconst response = await client.retrieve({\n    datafileId: 'your-datafile-id',\n    userQuery: 'How many superheroes are there?'\n});\n\nconsole.log(response.data);\nawait client.close();\n"
          }
        ],
        "parameters": [
          {
            "name": "datafile_id",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the datafile to query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userQuery"
                ],
                "properties": {
                  "userQuery": {
                    "type": "string",
                    "description": "Natural language query to execute against the Playground datafile",
                    "example": "How many superheroes are there?"
                  },
                  "knownData": {
                    "type": "object",
                    "description": "Optional key-value pairs to provide additional context for Snow Leopard to use when answering the question.",
                    "additionalProperties": true,
                    "example": {
                      "user_id": "12345",
                      "company_name": "Acme Corp"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful query execution",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetrieveResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "409": {
            "description": "Query execution error (e.g. invalid SQL generated)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "__type__",
                    "callId",
                    "responseStatus",
                    "description"
                  ],
                  "properties": {
                    "__type__": {
                      "type": "string",
                      "enum": [
                        "apiError"
                      ],
                      "description": "Type discriminator"
                    },
                    "callId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique identifier for this API call"
                    },
                    "responseStatus": {
                      "type": "string",
                      "enum": [
                        "UNABLE_TO_UNDERSTAND_QUESTION",
                        "NOT_FOUND_IN_SCHEMA",
                        "INTERNAL_SERVER_ERROR",
                        "AUTHORIZATION_FAILED",
                        "LLM_ERROR",
                        "LLM_TOKEN_LIMIT_REACHED",
                        "DB_ERROR",
                        "DB_CONNECTION_ERROR",
                        "DB_SYNTAX_ERROR"
                      ],
                      "description": "Status of the response"
                    },
                    "description": {
                      "type": "string",
                      "description": "Error description"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/datafiles/{datafile_id}/response": {
      "post": {
        "summary": "Stream query results",
        "description": "Execute a natural language query and return the summarized results in natural language.",
        "operationId": "response",
        "x-codeSamples": [
          {
            "lang": "Python",
            "label": "Asynchronous",
            "source": "from snowleopard import AsyncSnowLeopardClient\n\nasync def main():\n    client = AsyncSnowLeopardClient(api_key=\"{api_key}\")\n    async for response in client.response(\n        datafile_id=\"{datafile_id}\",\n        user_query=\"How many superheroes are there?\"\n    ):\n        print(response)"
          },
          {
            "lang": "Python",
            "label": "Synchronous",
            "source": "from snowleopard import SnowLeopardClient\n\nclient = SnowLeopardClient(api_key=\"{api_key}\")\nfor response in client.response(\n        datafile_id=\"{datafile_id}\",\n        user_query=\"How many superheroes are there?\"\n):\n    print(response)"
          },
          {
            "lang": "TypeScript",
            "label": "TypeScript",
            "source": "import { SnowLeopardClient } from '@snowleopard-ai/client';\n\nconst client = new SnowLeopardClient({\n    apiKey: 'your-api-key'\n});\n\nfor await (const chunk of client.response({\n    datafileId: 'your-datafile-id',\n    userQuery: 'How many superheroes are there?'\n})) {\n    console.log(chunk);\n}\n\nawait client.close();\n"
          }
        ],
        "parameters": [
          {
            "name": "datafile_id",
            "in": "path",
            "required": true,
            "description": "Unique identifier for the Playground datafile to query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "userQuery"
                ],
                "properties": {
                  "userQuery": {
                    "type": "string",
                    "description": "Natural language query to execute against the Playground datafile",
                    "example": "How many superheroes are there?"
                  },
                  "knownData": {
                    "type": "object",
                    "description": "Optional key-value pairs to provide additional context for Snow Leopard to use when answering the question.",
                    "additionalProperties": true,
                    "example": {
                      "user_id": "12345",
                      "company_name": "Acme Corp"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Streaming response with newline-delimited JSON objects",
            "content": {
              "application/json": {
                "schema": {
                  "description": "Stream of JSON objects, one per line, in order: ResponseStart, ResponseData, ResponseLLMResult (or EarlyTermination)",
                  "oneOf": [
                    {
                      "title": "responseStart",
                      "$ref": "#/components/schemas/ResponseStart"
                    },
                    {
                      "title": "responseData",
                      "$ref": "#/components/schemas/ResponseData"
                    },
                    {
                      "title": "responseResult",
                      "$ref": "#/components/schemas/ResponseLLMResult"
                    },
                    {
                      "title": "earlyTermination",
                      "$ref": "#/components/schemas/EarlyTermination"
                    }
                  ],
                  "discriminator": {
                    "propertyName": "__type__",
                    "mapping": {
                      "responseStart": "#/components/schemas/ResponseStart",
                      "responseData": "#/components/schemas/ResponseData",
                      "responseResult": "#/components/schemas/ResponseLLMResult",
                      "earlyTermination": "#/components/schemas/EarlyTermination"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/response": {
      "post": {
        "x-codeSamples": [
          {
            "lang": "Python",
            "label": "Synchronous",
            "source": "from snowleopard import SnowLeopardClient\n\nclient = SnowLeopardClient(api_key=\"{api_key}\")\nfor response in client.response(\n        datafile_id=\"{datafile_id}\",\n        user_query=\"How many superheroes are there?\"\n):\n    print(response)"
          },
          {
            "lang": "Python",
            "label": "Asynchronous",
            "source": "from snowleopard import AsyncSnowLeopardClient\n\nasync def main():\n    client = AsyncSnowLeopardClient(api_key=\"{api_key}\")\n    async for response in client.response(\n        datafile_id=\"{datafile_id}\",\n        user_query=\"How many superheroes are there?\"\n    ):\n        print(response)"
          },
          {
            "lang": "TypeScript",
            "label": "TypeScript",
            "source": "import { SnowLeopardClient } from '@snowleopard-ai/client';\n\nconst client = new SnowLeopardClient({\n    apiKey: 'your-api-key'\n});\n\nfor await (const chunk of client.response({\n    datafileId: 'your-datafile-id',\n    userQuery: 'How many superheroes are there?'\n})) {\n    console.log(chunk);\n}\n\nawait client.close();\n"
          }
        ]
      }
    },
    "/retrieve": {
      "post": {
        "x-codeSamples": [
          {
            "lang": "Python",
            "label": "Synchronous",
            "source": "from snowleopard import SnowLeopardClient\n\nclient = SnowLeopardClient(api_key=\"{api_key}\")\nresponse = client.retrieve(\n    datafile_id=\"{datafile_id}\",\n    user_query=\"How many superheroes are there?\"\n)\nprint(response.data)"
          },
          {
            "lang": "Python",
            "label": "Asynchronous",
            "source": "from snowleopard import AsyncSnowLeopardClient\n\nasync def main():\n    client = AsyncSnowLeopardClient(api_key=\"{api_key}\")\n    response = await client.retrieve(\n        datafile_id=\"{datafile_id}\",\n        user_query=\"How many superheroes are there?\"\n    )\n    print(response.data)"
          },
          {
            "lang": "TypeScript",
            "label": "TypeScript",
            "source": "import { SnowLeopardClient } from '@snowleopard-ai/client';\n\nconst client = new SnowLeopardClient({\n    apiKey: 'your-api-key'\n});\n\nconst response = await client.retrieve({\n    datafileId: 'your-datafile-id',\n    userQuery: 'How many superheroes are there?'\n});\n\nconsole.log(response.data);\nawait client.close();\n"
          }
        ]
      }
    }
  },
  "components": {
    "responses": {
      "Unauthorized": {
        "description": "Authorization error (e.g. invalid or missing API key)",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/APIError"
                },
                {
                  "properties": {
                    "code": {
                      "type": "integer",
                      "enum": [
                        401
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found error. The requested datafile does not exist.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/APIError"
                },
                {
                  "properties": {
                    "code": {
                      "type": "integer",
                      "enum": [
                        404
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal server error. Retry your request, and contact your Snow Leopard admin if the issue continues.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/APIError"
                },
                {
                  "properties": {
                    "code": {
                      "type": "integer",
                      "enum": [
                        500
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "Service unavailable. The server is down for scheduled maintenance. Retry your request shortly.",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/APIError"
                },
                {
                  "properties": {
                    "code": {
                      "type": "integer",
                      "enum": [
                        503
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      },
      "BadRequest": {
        "description": "Bad request error (e.g. missing required request body field)",
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/APIError"
                },
                {
                  "properties": {
                    "code": {
                      "type": "integer",
                      "enum": [
                        400
                      ]
                    }
                  }
                }
              ]
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "api_key",
        "description": "Bearer authentication header of the form `Bearer <api_key>`, where `<api_key>` is your auth API key. [Create an api_key](https://auth.snowleopard.ai/account/api_keys)"
      }
    },
    "schemas": {
      "RetrieveResponse": {
        "type": "object",
        "required": [
          "__type__",
          "callId",
          "data",
          "responseStatus"
        ],
        "properties": {
          "__type__": {
            "type": "string",
            "enum": [
              "retrieveResponse"
            ],
            "description": "Type discriminator"
          },
          "callId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this API call"
          },
          "data": {
            "type": "array",
            "description": "Array of query results or errors",
            "items": {
              "oneOf": [
                {
                  "title": "schemaData",
                  "$ref": "#/components/schemas/SchemaData"
                },
                {
                  "title": "errorSchemaData",
                  "$ref": "#/components/schemas/ErrorSchemaData"
                }
              ]
            }
          },
          "responseStatus": {
            "type": "string",
            "enum": [
              "SUCCESS"
            ],
            "description": "Status of the API response"
          }
        }
      },
      "APIError": {
        "type": "object",
        "required": [
          "__type__",
          "callId",
          "code",
          "description"
        ],
        "properties": {
          "__type__": {
            "type": "string",
            "enum": [
              "apiError"
            ],
            "description": "Type discriminator"
          },
          "callId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this API call"
          },
          "code": {
            "type": "integer",
            "description": "HTTP status code of the response"
          },
          "description": {
            "type": "string",
            "description": "Error description"
          }
        }
      },
      "SchemaData": {
        "type": "object",
        "required": [
          "__type__",
          "schemaId",
          "schemaType",
          "query",
          "rows",
          "querySummary",
          "rowMax",
          "isTrimmed"
        ],
        "properties": {
          "__type__": {
            "type": "string",
            "enum": [
              "schemaData"
            ],
            "description": "Type discriminator"
          },
          "schemaId": {
            "type": "string",
            "description": "Identifier for the schema/database queried"
          },
          "schemaType": {
            "type": "string",
            "description": "Type of database (e.g. SQLite, PostgreSQL)",
            "example": "SQLite"
          },
          "query": {
            "type": "string",
            "description": "Generated SQL query that was executed"
          },
          "rows": {
            "type": "array",
            "description": "Result rows from the query",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "querySummary": {
            "type": "object",
            "description": "Detailed explanation of the query",
            "properties": {
              "technical_details": {
                "type": "string",
                "description": "Technical explanation of the query logic"
              },
              "non_technical_explanation": {
                "type": "string",
                "description": "Plain language explanation for non-technical users"
              }
            }
          },
          "rowMax": {
            "type": "integer",
            "description": "Maximum number of rows that can be returned"
          },
          "isTrimmed": {
            "type": "boolean",
            "description": "Whether the result set was trimmed due to size limits"
          },
          "callId": {
            "type": "string",
            "format": "uuid",
            "description": "Call identifier (optional)"
          }
        }
      },
      "ErrorSchemaData": {
        "type": "object",
        "required": [
          "__type__",
          "schemaType",
          "schemaId",
          "query",
          "error",
          "querySummary"
        ],
        "properties": {
          "__type__": {
            "type": "string",
            "enum": [
              "errorSchemaData"
            ],
            "description": "Type discriminator"
          },
          "schemaId": {
            "type": "string",
            "description": "Identifier for the schema/database queried"
          },
          "schemaType": {
            "type": "string",
            "description": "Type of database",
            "example": "SQLite"
          },
          "query": {
            "type": "string",
            "description": "Generated SQL query that failed"
          },
          "error": {
            "type": "string",
            "description": "Error message from query execution"
          },
          "querySummary": {
            "type": "object",
            "description": "Explanation of what the query was attempting to do",
            "properties": {
              "technical_details": {
                "type": "string",
                "description": "Technical explanation of the query logic"
              },
              "non_technical_explanation": {
                "type": "string",
                "description": "Plain language explanation for non-technical users"
              }
            }
          },
          "datastoreExceptionInfo": {
            "type": "string",
            "nullable": true,
            "description": "Additional datastore-specific error information"
          },
          "callId": {
            "type": "string",
            "format": "uuid",
            "description": "Call identifier (optional)"
          }
        }
      },
      "ResponseStart": {
        "type": "object",
        "required": [
          "__type__",
          "callId",
          "userQuery"
        ],
        "properties": {
          "__type__": {
            "type": "string",
            "enum": [
              "responseStart"
            ],
            "description": "Type discriminator"
          },
          "callId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this API call"
          },
          "userQuery": {
            "type": "string",
            "description": "The original user query"
          }
        }
      },
      "ResponseData": {
        "type": "object",
        "required": [
          "__type__",
          "callId",
          "data"
        ],
        "properties": {
          "__type__": {
            "type": "string",
            "enum": [
              "responseData"
            ],
            "description": "Type discriminator"
          },
          "callId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this API call"
          },
          "data": {
            "type": "array",
            "description": "Array of query results or errors",
            "items": {
              "oneOf": [
                {
                  "title": "schemaData",
                  "$ref": "#/components/schemas/SchemaData"
                },
                {
                  "title": "errorSchemaData",
                  "$ref": "#/components/schemas/ErrorSchemaData"
                }
              ]
            }
          }
        }
      },
      "ResponseLLMResult": {
        "type": "object",
        "required": [
          "__type__",
          "callId",
          "responseStatus",
          "llmResponse"
        ],
        "properties": {
          "__type__": {
            "type": "string",
            "enum": [
              "responseResult"
            ],
            "description": "Type discriminator"
          },
          "callId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this API call"
          },
          "responseStatus": {
            "$ref": "#/components/schemas/ResponseStatus"
          },
          "llmResponse": {
            "type": "object",
            "description": "LLM-generated response with natural language answer",
            "properties": {
              "status": {
                "type": "string",
                "description": "Status of LLM processing"
              },
              "data": {
                "type": "object",
                "additionalProperties": true,
                "description": "Extracted key data points"
              },
              "complete_answer": {
                "type": "string",
                "description": "Natural language answer to the user's query"
              },
              "analysis": {
                "type": "object",
                "additionalProperties": true,
                "description": "Analysis and insights"
              },
              "explanation": {
                "type": "object",
                "properties": {
                  "howDataWasUsed": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Explanation of how the data was processed"
                  }
                }
              },
              "comments": {
                "type": "string",
                "description": "Additional comments about the result"
              }
            }
          }
        }
      },
      "EarlyTermination": {
        "type": "object",
        "required": [
          "__type__",
          "callId",
          "responseStatus",
          "reason",
          "extra"
        ],
        "properties": {
          "__type__": {
            "type": "string",
            "enum": [
              "earlyTermination"
            ],
            "description": "Type discriminator"
          },
          "callId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for this API call"
          },
          "responseStatus": {
            "$ref": "#/components/schemas/ResponseStatus"
          },
          "reason": {
            "type": "string",
            "description": "Reason for early termination"
          },
          "extra": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional context about the termination"
          }
        }
      },
      "ResponseStatus": {
        "type": "string",
        "enum": [
          "SUCCESS",
          "BAD_REQUEST",
          "UNABLE_TO_UNDERSTAND_QUESTION",
          "NOT_FOUND_IN_SCHEMA",
          "INTERNAL_SERVER_ERROR",
          "AUTHORIZATION_FAILED",
          "LLM_ERROR",
          "LLM_TOKEN_LIMIT_REACHED",
          "DB_ERROR",
          "DB_CONNECTION_ERROR",
          "DB_SYNTAX_ERROR"
        ],
        "description": "Status of the API response"
      }
    }
  }
}