AINSOF API

openapi: 3.1.0
info:
  title: AINSOF API
  version: '2026-11-01'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-01: 10 operation(s) read from 9 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; AINSOF has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 2
    documentation: 8
    pages-with-code: 9
    pages-read: 9
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-01'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://ainsof.io/docs/api-reference
  - https://ainsof.io/docs/search-by-reference
  - https://ainsof.io/docs/get-started
  - https://ainsof.io/docs/search-music
  - https://ainsof.io/docs/browse-tag
  - https://ainsof.io/docs/browse-playlist
  - https://ainsof.io/docs/find-similar
  - https://ainsof.io/docs/listen-link
  - https://ainsof.io/docs/analyze-video
servers:
- url: https://mcp.ainsof.io
paths:
  /:
    post:
      operationId: post
      tags:
      - Api
      summary: POST /
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
      x-evidence:
        kind: code-example
        language: python
        snippet: "requests.post(\n \"https://mcp.ainsof.io/\",\n headers={\"Authorization\": \"Bearer ain_000000000000000000000000\"},\n json={\n\
          \ \"action\": \"search\",\n \"brief\": \"piano\"\n },\n timeout=60,\n)"
    put:
      operationId: put
      tags:
      - Api
      summary: PUT /
      x-source: https://ainsof.io/docs/api-reference
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PutResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl Python JavaScript Copy › curl https://mcp.ainsof.io/  -H \"Content-Type: application/json\"  -H \"Authorization: Bearer\
          \ $AINSOF_API_KEY\"  -d '{\"action\": \"search\", \"brief\": \"dark cinematic trailer tension, pulsing synths\", \"top_k\": 2}' import\
          \ os, requests\nr = requests.post(\n \"https://mcp.ainsof.io/\",\n headers={\"Authorization\": f\"Bearer {os.environ['AINSOF_API_KEY']}\"\
          },\n json={\n \"action\": \"search\""
  /Create:
    post:
      operationId: post_Create
      tags:
      - Create
      summary: Upload a video
      description: A one‑time upload slot for a video that is on the user's computer.
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCreateRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCreateResponse'
      x-evidence:
        kind: documentation
  /Cut:
    post:
      operationId: post_Cut
      tags:
      - Cut
      summary: Editing
      description: Cut a cue to length, to a video's exact length, or into a loop, optionally with every stem cut the same way.
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCutRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCutResponse'
      x-evidence:
        kind: documentation
  /Find:
    post:
      operationId: post_Find
      tags:
      - Find
      summary: Music Search
      description: Search cues from a written brief, or look one up by its title, album, album code, track id, ISRC or composer.
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostFindRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostFindResponse'
      x-evidence:
        kind: documentation
  /Measure:
    post:
      operationId: post_Measure
      tags:
      - Measure
      summary: Analyze a video
      description: 'A video for scoring: length, frame rate, resolution, cuts, edit pace, storyboard frames and an optional transcript.'
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMeasureRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMeasureResponse'
      x-evidence:
        kind: documentation
  /Mix:
    post:
      operationId: post_Mix
      tags:
      - Mix
      summary: Score a video
      description: AINSOF music onto a video and return the rendered MP4.
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMixRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostMixResponse'
      x-evidence:
        kind: documentation
  /Open:
    post:
      operationId: post_Open
      tags:
      - Open
      summary: Browse a genre, mood, instrument or use
      description: An explicit AINSOF category selection and walk through its ordered pages.
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostOpenRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostOpenResponse'
      x-evidence:
        kind: documentation
  /Return:
    post:
      operationId: post_Return
      tags:
      - Return
      summary: Get a cue
      description: 'Return one cue in full: credits, description, every version and every stem, each with its own preview link.'
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostReturnRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostReturnResponse'
      x-evidence:
        kind: documentation
  /Send:
    post:
      operationId: post_Send
      tags:
      - Send
      summary: Feedback
      description: AINSOF a user's verdict on an answer, only with that user's consent.
      x-source: https://ainsof.io/docs/api-reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSendRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSendResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostRequest:
      type: object
      properties:
        action:
          type: string
        brief:
          type: string
    PostResponse:
      type: object
      properties:
        ok:
          type: boolean
        error:
          type: string
        message:
          type: string
    PutResponse:
      type: object
      properties:
        ok:
          type: boolean
        catalogue_note:
          type: string
        how_to_present:
          type: string
        results:
          type: array
          items:
            type: object
            properties:
              track_id:
                type: string
              title:
                type: string
              album_cover_url:
                type: string
              album_cover_thumb_url:
                type: string
              album:
                type: string
              catalogue:
                type: string
              composers:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    society:
                      type: string
                    ipi:
                      type: string
                    performance_share:
                      type: string
              publisher:
                type: string
              style:
                type: string
              also:
                type: array
                items:
                  type: string
              feels:
                type: array
                items:
                  type: string
              length:
                type: string
              bpm:
                type: integer
              description:
                type: string
              listen_url:
                type: string
              also_available:
                type: string
        licensing:
          type: string
    PostCreateRequest:
      type: object
      properties:
        action:
          type: string
          description: get_upload_link
        filename:
          type: string
          description: The file's name.
      required:
      - action
    PostCreateResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
        upload_page:
          type: string
          description: Page with a file picker.
        how_to_upload:
          type: string
          description: Instructions for AI assistants.
        upload_url:
          type: string
          description: Single‑use upload address for PUT.
        upload_command:
          type: string
          description: cURL command for the PUT.
        video_url:
          type: string
          description: The address to score once the upload has finished.
        next:
          type: string
          description: Next step after upload.
        valid_for_hours:
          type: integer
          description: '2'
        note:
          type: string
          description: What happens to the uploaded file.
    PostCutRequest:
      type: object
      properties:
        action:
          type: string
          description: fit
        track_id:
          type: string
          description: Cue id or title.
        seconds:
          type: number
          description: Target length.
        kind:
          type: string
          description: length, video or loop.
        hit_at:
          type: number
          description: Second at which the cue's climax should land.
        stems:
          type: boolean
          description: Also cut every stem at the same points.
        version:
          type: string
          description: Version to cut from.
      required:
      - action
      - track_id
      - seconds
    PostCutResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
        track:
          type: object
          description: Track details of the edit.
        asked:
          type: object
          description: Echo of the request parameters.
        got_seconds:
          type: number
          description: Length of the edit.
        edit_review:
          type: object
          description: Method, review_required and a note.
        how:
          type: string
          description: One‑line description of the edit.
        hit_lands_at:
          type: number
          description: Where the climax landed.
        stems:
          type: array
          description: The stems cut, when requested.
        listen_url:
          type: string
          description: Link to the edit MP3.
        download_url:
          type: string
          description: Link to the zip package.
        kept_for_days:
          type: integer
          description: '7'
        how_to_present:
          type: string
          description: Presentation guidance.
        licensing:
          type: object
          description: The licensing object.
    PostFindRequest:
      type: object
      properties:
        action:
          type: string
          description: search
        brief:
          type: string
          description: What the music should be, or the exact name of a cue, album, album code, track id, ISRC or composer.
        top_k:
          type: integer
          description: Number of results.
        count:
          type: integer
          description: Also accepted as count.
      required:
      - action
      - brief
    PostFindResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
        results:
          type: array
          description: Matching cues, best first.
        found_by_name:
          type: string
          description: States that the answer is the named cue, the whole album, or the composer's cues.
        enforced:
          type: array
          description: Negatives that were enforced.
        constraint_note:
          type: string
          description: Says how many matches were removed by the enforced negatives.
        composer_note:
          type: string
          description: How the named composer's cues were placed.
        catalogue_note:
          type: string
          description: States that every result is an original AINSOF composition.
        how_to_present:
          type: string
          description: Presentation guidance.
        licensing:
          type: object
          description: The licensing object.
    PostMeasureRequest:
      type: object
      properties:
        action:
          type: string
          description: analyze_video
        video_url:
          type: string
          description: The video file URL.
        sign_in_code:
          type: string
          description: Code returned after sign‑in required.
        user_request:
          type: string
          description: One‑sentence user request.
        project_type:
          type: string
          description: Project type.
        music_intent:
          type: string
          description: Music intent, up to 8 words.
      required:
      - action
      - video_url
    PostMeasureResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
        film:
          type: object
          description: Narrative description of the video.
        video:
          type: object
          description: Measured properties, scenes, cuts, transcript, etc.
        licensing:
          type: object
          description: The licensing object.
    PostMixRequest:
      type: object
      properties:
        action:
          type: string
          description: score_video
        video_url:
          type: string
          description: The video file URL.
        sign_in_code:
          type: string
          description: Code returned after sign‑in required.
        brief:
          type: string
          description: The music wanted, in English.
        track_id:
          type: string
          description: Exact cue to use.
        sections:
          type: array
          description: Timed acts, each with from, to, and either brief, track_id or stems.
        silences:
          type: array
          description: Music‑free moments with at and for.
        music_offset_db:
          type: number
          description: Music level relative to video audio, in dB.
        user_request:
          type: string
          description: One‑sentence user request, up to 500 characters.
        project_type:
          type: string
          description: Project type, e.g. ad, social, documentary, etc.
        music_intent:
          type: string
          description: Music intent, up to 8 words.
      required:
      - action
      - video_url
    PostMixResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
        video_url:
          type: string
          description: Watch page for the render.
        delivery_request:
          type: object
          description: Tool call arguments for delivering the score.
        download_url:
          type: string
          description: Download page for the MP4.
        format:
          type: string
          description: mp4
        used:
          type: object
          description: Track details used in the render.
        mix:
          type: object
          description: Music level info.
        video:
          type: object
          description: Video analysis details.
        licensing:
          type: object
          description: The licensing object.
    PostOpenRequest:
      type: object
      properties:
        action:
          type: string
          description: browse_tag
        tag:
          type: string
          description: Exact category/tag text.
        facet:
          type: string
          description: 'The field selected by the user: genre, mood, instrument or use.'
        scope:
          type: string
          description: Choose music or sound effects explicitly.
        page_size:
          type: integer
          description: Primary recordings per page.
        cursor:
          type: string
          description: Opaque continuation cursor.
      required:
      - action
      - tag
      - facet
      - scope
    PostOpenResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
        results:
          type: array
          description: Tracks in the selected website order.
        has_more:
          type: boolean
          description: Whether another page is available.
        cursor:
          type: string
          description: Continuation cursor when has_more is true.
        browse:
          type: object
          description: The exact normalized selection and saved page_size.
        catalogue_note:
          type: string
          description: As in search.
        how_to_present:
          type: string
          description: As in search.
        licensing:
          type: object
          description: The licensing object.
    PostReturnRequest:
      type: object
      properties:
        action:
          type: string
          description: track
        track_id:
          type: string
          description: Cue id or title.
      required:
      - action
      - track_id
    PostReturnResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
        credits:
          type: object
          description: Credits object plus album cover URLs, or null.
        track:
          type: object
          description: Track details, versions, stems, etc.
        licensing:
          type: object
          description: The licensing object.
    PostSendRequest:
      type: object
      properties:
        action:
          type: string
          description: feedback
        about:
          type: string
          description: The action or tool the feedback is about.
        verdict:
          type: string
          description: good, bad, or partly.
        consented:
          type: boolean
          description: True only if the user agreed.
        in_their_words:
          type: string
          description: User's own words.
        expected:
          type: string
          description: What they wanted instead.
        track_id:
          type: string
          description: The cue concerned.
        brief:
          type: string
          description: The brief concerned.
      required:
      - action
      - about
      - verdict
      - consented
    PostSendResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
        thanks:
          type: string
          description: Acknowledgement.
        tell_the_user:
          type: string
          description: Guidance for AI assistants.
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Create
- name: Cut
- name: Find
- name: Measure
- name: Mix
- name: Open
- name: Return
- name: Send