> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API

> API reference for Hacker News: every `hackernews.api.*` operation with input and output types.

Every `hackernews.api.*` operation is listed below with parameter shapes and return types from the plugin Zod schemas.

<Info>
  **New to Corsair?** See [API access](/concepts/api), [authentication](/concepts/auth), and [error handling](/concepts/error-handling).
</Info>

## Items

### get

`items.get`

Get a HackerNews item by numeric ID

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.items.get({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `number` | Yes | — |
| `type` | `job \| story \| comment \| poll \| pollopt` | Yes | — |
| `by` | `string` | No | — |
| `title` | `string` | No | — |
| `url` | `string` | No | — |
| `text` | `string` | No | — |
| `score` | `number` | No | — |
| `time` | `number` | No | — |
| `descendants` | `number` | No | — |
| `parent` | `number` | No | — |
| `poll` | `number` | No | — |
| `kids` | `number[]` | No | — |
| `parts` | `number[]` | No | — |
| `dead` | `boolean` | No | — |
| `deleted` | `boolean` | No | — |

***

### getMaxId

`items.getMaxId`

Get the current maximum item ID

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.items.getMaxId({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `print` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `max_item_id` | `number` | Yes | — |

***

### getWithId

`items.getWithId`

Get a HackerNews item with nested comments

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.items.getWithId({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `item_id` | `string` | Yes | — |
| `max_depth` | `number` | No | — |
| `max_children` | `number` | No | — |
| `truncate_text` | `boolean` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `found` | `boolean` | Yes | — |
| `item` | `object` | No | — |
| `error_message` | `string` | No | — |

<AccordionGroup>
  <Accordion title="item full type">
    ```ts theme={null}
    {
      id: number,
      type?: string,
      author?: string,
      title?: string | null,
      url?: string | null,
      text?: string | null,
      points?: number | null,
      parent_id?: number | null,
      story_id?: number | null,
      created_at?: string,
      created_at_i?: number,
      options?: number[],
      children?: {
      }[],
      children_shown?: number,
      max_depth_reached?: boolean,
      children_truncated?: boolean,
      total_children_count?: number
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Search

### getFrontpage

`search.getFrontpage`

Get current HackerNews frontpage posts

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.search.getFrontpage({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `min_points` | `number` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `posts` | `object[]` | Yes | — |
| `total_hits` | `number` | Yes | — |

<AccordionGroup>
  <Accordion title="posts full type">
    ```ts theme={null}
    {
      objectID?: string,
      title?: string,
      url?: string | null,
      author?: string,
      points?: number | null,
      story_id?: number | null,
      created_at?: string,
      num_comments?: number | null,
      story_text?: string | null
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### getLatest

`search.getLatest`

Get latest HackerNews posts

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.search.getLatest({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `tags` | `string[]` | No | — |
| `page` | `number` | No | — |
| `size` | `number` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `hits` | `object[]` | Yes | — |
| `nbHits` | `number` | Yes | — |
| `page` | `number` | Yes | — |
| `nbPages` | `number` | Yes | — |
| `hitsPerPage` | `number` | Yes | — |

<AccordionGroup>
  <Accordion title="hits full type">
    ```ts theme={null}
    {
      objectID?: string,
      title?: string,
      url?: string | null,
      author?: string,
      points?: number | null,
      story_id?: number | null,
      story_url?: string | null,
      story_title?: string | null,
      comment_text?: string | null,
      story_text?: string | null,
      created_at?: string,
      created_at_i?: number,
      num_comments?: number | null,
      _tags?: string[]
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### getTodays

`search.getTodays`

Get today's HackerNews posts

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.search.getTodays({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `min_points` | `number` | No | — |
| `page` | `number` | No | — |
| `size` | `number` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `hits` | `object[]` | Yes | — |
| `nbHits` | `number` | Yes | — |
| `page` | `number` | Yes | — |
| `nbPages` | `number` | Yes | — |
| `hitsPerPage` | `number` | Yes | — |

<AccordionGroup>
  <Accordion title="hits full type">
    ```ts theme={null}
    {
      objectID?: string,
      title?: string,
      url?: string | null,
      author?: string,
      points?: number | null,
      story_id?: number | null,
      created_at?: string,
      num_comments?: number | null
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

### posts

`search.posts`

Full-text search HackerNews posts

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.search.posts({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | — |
| `tags` | `string[]` | No | — |
| `page` | `number` | No | — |
| `size` | `number` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `hits` | `object[]` | Yes | — |
| `nbHits` | `number` | Yes | — |
| `page` | `number` | Yes | — |
| `nbPages` | `number` | Yes | — |
| `hitsPerPage` | `number` | Yes | — |
| `query` | `string` | Yes | — |

<AccordionGroup>
  <Accordion title="hits full type">
    ```ts theme={null}
    {
      objectID?: string,
      title?: string,
      url?: string | null,
      author?: string,
      points?: number | null,
      story_id?: number | null,
      story_url?: string | null,
      story_title?: string | null,
      comment_text?: string | null,
      story_text?: string | null,
      created_at?: string,
      created_at_i?: number,
      num_comments?: number | null,
      _tags?: string[]
    }[]
    ```
  </Accordion>
</AccordionGroup>

***

## Stories

### getAsk

`stories.getAsk`

Get Ask HN story IDs

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.stories.getAsk({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `print` | `pretty` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `story_ids` | `number[]` | Yes | — |

***

### getBest

`stories.getBest`

Get best HackerNews story IDs

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.stories.getBest({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `print` | `pretty` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `story_ids` | `number[]` | Yes | — |
| `count` | `number` | Yes | — |

***

### getJobs

`stories.getJobs`

Get HackerNews job story IDs

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.stories.getJobs({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `print` | `pretty` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `job_story_ids` | `number[]` | Yes | — |

***

### getNew

`stories.getNew`

Get newest HackerNews story IDs

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.stories.getNew({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `print` | `pretty` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `story_ids` | `number[]` | Yes | — |

***

### getShow

`stories.getShow`

Get Show HN story IDs

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.stories.getShow({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `print` | `pretty` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `story_ids` | `number[]` | Yes | — |

***

### getTop

`stories.getTop`

Get top HackerNews story IDs

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.stories.getTop({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `print` | `pretty` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `story_ids` | `number[]` | Yes | — |
| `count` | `number` | Yes | — |

***

## Updates

### get

`updates.get`

Get recently changed HackerNews items and profiles

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.updates.get({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `print` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `number[]` | Yes | — |
| `profiles` | `string[]` | Yes | — |

***

## Users

### get

`users.get`

Get a HackerNews user profile via Algolia

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.users.get({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `username` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `username` | `string` | Yes | — |
| `karma` | `number` | Yes | — |
| `about` | `string` | No | — |

***

### getByUsername

`users.getByUsername`

Get a HackerNews user profile via Firebase

**Risk:** `read`

```ts theme={null}
await corsair.hackernews.api.users.getByUsername({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `username` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `karma` | `number` | Yes | — |
| `created` | `number` | Yes | — |
| `about` | `string` | No | — |
| `submitted` | `number[]` | No | — |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.