Organisations
Choose how long an organisation keeps its library and its audit log
Sets "Delete library diagrams not updated for" and "Keep the audit log for".
PUT
/orgs/{org}/retentionTL;DR
| Question | Answer |
|---|---|
| What does it do? | Choose how long an organisation keeps its library and its audit log. |
| What does it take? | A JSON body of type SetOrganisationRetentionBody. |
| What does it return? | Status 200 with a body of type OrganisationGovernance. |
| What can go wrong? | 400 the body is not valid; 401 not signed in; 403 only the owner may (orgs.forbidden), the plan does not include the policies (plan.governance_not_included), or the request came from an origin that may not make changes; 404 no such organisation, or the caller is not a member of it; 429 too many requests; 503 organisations are not set up on this server. Every failure uses the one error envelope. |
What it does
Sets "Delete library diagrams not updated for" and "Keep the audit log for". The sweep deletes library diagrams nobody updated for that long, unless kept, with their public links; the plan's retention still applies when shorter. The audit log choice only lengthens. Enterprise; only the owner.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
Request body
The body has the type SetOrganisationRetentionBody.
| Field | Type | Required | Description |
|---|---|---|---|
libraryDays | 90 | yes | "Delete library diagrams not updated for": 90, 180, 365 or 730 days, or null for never (the default). |
auditDays | 365 | yes | "Keep the audit log for": 365, 730 or 2555 days (one, two or seven years), or null for the plan's days (the default). It only lengthens. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The policies now. | OrganisationGovernance |
| 400 | The body is not valid. | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 403 | Only the owner may (orgs.forbidden), the plan does not include the policies (plan.governance_not_included), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such organisation, or the caller is not a member of it. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 503 | Organisations are not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type OrganisationGovernance.
| Field | Type | Required | Description |
|---|---|---|---|
available | boolean | yes | Whether the organisation's plan includes the policies (Enterprise). A choice saved before is kept, and is not applied without it. |
retention | OrganisationRetention | yes | |
retention.libraryDays | 90 | yes | "Delete library diagrams not updated for": 90, 180, 365 or 730 days, or null for never (the default). |
retention.auditDays | 365 | yes | "Keep the audit log for": 365, 730 or 2555 days (one, two or seven years), or null for the plan's days (the default). It only lengthens. |
retention.planLibraryDays | integer | null | yes | How long the plan keeps a diagram after its last publish, or null for until it is deleted. The plan's limit wins when it is shorter. |
retention.planAuditDays | integer | yes | How many days the plan keeps an audit event. |
retention.effectiveLibraryDays | integer | null | yes | What is applied: the shorter of planLibraryDays and libraryDays. Null when diagrams are kept until they are deleted. |
retention.effectiveAuditDays | integer | yes | What is applied: the longer of planAuditDays and auditDays, auditDays counted up to auditMaxDays. |
retention.auditMaxDays | integer | yes | The longest auditDays this server takes: 730 unless its database is on D1's paid tier, then 2555. Every organisation shares one database. |
legalHold | object | null | yes | The legal hold, or null when it is off. While it is on nothing of the organisation is deleted: no sweep, no member, and not the organisation itself. |
legalHold.since | integer | yes | When the owner turned it on, in milliseconds since the epoch. |
legalHold.reason | string | null | yes | The reason the owner typed. Shown to the owner and admins; null for anyone else. |
patternsOnly | boolean | yes | "Agents start from approved patterns": find_pattern, called through the organisation's connections and keys, answers with its own patterns only. |
styleRulesStrict | boolean | yes | "Style rules are errors": a publish to the library that breaks a saved style rule is refused with the findings. |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |