---
title: "Create a tag policy"
method: POST
path: "/api/v2/tag-policies"
tags: ["Tag Policies"]
---

# Create a tag policy

`POST /api/v2/tag-policies`

Create a new tag policy for the organization. The caller's organization is derived from
the authenticated user; cross-organization creation is not supported. Fields such as
`policy_id`, `version`, and the timestamp/audit fields are assigned by the server.

## Request body

- TagPolicyCreateRequest — Payload for creating a new tag policy.
  - `data` TagPolicyCreateData, required — Data object for creating a tag policy.
    - `attributes` TagPolicyCreateAttributes, required — Attributes that can be supplied when creating a tag policy.
      - `enabled` boolean — Whether the policy is currently enforced. Defaults to `true` for newly created policies.
      - `negated` boolean — When `true`, the policy matches tag values that do NOT match any of the supplied patterns. Defaults to `false`.
      - `policy_name` string, required — Human-readable name for the tag policy.
      - `policy_type` 'surfacing', required — The policy type allowed when creating a tag policy. Only `surfacing` is accepted at creation time.
      - `required` boolean — When `true`, telemetry without this tag is treated as a violation. Defaults to `false`.
      - `scope` string, required — The scope the policy applies within. Typically an environment, team, or organization-level identifier used to limit where the policy is enforced.
      - `source` 'logs' | 'spans' | 'metrics' | 'rum' | 'feed', required — The telemetry source that a tag policy applies to.
      - `tag_key` string, required — The tag key that the policy governs (for example, `service`).
      - `tag_value_patterns` string[], required — One or more patterns that valid values for the tag key must match. At least one pattern is required.
    - `type` 'tag_policy', required — JSON:API resource type for a tag policy.

## Response `201`

Created

- TagPolicyResponse — A single tag policy.
  - `data` TagPolicyData, required — A tag policy resource.
    - `attributes` TagPolicyAttributes, required — The attributes of a tag policy resource.
      - `created_at` string, date-time, required — The RFC 3339 timestamp at which the policy was created.
      - `created_by` string, required — The identifier of the user who created the policy.
      - `deleted_at` string, date-time, nullable — The RFC 3339 timestamp at which the policy was soft-deleted. `null` if the policy has not been deleted. Only present when `include_deleted=true` is requested.
      - `deleted_by` string, nullable — The identifier of the user who soft-deleted the policy. `null` if the policy has not been deleted.
      - `enabled` boolean, required — Whether the policy is currently enforced.
      - `modified_at` string, date-time, required — The RFC 3339 timestamp at which the policy was last modified.
      - `modified_by` string, required — The identifier of the user who last modified the policy.
      - `negated` boolean, required — When `true`, the policy matches tag values that do NOT match any of the supplied patterns.
      - `policy_name` string, required — Human-readable name for the tag policy.
      - `policy_type` 'blocking' | 'surfacing', required — How the policy is enforced. `blocking` rejects telemetry that violates the policy. `surfacing` only highlights non-compliant telemetry without blocking it.
      - `required` boolean, required — When `true`, telemetry without this tag is treated as a violation.
      - `scope` string, required — The scope the policy applies within.
      - `source` 'logs' | 'spans' | 'metrics' | 'rum' | 'feed', required — The telemetry source that a tag policy applies to.
      - `tag_key` string, required — The tag key that the policy governs.
      - `tag_value_patterns` string[], required — The patterns that valid values for the tag key must match.
      - `version` integer, required — A monotonically increasing version counter that is incremented on each update.
    - `id` string, required — The unique identifier of the tag policy.
    - `relationships` TagPolicyRelationships — Related resources for a tag policy. Only present when the corresponding `include` query parameter is supplied.
      - `score` TagPolicyScoreRelationship — A relationship to the compliance score resource for this policy.
        - `data` TagPolicyScoreRelationshipData, required — Identifier of the related compliance score resource.
          - `id` string, required — The unique identifier of the related compliance score resource.
          - `type` 'tag_policy_score', required — JSON:API resource type for a tag policy compliance score.
    - `type` 'tag_policy', required — JSON:API resource type for a tag policy.
  - `included` TagPolicyScoreData[] — Related resources fetched alongside the primary tag policies. Populated when an `include` query parameter is supplied.
    - `attributes` TagPolicyScoreAttributes, required — Attributes of a tag policy compliance score.
      - `score` number, double, nullable, required — The compliance score for the policy over the requested time window, as a percentage between 0 and 100. `null` indicates that no relevant telemetry was found.
      - `ts_end` integer, required — End of the time window the score was computed over, as a Unix timestamp in milliseconds.
      - `ts_start` integer, required — Start of the time window the score was computed over, as a Unix timestamp in milliseconds.
      - `version` integer, required — The version of the tag policy that the score was computed against.
    - `id` string, required — The unique identifier of the compliance score resource.
    - `type` 'tag_policy_score', required — JSON:API resource type for a tag policy compliance score.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `409` — Conflict
- `429` — Too many requests

---

[API](https://skmtc.dev/datadog/apis/api-v2.md) · [All operations](https://skmtc.dev/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)