# Ohsee API Documentation

> The web context layer for AI products. Search, extract, structure, research, crawl, and monitor the live web from one API.

**Base URL:** `https://api.ohsee.tech`

All requests return JSON and are authenticated with an API key sent as a Bearer token.

---

## Authentication

Send your API key in the Authorization header on every request:

```
Authorization: Bearer ohsee-<your-key>
```

Create and revoke keys from your dashboard. The full secret is shown only once at creation. A missing, malformed, or revoked key returns `401`.

---

## Credits

Ohsee is usage-based. New accounts start with 100 free credits. Credits never expire while your account is active.

| Operation | Credits |
| --- | --- |
| Search (ultra-fast / fast / basic) | 1 (`include_answer` is free) |
| Search (advanced) | 2 (`include_answer` is free) |
| Search + include_evidence | +1 |
| Extract | 1 per 5 successfully extracted URLs (rounded up) |
| Structure | 2 per URL (+1 per URL if schema has more than 8 fields) |
| Research (standard / deep) | 10 / 25 (+5 detailed/comparison/timeline, +1 evidence) |
| Map | 1 per 10 URLs found (rounded up) |
| Crawl | 1 per 5 pages (rounded up); 1 per page with a schema |
| Domain | 5 + 3 per requested section |
| Monitor run | Varies by type; 1 when no change is detected |
| Estimate | Free |

Synchronous endpoints charge on completion. Async jobs reserve credits up front and settle on completion, refunding unused credits. When your balance is too low, the API returns `402` with `balance`, `required`, and `billing_url`.

---

## Sync vs async

- Synchronous: `/search`, `/extract`, `/structure`, `/estimate`, and `/map` when `limit <= 50`.
- Asynchronous (return a `job_id` to poll): `/research`, `/crawl`, `/domain`, large `/map`, and monitor runs.

Poll `GET /jobs/{job_id}` until `status` is `succeeded`, `partial`, or `failed`.

---

## Search

`POST /search` - discover relevant web content and return ranked, cited passages.

### Request

```bash
curl https://api.ohsee.tech/search \
  -H "Authorization: Bearer ohsee-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does the model context protocol handle auth?",
    "search_depth": "advanced",
    "max_results": 5,
    "include_answer": true
  }'
```

### Parameters

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `query` | string | required | 1 to 1000 characters |
| `search_depth` | string | `basic` | `ultra-fast`, `fast`, `basic`, `advanced` |
| `topic` | string | `general` | `general`, `news`, `finance` |
| `time_range` | string | null | `day`, `week`, `month`, `year` |
| `max_results` | int | 5 | 1 to 20 |
| `chunks_per_source` | int | 3 | 1 to 3 (advanced) |
| `include_answer` | bool \| string | false | `true` or `"advanced"`; included in the base search credit |
| `include_raw_content` | bool \| string | false | `"markdown"` or `"text"` |
| `include_evidence` | bool | false | adds 1 credit |
| `include_domains` / `exclude_domains` | string[] | [] | domain filters |
| `source_quality` | string | `standard` | `standard`, `strict`, `custom` |
| `allowed_source_types` / `excluded_source_types` | string[] | [] | source type filters |
| `prefer_domains` | string[] | [] | boost these domains |
| `cache` | string | `auto` | `auto`, `force`, `bypass` |
| `cache_ttl` | int | 900 | 60 to 86400 seconds |

### Response

```json
{
  "query": "how does the model context protocol handle auth?",
  "answer": "MCP uses OAuth 2.1 for authorization ...",
  "results": [
    {
      "url": "https://modelcontextprotocol.io/docs/concepts/authorization",
      "title": "Authorization - Model Context Protocol",
      "content": "MCP uses OAuth 2.1 for authorization ...",
      "score": 0.97,
      "source_type": "documentation",
      "citation_id": "c1"
    }
  ],
  "citations": [],
  "response_time": 1.42,
  "request_id": "b3f1a2c4",
  "credits_charged": 3,
  "cache_status": "miss"
}
```

---

## Extract

`POST /extract` - fetch known URLs and return clean content.

### Request

```bash
curl https://api.ohsee.tech/extract \
  -H "Authorization: Bearer ohsee-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://modelcontextprotocol.io/docs"],
    "format": "markdown"
  }'
```

### Parameters

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `urls` | string[] | required | 1 to 20 URLs |
| `format` | string | `markdown` | `markdown` or `text` |
| `include_favicon` | bool | false | include favicon URL |
| `schema` | object | null | run structured extraction per page |
| `cache` | string | `auto` | ignored when a schema is provided |
| `cache_ttl` | int | 3600 | 60 to 86400 seconds |

### Response

```json
{
  "results": [
    { "url": "https://modelcontextprotocol.io/docs", "raw_content": "# Model Context Protocol ...", "favicon": null }
  ],
  "failed_results": [],
  "response_time": 0.88,
  "request_id": "a91c33d0",
  "credits_charged": 1,
  "cache_status": "miss"
}
```

---

## Structured extraction

`POST /structure` - convert pages into JSON matching your schema.

### Request

```bash
curl https://api.ohsee.tech/structure \
  -H "Authorization: Bearer ohsee-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/pricing"],
    "schema": { "plan_name": "string", "monthly_price": "string" }
  }'
```

