categories

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

Methods

pd.categories.list(input, init?)

List categories

GET /api/workspaces/{workspaceId}/categories

Every category of the workspace, oldest first, each with its names in every language (sorted by language) and articleCount: how many of the workspace's articles carry it. Needs categories.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.categories.list({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.categories.create(input, init?)

Create a category

POST /api/workspaces/{workspaceId}/categories

A category belongs to the workspace, so every project can use it. It is named in at least its primary language; a name that already exists in that language (compared without regard to case) is a 409, and a body without a name in primaryLanguage or with two names in one language is refused with INVALID_REQUEST. Needs categories.create; writes an audit entry. Answers 201.

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.categories.create({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    primaryLanguage: "example",
    translations: [
      {
        language: "example",
        name: "example",
      },
    ],
  },
});
console.log(result);

pd.categories.update(input, init?)

Rename a category, add or remove a language

PATCH /api/workspaces/{workspaceId}/categories/{categoryId}

Changes any of the category's main language, its names and the languages it is named in; at least one of primaryLanguage, translations and removeLanguages is required. It must end with a name in the primary language, and a language cannot be both renamed and removed (INVALID_REQUEST); a name that clashes with another category's in that language is a 409. Needs categories.update. When the change alters what articles embed of the category (a name, a language, the primary language), each PUBLISHED article carrying it emits an article.updated webhook with categories among the changed fields. Writes an 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.categories.update({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  categoryId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.categories.delete(input, init?)

Delete a category

DELETE /api/workspaces/{workspaceId}/categories/{categoryId}

Permanent: the category, its names and its links to articles are removed, and the answer says how many articles carried it. Needs categories.delete. Each PUBLISHED article that carried it emits an article.updated webhook with categories among the changed fields. Writes an 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.categories.delete({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  categoryId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.categories.setForArticle(input, init?)

Set an article's categories

PUT /api/articles/{articleId}/categories

Replaces the article's whole set with categoryIds; ids not listed are unlinked, and listing the same id twice counts once. Every id must be a category of the article's own workspace (INVALID_REQUEST otherwise). Needs articles.update. When the set changed and the article is PUBLISHED, it emits an article.updated webhook with categories among the changed fields; assigning the same set again sends nothing. Writes an 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.categories.setForArticle({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    categoryIds: ["3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c"],
  },
});
console.log(result);

pd.categories.suggestForArticle(input, init?)

Suggest categories for an article

POST /api/articles/{articleId}/categories/suggest

Up to seven suggestions in all: the workspace's existing categories that the article does not carry yet, then new names only if none fits. Nothing is stored; accept a suggestion with PUT /api/articles/{articleId}/categories or POST /api/workspaces/{workspaceId}/categories. Needs articles.update. Costs one credit, reserved before the model is called (402 INSUFFICIENT_CREDITS when the wallet cannot cover it) and released when nothing comes back, in which case credits is 0. 429 QUOTA_EXCEEDED when the workspace's monthly AI operations quota is used up.

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.categories.suggestForArticle({
  articleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.categories.suggestForProject(input, init?)

Suggest a starter set of categories for a project

POST /api/projects/{projectId}/categories/suggest

Up to seven new names drawn from the project's article titles, target keywords and idea clusters, none repeating a category name the workspace already has. Nothing is stored; accept a name with POST /api/workspaces/{workspaceId}/categories. Needs categories.create and articles.read on the project. Costs one credit, reserved before the model is called (402 INSUFFICIENT_CREDITS) and released when nothing comes back, in which case credits is 0. 429 QUOTA_EXCEEDED when the workspace's monthly AI operations quota is used up.

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.categories.suggestForProject({
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.categories.translate(input, init?)

Suggest names for a category in other languages

POST /api/workspaces/{workspaceId}/categories/{categoryId}/translate

One suggested name per requested language, translated from the category's name in its primary language, for review: nothing is saved until the category is updated with PATCH /api/workspaces/{workspaceId}/categories/{categoryId}. Needs categories.update. Costs half a credit per language, rounded up per request (402 INSUFFICIENT_CREDITS when the wallet cannot cover it), and the reservation is released when nothing comes back, in which case credits is 0. INVALID_REQUEST when languages includes the category's primary language. 429 QUOTA_EXCEEDED when the workspace's monthly AI operations quota is used up.

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.categories.translate({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  categoryId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    languages: ["example"],
  },
});
console.log(result);