$ cli-blog docs

Authors

Create and manage public author profiles for post bylines.

Authors are public byline resources. Create an author before assigning its stable ID through a post's author_profile_ids field.

Choose a surface

The API, Node SDK, and CLI manage the same author records. Compare all Cli Blog tools.

ActionHTTP APINode SDKCLIDescription
ListGET /v1/authorsblog.authors.list() or .paginate()cli-blog authors listPage through public byline profiles
CreatePOST /v1/authorsblog.authors.create()cli-blog authors createCreate a profile and receive its ID
RetrieveGET /v1/authors/{id}blog.authors.get()cli-blog authors getGet a profile by ID or slug
UpdatePOST /v1/authors/{id}blog.authors.update()cli-blog authors updateChange public profile fields
DeleteDELETE /v1/authors/{id}blog.authors.delete()cli-blog authors deleteDelete a profile by ID or slug

Public and private keys can list and retrieve authors. Create, update, and delete actions require a private key with author permission.

Use the REST API

Call the resource from any technology that can send HTTP requests. Use a public key for allowed delivery reads and a private key for content changes.

GET or POST https://api.cli-blog.com/v1/authors
Choose an API key

Use the CLI

Use the CLI for local work, continuous integration, and JSON automation. Configure a narrowly scoped key before running content-changing commands.

cli-blog authors list --json
Read the CLI guide

Use the Node SDK

Use the Node SDK in Node.js 20+ servers, scripts, continuous integration, and trusted agent environments. Its methods map to the same resource actions.

await blog.authors.list({ limit: 20 })
Read the Node SDK guide

Use the agent skill

Give the agent the Cli Blog skill and a result-focused instruction. The skill helps it choose the API, CLI, or SDK and keeps publishing behind an approval gate.

List the existing authors. Create Maya Chen only if her slug does not exist, then return the author ID.
Install the agent skill

Create an author

This request creates the byline used throughout the examples:

curl "https://api.cli-blog.com/v1/authors" \
  --header "x-api-key: $CLI_BLOG_PRIVATE_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "public_name": "Maya Chen",
    "slug": "maya-chen",
    "bio": "Engineering notes about product systems and release workflows.",
    "website_url": "https://demo.cli-blog.example/authors/maya-chen"
  }'

The response returns a stable ID for post assignments:

{
  "id": "author_8af12c",
  "object": "author",
  "organization_id": "org_demo_acme",
  "public_name": "Maya Chen",
  "slug": "maya-chen",
  "bio": "Engineering notes about product systems and release workflows.",
  "avatar_media_id": null,
  "avatar_url": null,
  "website_url": "https://demo.cli-blog.example/authors/maya-chen",
  "metadata": {},
  "created_at": "2026-07-11T17:00:00.000Z",
  "updated_at": "2026-07-11T17:00:00.000Z"
}

The SDK and CLI create the same resource:

import { CliBlog } from "@cli-blog/node";

const blog = new CliBlog({
  apiKey: process.env.CLI_BLOG_PRIVATE_API_KEY!,
  apiUrl: "https://api.cli-blog.com",
});

const author = await blog.authors.create({
  public_name: "Maya Chen",
  slug: "maya-chen",
  bio: "Engineering notes about product systems and release workflows.",
});
cli-blog authors create \
  --public-name "Maya Chen" \
  --slug maya-chen \
  --bio "Engineering notes about product systems and release workflows." \
  --json

List and retrieve authors

Cursor pagination is the preferred list mode. Set limit up to 100, then pass next_cursor as after. Use numbered pagination only when a page interface requires exact totals. See Pagination.

const firstPage = await blog.authors.list({ limit: 20 });
const nextPage = firstPage.next_cursor
  ? await blog.authors.list({ limit: 20, after: firstPage.next_cursor })
  : null;

const maya = await blog.authors.get("maya-chen");
cli-blog authors list --limit 20 --json
cli-blog authors get maya-chen --json

Update and delete an author

Update only the fields that changed. member_id can associate a byline with an organization member, but public responses never expose that editorial link.

await blog.authors.update("author_8af12c", {
  bio: "Product engineering notes and practical release guides.",
  avatar_media_id: "media_c81f20",
});

await blog.authors.delete("author_8af12c");
cli-blog authors update author_8af12c \
  --bio "Product engineering notes and practical release guides." \
  --avatar-media-id media_c81f20 \
  --json

cli-blog authors delete author_8af12c --yes

Review post assignments before deleting a profile used by published content.

Author fields

FieldDescription
idStable profile ID used in author_profile_ids
public_nameReader-facing byline name; required on create
slugOrganization-unique author slug; derived from public_name when omitted
bioPublic author biography
avatar_media_idUploaded media ID used as the avatar
avatar_urlPublic avatar URL derived from the media asset
website_urlPublic author website URL
member_idOptional editorial link to an organization member; write-only for the public API
metadataIntegration-defined JSON object, up to 32 KB when serialized
created_at, updated_atISO timestamps returned by the API

Common errors

StatusCauseResolution
400Missing name, invalid URL, invalid metadata, or mixed pagination modesCheck the error param and request body
401Missing or invalid API keySend x-api-key with the organization key
403Public key used for a write or private key lacks author permissionUse a scoped private key
404ID or slug does not exist in the organizationConfirm the organization and identifier
409Slug already belongs to another authorChoose a unique author slug

