# Structured Extraction

> Extract structured JSON data from any URL using a field list or JSON schema — 4 credits per call.

Source: http://localhost:3000/docs/endpoints/structured-extract

## Structured Extract: `POST /v1/structured-extract/`

Typed JSON from a page using a schema or a plain-English prompt. Cost: 4 credits.

```bash
curl -X POST https://api.hushsearch.io/v1/structured-extract/ \
  -H "X-API-Key: hs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://news.ycombinator.com/",
  "prompt": "The top five story titles and their links"
}'
```

**POST** `/v1/structured-extract/` — **4 credits per call**

Fetch a URL, extract its main content, then use an LLM to populate a caller-supplied schema. Returns a typed JSON object with `null` for missing fields.

## Request

```json
{
  "url": "https://jobs.example.com/position/123",
  "schema_fields": ["job_title", "company", "salary", "location"],
  "prompt": "Extract job listing details"
}
```

| Field | Type | Required | Description |
|---|---|---|---|
| `url` | string | Yes | Page to extract from |
| `schema_fields` | list or JSON schema | No | Fields to extract |
| `prompt` | string | No | Custom extraction instruction |

### JSON schema variant

```json
{
  "url": "https://shop.example.com/product/42",
  "schema_fields": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" }
    }
  }
}
```

## Response

```json
{
  "url": "https://jobs.example.com/position/123",
  "data": {
    "job_title": "Senior Backend Engineer",
    "company": "Acme Corp",
    "salary": "$150k–$180k",
    "location": "Remote"
  },
  "title": "Senior Backend Engineer at Acme Corp",
  "credits_used": 4,
  "credits_remaining": 96,
  "response_time_ms": 1820
}
```

## Notes

- Requires `GROQ_API_KEY` for LLM extraction; without it all fields return `null`.
- SSRF protection applies — only public HTTP/HTTPS URLs are allowed.
