articles

The methods of pd.articles. Inputs and outputs are described in Conventions; every method can also fail as described in Errors.

Methods

pd.articles.create(input, init?)

Create an article

POST /api/articles

A DRAFT in the project, empty unless document or contentMarkdown is sent (one of the two, never both: 400). Needs articles.create, and articles.publish too when publishedAt is sent.

Importing Markdown. contentMarkdown is converted on the server. The images it refers to are downloaded (http and https only; relative URLs need imageBaseUrl; at most 50 distinct images, 25 MB each, 15 seconds each; every address and redirect is checked so private networks are refused) and stored as the article's assets, and the blocks point at them. The leading image (first in the document, or right after the level-1 heading) becomes the article's hero asset, stored whole, and is not a block of the body; it stays an inline image when the body shows the same picture again. Everything is one unit: if any image or construct is refused, no article and no asset is left behind, and the INVALID_REQUEST names the URL (details.src) or lists details.issues ([{ construct, line }]). QUOTA_EXCEEDED (429) when the images do not fit the workspace's storage quota. The first version is recorded as an import.

Language versions. translationGroupId makes the new article another language version of an existing one. language (or primaryLanguage) must be one of the project's languages; a group that already has that language answers 409 CONFLICT.

Keeping a legacy date. publishedAt is stored on the DRAFT. Publishing goes POST /submit, POST /approve, POST /publish, and the last call stamps its own time unless it repeats the date in its body. With no publishing integration nothing else is needed: cmsIntegration is null.

Possible duplicates. The response carries possibleDuplicates: articles of the same project and language, in another group, whose title or slug is close. The same matches are in warnings as { code: "POSSIBLE_DUPLICATE", articleId, translationGroupId, similarity, title, slug }. It is advice and never blocks the creation; when the check itself fails, both are empty.

Side effects. Costs no credits. Sends the article.created webhook and writes an articles.created audit entry. Records version 1 of the document. A given ideaId is marked written by the article.

Input

Returns 201 Created

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.create({
  body: {
    projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
    title: "example",
  },
});
console.log(result);

pd.articles.list(input, init?)

List articles

GET /api/articles

One page of the workspace's articles, newest change first, and how many match in all. Every filter narrows the result: an article is listed only when it passes all the filters given, and total counts the same set. Each language version of an article is its own article; translationGroupId links them. The list carries the card fields, never the document: read one article for that. Needs articles.read on the workspace, or on the project when projectId is given.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.list({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.duplicate(input, init?)

Duplicate an article

POST /api/articles/{articleId}/duplicate

A DRAFT copy in the same project, with its own copy of every image. Answers like POST /api/articles. Needs articles.read and articles.create. The copy has the original's blocks, keywords, language, generation settings and categories, a new translation group of its own, and a slug derived from its title; meta title and meta description, comments, reviews and version history are not copied, and the copy starts at version 1. QUOTA_EXCEEDED (429) when the copied images do not fit the workspace's storage quota. Sends the article.created webhook and writes an articles.created audit entry.

Input

