Blog Authors

Create, read, update, delete, bulk manage, and subscribe to blog authors through the Store API.

Blog authors provide the identity displayed with posts. Reads require read_blog; writes require write_blog. Names are required and determine the generated slug. Setting a non-empty avatar_media_id also requires read_files. Name and bio are translatable.

To delete an author assigned to posts, provide reassign_to_author_id for another author in the same store. The posts move to that author as part of the deletion. A large reassignment runs as a job. Posts are not deleted or left without an author. For bulk deletion, the replacement must not be among the authors being deleted.

Endpoints#

Blog Author limits

GET read_blog

Fetch blog author limits.

Returns field, pagination, search, and store caps for this store. max_per_store is this store's plan cap, count is how many exist now, and usage is the localized label.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

List blog authors

GET read_blog

List store blog authors.

Returns a strictly paginated list. Search and sorting are validated before pagination.

Query parameters

Name Type Description
page integer

Page number.

Example: 1
limit integer

Page size, up to list_max_limit from the Blog Author limits.

Example: 20
search string

Search by name or slug.

Example: avery
sort_by string

Sort field.

Allowed values
namepost_countupdated_at
Example: name
sort_direction string

Sort direction.

Allowed values
ascdesc
Example: asc

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 VALIDATION_LIST_INVALID_PAGE

    Page must be a positive integer.

  • 400 VALIDATION_LIST_INVALID_LIMIT

    Limit must be a positive integer within the contract cap.

  • 400 VALIDATION_LIST_INVALID_SORT_BY

    Sort field is not supported for Blog Authors.

  • 400 VALIDATION_LIST_INVALID_SORT_DIRECTION

    Sort direction must be asc or desc.

  • 400 BLOG_AUTHOR_SEARCH_TOO_LONG

    Search exceeds the Blog Author contract max length.

Search blog authors

GET read_blog

Search blog authors for picker UIs.

Returns lightweight store-scoped author options.

Query parameters

Name Type Description
q string

Search by name or slug.

Example: avery
limit integer

Suggestion count.

Example: 10
offset integer

Number of suggestions to skip.

Example: 0

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 VALIDATION_LIST_INVALID_LIMIT

    Limit must be a positive integer.

  • 400 INVALID_INPUT

    Offset must be zero or greater.

  • 400 BLOG_AUTHOR_SEARCH_TOO_LONG

    Search exceeds the Blog Author contract max length.

Get a blog author

GET read_blog

Fetch one blog author.

Returns the author when it belongs to the token's store.

Path parameters

Name Type Description
id required uuid

Blog Author id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Blog Author id is not a valid UUID.

  • 404 BLOG_AUTHOR_NOT_FOUND

    Blog Author does not exist in this store.

Create a blog author

POST write_blog

Create a store-scoped blog author.

The slug is generated from the name. A non-empty avatar_media_id must reference an uploaded image in this store and also requires read_files.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name required string

Author display name.

Example: Avery Stone
bio string

Author biography.

Example: Writes product and company updates.
avatar_media_id uuid

Uploaded image UUID. A non-empty value requires read_files; null clears it on update.

Example: 8f2a1c2b-9d4e-4a56-b789-0123456789ab

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is malformed, contains unknown fields, or has an invalid Blog Author id.

  • 400 BLOG_AUTHOR_NAME_REQUIRED

    Name is required.

  • 400 BLOG_AUTHOR_NAME_TOO_LONG

    Name exceeds the contract limit.

  • 400 BLOG_AUTHOR_BIO_TOO_LONG

    Bio exceeds the contract limit.

  • 400 BLOG_AUTHOR_SLUG_GENERATION_FAILED

    A unique slug could not be generated from the author name.

  • 404 NOT_FOUND

    The supplied avatar image does not exist in this store.

  • 400 INVALID_INPUT

    avatar_media_id is malformed, is not an image, or belongs to another store.

  • 403 STORE_API_SCOPE_REQUIRED

    A non-empty avatar_media_id requires read_files in addition to write_blog.

  • 400 BLOG_AUTHOR_LIMIT_REACHED

    The store author limit has been reached.

  • 400 BLOG_AUTHOR_PLAN_LIMIT_REACHED

    This store is at its plan blog author cap.

Update a blog author

PUT write_blog

Update one blog author.

Omitted fields are unchanged. Renaming regenerates the generated slug.

Path parameters

Name Type Description
id required uuid

Blog Author id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name string

Author display name.

Example: Avery Stone
bio string

Author biography.

Example: Writes product and company updates.
avatar_media_id uuid

Uploaded image UUID. A non-empty value requires read_files; null clears it on update.

