# Extract

## JSON

`client.extract.json(ExtractJsonParamsbody, RequestOptionsoptions?): ExtractJsonResponse`

**post** `/extract/json`

Fetches a URL and extracts structured data according to a provided JSON schema

### Parameters

- `body: ExtractJsonParams`

  - `json_schema: unknown`

    JSON schema definition that describes the structure of data to extract. If the schema includes a "page_title" or "favicon" property, those fields are automatically filled from page metadata when the AI leaves them empty.

  - `url: string`

    URL to fetch and extract data from

  - `effort?: "min" | "standard" | "max"`

    Fetch effort level controlling speed vs. capability tradeoff. "min": fastest, no fallback (1-5s). "standard": balanced with enhanced reliability (default, 3-15s). "max": full browser rendering for JS-heavy sites (15-60s).

    - `"min"`

    - `"standard"`

    - `"max"`

  - `geo_target?: GeotargetGeoTarget`

    Optional geotargeting parameters for proxy requests

    - `country?: string`

      Country code using ISO 3166-1 alpha-2 standard (2 letters, e.g., "US", "GB", "JP").
      See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

  - `nocache?: boolean`

    Bypass cache and force fresh data retrieval

### Returns

- `ExtractJsonResponse = Record<string, unknown>`

### Example

```typescript
import Tabstack from '@tabstack/sdk';

const client = new Tabstack({
  apiKey: process.env['TABSTACK_API_KEY'], // This is the default and can be omitted
});

const response = await client.extract.json({
  json_schema: {
    properties: {
      stories: {
        items: {
          properties: {
            author: { description: 'Author username', type: 'string' },
            points: { description: 'Story points', type: 'number' },
            title: { description: 'Story title', type: 'string' },
          },
          type: 'object',
        },
        type: 'array',
      },
    },
    type: 'object',
  },
  url: 'https://news.ycombinator.com',
});

console.log(response);
```

#### Response

```json
{
  "foo": "bar"
}
```

## Markdown

`client.extract.markdown(ExtractMarkdownParamsbody, RequestOptionsoptions?): ExtractMarkdownResponse`

**post** `/extract/markdown`

Fetches a URL and converts its HTML content to clean Markdown format with optional metadata extraction

### Parameters

- `body: ExtractMarkdownParams`

  - `url: string`

    URL to fetch and convert to markdown

  - `content?: "main" | "full"`

    Content scope. "main" (default) returns the main article content; "full" returns the whole page, including navigation, footer, and links.

    - `"main"`

    - `"full"`

  - `effort?: "min" | "standard" | "max"`

    Fetch effort level controlling speed vs. capability tradeoff. "min": fastest, no fallback (1-5s). "standard": balanced with enhanced reliability (default, 3-15s). "max": full browser rendering for JS-heavy sites (15-60s).

    - `"min"`

    - `"standard"`

    - `"max"`

  - `geo_target?: GeotargetGeoTarget`

    Optional geotargeting parameters for proxy requests

    - `country?: string`

      Country code using ISO 3166-1 alpha-2 standard (2 letters, e.g., "US", "GB", "JP").
      See: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

  - `metadata?: boolean`

    Include extracted metadata (Open Graph and HTML metadata) as a separate field in the response

  - `nocache?: boolean`

    Bypass cache and force fresh data retrieval

### Returns

- `ExtractMarkdownResponse`

  - `content: string`

    The markdown content (includes metadata as YAML frontmatter by default)

  - `url: string`

    The URL that was converted to markdown

  - `metadata?: Metadata`

    Extracted metadata from the page (only included when metadata parameter is true)

    - `author?: string`

      Author information from HTML metadata

    - `created_at?: string`

      Document creation date (ISO 8601)

    - `creator?: string`

      Creator application (e.g., "Microsoft Word")

    - `description?: string`

      Page description from Open Graph or HTML

    - `favicon?: string`

      Favicon URL (resolved to absolute) parsed from <link rel="icon"> / "shortcut icon" / "apple-touch-icon"

    - `image?: string`

      Featured image URL from Open Graph

    - `keywords?: Array<string>`

      PDF keywords as array

    - `modified_at?: string`

      Document modification date (ISO 8601)

    - `page_count?: number`

      Number of pages (PDF documents)

    - `pdf_version?: string`

      PDF version (e.g., "1.5")

    - `producer?: string`

      PDF producer software (e.g., "Adobe PDF Library")

    - `publisher?: string`

      Publisher information from Open Graph

    - `site_name?: string`

      Site name from Open Graph

    - `subject?: string`

      PDF-specific metadata fields (populated for PDF documents)
      PDF subject or summary

    - `title?: string`

      Page title from Open Graph or HTML

    - `type?: string`

      Content type from Open Graph (e.g., article, website)

    - `url?: string`

      Canonical URL from Open Graph

### Example

```typescript
import Tabstack from '@tabstack/sdk';

const client = new Tabstack({
  apiKey: process.env['TABSTACK_API_KEY'], // This is the default and can be omitted
});

const response = await client.extract.markdown({ url: 'https://example.com/blog/article' });

console.log(response.content);
```

#### Response

```json
{
  "content": "# Example Article Title\n\nThis is the article content converted to markdown...",
  "metadata": {
    "author": "Example Author",
    "description": "This is an example article description",
    "image": "https://example.com/images/article.jpg",
    "publisher": "Example Publisher",
    "site_name": "Example Blog",
    "title": "Example Article Title",
    "type": "article",
    "url": "https://example.com/blog/article"
  },
  "url": "https://example.com/blog/article"
}
```

## Domain Types

### Extract Json Response

- `ExtractJsonResponse = Record<string, unknown>`

### Extract Markdown Response

- `ExtractMarkdownResponse`

  - `content: string`

    The markdown content (includes metadata as YAML frontmatter by default)

  - `url: string`

    The URL that was converted to markdown

  - `metadata?: Metadata`

    Extracted metadata from the page (only included when metadata parameter is true)

    - `author?: string`

      Author information from HTML metadata

    - `created_at?: string`

      Document creation date (ISO 8601)

    - `creator?: string`

      Creator application (e.g., "Microsoft Word")

    - `description?: string`

      Page description from Open Graph or HTML

    - `favicon?: string`

      Favicon URL (resolved to absolute) parsed from <link rel="icon"> / "shortcut icon" / "apple-touch-icon"

    - `image?: string`

      Featured image URL from Open Graph

    - `keywords?: Array<string>`

      PDF keywords as array

    - `modified_at?: string`

      Document modification date (ISO 8601)

    - `page_count?: number`

      Number of pages (PDF documents)

    - `pdf_version?: string`

      PDF version (e.g., "1.5")

    - `producer?: string`

      PDF producer software (e.g., "Adobe PDF Library")

    - `publisher?: string`

      Publisher information from Open Graph

    - `site_name?: string`

      Site name from Open Graph

    - `subject?: string`

      PDF-specific metadata fields (populated for PDF documents)
      PDF subject or summary

    - `title?: string`

      Page title from Open Graph or HTML

    - `type?: string`

      Content type from Open Graph (e.g., article, website)

    - `url?: string`

      Canonical URL from Open Graph