Jump to

• Request
• Response

Create a Tag

post

/20160918/tagNamespaces/{tag_namespace_id}/tags

Create a new tag in the specified tag namespace. The tag requires either the OCID or the name of the tag namespace that will contain this tag definition.

You must specify a name for the tag, which must be unique across all tags in the tag namespace and cannot be changed. The name can contain any ASCII character except the space or period characters. Names are case insensitive. That means, for example, "myTag" and "mytag" are not allowed in the same namespace. If you specify a name that is already in use in the tag namespace, a 409 error is returned.

The tag must have a description. The description does not need to be unique, and you can change it with UpdateTag.

The tag must have a value type, which is specified with a validator. Tags can use either a static value or a list of possible values. Static values are entered by a user applying the tag to a resource. Lists are created by you, and the user must apply a value from the list. Lists are validiated.

If no validator is set, the user applying the tag to a resource can type in a static value or leave the tag value empty.

If a validator is set, the user applying the tag to a resource must select from a list of values that you supply with EnumTagDefinitionValidator.

Request

Supported Media Types

• application/json

Path Parameters

• tagNamespaceId(required): string
  Minimum Length: 1

  Maximum Length: 100

  The OCID of the tag namespace.

Query Parameters

• isLockOverride: boolean
  Whether to override locks (if any exist).

  Default Value: false

Header Parameters

• opc-retry-token: string
  Minimum Length: 1

  Maximum Length: 64

  A token that uniquely identifies a request so it can be retried in case of a timeout or server error without risk of executing that same action again. Retry tokens expire after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).

Body ()

Request object for creating a new tag in the specified tag namespace.

Root Schema : CreateTagDetails

Type: object

Show Source

• definedTags: object definedTags
  Additional Properties Allowed: additionalProperties

  Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {"Operations": {"CostCenter": "42"}}
• description(required): string
  Minimum Length: 1

  Maximum Length: 400

  The description you assign to the tag during creation.
• freeformTags: object freeformTags
  Additional Properties Allowed: additionalProperties

  Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {"Department": "Finance"}
• isCostTracking: boolean
  Indicates whether the tag is enabled for cost tracking.
• name(required): string
  Minimum Length: 1

  Maximum Length: 100

  The name you assign to the tag during creation. This is the tag key definition. The name must be unique within the tag namespace and cannot be changed.
