---
title: Authors
description: One directory of people, shared by every module that credits anybody.
---

A built-in module: the people who write. One person is one row whether they
write blog articles, knowledge base articles or both, which is why this lives
at `/v1/authors` and not under `/v1/blog`.

Release-independent, like the other modules.

## List authors

```http
GET /v1/authors
```

Every author alphabetically, each with their avatar, their three article counts
and the resolved `seo` of their page. That is enough to build a contributors
page from one request.

Takes `limit`, `offset` and `media_urls`.

## One author

```http
GET /v1/authors/{slug}
```

```json
{
  "data": {
    "id": "aut_…",
    "name": "Ada Lovelace",
    "slug": "ada",
    "bio": "Writes about deploys.",
    "avatar": { "url": "…", "alt": "…", "width": 400, "height": 400, "content_type": "image/jpeg" },
    "social": {
      "website": "https://ada.example.com",
      "x": "https://x.com/ada",
      "x_handle": "ada",
      "github": "https://github.com/ada",
      "github_handle": "ada",
      "linkedin": "https://linkedin.com/in/ada",
      "mastodon": null
    },
    "article_count": 14,
    "blog_article_count": 9,
    "kb_article_count": 5,
    "seo": { "title": "Ada Lovelace", "description": "Writes about deploys.", "og_image": {}, "canonical_url": null, "noindex": false }
  },
  "meta": { "module": "authors", "release_independent": true }
}
```

An unknown slug teaches with `did_you_mean` and names every author slug that
exists.

## Choose the count deliberately

Three numbers, and picking the wrong one is the mistake this module invites:

- **`article_count`**: every module together. What an author page across the
  whole site wants.
- **`blog_article_count`**: what a blog index means by "9 articles" under a
  byline.
- **`kb_article_count`**: knowledge base articles.

Printing the total under a blog byline overstates it for anyone who also writes
help articles.

> **INFO: Why `article_count` means the total**
>
> It was the blog's count when the blog was the only module that credited
> anyone. Renaming it would have removed a key integrations depend on, so instead
> it now means what the word actually describes, with the two breakdowns added
> beside it. No key disappeared.

## Social links

Both forms are served, resolved for you:

- `x_handle` / `github_handle`: the handle, stored without an `@`. Print this.
- `x` / `github` / `linkedin` / `mastodon` / `website`: the full URL. Link
  this.

Each is a string or null. You never have to build a profile URL from a handle,
or strip one out of a URL to display it.

## An author page is two requests

The person, and their articles:

```
GET /v1/authors/ada
GET /v1/blog/articles?author=ada&limit=20
```

There is no "articles by this author" endpoint, because the listing endpoint
already filters, pages and searches. `?author=` matches an article crediting
that person **anywhere** in its `authors`, so a co-authored post appears on
both authors' pages.

> **WARNING: The knowledge base has no `?author=` filter**
>
> `kb_article_count` tells you how many knowledge base articles somebody has
> written; there is no public endpoint that lists them. If you need that page,
> ask. It is an addition, not something to work around.

## References and pages

Nested inside an article, an author is a **reference**: id, name, slug, bio and
`social`. No `article_count`, no `avatar` on the knowledge base's byline, and
no `seo`. Those belong to the page, and a card printing twenty bylines will
never render twenty og images.

Fetch `/v1/authors/{slug}` for the page shape.

## Notes

- **Read-only**, any key kind. Authors are managed in the dashboard.
- These URLs were `/v1/blog/authors` before launch and moved when the knowledge
  base began crediting the same people. The old paths are gone, not redirected.