Returns 201 Created

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.duplicate({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.get(input, init?)

Read an article

GET /api/articles/{articleId}

documentJson is the canonical article; contentHtml and contentMarkdown are derived from it on every save. Also returns the article's images (assets), the blog address of a published post of the PrismDraft site (blogPath), its categories, and its language versions with the project's languages (translations). Needs articles.read. Send stripLead=true to get contentMarkdown without the title heading and hero image.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.get({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.update(input, init?)

Update an article

PATCH /api/articles/{articleId}

Changes the fields sent and leaves the others as they are; the status is never changed here (see POST /submit, /approve, /publish). Sending document replaces the whole body, writes a new version (source human) and re-renders contentHtml and contentMarkdown; a save without it writes no version. Needs articles.update. 409 CONFLICT when the slug or the language is taken, or when expectedUpdatedAt no longer matches (details.reason article_changed, with the current details.updatedAt, so a client can offer to reload); nothing is saved then. 400 when an image block points at the article's hero. For a PUBLISHED article that changed its title, content, slug, meta fields or keywords, the article.updated webhook is sent with the names of the changed fields; a draft sends none. Writes an articles.updated audit entry.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.update({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.delete(input, init?)

Delete an article

DELETE /api/articles/{articleId}

Permanently deletes the article with its versions, comments, reviews and image records, and removes the stored image files nothing else uses. Other language versions of the article are not touched. Needs articles.delete. Deleting a PUBLISHED article sends the article.unpublished webhook with reason: "deleted"; an articles.deleted audit entry is written. There is no undo.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.delete({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.submit(input, init?)

Submit an article for review

POST /api/articles/{articleId}/submit

Moves the article to NEEDS_REVIEW so a reviewer can decide on it. Needs articles.update. 409 CONFLICT when the article's status cannot move there, for example when it is already NEEDS_REVIEW, is QUEUED, or is PUBLISHED. Queues an email to every member who holds articles.approve and can open the project (not the caller, and not anyone who opted out), and updates open dashboards live.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.submit({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.approve(input, init?)

Approve an article

POST /api/articles/{articleId}/approve

Records an approved review and moves the article from NEEDS_REVIEW to APPROVED, ready for POST /publish; 409 CONFLICT from any other status. Needs articles.approve. The body is optional and may carry a comment. Sends the article.approved webhook, writes an articles.approved audit entry and queues an email to the article's author (unless that is the caller).

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.approve({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.reject(input, init?)

Record a review decision: rejected

POST /api/articles/{articleId}/reject

Records a rejected review and moves the article to CHANGES_REQUESTED, from NEEDS_REVIEW, APPROVED or PUBLISHED (409 CONFLICT from any other status). A non-blank comment is required (400 otherwise), since a bare decision gives the writer nothing to act on. Needs articles.reject. Sends the article.rejected webhook, which names the decision in decision, and writes an articles.rejected audit entry. A PUBLISHED article that is sent back also sends article.unpublished (reason: "status_changed"). Queues an email with the comment to the article's author (unless that is the caller).

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.reject({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.requestChanges(input, init?)

Record a review decision: changes_requested

POST /api/articles/{articleId}/request-changes

Records a changes_requested review and moves the article to CHANGES_REQUESTED, from NEEDS_REVIEW, APPROVED or PUBLISHED (409 CONFLICT from any other status). A non-blank comment is required (400 otherwise), since a bare decision gives the writer nothing to act on. Needs articles.reject. Sends the article.rejected webhook, which names the decision in decision, and writes an articles.changes_requested audit entry. A PUBLISHED article that is sent back also sends article.unpublished (reason: "status_changed"). Queues an email with the comment to the article's author (unless that is the caller).

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.requestChanges({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.publish(input, init?)

Publish an approved article to its integration

POST /api/articles/{articleId}/publish

The article must be APPROVED (POST /submit, then POST /approve): 409 otherwise. Without a publishing integration it is simply marked PUBLISHED and cmsIntegration is null; with one, the hand-off happens in the background.

publishedAt (optional) stores that date instead of now, for an imported article whose original date must survive. Publishing without it stamps the current time, also over a publishedAt given at creation. Needs articles.publish.

warnings lists what the publish went through despite, and is empty when there is nothing: hero_in_body means the cover image is also a block of the body, so a site that prints the cover above the title shows it twice (POST /hero/detach-from-body removes the block).

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.publish({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.unpublish(input, init?)

Take a published article back to DRAFT

POST /api/articles/{articleId}/unpublish

The article must be PUBLISHED: 409 otherwise. It becomes a DRAFT and keeps its publishedAt; an article.unpublished webhook is sent (reason: "status_changed"). Nothing already handed to a publishing integration is retracted. Needs articles.publish.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.unpublish({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.transitionTranslations(input, init?)

Submit, approve or publish every language version together

POST /api/articles/{articleId}/translations/{action}

Applies submit (to NEEDS_REVIEW), approve (to APPROVED) or publish (to PUBLISHED) to every language version of the article's translation group, each exactly as its single route would. Needs articles.update, articles.approve or articles.publish respectively. All-or-nothing: versions already at the target are skipped; if any other cannot make the transition (409 CONFLICT, details.blocked lists { id, language, status }), none moves. A version still QUEUED or PROCESSING, or an empty draft left by a failed translation, blocks the group. The versions move in one transaction, so a failure while applying leaves none of them changed. Answers which versions moved (applied) and which were skipped.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.transitionTranslations({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  action: "submit",
});
console.log(result);

pd.articles.listReviews(input, init?)

The article's review history

GET /api/articles/{articleId}/reviews

Every review decision recorded on the article, newest first, each with the status it moved from and to and the reviewer's name. A submission is not a review and is not listed. Needs articles.read.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.listReviews({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.listVersions(input, init?)

The article's version history

GET /api/articles/{articleId}/versions

The saved versions of the article's document, oldest first, without the documents (read one with GET /versions/{version}). A version is written when the article is created and by every save that changes document, including a restore; a save of the title, keywords or meta fields writes none. Needs articles.read.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.listVersions({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.getVersion(input, init?)

Read one version of an article

GET /api/articles/{articleId}/versions/{version}

The version's full documentJson, for preview and comparison before a restore.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.getVersion({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  version: 1,
});
console.log(result);

pd.articles.getSources(input, init?)

Research sources and fact checks behind an article

GET /api/articles/{articleId}/sources

The pages research retrieved for the article and the claims fact checking assessed against them, each oldest first. Both lists are empty for an article that was written without research. Needs articles.read.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.articles.getSources({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.articles.restoreVersion(input, init?)

Restore an earlier version

POST /api/articles/{articleId}/versions/{version}/restore

Puts the document of an earlier version back as the article's body. History is not rewritten: the restore is saved as a new version (source restore) and contentHtml and contentMarkdown are re-rendered. The title, keywords and status are untouched. Needs articles.update; 404 when the version does not exist. For a PUBLISHED article whose content changed, sends the article.updated webhook. Writes an articles.version_restored audit entry.

Input

Returns 200 OK