Create and publish an article

Creating and publishing articles is a common task in Document360. Using the v3 API you can automate this end to end: create a draft article, then publish a specific version.

Before you begin

To create an article you need a project ID, a workspace ID, and a category ID.

Value	How to retrieve it
`project_id`	`GET /v3/projects` — copy the `id` of the project you want to use.
`workspace_id`	`GET /v3/projects/{project_id}/workspaces` — copy the `id` of the workspace.
`category_id`	`GET /v3/projects/{project_id}/workspaces/{workspace_id}/categories` — copy the `id` of the target category.

Note

A workspace represents a version of your project's content. Identify it with the workspace_id field in the request body.

Step 1 — Create the article

Send a POST request to the articles endpoint. The article is created in draft status.

POST /v3/projects/{project_id}/articles

curl --request POST "https://apihub.document360.io/v3/projects/{project_id}/articles" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Getting Started with Single Sign-On",
    "content": "# Introduction\nThis guide walks you through configuring SSO.",
    "category_id": "f4a5b6c7-d8e9-0a1b-2c3d-4e5f6a7b8c9d",
    "workspace_id": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6",
    "order": 0,
    "content_type": "markdown",
    "slug": "getting-started-with-single-sign-on"
  }'

Field	Required	Description
`title`	Yes	The article title.
`category_id`	Yes	The category the article belongs to.
`workspace_id`	Yes	The workspace the article belongs to.
`content`	No	The article body, in Markdown or HTML depending on `content_type`.
`content_type`	No	`markdown` (default) or `block`. `wysiwyg` is deprecated.
`order`	No	Position within the category. `0` = first.
`slug`	No	URL slug. Generated from the title if omitted.

A successful request returns 201 Created. Copy data.id and data.version_number — you need them to publish.

{
  "success": true,
  "request_id": "req_abc123def456",
  "data": {
    "id": "9a3b4c5d-6e7f-8a9b-0c1d-2e3f4a5b6c7d",
    "title": "Getting Started with Single Sign-On",
    "category_id": "f4a5b6c7-d8e9-0a1b-2c3d-4e5f6a7b8c9d",
    "workspace_id": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6",
    "version_number": 1,
    "public_version": null,
    "latest_version": 1,
    "status": "draft",
    "order": 0,
    "slug": "getting-started-with-single-sign-on",
    "content_type": "markdown",
    "created_at": "2025-08-15T14:30:00Z"
  }
}

Note

content_type: block requires non-empty content. editor_version accepts v2 or v3; v3 is honoured only in projects enabled for the Editor 3.0 beta.

Important

You must have content access to the target location. If your content role does not grant access to the specified workspace and parent category, the request returns 403 with the error code FORBIDDEN.

Step 2 — Publish the article

Publish a specific version of the article, making it visible to readers.

POST /v3/projects/{project_id}/articles/{article_id}/publish

curl --request POST "https://apihub.document360.io/v3/projects/{project_id}/articles/{article_id}/publish" \
  --header "X-API-Key: YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "workspace_id": "1c2d3e4f-5a6b-7c8d-9e0f-a1b2c3d4e5f6",
    "version_number": 1,
    "message": "Publishing SSO guide after technical review"
  }'

Field	Required	Description
`workspace_id`	Yes	The workspace containing the article.
`version_number`	Yes	The version to publish (1 or higher).
`message`	No	A short note describing the publish action.

A successful publish returns 200 OK:

{
  "success": true,
  "request_id": "req_abc123def456"
}

Tip

Publishing requires the Publish articles permission. To publish many articles at once, see Create and publish multiple articles.

Documentation Index

Create and publish an article

Before you begin

Step 1 — Create the article

Step 2 — Publish the article