• validator: object BaseTagDefinitionValidator
  Discriminator: validatorType

  Validates a definedTag value. Each validator performs validation steps in addition to the standard validation for definedTag values. If you define a validator after a value has been set for a defined tag, then any updates that attempt to change the value must pass the additional validation defined by the current rule. Previously set values (even those that would fail the current validation) are not updated. You can still update other attributes to resources that contain a non-valid defined tag. To clear the validator call UpdateTag with [DefaultTagDefinitionValidator](/api/#/en/identity/latest/datatypes/DefaultTagDefinitionValidator).

{
    "required":[
        "name",
        "description"
    ],
    "properties":{
        "name":{
            "type":"string",
            "description":"The name you assign to the tag during creation. This is the tag key definition. The name must be unique within the tag namespace and cannot be changed.",
            "minLength":1,
            "maxLength":100
        },
        "description":{
            "type":"string",
            "description":"The description you assign to the tag during creation.",
            "minLength":1,
            "maxLength":400
        },
        "freeformTags":{
            "description":"Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {\"Department\": \"Finance\"} ",
            "type":"object",
            "additionalProperties":{
                "type":"string"
            }
        },
        "definedTags":{
            "type":"object",
            "description":"Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {\"Operations\": {\"CostCenter\": \"42\"}} ",
            "additionalProperties":{
                "type":"object",
                "description":"Key-value pair representing a defined tag key and value, scoped to a namespace.  Example: `{\"CostCenter\": \"42\"}` ",
                "additionalProperties":{
                    "type":"object",
                    "description":"The value of the tag. Only the String type is supported. "
                }
            }
        },
        "isCostTracking":{
            "type":"boolean",
            "description":"Indicates whether the tag is enabled for cost tracking."
        },
        "validator":{
            "$ref":"#/definitions/BaseTagDefinitionValidator"
        }
    },
    "type":"object"
}

Nested Schema : definedTags

Type: object

Additional Properties Allowed

Show Source

• object additionalProperties
  Additional Properties Allowed: additionalProperties

  Key-value pair representing a defined tag key and value, scoped to a namespace. Example: `{"CostCenter": "42"}`

{
    "type":"object",
    "description":"Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {\"Operations\": {\"CostCenter\": \"42\"}} ",
    "additionalProperties":{
        "type":"object",
        "description":"Key-value pair representing a defined tag key and value, scoped to a namespace.  Example: `{\"CostCenter\": \"42\"}` ",
        "additionalProperties":{
            "type":"object",
            "description":"The value of the tag. Only the String type is supported. "
        }
    }
}

Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {"Operations": {"CostCenter": "42"}}

Nested Schema : freeformTags

Type: object

Additional Properties Allowed

Show Source

• string

{
    "description":"Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {\"Department\": \"Finance\"} ",
    "type":"object",
    "additionalProperties":{
        "type":"string"
    }
}

Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {"Department": "Finance"}

Nested Schema : BaseTagDefinitionValidator

Type: object

Discriminator: validatorType

Validates a definedTag value. Each validator performs validation steps in addition to the standard validation for definedTag values. If you define a validator after a value has been set for a defined tag, then any updates that attempt to change the value must pass the additional validation defined by the current rule. Previously set values (even those that would fail the current validation) are not updated. You can still update other attributes to resources that contain a non-valid defined tag. To clear the validator call UpdateTag with [DefaultTagDefinitionValidator](/api/#/en/identity/latest/datatypes/DefaultTagDefinitionValidator).

Show Source

• validatorType(required): string
  Allowed Values: [ "ENUM", "DEFAULT" ]

  Specifies the type of validation: a static value (no validation) or a list.

{
    "description":"Validates a definedTag value. Each validator performs validation steps in addition to the standard validation for definedTag values. If you define a validator after a value has been set for a defined tag, then any updates that attempt to change the value must pass the additional validation defined by the current rule. Previously set values (even those that would fail the current validation) are not updated. You can still update other attributes to resources that contain a non-valid defined tag. To clear the validator call UpdateTag with [DefaultTagDefinitionValidator](/api/#/en/identity/latest/datatypes/DefaultTagDefinitionValidator).",
    "discriminator":"validatorType",
    "required":[
        "validatorType"
    ],
    "properties":{
        "validatorType":{
            "type":"string",
            "enum":[
                "ENUM",
                "DEFAULT"
            ],
            "description":"Specifies the type of validation: a static value (no validation) or a list."
        }
    },
    "type":"object"
}

Nested Schema : additionalProperties

Type: object

Additional Properties Allowed

Show Source

• object additionalProperties
  The value of the tag. Only the String type is supported.

{
    "type":"object",
    "description":"Key-value pair representing a defined tag key and value, scoped to a namespace.  Example: `{\"CostCenter\": \"42\"}` ",
    "additionalProperties":{
        "type":"object",
        "description":"The value of the tag. Only the String type is supported. "
    }
}

Key-value pair representing a defined tag key and value, scoped to a namespace. Example: `{"CostCenter": "42"}`

Nested Schema : additionalProperties

Type: object

The value of the tag. Only the String type is supported.

Back to Top

Response

Supported Media Types

• application/json

200 Response

The tag is being created.

Headers

• etag: string
  For optimistic concurrency control. See `if-match`.
• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Tag

Type: object

A tag definition that belongs to a specific tag namespace. "Defined tags" must be set up in your tenancy before you can apply them to resources. Avoid entering confidential information when you supply string values using the API.

Show Source

• compartmentId(required): string
  Minimum Length: 1

  Maximum Length: 100

  The OCID of the compartment that contains the tag definition.
• definedTags: object definedTags
  Additional Properties Allowed: additionalProperties

  Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {"Operations": {"CostCenter": "42"}}
• description(required): string
  Minimum Length: 1

  Maximum Length: 400

  The description you assign to the tag.
• freeformTags: object freeformTags
  Additional Properties Allowed: additionalProperties

  Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {"Department": "Finance"}
• id(required): string
  Minimum Length: 1

  Maximum Length: 100

  The OCID of the tag definition.
• isCostTracking: boolean
  Indicates whether the tag is enabled for cost tracking.
• isRetired(required): boolean
  Indicates whether the tag is retired.
• lifecycleState: string
  Allowed Values: [ "ACTIVE", "INACTIVE", "DELETING", "DELETED" ]

  The tag's current state. After creating a tag, make sure its lifecycleState is ACTIVE before using it. After retiring a tag, make sure its lifecycleState is INACTIVE before using it. If you delete a tag, you cannot delete another tag until the deleted tag's lifecycleState changes from DELETING to DELETED.
• name(required): string
  Minimum Length: 1

  Maximum Length: 100

  The name assigned to the tag during creation. This is the tag key definition. The name must be unique within the tag namespace and cannot be changed.
• tagNamespaceId(required): string
  Minimum Length: 1

  Maximum Length: 100

  The OCID of the namespace that contains the tag definition.
• tagNamespaceName(required): string
  Minimum Length: 1

  Maximum Length: 100

  The name of the tag namespace that contains the tag definition.
• timeCreated(required): string(date-time)
  Date and time the tag was created, in the format defined by RFC3339. Example: 2016-08-25T21:10:29.600Z
• validator: object BaseTagDefinitionValidator
  Discriminator: validatorType

  Validates a definedTag value. Each validator performs validation steps in addition to the standard validation for definedTag values. If you define a validator after a value has been set for a defined tag, then any updates that attempt to change the value must pass the additional validation defined by the current rule. Previously set values (even those that would fail the current validation) are not updated. You can still update other attributes to resources that contain a non-valid defined tag. To clear the validator call UpdateTag with [DefaultTagDefinitionValidator](/api/#/en/identity/latest/datatypes/DefaultTagDefinitionValidator).

{
    "description":"A tag definition that belongs to a specific tag namespace. \"Defined tags\" must be set up in your tenancy before you can apply them to resources. Avoid entering confidential information when you supply string values using the API.",
    "required":[
        "compartmentId",
        "tagNamespaceId",
        "tagNamespaceName",
        "id",
        "name",
        "description",
        "isRetired",
        "timeCreated"
    ],
    "x-obmcs-splat":{
        "resourceKind":"tag-definition",
        "adLocality":"regional"
    },
    "properties":{
        "compartmentId":{
            "type":"string",
            "description":"The OCID of the compartment that contains the tag definition.",
            "minLength":1,
            "maxLength":100
        },
        "tagNamespaceId":{
            "type":"string",
            "description":"The OCID of the namespace that contains the tag definition.",
            "minLength":1,
            "maxLength":100
        },
        "tagNamespaceName":{
            "type":"string",
            "description":"The name of the tag namespace that contains the tag definition.",
            "minLength":1,
            "maxLength":100
        },
        "id":{
            "type":"string",
            "description":"The OCID of the tag definition.",
            "minLength":1,
            "maxLength":100
        },
        "name":{
            "type":"string",
            "description":"The name assigned to the tag during creation. This is the tag key definition. The name must be unique within the tag namespace and cannot be changed.",
            "minLength":1,
            "maxLength":100
        },
        "description":{
            "type":"string",
            "description":"The description you assign to the tag.",
            "minLength":1,
            "maxLength":400
        },
        "freeformTags":{
            "description":"Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {\"Department\": \"Finance\"} ",
            "type":"object",
            "additionalProperties":{
                "type":"string"
            }
        },
        "definedTags":{
            "type":"object",
            "description":"Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {\"Operations\": {\"CostCenter\": \"42\"}} ",
            "additionalProperties":{
                "type":"object",
                "description":"Key-value pair representing a defined tag key and value, scoped to a namespace.  Example: `{\"CostCenter\": \"42\"}` ",
                "additionalProperties":{
                    "type":"object",
                    "description":"The value of the tag. Only the String type is supported. "
                }
            }
        },
        "isRetired":{
            "type":"boolean",
            "description":"Indicates whether the tag is retired."
        },
        "lifecycleState":{
            "type":"string",
            "enum":[
                "ACTIVE",
                "INACTIVE",
                "DELETING",
                "DELETED"
            ],
            "description":"The tag's current state. After creating a tag, make sure its lifecycleState is ACTIVE before using it. After retiring a tag, make sure its lifecycleState is INACTIVE before using it. If you delete a tag, you cannot delete another tag until the deleted tag's lifecycleState changes from DELETING to DELETED."
        },
        "timeCreated":{
            "type":"string",
            "format":"date-time",
            "description":"Date and time the tag was created, in the format defined by RFC3339. Example: 2016-08-25T21:10:29.600Z "
        },
        "isCostTracking":{
            "type":"boolean",
            "description":"Indicates whether the tag is enabled for cost tracking."
        },
        "validator":{
            "$ref":"#/definitions/BaseTagDefinitionValidator"
        }
    },
    "type":"object"
}

Nested Schema : definedTags

Type: object

Additional Properties Allowed

Show Source

• object additionalProperties
  Additional Properties Allowed: additionalProperties

  Key-value pair representing a defined tag key and value, scoped to a namespace. Example: `{"CostCenter": "42"}`

{
    "type":"object",
    "description":"Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {\"Operations\": {\"CostCenter\": \"42\"}} ",
    "additionalProperties":{
        "type":"object",
        "description":"Key-value pair representing a defined tag key and value, scoped to a namespace.  Example: `{\"CostCenter\": \"42\"}` ",
        "additionalProperties":{
            "type":"object",
            "description":"The value of the tag. Only the String type is supported. "
        }
    }
}

Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {"Operations": {"CostCenter": "42"}}

Nested Schema : freeformTags

Type: object

Additional Properties Allowed

Show Source

• string

{
    "description":"Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {\"Department\": \"Finance\"} ",
    "type":"object",
    "additionalProperties":{
        "type":"string"
    }
}

Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {"Department": "Finance"}

Nested Schema : BaseTagDefinitionValidator

Type: object

Discriminator: validatorType

Validates a definedTag value. Each validator performs validation steps in addition to the standard validation for definedTag values. If you define a validator after a value has been set for a defined tag, then any updates that attempt to change the value must pass the additional validation defined by the current rule. Previously set values (even those that would fail the current validation) are not updated. You can still update other attributes to resources that contain a non-valid defined tag. To clear the validator call UpdateTag with [DefaultTagDefinitionValidator](/api/#/en/identity/latest/datatypes/DefaultTagDefinitionValidator).

Show Source

• validatorType(required): string
  Allowed Values: [ "ENUM", "DEFAULT" ]

  Specifies the type of validation: a static value (no validation) or a list.

{
    "description":"Validates a definedTag value. Each validator performs validation steps in addition to the standard validation for definedTag values. If you define a validator after a value has been set for a defined tag, then any updates that attempt to change the value must pass the additional validation defined by the current rule. Previously set values (even those that would fail the current validation) are not updated. You can still update other attributes to resources that contain a non-valid defined tag. To clear the validator call UpdateTag with [DefaultTagDefinitionValidator](/api/#/en/identity/latest/datatypes/DefaultTagDefinitionValidator).",
    "discriminator":"validatorType",
    "required":[
        "validatorType"
    ],
    "properties":{
        "validatorType":{
            "type":"string",
            "enum":[
                "ENUM",
                "DEFAULT"
            ],
            "description":"Specifies the type of validation: a static value (no validation) or a list."
        }
    },
    "type":"object"
}

Nested Schema : additionalProperties

Type: object

Additional Properties Allowed

Show Source

• object additionalProperties
  The value of the tag. Only the String type is supported.

{
    "type":"object",
    "description":"Key-value pair representing a defined tag key and value, scoped to a namespace.  Example: `{\"CostCenter\": \"42\"}` ",
    "additionalProperties":{
        "type":"object",
        "description":"The value of the tag. Only the String type is supported. "
    }
}

Key-value pair representing a defined tag key and value, scoped to a namespace. Example: `{"CostCenter": "42"}`

Nested Schema : additionalProperties

Type: object

The value of the tag. Only the String type is supported.

Example Response (application-json)

{   "name" : "CostCenter",   "description" : "This tag will show the cost center that will be used for billing of associated resources.",   "type" : "string",   "tagNamespaceId" : "ocid1.namespace.oc1..aaaaaaaaqexampleuniqueID",   "tagNameSpaceName" : "BillingTags",   "compartmentId" : "ocid1.tenancy.oc1..aaaaaaaabaexampleuniqueID",   "isRetired" : "false",   "lifecycleState" : "ACTIVE",   "timeCreated" : "2017-09-01T18:13:12.210Z",   "isCostTracking" : "true",   "validator" : {} } 

400 Response

Bad Request

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

The properties that define an error.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm).
• message(required): string
  A human-readable error string.

{
    "description":"The properties that define an error.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm)."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "type":"object"
}

401 Response

Unauthorized

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

The properties that define an error.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm).
• message(required): string
  A human-readable error string.

{
    "description":"The properties that define an error.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm)."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "type":"object"
}

404 Response

Not Found

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

The properties that define an error.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm).
• message(required): string
  A human-readable error string.

{
    "description":"The properties that define an error.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm)."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "type":"object"
}

409 Response

Conflict

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

The properties that define an error.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm).
• message(required): string
  A human-readable error string.

{
    "description":"The properties that define an error.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm)."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "type":"object"
}

429 Response

Too Many Requests

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

The properties that define an error.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm).
• message(required): string
  A human-readable error string.

{
    "description":"The properties that define an error.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm)."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "type":"object"
}

500 Response

Internal Server Error

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

The properties that define an error.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm).
• message(required): string
  A human-readable error string.

{
    "description":"The properties that define an error.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm)."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "type":"object"
}

Default Response

An error has occurred.

Headers

• opc-request-id: string
  Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.

Body ()

Root Schema : Error

Type: object

The properties that define an error.

Show Source

• code(required): string
  A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm).
• message(required): string
  A human-readable error string.

{
    "description":"The properties that define an error.",
    "required":[
        "code",
        "message"
    ],
    "properties":{
        "code":{
            "type":"string",
            "description":"A short error code that defines the error, meant for programmatic parsing. See [API Errors](https://docs.us-phoenix-1.oraclecloud.com/Content/API/References/apierrors.htm)."
        },
        "message":{
            "type":"string",
            "description":"A human-readable error string."
        }
    },
    "type":"object"
}

Back to Top