Create an article
Create a tagged article and verify its generated slug and initial state.
Create an article with a title, description, body, and optional tags. The API generates the article slug and returns the complete article resource after creation.
Before you begin
You need a valid user token. Send it as Authorization: Token <jwt>; see Authentication and token usage. Use the hosted demo base URL https://api.realworld.show/api, and use a unique title or a test user so that you can identify the created resource.
article object. title, description, and body are required strings. tagList is optional and must be an array of strings.Create the article
Choose the content and tags you want to publish. This example uses two tags and a visibly fake token placeholder.
{
"article": {
"title": "Building a Conduit client",
"description": "Patterns for calling the article API",
"body": "Use the documented envelope and inspect the response.",
"tagList": ["api", "javascript"]
}
}Keep the required fields non-empty. The API returns a validation error when any required field is blank.
Send the payload to POST /articles with JSON content and your token.
curl --request POST \
--url 'https://api.realworld.show/api/articles' \
--header 'Authorization: Token demo-jwt-token' \
--header 'Content-Type: application/json' \
--data '{
"article": {
"title": "Building a Conduit client",
"description": "Patterns for calling the article API",
"body": "Use the documented envelope and inspect the response.",
"tagList": ["api", "javascript"]
}
}'The server returns HTTP 201 and wraps the new resource in article.
Read article.slug from the response and store it as the article identifier. Do not construct the URL from the title; the generated slug is the value used by article endpoints.
The response also includes createdAt and updatedAt timestamps, the submitted content, the tag list, the author profile, favorited: false, and favoritesCount: 0 for the newly created article.
Fetch the returned slug with Read an article by slug and confirm that the title, description, body, and tags match the request. Confirm that the response is wrapped in article and that the timestamps have an ISO date-time shape.
Pass the captured slug to article reads, updates, favorites, or comments. If another user follows the author, the article can appear in that user’s authenticated feed.
Endpoint contract
Creates an article for the authenticated user and returns the complete article resource.
/articlesToken header for the authenticated author.
The request body is JSON.
Object containing required `title`, `description`, and `body` strings, plus optional `tagList` string array.
curl --request POST \
--url https://api.realworld.show/api/articles \
--header 'Authorization: Token demo-jwt-token' \
--header 'Content-Type: application/json' \
--header 'Content-Type: application/json' \
--data '{
"article": "title, description, body, tagList"
}'{
"article": {
"slug": "building-a-conduit-client",
"title": "Building a Conduit client",
"description": "Patterns for calling the article API",
"body": "Use the documented envelope and inspect the response.",
"tagList": ["api", "javascript"],
"createdAt": "2026-09-25T09:00:00Z",
"updatedAt": "2026-09-25T09:00:00Z",
"favorited": false,
"favoritesCount": 0,
"author": {"username": "demo-author", "bio": null, "image": null, "following": false}
}
}Verify errors
The API uses the shared errors envelope for authentication and validation failures. A blank title, description, or body returns HTTP 422 with the corresponding field key. Missing authentication returns 401; see Error envelope and HTTP status behavior for handling guidance.
Next step
Read the created resource with Read an article by slug, or change its content with Update an article.