### Parameters

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `urls` | string[] | required | 1 to 20 URLs |
| `schema` | object | required | field name to type hint |
| `format` | string | `markdown` | internal read format |

Each result includes `data`, per-field `fields` (value, confidence, evidence), `warnings`, and an overall `confidence`.

---

## Research

`POST /research` - multi-source research job. Returns a `job_id`; poll `GET /jobs/{job_id}`.

### Parameters

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `query` | string | required | 1 to 2000 characters |
| `research_depth` | string | `standard` | `standard`, `deep` |
| `output_format` | string | `brief` | `brief`, `detailed`, `comparison_table`, `timeline`, `bullet_report`, `json` |
| `max_sources` | int | 8 | 1 to 30 |
| `include_evidence` | bool | true | adds 1 credit |

The job result includes `answer`, `key_findings`, `citations`, `source_list`, and `confidence`.

---

## Map & Crawl

`POST /map` - discover URLs on a site. Sync when `limit <= 50`, otherwise a job.

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `url` | string | required | seed URL |
| `limit` | int | 50 | 1 to 500 |
| `max_depth` | int | 2 | 0 to 5 |
| `include_patterns` / `exclude_patterns` | string[] | [] | regex filters |

`POST /crawl` - read many pages. Always a job.

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `url` | string | required | seed URL |
| `limit` | int | 20 | 1 to 200 pages |
| `max_depth` | int | 2 | 0 to 5 |
| `format` | string | `markdown` | `markdown` or `text` |
| `schema` | object | null | structure each page |
| `include_patterns` / `exclude_patterns` | string[] | [] | regex filters |

---

## Domain intelligence

`POST /domain` - summarize a company or site. Async job.

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `domain` | string | required | hostname or URL |
| `sections` | string[] | `["summary","important_pages","pricing","docs"]` | sections to build |
| `limit` | int | 40 | 5 to 200 |

Result includes `summary`, `important_pages`, `pages_sampled`, and `sections`.

---

## Monitors

Create and manage monitors from your dashboard. Types: `page_change_monitor`, `search_monitor`, `domain_monitor`, `pricing_monitor`. Frequencies: `hourly`, `daily`, `weekly`.

Trigger a run for a monitor you own (works with an API key):

```bash
curl https://api.ohsee.tech/monitors/42/run \
  -H "Authorization: Bearer ohsee-<your-key>"
```

Creating a monitor is free. Each run costs credits based on its type; a run with no detected change costs 1 credit. Low balance pauses the monitor.

---

## Jobs

`GET /jobs/{job_id}` - fetch a single job.

`GET /jobs` - list your jobs (`kind` filter, `limit` up to 100).

```json
{
  "job_id": "9b8c7d6e-...",
  "kind": "research",
  "status": "succeeded",
  "credits": { "reserved": 15, "charged": 15, "refunded": 0 },
  "result": { "...": "..." },
  "created_at": "2026-01-01T12:00:00Z",
  "finished_at": "2026-01-01T12:00:18Z"
}
```

Statuses: `queued`, `running`, `succeeded`, `partial`, `failed`.

---

## Credit estimate

`POST /estimate` - preview the credit cost of any operation. Free, never charges credits.

```bash
curl https://api.ohsee.tech/estimate \
  -H "Authorization: Bearer ohsee-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "research",
    "research": { "query": "...", "research_depth": "standard" }
  }'
```

```json
{ "estimated_credits": 15, "balance": 98, "sufficient": true, "operation": "research" }
```

Supported operations: `search`, `extract`, `structure`, `research`, `map`, `crawl`, `domain`, `monitor_run`.

---

## SDKs

JavaScript / TypeScript:

```bash
npm install @ohsee/sdk
```

```ts
import { Ohsee } from "@ohsee/sdk";
const client = new Ohsee({ apiKey: process.env.OHSEE_API_KEY! });
const res = await client.search({ query: "MCP auth", search_depth: "basic" });
```

Python:

```bash
pip install ohsee
```

```python
from ohsee import Ohsee
client = Ohsee(api_key=os.environ["OHSEE_API_KEY"])
res = client.search(query="MCP auth", search_depth="basic")
```

Both SDKs cover search, extract, structure, research, map, crawl, domain, estimate, jobs, and monitor runs. Monitor create/list and account usage require a dashboard session rather than an API key.

---

## Errors

Errors return a `detail` object with a stable `error` code, a human `message`, and often a `request_id`.

| Status | Meaning |
| --- | --- |
| `401` | Missing, malformed, or revoked API key |
| `402` | Insufficient credits (`balance`, `required`, `billing_url`) |
| `403` | Account disabled or not permitted |
| `404` | Job or monitor not found |
| `422` | Invalid parameters |
| `429` | Rate limit exceeded |
| `500` | Unexpected error (`internal_error`) with `contact` and `request_id` |
| `503` | Web discovery temporarily unavailable |
| `504` | Request timed out |

Unexpected failures never expose internal systems. Contact **hello@blazeddigital.com** and include the `request_id`.

---

## Rate limits

60 requests per minute per API key (or client IP). Exceeding the limit returns `429`; back off and retry.

---

*© Ohsee - https://ohsee.tech/docs*