# AGENTS.md

# Ubient Go(TM) Search API

> A privacy-focused metasearch engine for AI agents.
> No authentication required. Returns unified JSON results from multiple search engines.
>
> - **Homepage**: [https://go.ubient.dscloud.biz](https://go.ubient.dscloud.biz)
> - **API Documentation**: [https://ubient.dscloud.biz/docs/service/go-search/](https://ubient.dscloud.biz/docs/service/go-search/)

## Search Endpoint

```
GET  https://go.ubient.dscloud.biz/search
POST https://go.ubient.dscloud.biz/search
```

## Required Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `q` | String | The search query. Must be URL-encoded if it contains Korean, spaces, or special characters. |
| `format` | String | **Must be `json`**. Without this, the server returns HTML. |

## Optional Parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `categories` | String | (none) | Comma-separated list (e.g. `general`, `news`, `images`, `videos`, `music`, `files`, `it`, `science`, `social+media`). Retrieve available categories via `/config`. |
| `language` | String | (auto) | Language code: `ko`, `en`, `ja`, etc. |
| `pageno` | Integer | `1` | Page number of results. |
| `time_range` | String | (none) | Time filter: `day`, `month`, or `year`. Not all engines support this. |
| `safesearch` | Integer | `0` | SafeSearch level: `0` (none), `1` (moderate), `2` (strict). |

## Request Examples

### Basic Search (Bash)

```
curl -sS -G "https://go.ubient.dscloud.biz/search" \
  --data-urlencode "q=대한민국" \
  --data-urlencode "format=json"
```

### Multiple Parameters

```
curl -sS -G "https://go.ubient.dscloud.biz/search" \
  --data-urlencode "q=python programming" \
  --data-urlencode "format=json" \
  --data-urlencode "categories=general" \
  --data-urlencode "language=en" \
  --data-urlencode "pageno=1"
```

### Direct URL

```
GET https://go.ubient.dscloud.biz/search?q=%EB%8C%80%ED%95%9C%EB%AF%BC%EA%B5%AD&format=json&categories=general&language=ko
```

## JSON Response Structure

### Top-Level Fields

| Field | Type | Description |
| --- | --- | --- |
| `query` | String | The processed search query |
| `results` | Array | List of search results |
| `answers` | Array | Direct answer-style results (display with priority) |
| `corrections` | Array | Query correction suggestions |
| `infoboxes` | Array | Rich summary information objects |
| `suggestions` | Array | Related search term suggestions |
| `unresponsive_engines` | Array | Engines that failed: each entry is `[engine_name, reason]` |

### Search Result Fields (`results[]`)

| Field | Type | Description |
| --- | --- | --- |
| `title` | String | Result title |
| `url` | String | Original URL |
| `content` | String | Description or excerpt (may be empty) |
| `engine` | String | Primary engine name |
| `engines` | Array | All engines that returned this result |
| `positions` | Array | Rank positions in each engine |
| `category` | String | Result category |
| `score` | Number | Ranking score (higher = better, not normalized to 0-1) |
| `publishedDate` | String/null | Publication date if available |
| `img_src` | String | Image URL (for image results) |
| `thumbnail` | String | Thumbnail URL |

**Note**: Not all results contain the same fields. Treat `null` and `""` as missing values.

### Empty Results

A `200 OK` response does not guarantee results. Always check if `results` array is non-empty.

```
{
  "query": "example",
  "results": [],
  "answers": [],
  "corrections": [],
  "infoboxes": [],
  "suggestions": [],
  "unresponsive_engines": []
}
```

### Unresponsive Engines (`unresponsive_engines[]`)

Each entry: `[engine_name, human_readable_reason]`

```
"unresponsive_engines": [
  ["brave", "너무 많은 요청"],
  ["duckduckgo", "CAPTCHA"]
]
```

Do not string-match on reason text (it may be translated). Use for logging only.
Results can still be present even when some engines are unresponsive.

## HTTP Status Codes

| Code | Meaning | Action |
| --- | --- | --- |
| `200 OK` | Request processed | Parse JSON body |
| `403 Forbidden` | Access denied | Check format parameter and access policies |
| Other | Server/network error | Inspect status code and body |

## Configuration Endpoint

```
GET https://go.ubient.dscloud.biz/config
```

Returns instance information: available categories, engine list, language settings.
Does not return search results.

## Agent Instructions

1. **Always include `format=json`**.
2. **URL-encode** search queries.
3. Present `url`, `title`, `content` from `results[]` to the user.
4. Show `answers[]` with priority if present.
5. Include `suggestions[]` as related search terms.
6. Use `infoboxes[]` for rich context when available.
7. Check `unresponsive_engines[]` and warn the user if most engines failed.
8. **Check HTTP status code before JSON parsing**.
9. Handle empty `results[]` gracefully — suggest query refinement or alternative categories.