Complete API operations

The operation reference lists every path, request field, response field, validation rule, and error schema. Use Try it to open the request runner.

List authors

Key type: Public or private key

List author profiles that can be assigned to posts with author_profile_ids. Cursor pagination is the default; page and per_page opt into exact numbered pagination and cannot be combined with after or limit.

Authorization

ApiKeyAuth
x-api-key<token>

Organization API key. Each key selects exactly one organization; do not send an organization ID separately. Public keys use the cli_blog_pk_ prefix and are intended for published-content delivery reads. Private keys use the cli_blog_sk_ prefix, belong only in trusted environments, and are required for write, publish, delete, and editorial-state workflows when their scopes allow it.

In: header

Query Parameters

after?string

Opaque cursor returned by the previous list page.

limit?|

Maximum authors to return. Defaults to 20. The maximum accepted value is 100.

page?|

One-based exact page number. Supplying page selects numbered pagination and cannot be combined with after or limit.

per_page?|

Items per numbered page. Requires page, defaults to 20, and cannot be combined with after or limit.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/authors"
{  "object": "list",  "has_more": true,  "next_cursor": "string",  "page": 0,  "per_page": 0,  "total_items": 0,  "total_pages": 0,  "data": [    {      "id": "string",      "object": "author",      "organization_id": "string",      "public_name": "string",      "slug": "string",      "bio": "string",      "avatar_media_id": "string",      "avatar_url": "string",      "website_url": "string",      "metadata": null,      "created_at": "string",      "updated_at": "string"    }  ]}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Create an author

Key type: Private key

Send a JSON body to create a public byline profile, then assign its id to posts.

Authorization

ApiKeyAuth
x-api-key<token>

Organization API key. Each key selects exactly one organization; do not send an organization ID separately. Public keys use the cli_blog_pk_ prefix and are intended for published-content delivery reads. Private keys use the cli_blog_sk_ prefix, belong only in trusted environments, and are required for write, publish, delete, and editorial-state workflows when their scopes allow it.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/authors" \  -H "Content-Type: application/json" \  -d '{    "public_name": "string"  }'
{  "id": "string",  "object": "author",  "organization_id": "string",  "public_name": "string",  "slug": "string",  "bio": "string",  "avatar_media_id": "string",  "avatar_url": "string",  "website_url": "string",  "metadata": null,  "created_at": "string",  "updated_at": "string"}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Retrieve an author

Key type: Public or private key

Retrieve an author by author ID or author slug.

Authorization

ApiKeyAuth
x-api-key<token>

Organization API key. Each key selects exactly one organization; do not send an organization ID separately. Public keys use the cli_blog_pk_ prefix and are intended for published-content delivery reads. Private keys use the cli_blog_sk_ prefix, belong only in trusted environments, and are required for write, publish, delete, and editorial-state workflows when their scopes allow it.

In: header

Path Parameters

id*string

Author ID or author slug.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/authors/string"
{  "id": "string",  "object": "author",  "organization_id": "string",  "public_name": "string",  "slug": "string",  "bio": "string",  "avatar_media_id": "string",  "avatar_url": "string",  "website_url": "string",  "metadata": null,  "created_at": "string",  "updated_at": "string"}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Update an author

Key type: Private key

Send a JSON body to update an author by author ID or author slug.

Authorization

ApiKeyAuth
x-api-key<token>

Organization API key. Each key selects exactly one organization; do not send an organization ID separately. Public keys use the cli_blog_pk_ prefix and are intended for published-content delivery reads. Private keys use the cli_blog_sk_ prefix, belong only in trusted environments, and are required for write, publish, delete, and editorial-state workflows when their scopes allow it.

In: header

Path Parameters

id*string

Author ID or author slug.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/authors/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "object": "author",  "organization_id": "string",  "public_name": "string",  "slug": "string",  "bio": "string",  "avatar_media_id": "string",  "avatar_url": "string",  "website_url": "string",  "metadata": null,  "created_at": "string",  "updated_at": "string"}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Delete an author

Key type: Private key

Delete an author profile by author ID or author slug.

Authorization

ApiKeyAuth
x-api-key<token>

Organization API key. Each key selects exactly one organization; do not send an organization ID separately. Public keys use the cli_blog_pk_ prefix and are intended for published-content delivery reads. Private keys use the cli_blog_sk_ prefix, belong only in trusted environments, and are required for write, publish, delete, and editorial-state workflows when their scopes allow it.

In: header

Path Parameters

id*string

Author ID or author slug.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/authors/string"
{  "deleted": true,  "id": "string"}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Posts

Create, deliver, relate, update, publish, schedule, translate, and delete Markdown posts.

Media

Upload and manage images, documents, and video assets for posts and author profiles.

On this page

Choose a surfaceUse the REST APIUse the CLIUse the Node SDKUse the agent skillCreate an authorList and retrieve authorsUpdate and delete an authorAuthor fieldsCommon errorsComplete API operationsList authorsCreate an authorRetrieve an authorUpdate an authorDelete an author