{
  "openapi": "3.1.0",
  "info": {
    "title": "Tender84 AI API",
    "description": "Search 60,000+ live government tenders across India. Query by state, sector, department, value range, or keyword. Get full tender details with EMD, closing dates, and inviting authority. Request bid documents using Stars credits. Covers 43 NIC eProcurement portals including all states, union territories, and major PSUs like Railways, Defence, NTPC, SAIL, ONGC, BHEL, and more.\n\n**Use cases for AI agents:** Find road construction tenders in Rajasthan under ₹1Cr | Check PWD irrigation tenders closing this week | Get NHAI highway tender documents | Monitor GeM procurement opportunities | Compare EMD requirements across states.\n\n**Authentication:** Get your API key from POST /api/ai/auth (email+password). Paste into GPT Actions auth screen or Claude Tool Use header as Bearer token.",
    "version": "1.0.1",
    "x-logo": {
      "url": "https://tender84.com/assets/img/t84_logo.jpg",
      "backgroundColor": "#1e3a5f"
    },
    "x-use-cases": [
      "Find tenders matching specific keywords and value ranges",
      "Check EMD requirements before bid submission",
      "Monitor closing deadlines for active tenders",
      "Request tender documents for bid preparation",
      "Track document request status and credit balance"
    ],
    "contact": {
      "name": "Tender84 Support",
      "url": "https://tender84.com/api-docs",
      "email": "support@tender84.com"
    }
  },
  "servers": [
    {
      "url": "https://tender84.com",
      "description": "Staging (development)"
    },
    {
      "url": "https://tender84.com",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/ai/tenders/search": {
      "get": {
        "operationId": "searchTenders",
        "summary": "Search government tenders",
        "description": "Search tenders across India by keyword, state, department, sector, value range, and status. Returns up to 50 results sorted by closing date (closest first).",
        "tags": [
          "Tenders"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Keyword search in tender title and department name",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "State/portal code. Full list at GET /api/ai/meta/states",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dept",
            "in": "query",
            "description": "Department name (e.g., PWD, NHAI, Irrigation, Health)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "sector",
            "in": "query",
            "description": "Sector (e.g., construction, roads, it, healthcare, water)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "min_value",
            "in": "query",
            "description": "Minimum tender value in rupees",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "max_value",
            "in": "query",
            "description": "Maximum tender value in rupees",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Tender status: live (default) or all",
            "schema": {
              "type": "string",
              "enum": [
                "live",
                "all"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum results (1-50, default 10)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "object"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "tenders": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Tender ID (use for getTenderDetail)"
                          },
                          "title": {
                            "type": "string"
                          },
                          "department": {
                            "type": "string"
                          },
                          "state": {
                            "type": "string"
                          },
                          "tender_value": {
                            "type": "number"
                          },
                          "emd": {
                            "type": "string"
                          },
                          "published_date": {
                            "type": "string"
                          },
                          "closing_date": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "live",
                              "expired"
                            ]
                          },
                          "portal_code": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required — provide Bearer token"
          }
        }
      }
    },
    "/api/ai/tenders/{tender_id}": {
      "get": {
        "operationId": "getTenderDetail",
        "summary": "Get full tender details",
        "description": "Get complete details for a specific tender including value, EMD, dates, department, authority, and credit cost to request documents.",
        "tags": [
          "Tenders"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tender_id",
            "in": "path",
            "required": true,
            "description": "Tender ID from search results",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tender detail with credit cost",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tender": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "title": {
                          "type": "string"
                        },
                        "department": {
                          "type": "string"
                        },
                        "authority": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string"
                        },
                        "city": {
                          "type": "string"
                        },
                        "sector": {
                          "type": "string"
                        },
                        "tender_value": {
                          "type": "number"
                        },
                        "emd": {
                          "type": "string"
                        },
                        "published_date": {
                          "type": "string"
                        },
                        "closing_date": {
                          "type": "string"
                        },
                        "opening_date": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "portal_code": {
                          "type": "string"
                        },
                        "is_global": {
                          "type": "boolean"
                        }
                      }
                    },
                    "credit_cost": {
                      "type": "integer"
                    },
                    "next_action": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Tender not found"
          }
        }
      }
    },
    "/api/ai/tenders/{tender_id}/request-docs": {
      "post": {
        "operationId": "requestDocuments",
        "summary": "Request tender documents",
        "description": "Request PDF documents for a tender. Costs credits based on tender value tier. First call with confirm=false shows the cost and your balance. Then call with confirm=true to proceed and deduct credits.",
        "tags": [
          "Documents"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "tender_id",
            "in": "path",
            "required": true,
            "description": "Tender ID to request documents for",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirm": {
                    "type": "boolean",
                    "description": "Set true to confirm and deduct credits. Leave false to see cost first.",
                    "default": false
                  },
                  "tender_title": {
                    "type": "string",
                    "description": "Tender title (from search, helps if tender not in cache)"
                  },
                  "tender_value": {
                    "type": "number"
                  },
                  "department": {
                    "type": "string"
                  },
                  "state": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Confirmation needed OR request submitted (see oneOf)"
          },
          "401": {
            "description": "Authentication required"
          },
          "402": {
            "description": "Insufficient credits — includes top_up_url"
          }
        }
      }
    },
    "/api/ai/account/balance": {
      "get": {
        "operationId": "checkBalance",
        "summary": "Check credit balance",
        "description": "Get your current credit balance, plan name, and account info.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Account balance",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "company": {
                          "type": "string"
                        }
                      }
                    },
                    "credit_balance": {
                      "type": "integer"
                    },
                    "plan": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/ai/account/requests": {
      "get": {
        "operationId": "myRequests",
        "summary": "View document request history",
        "description": "List your document requests with status. Filter by status if needed.",
        "tags": [
          "Account"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "Filter by status",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "processing",
                "completed",
                "rejected"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Request history",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "requests": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "tender_id": {
                            "type": "string"
                          },
                          "tender_title": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending",
                              "processing",
                              "completed",
                              "rejected"
                            ]
                          },
                          "created_at": {
                            "type": "string"
                          },
                          "notes": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    },
    "/api/ai/meta/states": {
      "get": {
        "operationId": "listStates",
        "summary": "List available state/portal codes",
        "description": "Returns all available state codes and PSU portal codes that can be used in searchTenders state parameter.",
        "tags": [
          "Meta"
        ],
        "responses": {
          "200": {
            "description": "State codes list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "states": {
                      "type": "object",
                      "description": "State name → code mapping"
                    },
                    "psu_portals": {
                      "type": "object",
                      "description": "PSU name → code mapping"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Get your token via POST /api/ai/auth with your Tender84 email+password, or generate a developer key via the /api/ai/developer-keys API. Tokens start with t84_"
      }
    }
  }
}