workspaces

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

Methods

pd.workspaces.list(init?)

List the workspaces the caller belongs to

GET /api/workspaces

Newest first, each with the caller's own memberId. Needs a signed-in user, or an API key created by one; no permission is checked since the list only holds workspaces the user is a member of.

Input

Returns 200 OK

Errors 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.workspaces.list();
console.log(result);

pd.workspaces.create(input, init?)

Create a workspace

POST /api/workspaces

Any signed-in user may create a workspace; no permission is needed. In one transaction it provisions the six system roles (Owner, Admin, Editor, Writer, SEO Manager, Viewer), makes the caller its Owner, creates an empty credit wallet and applies the free plan's quotas. The caller's welcome credits are granted with it, once per user and only when their email address is verified. Records workspace.created (and credits.granted) audit entries 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.workspaces.create({
  body: {
    name: "example",
  },
});
console.log(result);

pd.workspaces.get(input, init?)

Read a workspace, the caller's permissions in it, and the server's features

GET /api/workspaces/{workspaceId}

Needs workspace.read. permissions lists what the caller can do here, so a client can decide what to offer, and features lists the server's enabled feature flags: a client must not offer a capability whose flag is absent. A caller who is not a member gets 404 RESOURCE_NOT_FOUND.

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

pd.workspaces.update(input, init?)

Update a workspace

PATCH /api/workspaces/{workspaceId}

Needs workspace.update. Only the fields sent change; the slug cannot be changed. settings replaces the stored object as a whole rather than merging. Records a workspace.updated audit entry listing the fields sent.

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

pd.workspaces.listMembers(input, init?)

List a workspace's members

GET /api/workspaces/{workspaceId}/members

Needs members.read. Members have no status: a person either holds a membership here or does not. Invited addresses that have not accepted yet are not members; they are listed by GET /api/workspaces/{workspaceId}/invitations.

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

pd.workspaces.addMember(input, init?)

Add a member, or invite an address by email

POST /api/workspaces/{workspaceId}/members

Needs members.invite. An address with an account joins at once, is told so by email, and the call answers { memberId, member }; one already in the workspace answers 409 CONFLICT. Any other address is invited: it gets an email with a link valid for seven days, and the call answers { invitation }. The roles given (the default role when none is sent) may only hold permissions the caller holds: 403 FORBIDDEN, with those permissions in details.permissions. Inviting an address that already has an open invitation renews it (new link, roles and expiry; the old link stops working), and answers 429 RATE_LIMITED with Retry-After within a minute of the last send. Both paths count against the users quota (429 QUOTA_EXCEEDED at the limit), and an open invitation holds a seat until it is accepted, revoked or expires. Either email is queued with the change and sent in the background, in the member's own language for an account and in locale for an invitation. Records a members.invited 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.workspaces.addMember({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    email: "ada@example.com",
  },
});
console.log(result);

pd.workspaces.setMemberRoles(input, init?)

Replace a member's roles

PATCH /api/workspaces/{workspaceId}/members/{memberId}

Needs roles.assign. Replaces all of the member's roles with the ones sent, in effect immediately. 403 FORBIDDEN when a role sent, or a role the member holds now, carries a permission the caller lacks (details.permissions lists them), so nobody can raise a member above themselves or demote someone more powerful than themselves. 403 FORBIDDEN also when it would take the Owner role from the workspace's last owner. 404 RESOURCE_NOT_FOUND when the member is not in the workspace. Records a members.roles_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.workspaces.setMemberRoles({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  memberId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    roleIds: ["3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c"],
  },
});
console.log(result);

pd.workspaces.removeMember(input, init?)

Remove a member from a workspace

DELETE /api/workspaces/{workspaceId}/members/{memberId}

Needs members.remove. Deletes the membership, and with it the member's roles and project memberships; their user account is untouched. 403 FORBIDDEN when the member holds a permission the caller lacks (details.permissions lists them), so nobody can remove someone more powerful than themselves; removing yourself is always allowed. 403 FORBIDDEN also for the workspace's last owner: give someone else the Owner role first. 404 RESOURCE_NOT_FOUND when the member is not in the workspace. Records a members.removed 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.workspaces.removeMember({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  memberId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);