> ## Documentation Index
> Fetch the complete documentation index at: https://altostrat.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Apply a tag to a resource

> Applies a tag with a specific value to a resource, identified by its `correlation_id` and `correlation_type`. If a tag with the same value (case-insensitive) already exists for this tag definition, the existing canonical value will be used.



## OpenAPI

````yaml /api/en/metadata.yaml post /tags/{tagId}/values
openapi: 3.0.3
info:
  title: Altostrat Metadata API
  version: 1.0.0
  description: >-
    The Altostrat Metadata API is the microservice responsible for managing
    user-defined metadata, structured tags, and associated site files for
    resources within the platform.


    It acts as a central repository for enrichment data, allowing users to
    categorize, search, and organize their network assets like sites and
    devices. This structured data is crucial for powering advanced network
    automation, reporting, and agentic AI features in the Altostrat SDX
    platform.


    This API allows you to programmatically manage:

    - **Metadata:** Arbitrary key-value pairs attached to any resource, perfect
    for storing custom information like circuit IDs or contact details.

    - **Tags:** A structured system for creating reusable labels (e.g.,
    "Region," "Customer Tier") and applying them consistently across resources.

    - **Site Files:** Attachments like network diagrams, photos, and notes
    associated with a specific site.


    Developers use this API to enrich their network resources with contextual
    data, enabling powerful filtering, automation, and organizational
    capabilities.
servers:
  - url: https://v1.api.altostrat.io
security:
  - BearerAuth: []
tags:
  - name: Tags
    description: Manage tag definitions, which act as templates for classifying resources.
  - name: Tag Values
    description: Apply, update, and remove tags on specific resources.
  - name: Metadata
    description: Manage arbitrary key-value metadata for any resource.
  - name: Site Files
    description: Manage files, such as notes, documents, and media, associated with sites.
paths:
  /tags/{tagId}/values:
    post:
      tags:
        - Tag Values
      summary: Apply a tag to a resource
      description: >-
        Applies a tag with a specific value to a resource, identified by its
        `correlation_id` and `correlation_type`. If a tag with the same value
        (case-insensitive) already exists for this tag definition, the existing
        canonical value will be used.
      operationId: applyTagToResource
      parameters:
        - $ref: '#/components/parameters/TagId'
      requestBody:
        required: true
        description: The details of the resource to tag and the value to apply.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagValueCreate'
            example:
              correlation_id: site_9b52d930f4324c0abac04c12dff85544
              correlation_type: site
              value: Production
      responses:
        '201':
          description: The tag was applied successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagValue'
        '400':
          description: Bad Request - The request was malformed or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    TagId:
      name: tagId
      in: path
      required: true
      description: The unique identifier for the tag definition.
      schema:
        type: string
      example: tag_01E8Z4Q6J7B6A5P4E3D2C1B0A9
  schemas:
    TagValueCreate:
      type: object
      required:
        - correlation_id
        - correlation_type
        - value
      properties:
        correlation_id:
          type: string
          description: The unique ID of the resource to apply the tag to.
          example: site_9b52d930f4324c0abac04c12dff85544
        correlation_type:
          $ref: '#/components/schemas/CorrelationType'
        value:
          type: string
          description: The value to assign.
          maxLength: 255
          example: Enterprise
    TagValue:
      type: object
      properties:
        tag_id:
          type: string
          description: The ID of the parent tag definition.
          example: tag_01E8Z4Q6J7B6A5P4E3D2C1B0A9
        correlation_id:
          type: string
          description: The ID of the resource this tag value is applied to.
          example: site_9b52d930f4324c0abac04c12dff85544
        correlation_type:
          $ref: '#/components/schemas/CorrelationType'
        value:
          type: string
          description: >-
            The specific value of the tag for this resource (e.g., "APAC",
            "High").
          example: APAC
        created_at:
          type: string
          format: date-time
          description: The timestamp when the tag value was created.
          example: '2025-10-29T13:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the tag value was last updated.
          example: '2025-10-29T13:00:00Z'
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          description: A broad category for the error (e.g., 'invalid_request_error').
          example: invalid_request_error
        code:
          type: string
          description: A short, unique string identifying the specific error.
          example: parameter_missing
        message:
          type: string
          description: A human-readable description of what went wrong.
          example: The 'name' parameter is required for this request.
        doc_url:
          type: string
          description: >-
            A direct link to the documentation page for this specific error
            code.
          example: https://docs.altostrat.io/errors/parameter_missing
    CorrelationType:
      type: string
      description: The type of resource being correlated.
      enum:
        - site
        - user
        - wan
        - account
      example: site
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: A bearer token is required for all API requests.

````