Content Buckets API

Content buckets organize entities into publishable collections. Each bucket is linked to an entity type and can be configured with SEO rules, Sanity CMS document mappings, and publish workflows. Use templates to bootstrap common content types like blogs, glossaries, and comparison pages.

List Content Buckets

GET /api/v1/content-buckets

Returns all content buckets in the current project, including entity counts.

Response

dataContentBucket[]

Array of content bucket objects with entity counts.

Create Content Bucket

POST /api/v1/content-buckets

Create a new content bucket with custom configuration.

Request Body

namestringrequired

Display name for the content bucket.

slugstring

URL-friendly identifier. Auto-generated from `name` if not provided.

entityTypeIdstringrequired

The entity type this bucket organizes. All entities in the bucket must be of this type.

sanityDocumentTypestring

Sanity CMS document type for publishing. Required if you plan to publish to Sanity.

publishConfigobject

Publishing configuration: `autoPublish` (boolean), `requireSeoScore` (number, 0-100).

seoConfigobject

SEO field mapping: `titleField`, `descriptionField`, `slugField` — the entity field names that map to SEO metadata.

Create Content Bucket from Template

POST /api/v1/content-buckets/from-template

Bootstrap a content bucket with pre-configured entity type, fields, SEO config, and publish rules using a built-in template.

Request Body

templatestringrequired

Template identifier. One of: `blog`, `glossary`, `comparisons`, `alternatives`.

namestring

Optional name override. Defaults to the template's default name (e.g., "Blog Posts" for the `blog` template).

Note

Creating from a template also creates the associated entity type with pre-configured fields. You can customize the entity type after creation.

List Available Templates

GET /api/v1/content-buckets/templates

Returns all available content bucket templates with their default configurations.

Response

dataTemplate[]

Array of available template definitions.

Publish Content Bucket

POST /api/v1/content-buckets/{bucketId}/publish

Trigger a publish job for entities in a content bucket. Only entities meeting the minimum SEO score will be published.

Path Parameters

bucketIdstringrequired

The ID of the content bucket to publish.

Request Body

entityIdsstring[]

Specific entity IDs to publish. If omitted, all eligible entities in the bucket are published.

minSeoScorenumber

Minimum SEO readiness score (0-100) required for an entity to be published. Overrides the bucket's `publishConfig.requireSeoScore` for this run.

Response

data.jobIdstring

The ID of the background job tracking this publish operation.

data.entitiesQueuednumber

Number of entities that met the criteria and were queued for publishing.

Note

Returns a job ID for tracking progress. Use the [Jobs API](/docs/api-jobs) to poll for completion status, or subscribe to webhook events for real-time updates.

Get SEO Readiness

GET /api/v1/content-buckets/{bucketId}/seo-readiness

Get SEO readiness statistics for all entities in a content bucket.

Path Parameters

bucketIdstringrequired

The ID of the content bucket to analyze.

Response

data.totalnumber

Total number of entities in the bucket.

data.readynumber

Number of entities meeting the minimum SEO score threshold.

data.needsWorknumber

Number of entities below the minimum SEO score threshold.

data.notScorednumber

Number of entities that have not been scored yet.

data.averageScorenumber

Average SEO readiness score across all scored entities.

data.distributionobject

Score distribution broken down by range.

Content Buckets API

Content Buckets API

Command Palette