AI Demos Content API

openapi: 3.2.0
info:
  title: Aidemos Com Content API
  version: 0.1.0
  description: 'Operations tagged content across 2 of this provider''s published API definitions: aidemos-com-openapi.json, mcp-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Content
paths:
  /v1/content/shape:
    post:
      tags:
      - Content
      summary: Submit Shape
      description: Shape one platform asset (post text + chosen artifact + claims) from the source.
      operationId: submit_shape_v1_content_shape_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShapeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/content/bundle:
    get:
      tags:
      - Content
      summary: Get Bundle
      description: 'Read the exact sip substrate used by both post and video generation.


        This preview lets editors inspect/select real evidence before spending an LLM call. Joins are by

        stored ids/exact filenames only; no lexical matching invents relationships.'
      operationId: get_bundle_v1_content_bundle_get
      parameters:
      - name: kind
        in: query
        required: true
        schema:
          enum:
          - tool
          - ranking
          type: string
          title: Kind
      - name: ref
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          title: Ref
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Bundle V1 Content Bundle Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/content/compose:
    post:
      tags:
      - Content
      summary: Submit Compose
      description: Choose ONE composite-image composition from the artifact pool (Payload renders it).
      operationId: submit_compose_v1_content_compose_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComposeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/content/infographic:
    post:
      tags:
      - Content
      summary: Submit Infographic
      description: Transcribe the per-criterion score matrix for the deterministic infographic renderer.
      operationId: submit_infographic_v1_content_infographic_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InfographicRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/content/insights:
    post:
      tags:
      - Content
      summary: Submit Insights
      description: Comprehend a source ONCE into the reusable insight library.
      operationId: submit_insights_v1_content_insights_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsightsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/content/video-script:
    post:
      tags:
      - Content
      summary: Submit Video Script
      description: 'Generate an evidence-aware, scene-by-scene SHORT or LONG video script for a topic (a tool or a

        ranking/research task). The grounded bundle is assembled server-side from sip — the console only

        passes the topic reference, mode, and target duration.'
      operationId: submit_video_script_v1_content_video_script_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoScriptRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/content/artifact-bundle/{job_run_id}/status:
    get:
      tags:
      - Content
      summary: Artifact Bundle Status
      description: 'Can this asset''s bundle actually be downloaded, and how big is it?


        The console calls this BEFORE offering the download. A plain `` cannot surface a

        server error — a 409 renders as the browser''s "Site wasn''t available" dead end — so the button

        must not promise files the store cannot serve. This reuses `prepare_artifact_archive`, so the UI,

        the ZIP route, and generation all decide "attachable" with the same preflight and cannot drift.'
      operationId: artifact_bundle_status_v1_content_artifact_bundle__job_run_id__status_get
      parameters:
      - name: job_run_id
        in: path
        required: true
        schema:
          type: string
          title: Job Run Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Artifact Bundle Status V1 Content Artifact Bundle  Job Run Id  Status Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/content/artifact-bundle/{job_run_id}.zip:
    get:
      tags:
      - Content
      summary: Download Artifact Bundle
      description: 'Stream one portable ZIP containing every real media file attached to a generated asset.


        The ZIP reads only our configured S3/CDN objects and includes a machine-readable manifest. It

        deliberately excludes the topic''s unused evidence inventory, so "all" means all files actually

        attached to this post/script rather than hundreds of unrelated source files.'
      operationId: download_artifact_bundle_v1_content_artifact_bundle__job_run_id__zip_get
      parameters:
      - name: job_run_id
        in: path
        required: true
        schema:
          type: string
          title: Job Run Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/content/feedback:
    post:
      tags:
      - Content
      summary: Post Feedback
      description: 'Record explicit human feedback (thumbs + reason + optional edit) on a generated asset. This +

        the persisted result.qa scores are the eval signal that tunes the platform specs.'
      operationId: post_feedback_v1_content_feedback_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FeedbackIn'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Post Feedback V1 Content Feedback Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Content
      summary: Get Feedback
      description: All feedback recorded for one generation job, newest first.
      operationId: get_feedback_v1_content_feedback_get
      parameters:
      - name: job_run_id
        in: query
        required: true
        schema:
          type: string
          title: Job Run Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
                title: Response Get Feedback V1 Content Feedback Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    TopicIn:
      properties:
        kind:
          type: string
          enum:
          - tool
          - ranking
          title: Kind
          description: '''tool'' (ref=tool slug) or ''ranking'' (ref=research_task id)'
        ref:
          type: string
          title: Ref
          description: Tool slug (kind=tool) or research_task id (kind=ranking)
      type: object
      required:
      - kind
      - ref
      title: TopicIn
    ArtifactIn:
      properties:
        filename:
          type: string
          title: Filename
        artifactType:
          anyOf:
          - type: string
          - type: 'null'
          title: Artifacttype
        alt:
          anyOf:
          - type: string
          - type: 'null'
          title: Alt
        caption:
          anyOf:
          - type: string
          - type: 'null'
          title: Caption
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
      type: object
      required:
      - filename
      title: ArtifactIn
    ComposeRequest:
      properties:
        source:
          $ref: '#/components/schemas/SourceIn'
        candidates:
          items:
            $ref: '#/components/schemas/ArtifactIn'
          type: array
          title: Candidates
          description: Payload-filtered composable artifacts (≥2 expected)
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
        insights:
          anyOf:
          - type: string
          - type: 'null'
          title: Insights
      type: object
      required:
      - source
      title: ComposeRequest
    FeedbackIn:
      properties:
        job_run_id:
          type: string
          title: Job Run Id
          description: The ai_job_runs.request_id that produced the asset.
        rating:
          type: string
          enum:
          - up
          - down
          title: Rating
        asset_key:
          type: string
          title: Asset Key
          description: Which asset within the job (platform / scene id / '' = whole).
          default: ''
        reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Reason
        edited_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Edited Text
          description: The human-corrected copy, if any.
        submitted_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Submitted By
      type: object
      required:
      - job_run_id
      - rating
      title: FeedbackIn
    ShapeRequest:
      properties:
        platform:
          type: string
          enum:
          - twitter
          - youtube-community
          - youtube-script
          - linkedin
          title: Platform
          default: twitter
        source:
          anyOf:
          - $ref: '#/components/schemas/SourceIn'
          - type: 'null'
          description: Legacy/raw source. Prefer topic for sip-grounded generation.
        topic:
          anyOf:
          - $ref: '#/components/schemas/TopicIn'
          - type: 'null'
          description: Durable sip source identity for tool/ranking generation.
        artifacts:
          items:
            $ref: '#/components/schemas/ArtifactIn'
          type: array
          title: Artifacts
          description: Choosable artifact pool
        artifact_filenames:
          items:
            type: string
          type: array
          title: Artifact Filenames
          description: Exact filenames selected from the topic bundle. Empty means the full pool.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
        insights:
          anyOf:
          - type: string
          - type: 'null'
          title: Insights
          description: Pre-comprehended insight-library context block
      type: object
      title: ShapeRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    InsightsRequest:
      properties:
        source:
          $ref: '#/components/schemas/SourceIn'
        artifacts:
          items:
            $ref: '#/components/schemas/ArtifactIn'
          type: array
          title: Artifacts
      type: object
      required:
      - source
      title: InsightsRequest
    SubmitResponse:
      properties:
        job_run_id:
          type: string
          title: Job Run Id
        status:
          type: string
          title: Status
          default: queued
      type: object
      required:
      - job_run_id
      title: SubmitResponse
    SourceIn:
      properties:
        title:
          type: string
          title: Title
        page_url:
          type: string
          title: Page Url
          description: Canonical public URL of the source page
          default: ''
        markdown:
          type: string
          title: Markdown
          description: Clean markdown of the full source
      type: object
      required:
      - title
      - markdown
      title: SourceIn
    InfographicRequest:
      properties:
        source:
          $ref: '#/components/schemas/SourceIn'
      type: object
      required:
      - source
      title: InfographicRequest
    VideoScriptRequest:
      properties:
        topic:
          $ref: '#/components/schemas/TopicIn'
        mode:
          type: string
          enum:
          - short
          - long
          title: Mode
          default: short
        target_duration_sec:
          anyOf:
          - type: integer
            maximum: 1800.0
            minimum: 10.0
          - type: 'null'
          title: Target Duration Sec
          description: Requested length in seconds. Duration is independent of frame format; defaults to 28 for 9:16 and 120 for 16:9.
        page_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Page Url
          description: Deprecated caller hint. The canonical public CTA is resolved server-side and is emitted only when the matching sip page is published.
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
        hook_style:
          anyOf:
          - type: string
            enum:
            - auto
            - result_number
            - paradox
            - myth_break
            - head_to_head
            - call_out
            - stakes_first
            - curiosity_artifact
          - type: 'null'
          title: Hook Style
          description: Researched hook pattern the chosen cold-open must use; auto/absent = writer's pick.
        angle:
          anyOf:
          - type: string
            enum:
            - auto
            - winner-with-caveat
            - surprising-loser
            - head-to-head-on-one-criterion
            - the-gap-nobody-passed
            - what-to-use-when
            - one-input-two-results
            - the-receipt
          - type: 'null'
          title: Angle
          description: Narrative angle for the script's spine; auto/absent = writer's pick.
      type: object
      required:
      - topic
      title: VideoScriptRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
x-refined-from:
- aidemos-com-openapi.json
- mcp-openapi.json