openapi: 3.0.3
info:
  title: MediaValet Open Assets Keywords API
  description: 'The MediaValet Open API is a RESTful, JSON, hypermedia-driven interface to the MediaValet cloud digital asset management (DAM) platform. It lets developers and partners automate the management of digital assets, categories, attributes, keywords, uploads, and users. Requests are made to the API gateway at https://api.mediavalet.com and must carry two credentials: an OAuth 2.0 (OIDC) Bearer access token obtained from https://login.mediavalet.com/connect/token, and a per-account subscription key sent in the Ocp-Apim-Subscription-Key header. Access to the API requires a MediaValet subscription and Developer Portal registration. The paths documented here are modeled from MediaValet''s public developer documentation and community SDKs; verify exact request/response schemas against the live reference at docs.mediavalet.com.'
  version: '1.0'
  contact:
    name: MediaValet
    url: https://www.mediavalet.com
servers:
- url: https://api.mediavalet.com
  description: MediaValet API gateway (public)
security:
- oauth2: []
  subscriptionKey: []
tags:
- name: Keywords
  description: Keyword vocabulary and per-asset tagging.
paths:
  /keywords:
    get:
      operationId: listKeywords
      tags:
      - Keywords
      summary: List keywords
      description: List the keyword vocabulary for the library.
      responses:
        '200':
          description: A list of keywords.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createKeyword
      tags:
      - Keywords
      summary: Create a keyword
      description: Add a new keyword to the library vocabulary.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Keyword'
      responses:
        '201':
          description: The created keyword.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Keyword'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /keywords/{keywordId}:
    get:
      operationId: getKeyword
      tags:
      - Keywords
      summary: Get a keyword
      description: Retrieve a single keyword by its identifier.
      parameters:
      - name: keywordId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested keyword.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Keyword'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /keywordGroups:
    get:
      operationId: listKeywordGroups
      tags:
      - Keywords
      summary: List keyword groups
      description: List the keyword groups that organize the keyword vocabulary.
      responses:
        '200':
          description: A list of keyword groups.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication failed - missing or invalid access token or subscription key.
    NotFound:
      description: The requested resource was not found.
  schemas:
    Keyword:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        keywordGroupId:
          type: string
          format: uuid
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 / OpenID Connect. Obtain an access token from https://login.mediavalet.com/connect/token using the authorization code flow (interactive apps) or password / client-credential grants, with scopes openid api offline_access. Send the token as a Bearer Authorization header.
      flows:
        authorizationCode:
          authorizationUrl: https://login.mediavalet.com/connect/authorize
          tokenUrl: https://login.mediavalet.com/connect/token
          scopes:
            openid: OpenID Connect identity
            api: Access the MediaValet API
            offline_access: Obtain a refresh token
    subscriptionKey:
      type: apiKey
      in: header
      name: Ocp-Apim-Subscription-Key
      description: Per-account API subscription key issued through the MediaValet Developer Portal.