DigitalOcean API (unofficial showcase)
POST/v2/agents/configs

Create an Environment Config

Creates an immutable Environment Config for the team from a name and environment-spec YAML. Supply name and manifest_yaml; optionally set per-signal Insights telemetry preferences with insights. Declare tenant secrets in the environment spec, not as sibling request fields; secret values are never returned, and you must create a clone to change config content.

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

3 body fields

Environment Config create body. Declare tenant secrets in the environment-spec YAML under secrets or legacy spec.secrets; secret values are write-only and are never returned.

namestringrequired
Config name, case-insensitively unique among the team's active configs.
manifest_yamlstringrequired
Customer environment-spec YAML text. The HTTP JSON body is capped at 1 MiB and this field is capped at 512 KiB.
insightsobjectoptional
Optional per-signal Insights telemetry preferences for `metrics`, `logs`, and `traces`. Each signal is independently optional; an omitted or null value records no choice and uses the product default, rather than opting out.

9 status codes
201Returns the created immutable config, including its identifier, name, sanitized manifest, content hash, creator, timestamps, and any credential slot metadata. Secret values are not included.
configobjectoptional
Immutable team-scoped Environment Config: one sanitized manifest per config. There is no update; clone to a new config to change content.
400Returned when the name, JSON wrapper, or environment spec 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 due to invalid credentials.
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.
409Returned when an active config with the same name already exists for the team.
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.
413Returned when the request body exceeds 1 MiB.
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.
415Returned when the request content type is not `application/json`.
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 an invalid name, JSON wrapper, or environment spec. A 401 indicates authentication failed due to invalid credentials. A 409 is returned when an active config already exists for the team with the same name. A 413 is returned when the request body exceeds 1 MiB, and a 415 is returned when the content type is not application/json. A 429 indicates the API rate limit has been exceeded, and a 500 indicates a server error. name and manifest_yaml are required; name must be 1–64 characters, match the specified naming pattern, and be unique among the team's active configs. manifest_yaml must not exceed 512 KiB.