# Lobsters API
> A live feed of the Lobsters computing social-news community (lobste.rs) as an API. Pull the hottest (front-page) or newest stories with their score, comment count, tags and submitter; fetch a single story by its short id; list the stories filed under a tag; look a user's profile up (karma, join date, about); or list every tag. The Lobsters front page and community graph as clean JSON for social, news-aggregation, reading-list and dashboard apps. Live data, no key. Distinct from other social-news platforms.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/lobsters-api/..."
```

## Pricing
- **Free** (Free) — 500 calls/Mo, 5 req/s
- **Starter** ($8/Mo) — 15,000 calls/Mo, 15 req/s
- **Pro** ($19/Mo) — 70,000 calls/Mo, 30 req/s
- **Business** ($46/Mo) — 350,000 calls/Mo, 50 req/s

## Endpoints

### Stories

#### `GET /v1/hottest` — Hottest (front-page) stories

**Parameters:**
- `limit` (query, optional, string) — Max 1-100 Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lobsters-api/v1/hottest?limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "total": 25,
        "stories": [
            {
                "url": "https://www.apple.com/apple-events/event-stream/",
                "tags": [
                    "event",
                    "ios",
                    "mac",
                    "swift",
                    "video"
                ],
                "score": 56,
                "title": "WWDC 2026",
                "short_id": "awlukh",
                "submitter": "calvin",
                "created_at": "2026-06-08T11:52:38.000-05:00",
                "description": "You'd think I'd forget dubdub? (Title isn't WWDC because the site thinks I'M SCREAMING IN ALL CAPS.)",
                "comments_url": "https://lobste.rs/s/awlukh/wwdc_2026",
                "lobsters_url": "https://lobste.rs/s/awlukh",
                "comment_count": 13
            },
            {
                "url": "https://invlpg.com/posts/2025-06-19-premature-optimization.html",
                "tags": [
                    "c",
                    "performance"
                ],
                "score": 78,
                "title": "Premature Optimization is Fun Sometimes (2025)",
                "short_id": "109l2t",
                "submitter": "invlpg",
                "created_at": "2026-06-08T02:41:58.000-05:00",
                "description": null,
                "comments_url": "https://lobste.rs/s/109l2t/premature_optimization_is_fun_sometimes",
                "lobsters_url
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/newest` — Newest stories

