briefs

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

Methods

pd.briefs.draft(input, init?)

Draft a content brief

POST /api/projects/{projectId}/brief

Asks the model for the angle, audience, search intent, keywords, reader questions, H2 headings, entities and a target length for one topic, fitted to the project's audience, and returns them without storing anything. Requires articles.create on the project. Costs no credits but counts against the ai_operations quota (429 QUOTA_EXCEEDED when used up). competitorTopics is never drafted: the model has no research to draw them from. To keep the brief send it to briefs.create; to write from it, copy its fields into the article's generationConfig.

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

pd.briefs.list(input, init?)

List a project's stored briefs

GET /api/projects/{projectId}/briefs

Returns the briefs stored for the project, most recently updated first; the list is not paginated. Requires articles.read on the project.

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

pd.briefs.create(input, init?)

Store a content brief

POST /api/projects/{projectId}/briefs

Stores a brief for the project: the fields of a drafted brief (briefs.draft) plus a title and competitorTopics, which only a person types. Requires articles.create on the project (409 when it is archived). An ideaId, when given, must be an idea of this workspace (404 otherwise) that belongs to the same project or to none (400 otherwise). A stored brief is not read by article generation on its own: link an article to it with briefId on articles.create, and copy the fields you want into that article's generationConfig. 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.briefs.create({
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    angle: "example",
    audience: "example",
    searchIntent: "informational",
    primaryKeyword: "example",
    secondaryKeywords: ["example"],
    questions: ["example"],
    headings: ["example"],
    entities: ["example"],
    wordCount: 600,
    title: "example",
  },
});
console.log(result);

pd.briefs.get(input, init?)

Read a stored brief

GET /api/briefs/{briefId}

Returns one stored brief. Requires articles.read on the brief's project; 404 when it does not exist or belongs to another workspace.

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

pd.briefs.update(input, init?)

Update a stored brief

PATCH /api/briefs/{briefId}

Changes the fields sent and keeps the others; a list sent replaces the stored list whole. Requires articles.update on the brief's project; 404 when it does not exist. The project cannot be changed: a brief is written again, not moved. ideaId follows the rules of briefs.create, and null unlinks the idea.

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

pd.briefs.delete(input, init?)

Delete a stored brief

DELETE /api/briefs/{briefId}

Deletes the brief. Requires articles.delete on the brief's project; 404 when it does not exist. Articles written from the brief keep their content and lose the link: their briefId becomes null.

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