admin-api.yaml

openapi: 3.0.0
info:
  title: api.video Admin API
  description: The Admin API is tool that enables you to directly manage your api.video projects and API keys through a secure API.
  version: 1.0.0
servers:
  - url: https://admin.api.video
paths:
  /projects/count:
    get:
      tags:
        - Projects
      summary: Get project count
      description: This endpoint enables you to retrieve the overall number of projects you have.
      parameters:
        - in: query
          name: name
          schema:
            type: string
          description: Filter for projects names that contain this value. The API can return partial matches.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    description: The number of projects.
                    type: integer
                    example: 37
      security:
        - basicAuth: []
  /projects:
    get:
      tags:
        - Projects
      summary: List projects
      description: |
        This endpoint enables you to retrieve a paginated list of every project you have. You can filter the list by project name, and sort by name, creation date, and ascending or descending order.

        Note that the API response only contains one page of results. To navigate to another page, use the `previous` or `next` path queries provided in the respone's `links` object.
      parameters:
        - in: query
          name: page_size
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Number of records per page.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number to retrieve.
        - in: query
          name: name
          schema:
            type: string
          description: Filter for projects names that contain this value.
        - in: query
          name: sort_by
          schema:
            type: string
            enum:
              - created_at
              - name
          description: 'Select a property to sort by. Allowed values: `created_at`, `name`.'
        - in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
          description: 'Select the order to sort by. Allowed values: `asc`, `desc`.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  pagination:
                      $ref: '#/components/schemas/Pagination'
                  links:
                      $ref: '#/components/schemas/Links'
      security:
        - basicAuth: []
    post:
      tags:
        - Projects
      summary: Create project
      description: This endpoint enables you to create a new project and select the hosting region for it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the Admin API key. Also visible in the dashboard. You may set any value that fits your organization purposes.
                region:
                  type: string
                  description: The region where your data is hosted.
                  enum:
                    - us-east-1
                    - eu-central-1
              required:
                - name
                - region
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
      security:
        - basicAuth: []
  /projects/{project_id}/api-keys/count:
    get:
      tags:
        - API keys
      summary: Count API keys
      description: This endpoint enables you to count the overall number of API keys for a specific project.
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
          description: The ID of the project you want to count API keys for.
        - in: query
          name: name
          schema:
            type: string
          description: Filter for API key names that contain this value. The API can return partial matches.
        - in: query
          name: value
          schema:
            type: string
          description: Filter for the value of a specific API key.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    description: The number of API keys.
                    type: integer
                    example: 16
      security:
        - basicAuth: []
  /projects/{project_id}:
    get:
      tags:
        - Projects
      summary: Get project
      description: This endpoint enables you to retrieve a specific project based on its `project_id`.
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
          description: The ID of the project you want to retrieve.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
      security:
        - basicAuth: []
    patch:
      tags:
        - Projects
      summary: Update project
      description: |
        This endpoint enables you to update a specific project based on its `project_id`.

        You can update the project name and schedule the project for deletion. When you schedule a project for deletion, the project will be deleted on the first day of the next billing cycle. The API sends the exact date-time of deletion in the response.
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
          description: The ID of the project you want to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The project name that you want to update.
                deletes_at:
                  type: string
                  enum:
                    - next_cycle
                  description: Schedule the project for deletion. The accepted value is `next_cycle`. The project will be deleted on the first day of the next billing cycle. The API sends the exact date-time of deletion in the response.
              required:
                - name
      responses:
        '200':
          description: Project updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
      security:
        - basicAuth: []
  /projects/{project_id}/delivery-usage:
    get:
      tags:
        - Usage
      summary: Get delivery usage
      description: This endpoint enables you to retrieve the total amount of minutes delivered for a specific project based on its `project_id`.
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
          description: The ID of the project you want to retrieve usage data for.
        - in: query
          name: interval
          required: true
          schema:
            type: string
            enum:
              - month
              - week
          description: Set the period of time that you want to retrieve delivery usage for. `month` returns data for the past 30 days, while `week` returns data for the past 7 days.
      responses:
        '200':
          description: Successful response
          content: 
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DeliveryUsageResponse'
                example:
                  items:
                  - collected_on: '2024-08-09'
                    video_hls_duration_minutes: 10
                    video_mp4_duration_minutes: 22
                    live_stream_hls_duration_minutes: 422
                  - collected_on: '2024-08-10'
                    video_hls_duration_minutes: 33
                    video_mp4_duration_minutes: 245
                    live_stream_hls_duration_minutes: 32
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                constraint: required
                detail: An attribute is invalid.
                name: interval
                title: Bad request.
                total_problems: 1
                type: 'https://docs.api.video/reference/invalid-attribute'
      security:
        - basicAuth: []
  /projects/{project_id}/hosting-usage:
    get:
      tags:
        - Usage
      summary: Get hosting usage
      description: This endpoint enables you to retrieve the cumulative amount of video minutes hosted in a specific project based on its `project_id`.
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
          description: The ID of the project you want to retrieve usage data for.
        - in: query
          name: interval
          required: true
          schema:
            type: string
            enum:
              - month
              - week
          description: Set the period of time that you want to retrieve hosting usage data for. `month` returns data for the past 30 days, while `week` returns data for the past 7 days.
      responses:
        '200':
          description: Successful response
          content: 
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/HostingUsageResponse'
                example:
                  items:
                  - collected_on: '2024-08-09'
                    video_duration_minutes: 235
                  - collected_on: '2024-08-10'
                    video_duration_minutes: 454
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
              example:
                constraint: required
                detail: An attribute is invalid.
                name: interval
                title: Bad request.
                total_problems: 1
                type: 'https://docs.api.video/reference/invalid-attribute'
      security:
        - basicAuth: []
  /projects/{project_id}/api-keys:
    get:
      tags:
        - API keys
      summary: List API keys
      description: |
        This endpoint enables you to list all API keys in a project.

        Note that the API response only contains one page of results. To navigate to another page, use the `previous` or `next` path queries provided in the respone's `links` object.
      parameters:
        - in: query
          name: page_size
          schema:
            type: integer
            minimum: 1
            default: 20
            maximum: 100
          description: Number of records per page.
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number to retrieve.
        - in: query
          name: name
          schema:
            type: string
          description: Filter for API key names that contain this value. The API can return partial matches.
        - in: query
          name: value
          schema:
            type: string
          description: Filter for the value of a specific API key.
        - in: query
          name: sort_by
          schema:
            type: string
            enum:
              - created_at
              - name
              - value
          description: 'Select a property to sort by. Allowed values: `created_at`, `name`, `value`.'
        - in: query
          name: sort_order
          schema:
            type: string
            enum:
              - asc
              - desc
          description: 'Select the order to sort by. Allowed values: `asc`, `desc`.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
                  pagination:
                      $ref: '#/components/schemas/Pagination'
                  links:
                      $ref: '#/components/schemas/Links'
      security:
        - basicAuth: []
    post:
      tags:
        - API keys
      summary: Create API key
      description: This endpoint enables you to create a new API key in a specific project.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the Admin API key. Also visible in the dashboard. You may set any value that fits your organization purposes.
              required:
                - name
      responses:
        '201':
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
      security:
        - basicAuth: []
  /projects/{project_id}/api-keys/{api_key_id}:
    get:
      tags:
        - API keys
      summary: Get API key
      description: This endpoint enables you to retrieve a specific API key from a project.
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
          description: The ID of the project that the API key belongs to.
        - in: path
          name: api_key_id
          required: true
          schema:
            type: string
          description: The ID of the API key to retrieve.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
      security:
        - basicAuth: []
    patch:
      tags:
        - API keys
      summary: Update API key
      description: This endpoint enables you to update the `name` of a project that is tied to an API key.
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
          description: The ID of the project that the API key belongs to.
        - in: path
          name: api_key_id
          required: true
          schema:
            type: string
          description: The ID of the API key to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the project you want to update.
                  example: My project 2
      responses:
        '200':
          description: API key updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
      security:
        - basicAuth: []
    delete:
      tags:
        - API keys
      summary: Delete API key
      description: |
        This endpoint enables you to delete an API key from a specific project.
        
        Note that deleting an API key is permanent - there is no way to retrieve an API key after you delete it.
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            type: string
          description: The ID of the project that the API key belongs to.
        - in: path
          name: api_key_id
          required: true
          schema:
            type: string
          description: The ID of the API key you want to delete.
      responses:
        '204':
          description: API key deleted successfully
      security:
        - basicAuth: []
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
  schemas:
    Project:
      type: object
      properties:
        project_id:
          type: string
          description: The unique ID of a project.
          example: project_1CCq9NurjJBRehCVCe8XQY
        created_at:
          type: string
          format: date-time
          description: 'The date when the project was created. This field uses the ATOM date-time format: `2024-02-05T00:00:00+01:00`'
        name:
          type: string
          description: The name of the project. Also visible in the dashboard. You may set any value that fits your organization purposes.
          example: My project
        deletes_at:
          type: string
          format: date-time
          nullable: true
          description: 'The scheduled date for deletion. The value is generally the first day of the next month. This field uses the ATOM date-time format: `2024-02-05T00:00:00+01:00`'
        region:
          type: string
          description: The region where your data is hosted.
          enum:
            - us-east-1
            - eu-central-1
        deleted:
          type: boolean
          description: When true, the project is currently being deleted. The project will disappear from your projects' list after deletion finishes. You should not use projects that return `true` for `deleted`.
    ApiKey:
      type: object
      properties:
        project_id:
          type: string
          description: The unique ID of the project that the API key belongs to.
          example: project_1CCq9NurjJBRehCVCe8XQY
        api_key_id:
          type: string
          description: The unique ID of an API key.
          example: api_key_1CCq9NwWhBxwjAgHzpuZx4
        created_at:
          type: string
          format: date-time
          description: 'The date when the API key was created. This field uses the ATOM date-time format: `2024-02-05T00:00:00+01:00`'
        name:
          type: string
          description: The name of the API key. Also visible in the dashboard. You may set any value that fits your organization purposes.
          example: Development key
        value:
          type: string
          description: The actual value of the API key. Use this value to authenticate your requests to the API.
          example: 19Kc5nhC7...ADWwAbTuUer
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Returns the number of the currently active page.
        page_size:
          type: integer
          description: Returns the number of items per page.
        item_count:
          type: integer
          description: Returns the total number of items.
    Links:
      type: array
      items:
        type: object
        properties:
          rel:
            type: string
            description: |
              The relationship between the current page and the linked pages. Allowed values:
              - `previous`: The link in `href` points to the previous page when the current page is more than 1.
              - `self`: The link in `href` points to the current page.
              - `next`: The link in `href` points to the next page when there are more pages available. You can use this link to retrieve the next page of items or create an infinite scroll.
            enum:
              - previous
              - self
              - next
          href:
            type: string
            format: uri
            description: The URL path of the linked page.
            example: /projects?page_size=20&name=aaa&sort_by=name&sort_order=desc&page=2
    DeliveryUsageResponse:
      type: object
      properties:
        collected_on:
          description: A date within the interval you selected, returned in `YYYY-MM-DD` format.
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
        live_stream_hls_duration_minutes:
          description: Returns the total value of HLS live stream delivery in minutes. This field only returns delivery data for the date in the `collected_on` field.
          type: integer
          example: 51
        video_hls_duration_minutes:
          description: Returns the total value of HLS video delivery in minutes. This field only returns delivery data for the date in the `collected_on` field.
          type: integer
          example: 100
        video_mp4_duration_minutes:
          description: Returns the total value of mp4 video delivery in minutes. This field only returns delivery data for the date in the `collected_on` field.
          type: integer
          example: 33
    HostingUsageResponse:
      type: object
      properties:
        collected_on:
          description: A date within the interval you selected, returned in `YYYY-MM-DD` format.
          type: string
          pattern: '^\d{4}-\d{2}-\d{2}$'
        video_duration_minutes:
          description: Returns the cumulative length of hosted videos in minutes. This field only returns hosting data for the date in the `collected_on` field.
          type: integer
          example: 345
    BadRequest:
      type: object
      properties:
        type:
          description: A link to the error documentation.
          type: string
        title:
          description: A description of the error that occurred.
          type: string
        name:
          description: The name of the parameter that caused the error.
          type: string
        detail:
          description: Details about the error that happened.
          type: string
        total_problems:
          description: The number of problems in your request.
          type: integer
        constraint:
          description: The limitation that your request did not meet.
          type: string
      example:
        constraint: required
        detail: An attribute is invalid.
        name: interval
        title: Bad request.
        total_problems: 1
        type: 'https://docs.api.video/reference/invalid-attribute'