**Parameters:**
- `limit` (query, optional, string) — Max 1-100 Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lobsters-api/v1/newest?limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "total": 25,
        "stories": [
            {
                "url": "https://www.codingwithjesse.com/blog/rockstar-developers/",
                "tags": [
                    "practices"
                ],
                "score": 2,
                "title": "Cleaning up after AI rockstar developers",
                "short_id": "uvwcdo",
                "submitter": "jesseskinner",
                "created_at": "2026-06-08T21:32:38.000-05:00",
                "description": null,
                "comments_url": "https://lobste.rs/s/uvwcdo/cleaning_up_after_ai_rockstar_developers",
                "lobsters_url": "https://lobste.rs/s/uvwcdo",
                "comment_count": 0
            },
            {
                "url": "https://arxiv.org/html/2409.05351",
                "tags": [
                    "compsci",
                    "plt"
                ],
                "score": 0,
                "title": "𝜇⁢𝜆⁢ϵ⁢𝛿-Calculus: Self Optimizing Language that Seems to Exhibit Paradoxical Transfinite Cognitive Capabilities",
                "short_id": "ta3ipk",
                "submitter": "veqq",
                "created_at": "2026-06-08T20:12:27.000-05:00",
                "description": null,
                "comments_url": "https://lobste.rs/s/ta3ipk/calculus_self_optimizing_language_seems",
                "lobsters_url": "https://lobste.rs/s/ta3ipk",
                "comment_count": 1
            },
  
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/story` — Single story by short id

**Parameters:**
- `id` (query, required, string) — Story short id Example: `109l2t`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lobsters-api/v1/story?id=109l2t"
```

**Response:**
```json
{
    "data": {
        "story": {
            "url": "https://invlpg.com/posts/2025-06-19-premature-optimization.html",
            "tags": [
                "c",
                "performance"
            ],
            "score": 78,
            "title": "Premature Optimization is Fun Sometimes (2025)",
            "comments": 9,
            "short_id": "109l2t",
            "submitter": "invlpg",
            "created_at": "2026-06-08T02:41:58.000-05:00",
            "description": null,
            "comments_url": "https://lobste.rs/s/109l2t/premature_optimization_is_fun_sometimes",
            "lobsters_url": "https://lobste.rs/s/109l2t",
            "comment_count": 9
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:43.631Z",
        "request_id": "201906a2-a276-4b4a-b470-c25c6ddf2b11"
    },
    "status": "ok",
    "message": "Story retrieved successfully",
    "success": true
}
```

#### `GET /v1/tag` — Stories filed under a tag

**Parameters:**
- `tag` (query, required, string) — Tag Example: `web`
- `limit` (query, optional, string) — Max 1-100 Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lobsters-api/v1/tag?tag=web&limit=25"
```

**Response:**
```json
{
    "data": {
        "tag": "web",
        "count": 25,
        "total": 25,
        "stories": [
            {
                "url": "https://forgejo.org/2026-05-monthly-report/",
                "tags": [
                    "vcs",
                    "web"
                ],
                "score": 16,
                "title": "Forgejo monthly report - May 2026",
                "short_id": "ewaxh7",
                "submitter": "FedericoSchonborn",
                "created_at": "2026-06-08T13:41:21.000-05:00",
                "description": null,
                "comments_url": "https://lobste.rs/s/ewaxh7/forgejo_monthly_report_may_2026",
                "lobsters_url": "https://lobste.rs/s/ewaxh7",
                "comment_count": 2
            },
            {
                "url": "https://dbushell.com/2024/04/16/htmx-and-modern-javascript/",
                "tags": [
                    "javascript",
                    "web"
                ],
                "score": 33,
                "title": "HTMX Is So Cool I Rolled My Own (2024)",
                "short_id": "8hiogg",
                "submitter": "FedericoSchonborn",
                "created_at": "2026-06-08T07:20:23.000-05:00",
                "description": null,
                "comments_url": "https://lobste.rs/s/8hiogg/htmx_is_so_cool_i_rolled_my_own_2024",
                "lobsters_url": "https://lobste.rs/s/8hiogg",
                "comment_count": 15
            },
            {
                "
…(truncated, see openapi.json for full schema)
```

### Community

#### `GET /v1/tags` — All tags

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lobsters-api/v1/tags"
```

**Response:**
```json
{
    "data": {
        "tags": [
            {
                "tag": "ruby",
                "category": "languages",
                "description": "Ruby programming",
                "stories_count": null
            },
            {
                "tag": "event",
                "category": "genre",
                "description": "Events, conferences, and meetups",
                "stories_count": null
            },
            {
                "tag": "person",
                "category": "culture",
                "description": "Stories about particular persons",
                "stories_count": null
            },
            {
                "tag": "meta",
                "category": "lobsters",
                "description": "Lobsters-related bikeshedding - report bugs at https://github.com/lobsters/lobsters",
                "stories_count": null
            },
            {
                "tag": "php",
                "category": "languages",
                "description": "PHP programming",
                "stories_count": null
            },
            {
                "tag": "python",
                "category": "languages",
                "description": "Python programming",
                "stories_count": null
            },
            {
                "tag": "news",
                "category": "genre",
                "description": "General news and current events",
                "stories_count": null
            },
            {
              
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/user` — User profile

**Parameters:**
- `username` (query, required, string) — Username Example: `jcs`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lobsters-api/v1/user?username=jcs"
```

**Response:**
```json
{
    "data": {
        "user": {
            "about": "<p>hello, cyberpals</p>\n",
            "karma": 16853,
            "is_admin": false,
            "username": "jcs",
            "avatar_url": "https://lobste.rs/avatars/jcs-100.png",
            "created_at": "2012-06-30T16:39:19.000-05:00",
            "is_moderator": false,
            "github_username": "jcs",
            "invited_by_user": null,
            "mastodon_username": null
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:44.299Z",
        "request_id": "16fe7d3f-8ae7-4627-8956-0bf790112cab"
    },
    "status": "ok",
    "message": "User retrieved successfully",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/lobsters-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "source": "lobste.rs public JSON (live)",
        "service": "lobsters-api",
        "endpoints": {
            "GET /v1/tag": "Stories filed under a tag (tag=, e.g. web, limit).",
            "GET /v1/meta": "This document.",
            "GET /v1/tags": "All tags with story counts.",
            "GET /v1/user": "User profile (username=, e.g. jcs).",
            "GET /v1/story": "Single story by short id (id=, e.g. ewaxh7).",
            "GET /v1/newest": "Newest stories (limit).",
            "GET /v1/hottest": "Hottest (front-page) stories (limit)."
        },
        "description": "Live feed of the Lobsters computing social-news community (lobste.rs): hottest and newest stories with score, comments, tags and submitter; single story by short id; stories by tag; user profiles (karma, join date, about); and the full tag list. Live, no key.",
        "hottest_now": 25
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:44.488Z",
        "request_id": "e43f568d-70ba-45cd-9f0d-4941157a861e"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/lobsters-api
OpenAPI spec: https://www.oanor.com/api/lobsters-api/openapi.json