{
  "openapi": "3.1.0",
  "info": {
    "title": "Ceramic Search API",
    "description": "AI-powered web search API that returns relevant content for natural language queries.",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.ceramic.ai"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/search": {
      "post": {
        "operationId": "search",
        "summary": "Search",
        "description": "Search the web and retrieve relevant content.",
        "x-codeSamples": [
          {
            "lang": "curl",
            "label": "Search",
            "source": "curl https://api.ceramic.ai/search \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"California rental laws\"}'"
          },
          {
            "lang": "python",
            "label": "Search",
            "source": "from ceramic_ai import Ceramic\n\nclient = Ceramic(api_key=\"YOUR_API_KEY\")\n\nresponse = client.search(\n    query=\"California rental laws\")\n\nprint(response)"
          },
          {
            "lang": "typescript",
            "label": "Search",
            "source": "import Ceramic from \"ceramic-ai\";\n\nconst client = new Ceramic({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await client.search({\n  query: \"California rental laws\"});\n\nconsole.log(response);"
          },
          {
            "lang": "curl",
            "label": "Search with maxDescriptionLength",
            "source": "curl https://api.ceramic.ai/search \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"query\": \"California rental laws\",\n        \"maxDescriptionLength\": 3000\n      }'"
          },
          {
            "lang": "python",
            "label": "Search with maxDescriptionLength",
            "source": "from ceramic_ai import Ceramic\n\nclient = Ceramic(api_key=\"YOUR_API_KEY\")\n\nresponse = client.search(\n    query=\"California rental laws\",\n    max_description_length=3000)\n\nprint(response)"
          },
          {
            "lang": "typescript",
            "label": "Search with maxDescriptionLength",
            "source": "import Ceramic from \"ceramic-ai\";\n\nconst client = new Ceramic({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await client.search({\n  query: \"California rental laws\",\n  maxDescriptionLength: 3000});\n\nconsole.log(response);"
          },
          {
            "lang": "curl",
            "label": "Search with maxResults",
            "source": "curl https://api.ceramic.ai/search \\\n  -H \"Authorization: Bearer YOUR_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"query\": \"California rental laws\",\n        \"maxResults\": 10\n      }'"
          },
          {
            "lang": "python",
            "label": "Search with maxResults",
            "source": "from ceramic_ai import Ceramic\n\nclient = Ceramic(api_key=\"YOUR_API_KEY\")\n\nresponse = client.search(\n    query=\"California rental laws\",\n    max_results=10)\n\nprint(response)"
          },
          {
            "lang": "typescript",
            "label": "Search with maxResults",
            "source": "import Ceramic from \"ceramic-ai\";\n\nconst client = new Ceramic({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await client.search({\n  query: \"California rental laws\",\n  maxResults: 10});\n\nconsole.log(response);"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchRequest"
              },
              "example": {
                "query": "California rental laws"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful search response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                },
                "example": {
                  "requestId": "ae2ebd93-194f-4460-9996-15e3f86b05d8",
                  "result": {
                    "results": [
                      {
                        "title": "California Tenant Rights Guide",
                        "url": "https://example.com/california-tenant-rights",
                        "description": "Comprehensive guide to California rental laws..."
                      }
                    ],
                    "searchMetadata": {
                      "executionTime": 0.097
                    },
                    "totalResults": 10
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "query"
        ],
        "properties": {
          "query": {
            "type": "string",
            "description": "The search query in keyword format. Must contain between 1 and 50 words (words are separated by spaces; extra whitespace is ignored)."
          },
          "maxDescriptionLength": {
            "type": "integer",
            "minimum": 1000,
            "maximum": 8000,
            "default": 3000,
            "description": "Maximum character length for each result's description."
          },
          "maxResults": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 10,
            "description": "The number of search results to return."
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "requestId",
          "result"
        ],
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Server-generated request identifier (often a UUID)."
          },
          "result": {
            "$ref": "#/components/schemas/SearchResult"
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "results",
          "searchMetadata",
          "totalResults"
        ],
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResultItem"
            },
            "description": "Array of search results."
          },
          "searchMetadata": {
            "$ref": "#/components/schemas/SearchMetadata"
          },
          "totalResults": {
            "type": "integer",
            "description": "Total number of results returned."
          }
        }
      },
      "SearchResultItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "title",
          "url",
          "description"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "The title of the web page."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The URL of the web page."
          },
          "description": {
            "type": "string",
            "description": "A text snippet from the page content."
          }
        }
      },
      "SearchMetadata": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "executionTime"
        ],
        "properties": {
          "executionTime": {
            "type": "number",
            "description": "Time taken to execute the search in seconds."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "title",
          "status",
          "detail",
          "requestId",
          "code"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type."
          },
          "status": {
            "type": "integer",
            "minimum": 100,
            "maximum": 599,
            "description": "The HTTP status code."
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem."
          },
          "requestId": {
            "type": "string",
            "description": "Server-generated request identifier (often a UUID)."
          },
          "code": {
            "type": "string",
            "description": "Application-specific error code."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key authentication. Include your API key as a Bearer token in the Authorization header."
      }
    }
  }
}