DigitalOcean API (unofficial showcase)
POST/v2/agents/sessions/policy/validate

Validate an environment spec policy

Validates an environment spec's tool-permission policy against the capabilities of the agent selected by its template, without creating a session. Send the YAML environment spec and review the per-rule verdicts; ok is false when a strict rule is unsupported or unverified. Use this preflight to check whether CreateSession would accept the policy for the resolved agent and version.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

4 body fields

YAML environment spec for policy preflight; only agent and template selection and the permissions block are used. Supported YAML content types include application/x-yaml, application/yaml, text/yaml, and `text/x-yaml.

apiVersionstringoptional
Legacy envelope only - must be "agents.digitalocean.com/v1alpha1", and its presence is what routes the document to the deprecated legacy parser. Flat-format manifests carry no version key (the endpoint owns the contract); required, with kind and spec, when authoring the legacy format.
Allowed:agents.digitalocean.com/v1alpha1
kindstringoptional
Must be "Agent".
Allowed:Agent
metadataobjectoptional
Manifest metadata, including the optional session name, description, and labels.
specobjectoptional
Environment specification. `runtime` is required; includes agent and template selection, permissions, and other environment settings. `mode` accepts `interactive` or `served`, and `skills` can contain at most 32 entries.

7 status codes
200Returns the resolved agent and version, `ok` status, default-action verdicts, and per-rule verdicts. An `ok` value of false means CreateSession would reject the policy for that agent and version.
agentstringoptional
versionstringoptional
okbooleanoptional
False when any strict rule is unsupported or unverified — i.e. CreateSession would reject this policy for this (agent, version).
defaultActionstringoptional
Catch-all disposition AS SHIPPED (after unverified allow→ask downgrade). When defaultActionVerdict is degraded, this remains the shipped value; see defaultActionRendered for what the agent will actually enforce.
Allowed:allowaskdeny
defaultActionVerdictstringoptional
exact — agent can enforce the catch-all as written; degraded — agent cannot enforce the requested defaultAction (warn-only; shipped value unchanged); omitted when no descriptor was available to classify against.
Allowed:exactdegradedunsupportedunverified
defaultActionRenderedstringoptional
Disposition the agent will actually enforce as the catch-all: equals defaultAction when exact; the more-restrictive degrade target (usually ask) when degraded.
Allowed:allowaskdeny
defaultActionReasonstringoptional
Human-readable explanation when defaultActionVerdict is degraded.
verdictsarray<object>optional
400Returned when the manifest is malformed or `spec.permissions` is invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Returned when the requested resource is not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.

Error handling

A 400 is returned for a malformed manifest or invalid spec.permissions; 401 indicates invalid authentication credentials; 404 indicates that a resource was not found; 429 indicates that the API rate limit was exceeded; and 500 indicates a server error. In the manifest, spec.runtime and spec.runtime.adapter are required, kind must be Agent, and any apiVersion must be agents.digitalocean.com/v1alpha1.