links

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

Methods

pd.links.list(input, init?)

Internal link suggestions for an article

GET /api/articles/{articleId}/links

Returns every link suggestion generated for the article, whatever its status (pending, accepted, rejected), newest first, each with the title and slug of the article it points at. Requires articles.read. It does not depend on the internal_linking_automation flag.

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

pd.links.generate(input, init?)

Generate internal link suggestions

POST /api/articles/{articleId}/links

Asks the model which of the project's other published articles in the same language (at most 50 candidates) the article could link to, from the first 6,000 characters of its text, and stores up to 10 suggestions as pending; none is applied until links.decide. Requires articles.update; behind the internal_linking_automation feature flag, and 400 INVALID_REQUEST when the flag is off or the article has no text. With no candidate it answers at once with an empty list and no model call; otherwise it costs no credits but counts against the ai_operations quota (429 QUOTA_EXCEEDED). A pair of source and target already suggested, whatever its status, is not added again, so a rejected pair never comes back. The anchor is requested to appear in the article but is not checked: accepting a suggestion whose anchor does not appear answers 409.

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

pd.links.decide(input, init?)

Accept, edit or reject a link suggestion

POST /api/workspaces/{workspaceId}/links/{suggestionId}

Decides one suggestion; requires articles.update on the source article's project, and 404 when the suggestion is not in the workspace. rejected only records the refusal. accepted writes the link into the source article and sets the status in one transaction: the anchor is looked up, exactly as written, in the first plain-text paragraph or quote that contains it, and the article gets a new version; 409 CONFLICT (anchor_not_found) when no block does, so edit it first with anchorText. Accepting again with the same anchor changes nothing, a different anchor adds a second link, and rejecting afterwards does not remove a written link. An acceptance records an articles.updated audit entry and, when the article is published, emits the article.updated webhook event.

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.links.decide({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  suggestionId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    decision: "accepted",
  },
});
console.log(result);