openapi: 3.1.0
info:
  title: Amplified attentionAI API
  description: ''
  version: 1.0.0
servers:
  - url: https://synthetic-audience.plan.amplified.co/
tags:
  - name: creatives
    description: Everything about your creatives
  - name: accounts
    description: Account details
paths:
  /accounts/service_usages:
    get:
      tags:
        - accounts
      summary: Fetch service usage details.
      description: Fetch service usage details.
      operationId: getAccountServiceUsages
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceUsages'
        '404':
          description: No available services
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /creatives:
    post:
      tags:
        - creatives
      summary: Add a new creative.
      description: Add a new creative.
      operationId: addCreative
      requestBody:
        description: Create a new creative
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreativeRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreativeRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Creative'
        '400':
          description: Invalid input
        '422':
          description: Validation exception
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      tags:
        - creatives
      summary: Get all creatives
      description: >-
        Returns all registered creative assets and their metadata for easy
        tracking and management.
      operationId: getAllCreatives
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Creative'
        '400':
          description: Invalid ID supplied
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /creatives/{creativeId}:
    get:
      tags:
        - creatives
      summary: Find creative by ID.
      description: Retrieves metadata for a specific creative using its creativeId.
      operationId: getCreativeById
      parameters:
        - name: creativeId
          in: path
          description: ID of creative to return
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Creative'
        '400':
          description: Invalid ID supplied
        '404':
          description: Creative not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      tags:
        - creatives
      summary: Delete a creative
      description: >-
        Removes a specific creative(including its file & results), identified by
        creativeId.
      operationId: deleteCreative
      parameters:
        - name: creativeId
          in: path
          description: Creative id to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '400':
          description: Invalid creative ID value
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /creatives/{creativeId}/file:
    delete:
      tags:
        - creatives
      summary: Delete a creative file
      description: >-
        Removes the file associated with a specific creative, identified by
        creativeId.
      operationId: deleteCreativeFile
      parameters:
        - name: creativeId
          in: path
          description: Creative id to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
        '400':
          description: Invalid creative ID value
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /creatives/upload:
    post:
      tags:
        - creatives
      summary: Create a creative by uploading a file
      description: >-
        Creates a new creative by uploading a video file directly (mp4 or mov,
        ≤5MB) with optional targeting details for prediction jobs.
      operationId: uploadFile
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreativeUploadRequest'
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /creatives/{creativeId}/synthetic_audience:
    get:
      tags:
        - creatives
      summary: Get synthetic audience data by creativeId.
      description: Returns synthetic audience data.
      operationId: getSyntheticAudienceDataByCreativeId
      parameters:
        - name: creativeId
          in: path
          description: ID of creative to return
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyntheticAudience'
        '400':
          description: Invalid ID supplied
        '404':
          description: Creative not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /creatives/{creativeId}/webhook:
    get:
      tags:
        - creatives
      summary: Find Webhook notifications by creative ID.
      description: Returns a list of notifications.
      operationId: getNotificationsByCreativeId
      parameters:
        - name: creativeId
          in: path
          description: ID of creative to return
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookNotifications'
        '400':
          description: Invalid ID supplied
        '404':
          description: creative_id not found
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    WebhookNotifications:
      type: array
      items:
        $ref: '#/components/schemas/WebhookNotification'
    ServiceUsages:
      type: array
      items:
        type: object
        properties:
          serviceId:
            type: string
            examples:
              - 550e8400-e29b-41d4-a716-446655445555
              - 550e8400-e29b-41d4-a716-446655446666
          serviceName:
            type: string
            examples:
              - synthetic_audience
          period:
            type: object
            properties:
              start:
                type: string
                examples:
                  - '2026-03-01T00:00:00Z'
              end:
                type: string
                examples:
                  - '2026-03-31T23:59:59Z'
              granularity:
                type: string
                examples:
                  - monthly
          usage:
            type: object
            properties:
              used:
                type: integer
                examples:
                  - 300
              limit:
                type: integer
                examples:
                  - 400
                  - 800
                  - 1600
              remaining:
                type: integer
                examples:
                  - -100
              overage:
                type: integer
                examples:
                  - 0
              unit:
                type: string
                examples:
                  - files
              resetAt:
                type: string
                examples:
                  - '2026-04-01T00:00:00Z'
    WebhookNotification:
      type: object
      properties:
        creativeId:
          type: string
          examples:
            - 550e8400-e29b-41d4-a716-446655445555
            - 550e8400-e29b-41d4-a716-446655446666
        webhookUrl:
          type: string
          examples:
            - https://app.amplified.co/webhook
        event:
          type: string
          examples:
            - creative_status_update
        status:
          type: string
          examples:
            - prediction_result_ready
        message:
          type: string
          examples:
            - creative is downloaded
        timestamp:
          type: string
          examples:
            - 0
    SyntheticAudience:
      type: object
      properties:
        creative:
          $ref: '#/components/schemas/Creative'
        resultDownloadLink:
          type: string
          format: uri
          examples:
            - https://attention-ai.amplified.co/download/abc.csv
        syntheticData:
          type: array
          items:
            type: object
            properties:
              targeting:
                type: object
                properties:
                  channel:
                    type: string
                    examples:
                      - facebook
                      - youtube
                  format:
                    type: string
                    examples:
                      - story
                      - in-feed
                  skippable:
                    type: boolean
                  formatName:
                    type: string
                    examples:
                      - pre-roll non-skippable
                      - story
                  deviceType:
                    type: string
                    enum:
                      - tv
                      - mobile
                  ageGroup:
                    type: string
                    examples:
                      - 18-24
                  gender:
                    type: string
                    examples:
                      - male
                      - female
              metrics:
                type: object
                properties:
                  creativeAttentionScore:
                    type: number
                    examples:
                      - 53.18
                  benchmarkCreativeAttentionScore:
                    type: number
                    examples:
                      - 45.67
                  avgActiveSec:
                    type: number
                    examples:
                      - 4.7272727272727275
                  avgPassiveSec:
                    type: number
                    examples:
                      - 0.20454545454545456
                  avgInactiveSec:
                    type: number
                    examples:
                      - 55.06818181818182
                  activePercentageAdLength:
                    type: number
                    examples:
                      - 0.0787878787878788
                  hookIndex:
                    type: number
                    examples:
                      - 53.18
                  holdIndex:
                    type: number
                    examples:
                      - 53.18
                  creativeBenchmarkIndex:
                    type: number
                    examples:
                      - 53.18
                  audienceSecondThreeProportion:
                    type: number
                    examples:
                      - 53.18
                  brandedMomentReachProportion:
                    type: number
                    examples:
                      - 53.18
                  endRetentionProportion:
                    type: number
                    examples:
                      - 53.18
                  audienceAdvantage:
                    type: number
                    examples:
                      - 53.18
                  activePassiveShare:
                    type: number
                    examples:
                      - 53.18
              timeSeries:
                type: object
                properties:
                  attentionDecay:
                    type: object
                    properties:
                      active:
                        type: array
                        items:
                          type: number
                          examples:
                            - 90.9090909090909
                            - 63.63636363636363
                            - 47.72727272727273
                      passive:
                        type: array
                        items:
                          type: number
                          examples:
                            - 4.545454545454546
                            - 6.8181818181818175
                            - 2.272727272727273
                      inactive:
                        type: array
                        items:
                          type: number
                          examples:
                            - 4.545454545454546
                            - 29.545454545454547
                            - 50
                  attentionDecayBenchmark:
                    type: object
                    properties:
                      active:
                        type: array
                        items:
                          type: number
                          examples:
                            - 89
                            - 44
                            - 32
                      passive:
                        type: array
                        items:
                          type: number
                          examples:
                            - 6
                            - 3
                            - 2
                      inactive:
                        type: array
                        items:
                          type: number
                          examples:
                            - 5
                            - 53
                            - 66
    Creative:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier assigned to the creative asset.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
        fileName:
          type: string
          description: >-
            The name of the uploaded or registered creative file, typically
            including its file extension (e.g., .mp4).
          examples:
            - test.mp4
        fileSource:
          type: string
          description: >-
            The source of the creative file, indicating how it was provided —
            either as an external downloadable link, a direct upload, or stored
            in Amplified’s internal bucket.
          enum:
            - external_downloadable_link
            - direct_upload
            - amplified_bucket
        downloadableUrl:
          type: string
          description: >-
            A public URL where the creative file can be accessed and downloaded
            if applicable.
          examples:
            - test.mp4
        fileSize:
          type: integer
          description: The size of the creative file in bytes.
          format: int64
          examples:
            - 10
        adLength:
          type: number
          format: double
          examples:
            - 6
            - 15
            - 20
            - 30
        aspectRatio:
          type: string
          examples:
            - 969
            - 61
        webhookUrl:
          type: string
          description: >-
            A URL provided by the user to receive asynchronous notifications
            about the creative processing status and results.
          examples:
            - https://app.amplified.co/webhook
        status:
          type: string
          description: Creative status
          enum:
            - uploaded
            - pending
            - downloading
            - downloaded
            - failed_to_download
            - file_deleted
            - file_invalid
            - processing
            - processed
        createdAt:
          type: string
          description: >-
            The timestamp indicating when the creative asset was first created
            in the system.
        updatedAt:
          type: string
          description: >-
            The timestamp indicating the last time the creative asset’s record
            was updated.
    CreativeRequest:
      required:
        - downloadableUrl
        - webhookUrl
      type: object
      properties:
        downloadableUrl:
          type: string
          description: >-
            A public URL where the creative file can be accessed and downloaded
            if applicable.
          examples:
            - test.mp4
        webhookUrl:
          type: string
          description: >-
            A URL provided by the user to receive asynchronous notifications
            about the creative processing status and results.
          examples:
            - https://app.amplified.co/webhook
    CreativeUploadRequest:
      required:
        - webhookUrl
      type: object
      properties:
        webhookUrl:
          type: string
          description: >-
            A URL provided by the user to receive asynchronous notifications
            about the creative processing status and results.
          examples:
            - https://app.amplified.co/webhook
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
        type:
          type: string
        message:
          type: string
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
