Skip to content

How to schedule and publish a Strapi 5 release via API

Learn step‑by‑step how to generate an admin token, create a scheduled release, add publish actions, and trigger the release with Strapi 5’s Admin API—all in code.

By the Revisionary team · · 4 min read

person using black laptop computer on brown wooden table
Photo by Dell on Unsplash

You can create a scheduled content release and publish it entirely through Strapi 5’s Admin API. The process involves generating an admin token, creating a release, adding actions that describe which entries to publish or unpublish, and finally calling the publish endpoint at the scheduled time.

Prerequisites

  • Strapi 5 running on Node 18‑24 with a PostgreSQL, MySQL or SQLite database (see the Requirements page).
  • A Growth or Enterprise plan, because the Content Releases feature is not available on the free tier.
  • An account with the admin role that can manage the plugin::content-releases.* permissions.
  • Basic familiarity with curl or a Node.js HTTP client.

1. Generate an admin token

The Admin API is protected by admin tokens, not the public content‑API tokens. Create a token in the Strapi admin UI under Settings → Administration Panel → Admin Tokens. Give it a descriptive name (e.g., Release‑automation) and copy the generated secret.

bash
# Example: store the token in an environment variable
export STRAPI_ADMIN_TOKEN="<your‑admin‑token>"

When calling the API, include the token in the Authorization header:

http
Authorization: Bearer <your‑admin‑token>

For more details on token creation see the admin token documentation.

2. Create a release

A release groups a set of publish/unpublish actions and can be scheduled for a future UTC time. The endpoint is a standard POST request to /content-releases.

bash
curl -X POST https://my‑strapi.example.com/content-releases \
  -H "Authorization: Bearer $STRAPI_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring 2027 Launch",
    "scheduledAt": "2027-04-01T10:00:00Z",
    "timezone": "Europe/Paris"
  }'

The response contains the newly created release ID and a status of empty:

json
{
  "id": 42,
  "name": "Spring 2027 Launch",
  "scheduledAt": "2027-04-01T10:00:00Z",
  "timezone": "Europe/Paris",
  "status": "empty",
  "actions": { "meta": { "count": 0 } }
}

3. Add entries to the release

Each entry you want to publish (or unpublish) becomes an action. The minimal payload includes the action type, the contentType slug, and the entryDocumentId that you obtain from the Document Service API.

bash
curl -X POST https://my‑strapi.example.com/content-releases/42/actions \
  -H "Authorization: Bearer $STRAPI_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "publish",
    "contentType": "articles",
    "entryDocumentId": "hgv1vny5cebq2l3czil1rpb3",
    "locale": "en"
  }'

You can repeat the request for each entry, or use the bulk endpoint (see next section).

4. Bulk‑add actions (optional)

When you have many entries, POST an array to /content-releases/:releaseId/actions/bulk.

bash
curl -X POST https://my‑strapi.example.com/content-releases/42/actions/bulk \
  -H "Authorization: Bearer $STRAPI_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {"type":"publish","contentType":"articles","entryDocumentId":"id‑1","locale":"en"},
      {"type":"publish","contentType":"pages","entryDocumentId":"id‑2"},
      {"type":"unpublish","contentType":"news","entryDocumentId":"id‑3","locale":"fr"}
    ]
  }'

The response tells you how many entries were added and which ones were already part of the release.

5. Understand release status

A release goes through a simple lifecycle:

StatusMeaning
emptyNo actions attached yet
readyAt least one action, ready to be published
blockedValidation error (e.g., past scheduledAt)
failedPublishing failed for one or more actions
doneAll actions processed successfully

The status updates automatically when you call the publish endpoint.

Lines of colorful JavaScript code displayed on a dark screen
Photo by Markus Spiske on Unsplash

6. Publish the release

When the scheduledAt time arrives, Strapi automatically runs the publish job. You can also trigger it manually (useful for testing) with:

bash
curl -X POST https://my‑strapi.example.com/content-releases/42/publish \
  -H "Authorization: Bearer $STRAPI_ADMIN_TOKEN"

The response provides a short summary:

json
{
  "totalEntries": 3,
  "totalPublishedEntries": 2,
  "totalUnpublishedEntries": 1,
  "status": "done"
}

If the release is scheduled for the future, the same endpoint will queue the actions and they will be executed at the defined UTC time.

7. Listing and inspecting releases

You can retrieve all releases (paginated) with:

bash
curl -X GET "https://my‑strapi.example.com/content-releases?page=1&pageSize=20" \
  -H "Authorization: Bearer $STRAPI_ADMIN_TOKEN"

A single release detail request (GET /content-releases/:id) returns the full payload, including the list of actions and their current state. This is handy for dashboards that need to show pending releases.

8. Common error handling

SituationHTTP statusTypical causeFix
400 Bad RequestValidation errorscheduledAt in the past or missing required fieldsEnsure the timestamp is future‑looking and all fields are present
403 ForbiddenMissing permissionAdmin token lacks plugin::content-releases.* permissionsGrant the three permissions (create, read, publish) in Settings → Roles → Plugins → Content‑releases
404 Not FoundWrong release IDTypo in the URL or the release was deletedVerify the ID via the list endpoint

Always log the response body; Strapi includes a message field that explains the validation problem.

9. Best practices for production

  1. Use scoped admin tokens – Create a dedicated token with only the three release permissions. Store it securely (e.g., Vault or environment secret manager).
  2. Validate payloads locally – Replicate the JSON schema from @strapi/content-releases (available in the npm package) to catch errors before hitting the API.
  3. Idempotent actions – If your CI/CD pipeline may run twice, check whether an action already exists (GET /content-releases/:id/actions) before adding duplicates.
  4. Monitor the audit log – Strapi’s built‑in audit log records every release creation and publish event. Review it regularly for unexpected activity.
  5. Graceful fallback – When a scheduled publish fails, the status becomes failed. Implement a retry routine that reads the failed actions and attempts republishing after fixing the root cause.

10. Optional: combine with Revisionary for versioned content

If you also need fine‑grained version history, the Revisionary plugin keeps every change of a versioned content type. While Revisionary does not replace the Release API, it complements it: you can schedule a release that publishes a specific version of an entry, then use Revisionary’s Version history panel to audit exactly which fields changed before the release went live. For more information see the plugin’s user guide pages such as What Revisionary does and The audit log.

Conclusion

Scheduling and publishing content with Strapi 5’s Admin API is straightforward once you have an admin token and the correct permissions. Create a release, attach publish actions (individually or in bulk), and let Strapi handle the timed execution. By following the error‑handling tips and production best practices above, you can automate content rollouts for marketing campaigns, product launches, or any time‑sensitive publication workflow.

Tagsstrapi 5content releasesadmin APIscheduled publishingnode.js

Sources

  1. Strapi 5 releases feature
  2. Admin tokens documentation
  3. Strapi REST API reference
  4. Introducing scheduling for your releases
  5. Release service implementation
  6. Draft and publish feature

The Revisionary team

Developers who build Revisionary, a version history plugin for Strapi 5. We write about Strapi, web development, AI and application security.

This article was written with the help of AI.

All articles