Example: 8f2a1c2b-9d4e-4a56-b789-0123456789ab

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is malformed, contains unknown fields, or has an invalid Blog Author id.

  • 400 BLOG_AUTHOR_NAME_REQUIRED

    Name is required.

  • 400 BLOG_AUTHOR_NAME_TOO_LONG

    Name exceeds the contract limit.

  • 400 BLOG_AUTHOR_BIO_TOO_LONG

    Bio exceeds the contract limit.

  • 400 BLOG_AUTHOR_SLUG_GENERATION_FAILED

    A unique slug could not be generated from the author name.

  • 404 NOT_FOUND

    The supplied avatar image does not exist in this store.

  • 400 INVALID_INPUT

    avatar_media_id is malformed, is not an image, or belongs to another store.

  • 403 STORE_API_SCOPE_REQUIRED

    A non-empty avatar_media_id requires read_files in addition to write_blog.

  • 404 BLOG_AUTHOR_NOT_FOUND

    Blog Author does not exist in this store.

Delete a blog author

DELETE write_blog

Delete one blog author.

If posts reference the author, the request must name reassign_to_author_id; otherwise it returns BLOG_AUTHOR_REASSIGN_REQUIRED. The named author takes over every assigned post in the same transaction as the delete. No post is deleted or left without an author.

Path parameters

Name Type Description
id required uuid

Blog Author id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
reassign_to_author_id string

Author UUID that takes over this author's posts. Required when the author has posts.

Example: 5d0a6f3e-2c1b-4e8f-9a7d-3b2c1d0e9f8a

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Blog Author id or delete request body is invalid.

  • 404 BLOG_AUTHOR_NOT_FOUND

    Blog Author does not exist in this store.

  • 409 BLOG_AUTHOR_REASSIGN_REQUIRED

    The author has assigned posts. Retry with reassign_to_author_id naming the author who takes them over.

  • 400 BLOG_AUTHOR_REASSIGN_TARGET_INVALID

    reassign_to_author_id is missing from the store or is the author being deleted.

  • 409 BLOG_AUTHOR_BULK_RACED

    Author assignments changed during deletion; retry from fresh state.

Bulk delete blog authors

POST write_blog

Delete multiple blog authors.

Missing authors are reported in failed. If any selected author is assigned to posts, the request must name reassign_to_author_id (an author outside the selection); otherwise it returns BLOG_AUTHOR_BULK_REASSIGN_REQUIRED. The named author takes over every assigned post and the selected authors are deleted atomically.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
author_ids required array<string>

Store-scoped author UUIDs.

Example: ["44bf70b7-88e2-4770-a30e-d7a1db522499"]
reassign_to_author_id string

Author UUID, outside the selection, that takes over the selected authors' posts. Required when any has posts.

Example: 5d0a6f3e-2c1b-4e8f-9a7d-3b2c1d0e9f8a

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is malformed, contains unknown fields, or includes an invalid UUID.

  • 400 BLOG_AUTHOR_BULK_NO_IDS

    No author IDs were supplied.

  • 400 BLOG_AUTHOR_BULK_DELETE_TOO_MANY

    The batch exceeds the documented cap.

  • 409 BLOG_AUTHOR_BULK_REASSIGN_REQUIRED

    One or more selected authors have assigned posts. Retry with reassign_to_author_id naming the author who takes them over.

  • 400 BLOG_AUTHOR_REASSIGN_TARGET_INVALID

    reassign_to_author_id is missing from the store or is one of the selected authors.

  • 409 BLOG_AUTHOR_BULK_RACED

    Author assignments changed during deletion; retry from fresh state.

Fields#

Field

Type

Create

Update

Required

Translatable

name

string

Yes

Yes

create

Yes

slug

string

No

No

No

bio

string

Yes

Yes

Yes

avatar_media_id

string (UUID)

Yes

Yes

No

post_count

integer

No

No

No

created_at

string (RFC 3339)

No

No

No

updated_at

string (RFC 3339)

No

No

No

Webhook events#

Subscribe to these events to keep your integration in sync with blog authors. Each event shows the required Store API scope and store permission, the available payload fields, and an example payload. Subscription setup is validated against those permissions; delivery is always restricted to the subscription's store.

Blog author created

EVENT blog_authors/create App scope: read_blog Staff permission: blog:write

Fired when a blog author is created.

Payload fields

Field Type Description
blog_author.id string Always present
blog_author.name string Selectable in the Payload builder
blog_author.slug string Selectable in the Payload builder
blog_author.bio string Selectable in the Payload builder
blog_author.avatar_url string Selectable in the Payload builder
blog_author.created_at string Selectable in the Payload builder

Blog author updated

EVENT blog_authors/update App scope: read_blog Staff permission: blog:write

Fired when a blog author is updated.

Payload fields

Field Type Description
blog_author.id string Always present
blog_author.name string Selectable in the Payload builder
blog_author.slug string Selectable in the Payload builder
blog_author.bio string Selectable in the Payload builder
blog_author.avatar_url string Selectable in the Payload builder
blog_author.created_at string Selectable in the Payload builder

Blog author deleted

EVENT blog_authors/delete App scope: read_blog Staff permission: blog:write

Fired when a blog author is deleted.

Payload fields

Field Type Description
blog_author.id string Always present
blog_author.name string Selectable in the Payload builder
blog_author.slug string Selectable in the Payload builder