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
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.
# 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:
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.
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:
{
"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.
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.
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:
| Status | Meaning |
|---|---|
empty | No actions attached yet |
ready | At least one action, ready to be published |
blocked | Validation error (e.g., past scheduledAt) |
failed | Publishing failed for one or more actions |
done | All actions processed successfully |
The status updates automatically when you call the publish endpoint.
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:
curl -X POST https://my‑strapi.example.com/content-releases/42/publish \
-H "Authorization: Bearer $STRAPI_ADMIN_TOKEN"The response provides a short summary:
{
"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:
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
| Situation | HTTP status | Typical cause | Fix |
|---|---|---|---|
| 400 Bad Request | Validation error | scheduledAt in the past or missing required fields | Ensure the timestamp is future‑looking and all fields are present |
| 403 Forbidden | Missing permission | Admin token lacks plugin::content-releases.* permissions | Grant the three permissions (create, read, publish) in Settings → Roles → Plugins → Content‑releases |
| 404 Not Found | Wrong release ID | Typo in the URL or the release was deleted | Verify 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
- Use scoped admin tokens – Create a dedicated token with only the three release permissions. Store it securely (e.g., Vault or environment secret manager).
- Validate payloads locally – Replicate the JSON schema from
@strapi/content-releases(available in the npm package) to catch errors before hitting the API. - Idempotent actions – If your CI/CD pipeline may run twice, check whether an action already exists (
GET /content-releases/:id/actions) before adding duplicates. - Monitor the audit log – Strapi’s built‑in audit log records every release creation and publish event. Review it regularly for unexpected activity.
- 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.
Sources
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.