{
 "openapi": "3.1.0",
 "info": {
  "title": "PublicFeed API",
  "version": "1.0.0",
  "summary": "Official public updates from India, explained, as data.",
  "description": "Orders, notifications, press releases, Bills, consultations, audit reports, deadlines, weather alerts and tenders from Indian public bodies, with plain-language summaries and links to the official originals. No key is needed for the free plan. Paid keys go in the Authorization header as a Bearer token. Data: PublicFeed (https://publicfeed.in), summarising official documents linked in each record. Summaries are AI-generated and not legal advice; the official original is the authority.",
  "termsOfService": "https://publicfeed.in/terms",
  "contact": {
   "name": "PublicFeed",
   "url": "https://publicfeed.in/developers"
  },
  "license": {
   "name": "PublicFeed data terms",
   "url": "https://publicfeed.in/terms#data-licence"
  }
 },
 "servers": [
  {
   "url": "https://publicfeed.in/api/v1"
  }
 ],
 "externalDocs": {
  "url": "https://publicfeed.in/developers"
 },
 "security": [
  {},
  {
   "bearer": []
  },
  {
   "apiKey": []
  }
 ],
 "paths": {
  "/updates": {
   "get": {
    "summary": "Search explained updates",
    "description": "Newest first. The free plan covers the last 30 days.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Words that must all appear.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "state",
      "in": "query",
      "required": false,
      "description": "State or union territory code (jk, mh, ka, ...); 'in' for national items only.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "topic",
      "in": "query",
      "required": false,
      "description": "Reader topic or pipeline topic, e.g. Budget.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "source",
      "in": "query",
      "required": false,
      "description": "Source key, e.g. pib, cag_reports.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "type",
      "in": "query",
      "required": false,
      "description": "Document type, e.g. Press release.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "intent",
      "in": "query",
      "required": false,
      "description": "changes, consultations, opportunities or updates.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "issuer",
      "in": "query",
      "required": false,
      "description": "Words in the issuer or department.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "since",
      "in": "query",
      "required": false,
      "description": "Issued on or after (YYYY-MM-DD).",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "until",
      "in": "query",
      "required": false,
      "description": "Issued on or before (YYYY-MM-DD).",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "changed_since",
      "in": "query",
      "required": false,
      "description": "Written to the feed after this time; for sync. Compare revision to skip unchanged records.",
      "schema": {
       "type": "string",
       "format": "date-time"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page (plan maximum applies).",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "Rows to skip; follow meta.next instead.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "A page of records.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Update"
           }
          },
          "meta": {
           "$ref": "#/components/schemas/Meta"
          },
          "attribution": {
           "type": "string"
          },
          "license": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/updates/{id}": {
   "get": {
    "summary": "One explained update",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The update.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/Update"
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/deadlines": {
   "get": {
    "summary": "Upcoming deadlines and effective dates",
    "description": "Dated deadlines, effective dates and end dates, soonest first.",
    "parameters": [
     {
      "name": "days",
      "in": "query",
      "required": false,
      "description": "How far ahead to look.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "state",
      "in": "query",
      "required": false,
      "description": "State or union territory code (jk, mh, ka, ...); 'in' for national items only.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "kind",
      "in": "query",
      "required": false,
      "description": "deadline, effective or period_end. Default: deadlines and effective dates.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page (plan maximum applies).",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "Rows to skip; follow meta.next instead.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "A page of records.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Deadline"
           }
          },
          "meta": {
           "$ref": "#/components/schemas/Meta"
          },
          "attribution": {
           "type": "string"
          },
          "license": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/alerts": {
   "get": {
    "summary": "Weather and disaster alerts in force",
    "description": "CAP alerts from NDMA SACHET issued in the last two days.",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": false,
      "description": "State or union territory code (jk, mh, ka, ...); 'in' for national items only.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "severity",
      "in": "query",
      "required": false,
      "description": "Extreme, Severe, Moderate, Minor or Unknown.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "include_ended",
      "in": "query",
      "required": false,
      "description": "true to add alerts that ended in the last day.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page (plan maximum applies).",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "A page of records.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Alert"
           }
          },
          "meta": {
           "$ref": "#/components/schemas/Meta"
          },
          "attribution": {
           "type": "string"
          },
          "license": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/tenders": {
   "get": {
    "summary": "Public tenders (paid plans)",
    "description": "Closing soonest first. In the portals' own fields.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Words in the title, organisation or reference.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "state",
      "in": "query",
      "required": false,
      "description": "State or union territory code (jk, mh, ka, ...); 'in' for national items only.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "district",
      "in": "query",
      "required": false,
      "description": "District name.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "Category, e.g. Civil Works.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "organisation",
      "in": "query",
      "required": false,
      "description": "Words in the buyer's name.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status",
      "in": "query",
      "required": false,
      "description": "open (default) or all.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "closes_before",
      "in": "query",
      "required": false,
      "description": "YYYY-MM-DD.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "published_since",
      "in": "query",
      "required": false,
      "description": "YYYY-MM-DD.",
      "schema": {
       "type": "string",
       "format": "date"
      }
     },
     {
      "name": "min_value",
      "in": "query",
      "required": false,
      "description": "Minimum estimated value in rupees.",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Rows per page (plan maximum applies).",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "offset",
      "in": "query",
      "required": false,
      "description": "Rows to skip; follow meta.next instead.",
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "A page of records.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Tender"
           }
          },
          "meta": {
           "$ref": "#/components/schemas/Meta"
          },
          "attribution": {
           "type": "string"
          },
          "license": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/sources": {
   "get": {
    "summary": "Source websites represented in updates",
    "description": "Not a claim of complete coverage.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "A page of records.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Source"
           }
          },
          "meta": {
           "$ref": "#/components/schemas/Meta"
          },
          "attribution": {
           "type": "string"
          },
          "license": {
           "type": "string",
           "format": "uri"
          }
         }
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "403": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/me": {
   "get": {
    "summary": "Your plan and remaining limits",
    "responses": {
     "200": {
      "description": "Plan details."
     }
    }
   }
  },
  "/export/{dataset}.{format}": {
   "get": {
    "summary": "Bulk export (paid plans)",
    "description": "The full dataset as JSON Lines or CSV.",
    "parameters": [
     {
      "name": "dataset",
      "in": "path",
      "required": true,
      "schema": {
       "enum": [
        "updates",
        "deadlines",
        "tenders",
        "alerts"
       ]
      }
     },
     {
      "name": "format",
      "in": "path",
      "required": true,
      "schema": {
       "enum": [
        "jsonl",
        "csv"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The file."
     },
     "403": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "description": "A PublicFeed or Gumroad license key."
   },
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   }
  },
  "responses": {
   "Error": {
    "description": "An error.",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "object",
         "properties": {
          "code": {
           "type": "string"
          },
          "message": {
           "type": "string"
          },
          "docs": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "schemas": {
   "Meta": {
    "type": "object",
    "properties": {
     "schema": {
      "type": "string"
     },
     "total": {
      "type": "integer"
     },
     "count": {
      "type": "integer"
     },
     "limit": {
      "type": "integer"
     },
     "offset": {
      "type": "integer"
     },
     "next": {
      "type": [
       "string",
       "null"
      ]
     },
     "plan": {
      "type": "string"
     },
     "history_from": {
      "type": [
       "string",
       "null"
      ]
     },
     "notice": {
      "type": "string"
     },
     "feed_updated_at": {
      "type": [
       "string",
       "null"
      ]
     },
     "generated_at": {
      "type": "string"
     }
    }
   },
   "Update": {
    "type": "object",
    "description": "publicfeed.update.v1",
    "properties": {
     "schema": {
      "const": "publicfeed.update.v1"
     },
     "id": {
      "type": "string"
     },
     "url": {
      "type": "string",
      "format": "uri"
     },
     "headline": {
      "type": "string"
     },
     "summary": {
      "type": "string"
     },
     "key_points": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "issued_date": {
      "type": [
       "string",
       "null"
      ]
     },
     "listing_date": {
      "type": [
       "string",
       "null"
      ]
     },
     "document": {
      "type": "object",
      "properties": {
       "form": {
        "type": [
         "string",
         "null"
        ]
       },
       "number": {
        "type": [
         "string",
         "null"
        ]
       },
       "type": {
        "type": [
         "string",
         "null"
        ]
       },
       "legal_character": {
        "type": [
         "string",
         "null"
        ]
       },
       "functions": {
        "type": "array",
        "items": {
         "type": "string"
        }
       },
       "cites": {
        "type": "array",
        "items": {
         "type": "string"
        }
       }
      }
     },
     "issuer": {
      "type": [
       "string",
       "null"
      ]
     },
     "department": {
      "type": [
       "string",
       "null"
      ]
     },
     "source": {
      "type": "object",
      "properties": {
       "key": {
        "type": [
         "string",
         "null"
        ]
       },
       "name": {
        "type": [
         "string",
         "null"
        ]
       },
       "site": {
        "type": [
         "string",
         "null"
        ]
       },
       "official_url": {
        "type": "string",
        "format": "uri"
       }
      }
     },
     "topics": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "reader_topics": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "intent": {
      "type": "string"
     },
     "states": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "national": {
      "type": "boolean"
     },
     "places": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "applies_to": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "dates": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "kind": {
         "type": "string"
        },
        "date": {
         "type": [
          "string",
          "null"
         ]
        },
        "wording": {
         "type": [
          "string",
          "null"
         ]
        },
        "what": {
         "type": [
          "string",
          "null"
         ]
        },
        "counts_from": {
         "type": [
          "string",
          "null"
         ]
        }
       }
      }
     },
     "revision": {
      "type": [
       "string",
       "null"
      ]
     },
     "recorded_at": {
      "type": [
       "string",
       "null"
      ],
      "description": "When this revision was written to the feed. Not a publication date; replays can change it."
     },
     "provenance": {
      "type": "object",
      "properties": {
       "method": {
        "enum": [
         "ai_summary",
         "structured"
        ]
       },
       "automated_check": {
        "type": [
         "string",
         "null"
        ]
       },
       "human_review": {
        "type": "string"
       }
      }
     }
    }
   },
   "Deadline": {
    "type": "object",
    "properties": {
     "date": {
      "type": "string",
      "format": "date"
     },
     "days_left": {
      "type": "integer"
     },
     "kind": {
      "enum": [
       "deadline",
       "effective",
       "period_end"
      ]
     },
     "label": {
      "type": "string"
     },
     "what": {
      "type": [
       "string",
       "null"
      ]
     },
     "wording": {
      "type": [
       "string",
       "null"
      ]
     },
     "update_id": {
      "type": "string"
     },
     "headline": {
      "type": "string"
     },
     "url": {
      "type": "string"
     },
     "issuer": {
      "type": [
       "string",
       "null"
      ]
     },
     "states": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "official_url": {
      "type": "string"
     }
    }
   },
   "Alert": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "event": {
      "type": "string"
     },
     "severity": {
      "type": "string"
     },
     "urgency": {
      "type": "string"
     },
     "certainty": {
      "type": "string"
     },
     "headline": {
      "type": "string"
     },
     "areas": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "states": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "effective": {
      "type": [
       "string",
       "null"
      ]
     },
     "expires": {
      "type": [
       "string",
       "null"
      ]
     },
     "active": {
      "type": "boolean"
     },
     "sender": {
      "type": [
       "string",
       "null"
      ]
     },
     "official_url": {
      "type": "string"
     }
    }
   },
   "Tender": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "tender_id": {
      "type": [
       "string",
       "null"
      ]
     },
     "reference": {
      "type": [
       "string",
       "null"
      ]
     },
     "title": {
      "type": "string"
     },
     "organisation": {
      "type": [
       "string",
       "null"
      ]
     },
     "category": {
      "type": [
       "string",
       "null"
      ]
     },
     "value_inr": {
      "type": [
       "integer",
       "null"
      ]
     },
     "published": {
      "type": [
       "string",
       "null"
      ]
     },
     "closes": {
      "type": [
       "string",
       "null"
      ]
     },
     "open": {
      "type": "boolean"
     },
     "state": {
      "type": [
       "string",
       "null"
      ]
     },
     "district": {
      "type": [
       "string",
       "null"
      ]
     },
     "portal": {
      "type": [
       "string",
       "null"
      ]
     },
     "portal_url": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "Source": {
    "type": "object",
    "properties": {
     "site": {
      "type": "string"
     },
     "url": {
      "type": [
       "string",
       "null"
      ]
     },
     "name": {
      "type": "string"
     },
     "material": {
      "type": "string"
     },
     "updates": {
      "type": "integer"
     }
    }
   }
  }
 }
}