projects

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

Methods

pd.projects.list(input, init?)

List a workspace's projects

GET /api/workspaces/{workspaceId}/projects

Needs projects.read in the workspace. Newest first. Archived projects are left out unless includeArchived=true. A project that has members is listed only to them, and to a caller who holds projects.members.manage in the workspace, who administers it; a project with no members is listed to everyone. A member whose project role does not grant projects.read does not see the project either. An API key has no project membership, so it lists the open projects, and the restricted ones too when its role holds projects.members.manage. A platform administrator reading a workspace they do not belong to sees every project. A project left out of the list answers 403 when opened; one listed only because the caller manages members is likewise refused on read until they are a member, but its members can still be managed.

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

pd.projects.create(input, init?)

Create a project

POST /api/workspaces/{workspaceId}/projects

Needs projects.create. Creates an active project with no members, so it is open to every workspace member who holds the permissions. Counts against the workspace's projects quota: 429 QUOTA_EXCEEDED when the plan's limit is reached. Records a projects.created audit entry and answers 201. With a websiteUrl, queues a fetch of the site's icon.

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

pd.projects.get(input, init?)

Read a project

GET /api/workspaces/{workspaceId}/projects/{projectId}

Needs projects.read on the project: 404 when it is not in the workspace, 403 when it has members and the caller is not one. Carries the stored settings and imageSettings, the same with its defaults filled in. Works on archived projects.

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

pd.projects.update(input, init?)

Update a project

PATCH /api/workspaces/{workspaceId}/projects/{projectId}

Needs projects.update on the project. Only the fields sent change; slug cannot be changed. settings sets the keys it carries and keeps the others. settings.images configures image generation (style description, never-depict list, hero and inline aspect and style); the response's imageSettings is that with the defaults filled in. Removing a language that articles are written in answers 409 CONFLICT with those languages in details.inUse, unless deleteArticlesInRemovedLanguages is true. Allowed on an archived project too. Records a projects.updated audit entry listing the fields sent. Setting websiteUrl to a new address queues a fetch of the site's icon.

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

pd.projects.delete(input, init?)

Delete a project

DELETE /api/workspaces/{workspaceId}/projects/{projectId}

