Organisations

Make an auditor's share link for an evidence report

A read-only link to one evidence report (a framework and a period) that stops working after 7, 30 or 90 days or when revoked, with a password or a list of addresses if asked.

POST/orgs/{org}/evidence/shares

TL;DR

Question	Answer
What does it do?	Make an auditor's share link for an evidence report.
What does it take?	A JSON body of type `EvidenceShareBody`.
What does it return?	Status 201 with a body of type `EvidenceShareCreated`.
What can go wrong?	`400` the body or the period is not valid (evidence.range_invalid); `401` not signed in; `403` a member or a reader (orgs.forbidden), a plan without compliance evidence (plan.compliance_evidence_not_included), or an origin that may not make changes; `404` no such organisation, or the caller is not a member of it; `409` the organisation shares only Public diagrams (evidence.share_classified), or has 25 live links (evidence.share_limit_reached); `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope.

What it does

A read-only link to one evidence report (a framework and a period) that stops working after 7, 30 or 90 days or when revoked, with a password or a list of addresses if asked. Only the hash of its token is stored. Every view is audited. The owner and admins, on Enterprise.

Path parameters

Field	Type	Required	Description
`org`	`string`	yes	The organisation's id or its slug.

Request body

The body has the type EvidenceShareBody.

Field	Type	Required	Description
`framework`	`"pci-dss" \| "soc2" \| "iso27001" \| "nist-800-53" \| "all"`	yes	One framework, or all.
`from`	`string`	yes	The first day, YYYY-MM-DD, UTC.
`to`	`string`	yes	The last day, YYYY-MM-DD, UTC.
`paper`	`"a4" \| "letter"`	no	The report's paper. default "a4".
`label`	`string \| null`	no	A name for the link in the list, such as "FY26 SOC 2 audit". Shown to the viewer. at least 1 character; at most 80 characters; default null.
`days`	`7 \| 30 \| 90`	yes	Days until the link stops working: 7, 30 or 90.
`password`	`string \| null`	no	A password the viewer types, at least 10 characters. Only a salted hash is kept. at least 10 characters; at most 200 characters; default null.
`emails`	`array \| null`	no	The addresses that may open it, signed in to Plotwork with an emailed code. Not with a password. default null.

Responses

Status	Meaning	Body
201	The link, with its address, shown once.	`EvidenceShareCreated`
400	The body or the period is not valid (evidence.range_invalid).	`ErrorResponse`
401	Not signed in.	`ErrorResponse`
403	A member or a reader (orgs.forbidden), a plan without compliance evidence (plan.compliance_evidence_not_included), or an origin that may not make changes.	`ErrorResponse`
404	No such organisation, or the caller is not a member of it.	`ErrorResponse`
409	The organisation shares only Public diagrams (evidence.share_classified), or has 25 live links (evidence.share_limit_reached).	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	Organisations are not set up on this server.	`ErrorResponse`

Response body

A 201 answer has the type EvidenceShareCreated.

Field	Type	Required	Description
`id`	`string`	yes
`framework`	`"pci-dss" \| "soc2" \| "iso27001" \| "nist-800-53" \| "all"`	yes
`from`	`string`	yes
`to`	`string`	yes
`paper`	`"a4" \| "letter"`	yes
`label`	`string \| null`	yes
`protection`	`"none" \| "password" \| "emails"`	yes
`emails`	`string[]`	yes
`createdBy`	`string \| null`	yes
`createdAt`	`integer`	yes
`expiresAt`	`integer`	yes
`revokedAt`	`integer \| null`	yes
`views`	`integer`	yes	minimum 0.
`lastViewedAt`	`integer \| null`	yes
`state`	`"live" \| "expired" \| "revoked"`	yes
`url`	`string`	yes	The link. Its address is the secret: only its hash is stored, so it is in this answer and nowhere else.

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools