$ cli-blog docs
API ReferenceAPI Reference

Media

Resource overviewUpload-first media assets for posts, attachments, and social previews.
AuthenticationPublic reads or private writes
Common workflowUpload the file, keep its generated media ID, then attach it to content or SEO fields.
Read the action guide

List media assets

Key type: Private key

List uploaded media assets. 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 media list page.

limit?|

Maximum media assets 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/media"
{  "object": "list",  "has_more": true,  "next_cursor": "string",  "page": 0,  "per_page": 0,  "total_items": 0,  "total_pages": 0,  "data": [    {      "id": "string",      "object": "media_asset",      "organization_id": "string",      "url": "string",      "original_filename": "string",      "alt_text": "string",      "caption": "string",      "mime_type": "string",      "width": 0,      "height": 0,      "size_bytes": 0,      "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"  }}

Upload media asset

Key type: Private key

Send multipart file data to upload a supported blog media file into service-managed storage and create the media record with generated URL and storage metadata. SVG uploads are limited to safe static vector markup and reject scripts, embedded HTML, animation, external references, and unsafe CSS. This file route is the content API exception to JSON write bodies.

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

multipart/form-data

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

application/json

curl -X POST "https://example.com/v1/media" \  -F file="File"
{  "id": "string",  "object": "media_asset",  "organization_id": "string",  "url": "string",  "original_filename": "string",  "alt_text": "string",  "caption": "string",  "mime_type": "string",  "width": 0,  "height": 0,  "size_bytes": 0,  "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"  }}
{  "error": {    "code": "invalid_request",    "message": "string",    "param": "string"  }}

Retrieve media asset

Key type: Private key

Retrieve one uploaded media asset.

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/media/string"
{  "id": "string",  "object": "media_asset",  "organization_id": "string",  "url": "string",  "original_filename": "string",  "alt_text": "string",  "caption": "string",  "mime_type": "string",  "width": 0,  "height": 0,  "size_bytes": 0,  "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 media asset

Key type: Private key

Send a JSON body to update editorial media metadata. Storage fields are generated by upload and cannot be edited here.

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

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

curl -X POST "https://example.com/v1/media/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "object": "media_asset",  "organization_id": "string",  "url": "string",  "original_filename": "string",  "alt_text": "string",  "caption": "string",  "mime_type": "string",  "width": 0,  "height": 0,  "size_bytes": 0,  "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"  }}

Delete media asset

Key type: Private key

Delete one uploaded media asset.

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

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/v1/media/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"  }}