# AGENTS.md

- Link: https://ubient.dscloud.biz/docs/service/go-search/go-search-skill/agents/
- Published: 2026-10-25T07:25:53+09:00
- Author: Ubient

# 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

    ```ubient-docs-code
    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)

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

### Multiple Parameters

    ```ubient-docs-code
    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

    ```ubient-docs-code
    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.

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

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

Each entry: `[engine_name, human_readable_reason]`

    ```ubient-docs-code
    "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

    ```ubient-docs-code
    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.