{
 "openapi": "3.1.0",
 "info": {
  "title": "pulaudomain agent API",
  "version": "2026-10-24",
  "description": "Read-only API for AI agents: search and check domains for sale on pulaudomain. Prices in IDR. 60 requests/minute per IP. Payment is done by the user on the listing page.",
  "contact": {
   "email": "hello@pulaudomain.com"
  }
 },
 "servers": [
  {
   "url": "https://pulaudomain.com/api/agent/v1"
  }
 ],
 "paths": {
  "/search": {
   "get": {
    "operationId": "searchDomains",
    "summary": "Search available domains",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Keyword or full domain."
     },
     {
      "name": "tld",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Extension(s), comma separated, e.g. \"biz.id,id\"."
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Category, e.g. Tech."
     },
     {
      "name": "min_price_idr",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "max_price_idr",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "min_length",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      },
      "description": "Minimum length of the name part."
     },
     {
      "name": "max_length",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "sort",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "relevance",
        "price_asc",
        "price_desc",
        "length",
        "newest"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 20
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "next_cursor from the previous page."
     }
    ],
    "responses": {
     "200": {
      "description": "Results",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "total": {
           "type": "integer"
          },
          "count": {
           "type": "integer"
          },
          "sort": {
           "type": "string"
          },
          "results": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Domain"
           }
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          },
          "data_as_of": {
           "type": "string",
           "format": "date-time"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Rate limited"
     }
    }
   }
  },
  "/domains/{domain}": {
   "get": {
    "operationId": "getDomain",
    "summary": "Detail for one domain",
    "parameters": [
     {
      "name": "domain",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "risco.web.id"
     }
    ],
    "responses": {
     "200": {
      "description": "Available listing",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "domain": {
           "$ref": "#/components/schemas/Domain"
          },
          "similar": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Domain"
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not for sale; body has status (sold, reserved, not_for_sale, not_listed)."
     }
    }
   }
  },
  "/check": {
   "get": {
    "operationId": "checkDomains",
    "summary": "Status of up to 25 domains",
    "parameters": [
     {
      "name": "domains",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Comma-separated domains."
     }
    ],
    "responses": {
     "200": {
      "description": "Statuses",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "results": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "domain": {
              "type": "string"
             },
             "status": {
              "type": "string",
              "enum": [
               "available",
               "sold",
               "reserved",
               "not_for_sale",
               "not_listed"
              ]
             },
             "price": {
              "$ref": "#/components/schemas/Price"
             },
             "url": {
              "type": "string"
             },
             "note": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/overview": {
   "get": {
    "operationId": "catalogOverview",
    "summary": "Inventory overview",
    "responses": {
     "200": {
      "description": "Overview"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Price": {
    "type": "object",
    "properties": {
     "amount": {
      "type": "integer",
      "description": "Price in IDR (no decimals)."
     },
     "currency": {
      "type": "string",
      "enum": [
       "IDR"
      ]
     },
     "display": {
      "type": "string",
      "example": "Rp 95.000"
     }
    }
   },
   "Domain": {
    "type": "object",
    "properties": {
     "domain": {
      "type": "string",
      "example": "risco.web.id"
     },
     "extension": {
      "type": "string",
      "example": ".web.id"
     },
     "name_length": {
      "type": "integer"
     },
     "price": {
      "$ref": "#/components/schemas/Price"
     },
     "availability": {
      "type": "string",
      "enum": [
       "available"
      ]
     },
     "category": {
      "type": [
       "string",
       "null"
      ]
     },
     "tags": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "tagline": {
      "type": [
       "string",
       "null"
      ],
      "description": "Indonesian."
     },
     "description": {
      "type": [
       "string",
       "null"
      ],
      "description": "Indonesian. Detail endpoint only."
     },
     "url": {
      "type": "string",
      "format": "uri"
     },
     "markdown_url": {
      "type": "string",
      "format": "uri"
     },
     "image_url": {
      "type": "string",
      "format": "uri"
     },
     "checkout_url": {
      "type": "string",
      "format": "uri",
      "description": "Listing page where the user pays."
     }
    }
   }
  }
 }
}