{
  "openapi": "3.1.1",
  "info": {
    "title": "SheetsDB API",
    "version": "0.2.0",
    "description": "Read a public Google Sheet as a JSON array.",
    "contact": {
      "name": "Zainul Ariffin",
      "url": "https://www.sheetsdb.io/about"
    },
    "license": {
      "name": "All rights reserved",
      "identifier": "LicenseRef-All-Rights-Reserved"
    }
  },
  "servers": [
    {
      "url": "https://www.sheetsdb.io",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v1/getsheet": {
      "post": {
        "operationId": "getSheet",
        "summary": "Read a public Google Sheet as JSON",
        "description": "Accepts a public shared URL, a published-to-web URL, or a spreadsheet ID.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetSheetRequest"
              },
              "examples": {
                "sharedSheet": {
                  "summary": "Shared Google Sheet with headers",
                  "value": {
                    "sheetRef": "https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit?usp=sharing",
                    "hasHeader": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sheet rows returned as JSON.",
            "headers": {
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "X-Request-ID": { "$ref": "#/components/headers/RequestId" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "example": [
                  {
                    "name": "Ada",
                    "role": "Engineer"
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid request or inaccessible Sheet.",
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "description": "The bearer API key is missing, invalid, or revoked.",
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "description": "The Sheet exceeded an enforced row or response-size limit.",
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "description": "The API key exceeded its enforced request allowance.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": { "type": "integer" }
              },
              "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" },
              "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" },
              "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" },
              "X-Request-ID": { "$ref": "#/components/headers/RequestId" }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "502": {
            "description": "Google Sheets returned an unusable response.",
            "$ref": "#/components/responses/Error"
          },
          "504": {
            "description": "Google Sheets did not respond before the upstream timeout.",
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "SheetsDB API key",
        "description": "Create an API key in the SheetsDB dashboard."
      }
    },
    "schemas": {
      "GetSheetRequest": {
        "type": "object",
        "required": ["sheetRef"],
        "properties": {
          "sheetRef": {
            "type": "string",
            "minLength": 1,
            "description": "A public shared URL, a published-to-web URL, or a spreadsheet ID."
          },
          "hasHeader": {
            "type": "boolean",
            "default": false,
            "description": "Use the first row as object keys."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "code": {
            "type": "string",
            "enum": [
              "UNAUTHORIZED",
              "INVALID_REQUEST",
              "SHEET_UNAVAILABLE",
              "RESPONSE_TOO_LARGE",
              "ROW_LIMIT_EXCEEDED",
              "RATE_LIMITED",
              "GOOGLE_REQUEST_FAILED",
              "GOOGLE_REQUEST_TIMEOUT"
            ]
          }
        }
      }
    },
    "headers": {
      "RateLimitLimit": {
        "description": "Maximum requests in the current fixed window.",
        "schema": { "type": "integer" }
      },
      "RateLimitRemaining": {
        "description": "Requests remaining in the current fixed window.",
        "schema": { "type": "integer" }
      },
      "RateLimitReset": {
        "description": "Unix timestamp in seconds when the current window resets.",
        "schema": { "type": "integer" }
      },
      "RequestId": {
        "description": "Opaque identifier for tracing one request.",
        "schema": { "type": "string" }
      }
    },
    "responses": {
      "Error": {
        "description": "Request failed.",
        "headers": {
          "X-Request-ID": { "$ref": "#/components/headers/RequestId" }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/Error" }
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "SheetsDB API reference",
    "url": "https://www.sheetsdb.io/docs/api-reference"
  }
}