{
 "openapi": "3.1.0",
 "info": {
  "title": "Bots Do The Work agent API",
  "version": "2.0.0",
  "description": "Bots Do The Work is a directory of Grok Bot templates that help you automate tasks in your life and work. Free search and details. Paid with x402 on Base mainnet (real USDC): recommend $0.01, feed $0.05 per call."
 },
 "servers": [
  {
   "url": "https://www.botsdothework.com"
  }
 ],
 "paths": {
  "/api/agent/search": {
   "get": {
    "operationId": "search_bots",
    "summary": "Search the directory for bots by keyword or category. Free.",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Keywords",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "One of: recruiting, sales, support, ops, bookkeeping, real estate, personal, crypto, other",
      "schema": {
       "type": "string",
       "enum": [
        "recruiting",
        "sales",
        "support",
        "ops",
        "bookkeeping",
        "real estate",
        "personal",
        "crypto",
        "other"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "1 to 50, default 10",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matching bots",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/SearchResult"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited"
     }
    }
   }
  },
  "/api/agent/bot/{slug}": {
   "get": {
    "operationId": "get_bot",
    "summary": "Get full details for one bot by slug, including creator, description, install link, likes, installs and ratings. Free.",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^[a-z0-9-]{1,80}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Bot details",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Bot"
        }
       }
      }
     },
     "404": {
      "description": "Unknown slug"
     },
     "429": {
      "description": "Rate limited"
     }
    }
   }
  },
  "/api/agent/recommend": {
   "get": {
    "operationId": "recommend_bots",
    "summary": "Get a ranked shortlist of bots for a described task, with reasons. Paid per call with x402 (USDC on Base). $0.01 per call.",
    "parameters": [
     {
      "name": "task",
      "in": "query",
      "required": true,
      "description": "Describe the task, max 300 characters",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "n",
      "in": "query",
      "required": false,
      "description": "1 to 10, default 5",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 10
      }
     },
     {
      "name": "X-PAYMENT",
      "in": "header",
      "required": false,
      "description": "x402 v1 payment payload, base64 JSON (or PAYMENT-SIGNATURE for v2).",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ranked shortlist plus receipt. Header X-PAYMENT-RESPONSE holds the settlement.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Missing task"
     },
     "402": {
      "description": "x402 payment requirements: scheme exact, network base, USDC, 10000 atomic units = $0.01",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaymentRequired"
        }
       }
      }
     },
     "503": {
      "description": "Payments not configured"
     }
    }
   }
  },
  "/api/agent/feed": {
   "get": {
    "operationId": "get_feed",
    "summary": "Get the full directory as JSON with live stats, new bots by day and the popular-today list. Paid per call with x402 (USDC on Base). $0.05 per call.",
    "parameters": [
     {
      "name": "X-PAYMENT",
      "in": "header",
      "required": false,
      "description": "x402 v1 payment payload, base64 JSON (or PAYMENT-SIGNATURE for v2).",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Directory feed plus receipt. Header X-PAYMENT-RESPONSE holds the settlement.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "402": {
      "description": "x402 payment requirements: scheme exact, network base, USDC, 50000 atomic units = $0.05",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/PaymentRequired"
        }
       }
      }
     },
     "503": {
      "description": "Payments not configured"
     }
    }
   }
  },
  "/api/agent/pricing": {
   "get": {
    "operationId": "get_pricing",
    "summary": "Current x402 mode, network, asset and prices. Free.",
    "responses": {
     "200": {
      "description": "Pricing",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/agent/receipt/{id}": {
   "get": {
    "operationId": "get_receipt",
    "summary": "Read a stored x402 payment receipt.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "pattern": "^[a-f0-9]{20}$"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Receipt",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Receipt"
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/api/submit": {
   "post": {
    "operationId": "submit_bot",
    "summary": "Submit a Grok Bot link for human review. Free. Nothing is published automatically.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "bot_url",
         "name",
         "description",
         "category",
         "creator_handle"
        ],
        "properties": {
         "bot_url": {
          "type": "string",
          "pattern": "^https://x\\.ai/bot/[A-Za-z0-9_-]{10,40}$"
         },
         "name": {
          "type": "string",
          "maxLength": 80
         },
         "description": {
          "type": "string",
          "maxLength": 160
         },
         "category": {
          "type": "string",
          "enum": [
           "recruiting",
           "sales",
           "support",
           "ops",
           "bookkeeping",
           "real estate",
           "personal",
           "crypto",
           "other"
          ]
         },
         "creator_handle": {
          "type": "string"
         },
         "contact_email": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Queued for human review",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Invalid"
     },
     "429": {
      "description": "Rate limited"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Bot": {
    "type": "object",
    "properties": {
     "slug": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "creator": {
      "type": "string"
     },
     "category": {
      "type": "string"
     },
     "description": {
      "type": "string"
     },
     "install_url": {
      "type": "string",
      "format": "uri"
     },
     "bot_url": {
      "type": "string",
      "format": "uri"
     },
     "page_url": {
      "type": "string",
      "format": "uri"
     },
     "source_post_url": {
      "type": "string",
      "format": "uri"
     },
     "stats": {
      "type": "object",
      "properties": {
       "likes": {
        "type": "integer"
       },
       "installs": {
        "type": "integer"
       },
       "ratings": {
        "type": "integer"
       },
       "avg_rating": {
        "type": [
         "number",
         "null"
        ]
       }
      }
     }
    }
   },
   "SearchResult": {
    "type": "object",
    "properties": {
     "query": {
      "type": "string"
     },
     "count": {
      "type": "integer"
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/Bot"
      }
     }
    }
   },
   "Receipt": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "ts": {
      "type": "string"
     },
     "product": {
      "type": "string"
     },
     "payer": {
      "type": [
       "string",
       "null"
      ]
     },
     "amount": {
      "type": "string"
     },
     "network": {
      "type": "string"
     },
     "tx": {
      "type": [
       "string",
       "null"
      ]
     },
     "resource": {
      "type": "string"
     }
    }
   },
   "PaymentRequired": {
    "type": "object",
    "properties": {
     "x402Version": {
      "type": "integer"
     },
     "error": {
      "type": "string"
     },
     "accepts": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "scheme": {
         "type": "string"
        },
        "network": {
         "type": "string"
        },
        "maxAmountRequired": {
         "type": "string"
        },
        "resource": {
         "type": "string"
        },
        "description": {
         "type": "string"
        },
        "mimeType": {
         "type": "string"
        },
        "payTo": {
         "type": "string"
        },
        "maxTimeoutSeconds": {
         "type": "integer"
        },
        "asset": {
         "type": "string"
        },
        "extra": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 }
}