Needs projects.delete. Permanently deletes the project and the content that belongs to it, including its articles. It cannot be undone; archive the project to keep the content. Works on archived projects. Records a projects.deleted 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.projects.delete({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.projects.archive(input, init?)

Archive a project

POST /api/workspaces/{workspaceId}/projects/{projectId}/archive

Needs projects.update. Makes the project read-only: every other write in it (articles, images, generation, members) answers 409 CONFLICT until it is restored, while reads and exports keep working. Updating and deleting the project itself stay allowed. 409 CONFLICT when it is already archived. Records a projects.archived 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.projects.archive({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.projects.restore(input, init?)

Restore an archived project

POST /api/workspaces/{workspaceId}/projects/{projectId}/restore

Needs projects.update; one of the few writes an archived project accepts. Makes the project active again, with its content as it was. 409 CONFLICT when the project is not archived. Records a projects.restored 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.projects.restore({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.projects.refreshIcon(input, init?)

Refetch a project's website icon

POST /api/workspaces/{workspaceId}/projects/{projectId}/icon/refresh

Needs projects.update on the project. Queues a fetch of the icon of the project's websiteUrl and answers 202 at once. When the fetch finds a readable icon (PNG, ICO, JPEG, GIF or WebP; SVG is never used), the project's iconUrl changes to a new address; when it finds none, the current icon stays. 409 CONFLICT when the project has no websiteUrl. A request made while a fetch for the project is waiting or running joins it rather than queueing a second. Allowed on an archived project, as updating it is. Records a projects.icon_refreshed audit entry.

Input

Returns 202 Accepted

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

pd.projects.listMembers(input, init?)

List a project's members

GET /api/workspaces/{workspaceId}/projects/{projectId}/members

Needs projects.read on the project. A project with no members is open to every workspace member; once it has any, only its members (and holders of projects.members.manage, for administration only) can open it.

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

pd.projects.addMember(input, init?)

Add a member to a project

POST /api/workspaces/{workspaceId}/projects/{projectId}/members

Needs projects.members.manage, which does not require being on the project. Adding the first member makes an open project restricted: from then on only its members can open it, so add yourself if you still need access. The member must belong to the workspace and roleId, when given, to the same workspace (400 INVALID_REQUEST); a member already on the project answers 409 CONFLICT, as does an archived project. Records a projects.members_changed audit entry and 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.projects.addMember({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    workspaceMemberId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  },
});
console.log(result);

pd.projects.setMemberRole(input, init?)

Change a project member's role

PATCH /api/workspaces/{workspaceId}/projects/{projectId}/members/{projectMemberId}

Needs projects.members.manage. Replaces the member's project role in one update; null falls back to their workspace roles. 404 RESOURCE_NOT_FOUND when the member is not on the project, 409 CONFLICT when the project is archived. Records a projects.members_changed audit entry with the previous and new role.

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.projects.setMemberRole({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectMemberId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    roleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  },
});
console.log(result);

pd.projects.removeMember(input, init?)

Remove a member from a project

DELETE /api/workspaces/{workspaceId}/projects/{projectId}/members/{projectMemberId}

Needs projects.members.manage. Removing the last member makes the project open to every workspace member again. 404 RESOURCE_NOT_FOUND when the membership is not on the project, 409 CONFLICT when the project is archived. Records a projects.members_changed 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.projects.removeMember({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectMemberId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.projects.detectImageStyle(input, init?)

Detect the project's image style from its website

POST /api/workspaces/{workspaceId}/projects/{projectId}/image-style/detect

Needs projects.update on the project. Starts a detect run and answers 202 with it: the service reads the homepage and up to 3 article pages, takes up to 8 of their images (cover images first), and has a vision model name the closest preset and describe the style. The website must be set: without websiteUrl the answer is 409 CONFLICT. A site with fewer than 2 readable images of at least 200 × 200 ends failed. A run already queued or running of the same kind for this project is answered instead of a new one. A workspace may start 10 runs in any 24 hours, detections and proposals together (the detection onboarding starts on its own is outside the cap); past that the answer is 429 RATE_LIMITED with Retry-After (seconds until the oldest run of the window is 24 hours old) and details { retryAfterSeconds, limit, used }. Runs cost no credits. Follow the run with GET .../image-style/runs/latest until it is succeeded or failed, then apply a suggestion with POST .../image-style/apply.

Input

Returns 202 Accepted

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

pd.projects.proposeImageStyles(input, init?)

Propose three image styles for the project

POST /api/workspaces/{workspaceId}/projects/{projectId}/image-style/proposals

Needs projects.update on the project. Starts a propose run and answers 202 with it: a text model proposes three styles from the project's industry, audience, language, default brand voice, current image settings and latest detection, when there is one. The first refines the current or detected style; the other two are clearly different. Works without a website. A run already queued or running of the same kind for this project is answered instead of a new one. A workspace may start 10 runs in any 24 hours, detections and proposals together (the detection onboarding starts on its own is outside the cap); past that the answer is 429 RATE_LIMITED with Retry-After (seconds until the oldest run of the window is 24 hours old) and details { retryAfterSeconds, limit, used }. Runs cost no credits. Follow the run with GET .../image-style/runs/latest until it is succeeded or failed, then apply a suggestion with POST .../image-style/apply.

Input

Returns 202 Accepted

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

pd.projects.latestImageStyleRuns(input, init?)

Read the project's latest image style runs

GET /api/workspaces/{workspaceId}/projects/{projectId}/image-style/runs/latest

Needs projects.update on the project. Answers the most recent detect run and the most recent propose run, each null when there is none. A run that has not moved for 10 minutes is marked failed when it is read, with error "The run stopped before it finished", so a lost run never stays queued or running.

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

pd.projects.applyImageStyle(input, init?)

Apply a detected or proposed image style

POST /api/workspaces/{workspaceId}/projects/{projectId}/image-style/apply

Needs projects.update on the project. Writes the chosen suggestion into settings.images: its preset becomes hero.style and inline.style, its styleDescription the style description, and its neverDepict, when it has one, the never-depict list. Aspects, the hero prompt and the other settings keys stay. The result is validated as PATCH validates settings.images, and the run's appliedAt is set. Images generated or regenerated afterwards follow it. Records a projects.image_style_applied audit entry and answers 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.projects.applyImageStyle({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  projectId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    runId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  },
});
console.log(result);