Policies API reference
A moderation policy decides what happens to content in each category. Policies belong to your organisation and its projects share them. Each project moderates with one policy, and an upload preset can name another for the uploads it accepts.
Every request names a project. Its API key needs policies:read to list and retrieve policies, and policies:write to create, change, delete and assign them. A key can change or delete only policies that no other project uses or owns, so it never changes how another project is moderated; change those in the portal.
Every change sends the policy's revision. A policy changed since you read it is refused with policy/revision-conflict: retrieve it again and retry.
Guide: Moderation policies.
Endpoints
| Endpoint | Description |
|---|---|
GET / | List the moderation policies of the project's organisation, and which one the project uses. |
POST / | Create a moderation policy in the project's organisation, from settings or as a copy of a built-in preset. |
GET / | Get one of the organisation's moderation policies by ID |
PATCH / | Change a policy's name, description or settings. |
POST / | Reset a policy copied from a preset to its pinned preset version, or update an unchanged copy to the latest preset release |
PUT / | Switch automatic updates on or off for a project's preset policy. |
DELETE / | Delete a policy that no project or upload preset uses. |
PUT / | Choose the policy the project moderates with. |
The policy object
Policy
idstring
Unique policy ID
namestring
Display name
descriptionstring
What the policy is for
settingsobject
What the policy does with each category, its allowances and restrictions
revisionnumber
Changes with every saved change. Send it with each change; a policy changed since is refused with
policy/revision-conflict.automaticUpdatesboolean
Whether the policy follows its preset: it always has the latest preset settings until its first saved edit pins a copy
presetobject (optional)
projectIds[]string[]
Projects this policy moderates, as their default policy or through one of their upload presets
createdAtnumber
When the policy was created, in milliseconds since the Unix epoch
updatedAtnumber (optional)
When the policy was last changed, in milliseconds since the Unix epoch
Endpoint details
List Policies
List the moderation policies of the project's organisation, and which one the project uses. Policies are shared by the organisation's projects.
const response = await client.policies.list();
Response
policies[]Policy[]
Every policy of the project's organisation, oldest first
projectPolicyIdstring
ID of the policy the project moderates with
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
403
auth/permission-deniedThis API key lacks a permission the request needs, such as assets:delete for an asset's folder, or the resource belongs to another project.
400
validation/invalid-typeA field has the wrong type. details.issues lists each problem.
400
validation/too-smallA value is below its minimum. details.issues lists each problem.
400
validation/too-bigA value is above its maximum. details.issues lists each problem.
400
validation/invalid-formatA string is not in the required format, such as an ID or URL. details.issues lists each problem.
400
validation/invalid-valueA field has a value it cannot take. details.issues lists each problem.
400
validation/unknown-fieldThe request has a field this endpoint does not accept.
404
project/not-foundProject not found
500
misc/internal-errorAn internal error occurred. Retry later, and quote requestId to support.
Create Policy
Create a moderation policy in the project's organisation, from settings or as a copy of a built-in preset. It moderates nothing until you assign it to a project or name it on an upload preset.
const response = await client.policies.create({
"presetId": "children-platform",
"name": "Kids section"
});
Response
Policy
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
403
auth/permission-deniedThis API key lacks a permission the request needs, such as assets:delete for an asset's folder, or the resource belongs to another project.
400
validation/invalid-typeA field has the wrong type. details.issues lists each problem.
400
validation/too-smallA value is below its minimum. details.issues lists each problem.
400
validation/too-bigA value is above its maximum. details.issues lists each problem.
400
validation/invalid-formatA string is not in the required format, such as an ID or URL. details.issues lists each problem.
400
validation/invalid-valueA field has a value it cannot take. details.issues lists each problem.
400
validation/unknown-fieldThe request has a field this endpoint does not accept.
415
validation/unsupported-content-typeSend the request body as application/json.
404
project/not-foundProject not found
500
misc/internal-errorAn internal error occurred. Retry later, and quote requestId to support.
const response = await client.policies.retrieve({
"policyId": "pol_2Wk7Rm4Xq9Lt3Vb8Np6C"
});
Response
Policy
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
403
auth/permission-deniedThis API key lacks a permission the request needs, such as assets:delete for an asset's folder, or the resource belongs to another project.
400
validation/invalid-typeA field has the wrong type. details.issues lists each problem.
400
validation/too-smallA value is below its minimum. details.issues lists each problem.
400
validation/too-bigA value is above its maximum. details.issues lists each problem.
400
validation/invalid-formatA string is not in the required format, such as an ID or URL. details.issues lists each problem.
400
validation/invalid-valueA field has a value it cannot take. details.issues lists each problem.
400
validation/unknown-fieldThe request has a field this endpoint does not accept.
404
project/not-foundProject not found
404
policy/not-foundPolicy not found. Check the policy ID in the portal.
500
misc/internal-errorAn internal error occurred. Retry later, and quote requestId to support.
Update Policy
Change a policy's name, description or settings. Changes apply to later moderation. Saving a policy that follows automatic updates pins it as a copy under the same ID. Only policies that no other project uses or owns can be changed through a project's key.
const response = await client.policies.update({
"policyId": "pol_2Wk7Rm4Xq9Lt3Vb8Np6C",
"revision": 1
});
Response
Policy
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
403
auth/permission-deniedThis API key lacks a permission the request needs, such as assets:delete for an asset's folder, or the resource belongs to another project.
400
validation/invalid-typeA field has the wrong type. details.issues lists each problem.
400
validation/too-smallA value is below its minimum. details.issues lists each problem.
400
validation/too-bigA value is above its maximum. details.issues lists each problem.
400
validation/invalid-formatA string is not in the required format, such as an ID or URL. details.issues lists each problem.
400
validation/invalid-valueA field has a value it cannot take. details.issues lists each problem.
400
validation/unknown-fieldThe request has a field this endpoint does not accept.
415
validation/unsupported-content-typeSend the request body as application/json.
404
project/not-foundProject not found
404
policy/not-foundPolicy not found. Check the policy ID in the portal.
409
policy/revision-conflictThe policy changed. Retrieve it again and retry with its current revision.
409
policy/projects-changedThe projects using this policy changed. Retrieve it again and review the affected projects before saving.
409
policy/used-by-another-projectAnother project uses or owns this policy, so it can only be changed from the portal or that project.
500
misc/internal-errorAn internal error occurred. Retry later, and quote requestId to support.
Reset or Update Policy Preset
Reset a policy copied from a preset to its pinned preset version, or update an unchanged copy to the latest preset release
const response = await client.policies.applyPreset({
"policyId": "pol_2Wk7Rm4Xq9Lt3Vb8Np6C",
"operation": "reset",
"revision": 3,
"presetVersion": 35
});
Response
Policy
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
403
auth/permission-deniedThis API key lacks a permission the request needs, such as assets:delete for an asset's folder, or the resource belongs to another project.
400
validation/invalid-typeA field has the wrong type. details.issues lists each problem.
400
validation/too-smallA value is below its minimum. details.issues lists each problem.
400
validation/too-bigA value is above its maximum. details.issues lists each problem.
400
validation/invalid-formatA string is not in the required format, such as an ID or URL. details.issues lists each problem.
400
validation/invalid-valueA field has a value it cannot take. details.issues lists each problem.
400
validation/unknown-fieldThe request has a field this endpoint does not accept.
415
validation/unsupported-content-typeSend the request body as application/json.
404
project/not-foundProject not found
404
policy/not-foundPolicy not found. Check the policy ID in the portal.
409
policy/revision-conflictThe policy changed. Retrieve it again and retry with its current revision.
409
policy/projects-changedThe projects using this policy changed. Retrieve it again and review the affected projects before saving.
409
policy/used-by-another-projectAnother project uses or owns this policy, so it can only be changed from the portal or that project.
400
policy/no-presetThis policy has no preset baseline.
409
policy/preset-version-conflictThe preset changed. Review the latest differences and retry with its version.
500
misc/internal-errorAn internal error occurred. Retry later, and quote requestId to support.
Set Policy Automatic Updates
Switch automatic updates on or off for a project's preset policy. A policy that follows automatic updates always has the latest preset settings.
const response = await client.policies.setAutomaticUpdates({
"policyId": "pol_2Wk7Rm4Xq9Lt3Vb8Np6C",
"enabled": true,
"revision": 3,
"presetVersion": 35
});
Response
Policy
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
403
auth/permission-deniedThis API key lacks a permission the request needs, such as assets:delete for an asset's folder, or the resource belongs to another project.
400
validation/invalid-typeA field has the wrong type. details.issues lists each problem.
400
validation/too-smallA value is below its minimum. details.issues lists each problem.
400
validation/too-bigA value is above its maximum. details.issues lists each problem.
400
validation/invalid-formatA string is not in the required format, such as an ID or URL. details.issues lists each problem.
400
validation/invalid-valueA field has a value it cannot take. details.issues lists each problem.
400
validation/unknown-fieldThe request has a field this endpoint does not accept.
415
validation/unsupported-content-typeSend the request body as application/json.
404
project/not-foundProject not found
404
policy/not-foundPolicy not found. Check the policy ID in the portal.
409
policy/revision-conflictThe policy changed. Retrieve it again and retry with its current revision.
409
policy/projects-changedThe projects using this policy changed. Retrieve it again and review the affected projects before saving.
409
policy/used-by-another-projectAnother project uses or owns this policy, so it can only be changed from the portal or that project.
409
policy/preset-version-conflictThe preset changed. Review the latest differences and retry with its version.
500
misc/internal-errorAn internal error occurred. Retry later, and quote requestId to support.
Delete Policy
Delete a policy that no project or upload preset uses. Only policies that no other project owns can be deleted through a project's key.
const response = await client.policies.delete({
"policyId": "pol_2Wk7Rm4Xq9Lt3Vb8Np6C"
});
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
403
auth/permission-deniedThis API key lacks a permission the request needs, such as assets:delete for an asset's folder, or the resource belongs to another project.
400
validation/invalid-typeA field has the wrong type. details.issues lists each problem.
400
validation/too-smallA value is below its minimum. details.issues lists each problem.
400
validation/too-bigA value is above its maximum. details.issues lists each problem.
400
validation/invalid-formatA string is not in the required format, such as an ID or URL. details.issues lists each problem.
400
validation/invalid-valueA field has a value it cannot take. details.issues lists each problem.
400
validation/unknown-fieldThe request has a field this endpoint does not accept.
404
project/not-foundProject not found
404
policy/not-foundPolicy not found. Check the policy ID in the portal.
409
policy/in-useProjects or upload presets still use this policy. Choose another policy for each of them before deleting it.
409
policy/used-by-another-projectAnother project uses or owns this policy, so it can only be changed from the portal or that project.
500
misc/internal-errorAn internal error occurred. Retry later, and quote requestId to support.
Assign Policy
Choose the policy the project moderates with. Later uploads use it, except those through an upload preset that names its own policy.
const response = await client.policies.assign({
"policyId": "pol_2Wk7Rm4Xq9Lt3Vb8Np6C"
});
Response
Policy
Error Codes
401
auth/missing-tokenAuthentication required. Send your project API key in the X-Api-Key header.
401
auth/invalid-api-keyThe API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403
auth/project-mismatchThis API key belongs to a different project. Use a key created for the project that owns this resource.
403
auth/permission-deniedThis API key lacks a permission the request needs, such as assets:delete for an asset's folder, or the resource belongs to another project.
400
validation/invalid-typeA field has the wrong type. details.issues lists each problem.
400
validation/too-smallA value is below its minimum. details.issues lists each problem.
400
validation/too-bigA value is above its maximum. details.issues lists each problem.
400
validation/invalid-formatA string is not in the required format, such as an ID or URL. details.issues lists each problem.
400
validation/invalid-valueA field has a value it cannot take. details.issues lists each problem.
400
validation/unknown-fieldThe request has a field this endpoint does not accept.
415
validation/unsupported-content-typeSend the request body as application/json.
404
project/not-foundProject not found
404
policy/not-foundPolicy not found. Check the policy ID in the portal.
500
misc/internal-errorAn internal error occurred. Retry later, and quote requestId to support.