> ## 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.

# Create a metadata object

> Creates a new metadata object for a given resource, or fully overwrites an existing one for that resource. The metadata itself is a flexible key-value store.



## OpenAPI

````yaml /api/en/metadata.yaml post /metadata
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:
  /metadata:
    post:
      tags:
        - Metadata
      summary: Create a metadata object
      description: >-
        Creates a new metadata object for a given resource, or fully overwrites
        an existing one for that resource. The metadata itself is a flexible
        key-value store.
      operationId: createMetadata
      requestBody:
        required: true
        description: The resource identifier and the metadata to associate with it.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetadataCreate'
      responses:
        '200':
          description: Metadata created or updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Metadata'
        '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:
  schemas:
    MetadataCreate:
      type: object
      required:
        - resource_id
        - type
        - metadata
      properties:
        resource_id:
          type: string
          format: uuid
          description: The UUID of the resource to associate metadata with.
          example: 9b52d930-f432-4c0a-bac0-4c12dff85544
        type:
          type: string
          description: A string identifying the type of the resource.
          example: mikrotik.device
        metadata:
          type: object
          description: >-
            The key-value data to store. A 'name' key is required when creating
            new metadata.
          required:
            - name
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
          example:
            name: Main Office Router
            location: Level 5, Server Room A
            contact_person: john.doe@example.com
    Metadata:
      type: object
      properties:
        resource_id:
          type: string
          format: uuid
          description: The unique identifier of the resource this metadata belongs to.
          example: 9b52d930-f432-4c0a-bac0-4c12dff85544
        type:
          type: string
          description: A string identifying the type of the resource.
          example: mikrotik.device
        metadata:
          type: object
          description: >-
            A free-form object containing key-value pairs. Values can be
            strings, numbers, or booleans.
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
          example:
            circuit_id: AS12345-XYZ
            install_date: '2025-01-15'
            is_critical: true
            rack_units: 2
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: A bearer token is required for all API requests.

````