AnimationKit.git · openapi.yaml

revision a42aba5f7ece0e28aa61bea598909a7d7bbf84ac · complete file
openapi: 3.0.3
info:
  title: AnimationKit API
  version: 0.1.0
  description: |
    AnimationKit service for managing, evaluating, and orchestrating declarative animation timelines.
    The specification reflects the current Swift client implementation while preserving the historical
    timeline management surface that inspired the service. Authentication defaults to bearer tokens.
servers:
  - url: https://api.animationkit.local
    description: Primary production endpoint
  - url: http://localhost:8080
    description: Local development server
security:
  - bearerAuth: []
paths:
  /health:
    get:
      summary: Health check
      operationId: getHealth
      security: []
      responses:
        '200':
          description: Service health status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
  /animations:
    get:
      summary: List animations
      operationId: listAnimations
      description: Retrieve a paginated list of stored animations.
      parameters:
        - in: query
          name: pageToken
          schema:
            type: string
          description: Token for retrieving the next page of results.
        - in: query
          name: pageSize
          schema:
            type: integer
            minimum: 1
            maximum: 200
          description: Maximum number of items to return.
      responses:
        '200':
          description: Animation page
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimationListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      summary: Submit an animation
      operationId: submitAnimation
      description: Create a new animation resource from a declarative clip.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Animation'
      responses:
        '201':
          description: Animation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAnimationResponse'
        '400':
          description: Invalid animation payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /animations/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Identifier of the animation resource.
    get:
      summary: Fetch an animation
      operationId: getAnimation
      responses:
        '200':
          description: Animation resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimationResource'
        '404':
          description: Animation not found
        default:
          $ref: '#/components/responses/ErrorResponse'
    put:
      summary: Update an animation
      operationId: updateAnimation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAnimationRequest'
      responses:
        '200':
          description: Updated animation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimationResource'
        '201':
          description: Created new animation record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnimationResource'
        '400':
          description: Invalid update payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Animation not found
        default:
          $ref: '#/components/responses/ErrorResponse'
  /evaluate:
    post:
      summary: Evaluate a timeline at a given instant
      operationId: evaluateTimeline
      description: Evaluate the provided timeline at absolute time `t` (seconds).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EvaluateTimelineRequest'
      responses:
        '200':
          description: Evaluation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluateTimelineResponse'
        '400':
          description: Invalid evaluation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /evaluate/bulk:
    post:
      summary: Evaluate a timeline at multiple samples
      operationId: evaluateTimelineBulk
      description: Compute a timeline's values at multiple sample points in one request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkEvaluationRequest'
      responses:
        '200':
          description: Bulk evaluation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkEvaluationResponse'
        '400':
          description: Invalid evaluation request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /timelines:
    get:
      summary: List timelines
      operationId: listTimelines
      description: Retrieve summaries of stored MIDI timeline resources.
      responses:
        '200':
          description: Timeline summaries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimelineListResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
    post:
      summary: Create a timeline
      operationId: createTimeline
      description: Create a new MIDI timeline by providing its events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Timeline'
      responses:
        '201':
          description: Timeline created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
        '400':
          description: Invalid timeline payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /timelines/{id}:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: Timeline identifier.
    get:
      summary: Get a timeline
      operationId: getTimeline
      responses:
        '200':
          description: Timeline data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
        '404':
          description: Timeline not found
        default:
          $ref: '#/components/responses/ErrorResponse'
    put:
      summary: Replace a timeline
      operationId: updateTimeline
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Timeline'
      responses:
        '200':
          description: Updated timeline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
        '201':
          description: Created new timeline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
        '400':
          description: Invalid timeline payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Timeline not found
        default:
          $ref: '#/components/responses/ErrorResponse'
    delete:
      summary: Delete a timeline
      operationId: deleteTimeline
      responses:
        '204':
          description: Timeline deleted
        '404':
          description: Timeline not found
        default:
          $ref: '#/components/responses/ErrorResponse'
  /timelines/{id}/play:
    post:
      summary: Trigger playback of a timeline
      operationId: playTimeline
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Timeline identifier.
      responses:
        '202':
          description: Playback accepted
        '404':
          description: Timeline not found
        default:
          $ref: '#/components/responses/ErrorResponse'
  /timelines/importOTIO:
    post:
      summary: Import an OTIO timeline
      operationId: importTimelineOTIO
      description: Create a timeline from an OpenTimelineIO document.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OTIO'
      responses:
        '201':
          description: Timeline imported successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeline'
        '400':
          description: OTIO payload could not be processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          $ref: '#/components/responses/ErrorResponse'
  /timelines/{id}/otio:
    get:
      summary: Export a timeline to OTIO
      operationId: exportTimelineOTIO
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Timeline identifier.
      responses:
        '200':
          description: OTIO representation of the timeline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OTIO'
        '404':
          description: Timeline not found
        default:
          $ref: '#/components/responses/ErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  responses:
    ErrorResponse:
      description: Generic error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    HealthStatus:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: Human-readable service status indicator.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Application specific error identifier.
        message:
          type: string
          description: Human-readable description of the error.
        details:
          type: object
          additionalProperties: true
          description: Optional structured details for debugging.
    CreateAnimationResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Identifier of the created animation.
    AnimationListResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AnimationSummary'
        nextPageToken:
          type: string
          nullable: true
          description: Cursor for retrieving the next page of results.
    AnimationSummary:
      type: object
      required:
        - id
        - duration
      properties:
        id:
          type: string
        name:
          type: string
          nullable: true
        duration:
          type: number
          format: double
        updatedAt:
          type: string
          format: date-time
          nullable: true
    AnimationResource:
      type: object
      required:
        - id
        - animation
      properties:
        id:
          type: string
        animation:
          $ref: '#/components/schemas/Animation'
        name:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
    UpdateAnimationRequest:
      type: object
      required:
        - animation
      properties:
        animation:
          $ref: '#/components/schemas/Animation'
        name:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
    EvaluateTimelineRequest:
      type: object
      required:
        - timeline
        - t
      properties:
        timeline:
          $ref: '#/components/schemas/Timeline'
        t:
          type: number
          format: double
          description: Absolute time (seconds) at which to evaluate the timeline.
    EvaluateTimelineResponse:
      type: object
      required:
        - value
      properties:
        value:
          type: number
          format: double
          description: Scalar value of the evaluated timeline at time `t`.
    BulkEvaluationRequest:
      type: object
      required:
        - timeline
        - samples
      properties:
        timeline:
          $ref: '#/components/schemas/Timeline'
        samples:
          type: array
          items:
            type: number
            format: double
            description: Absolute times (seconds) at which to evaluate the timeline.
    BulkEvaluationResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/EvaluationSample'
    EvaluationSample:
      type: object
      required:
        - t
        - value
      properties:
        t:
          type: number
          format: double
        value:
          type: number
          format: double
    Animation:
      type: object
      required:
        - duration
      properties:
        duration:
          type: number
          format: double
          description: Total length of the clip in seconds.
        opacity:
          $ref: '#/components/schemas/Timeline'
        position:
          $ref: '#/components/schemas/Position'
        scale:
          $ref: '#/components/schemas/Timeline'
        rotation:
          $ref: '#/components/schemas/Timeline'
        color:
          $ref: '#/components/schemas/Color'
    Position:
      type: object
      required:
        - x
        - y
      properties:
        x:
          $ref: '#/components/schemas/Timeline'
        y:
          $ref: '#/components/schemas/Timeline'
    Color:
      type: object
      properties:
        r:
          $ref: '#/components/schemas/Timeline'
        g:
          $ref: '#/components/schemas/Timeline'
        b:
          $ref: '#/components/schemas/Timeline'
        a:
          $ref: '#/components/schemas/Timeline'
    Timeline:
      type: object
      required:
        - keyframes
      properties:
        keyframes:
          type: array
          items:
            $ref: '#/components/schemas/Keyframe'
    Keyframe:
      type: object
      required:
        - time
        - value
        - easing
      properties:
        time:
          type: number
          format: double
        value:
          type: number
          format: double
        easing:
          $ref: '#/components/schemas/Easing'
    Easing:
      type: string
      enum:
        - linear
        - easeIn
        - easeOut
        - easeInOut
    TimelineListResponse:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TimelineSummary'
    TimelineSummary:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        name:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        duration:
          type: number
          format: double
          nullable: true
    OTIO:
      type: object
      description: Generic OpenTimelineIO JSON structure represented as an object tree.
      additionalProperties: true