Ask Your Audience API

openapi: 3.1.0
info:
  title: Ask Your Audience API
  version: '2026-11-02'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-02: 11 operation(s) read from 5 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Ask Your Audience has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 10
    pages-with-code: 3
    pages-read: 5
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-02'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://www.askyouraudience.ai/docs/api
  - https://www.askyouraudience.ai/docs/reference
  - https://www.askyouraudience.ai/docs
  - https://www.askyouraudience.ai/developers
  - https://www.askyouraudience.ai/docs/auth
servers:
- url: https://api.askyouraudience.ai
paths:
  /oauth/authorize:
    get:
      operationId: get_oauth_authorize
      tags:
      - Oauth
      summary: Authorize step validates the client and redirect before asking for workspace confirmation.
      x-source: https://www.askyouraudience.ai/docs/auth
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /oauth/revoke:
    post:
      operationId: post_oauth_revoke
      tags:
      - Oauth
      summary: Revocation behavior coherent across Claude and ChatGPT.
      x-source: https://www.askyouraudience.ai/docs/auth
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /oauth/token:
    post:
      operationId: post_oauth_token
      tags:
      - Oauth
      summary: Tokens are issued and refreshed against the same install record instead of creating a second account model.
      x-source: https://www.askyouraudience.ai/docs/auth
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/assets/analyze:
    post:
      operationId: post_v1_assets_analyze
      tags:
      - Assets
      summary: Submit an image for creative analysis.
      x-source: https://www.askyouraudience.ai/docs/reference
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: Deduplicate retries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AssetsAnalyzeRequest'
      responses:
        '202':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1AssetsAnalyzeResponse'
      x-evidence:
        kind: documentation
  /v1/concept-tests:
    post:
      operationId: post_v1_concept_tests
      tags:
      - Concept Tests
      summary: POST /v1/concept-tests
      x-source: https://www.askyouraudience.ai/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ConceptTestsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl Python bash curl https://api.askyouraudience.ai/v1/concept-tests \ -H "X-Api-Key: aya_test_..." \ -H "Idempotency-Key:
          ct-001" \ -H "Content-Type: application/json" \ -d ''{ "brief": "UK fintech app for first-time investors", "concept": "An investing
          app that explains every decision in plain English" }'' Transport Production contract and staging transport Production and staging both
          use the sam'
  /v1/focus-groups/sessions:
    post:
      operationId: post_v1_focus_groups_sessions
      tags:
      - Focus Groups
      summary: Start a multi-persona focus group session from a saved panel or focus group.
      x-source: https://www.askyouraudience.ai/docs/reference
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: Deduplicate retries.
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
        description: Client-generated request ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1FocusGroupsSessionsRequest'
      responses:
        '202':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1FocusGroupsSessionsResponse'
      x-evidence:
        kind: documentation
  /v1/interviews:
    post:
      operationId: post_v1_interviews
      tags:
      - Interviews
      summary: Start an automated 1:1 interview with the best-fit digital twin in a saved panel.
      x-source: https://www.askyouraudience.ai/docs/reference
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: Deduplicate retries.
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
        description: Client-generated request ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1InterviewsRequest'
      responses:
        '202':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1InterviewsResponse'
      x-evidence:
        kind: documentation
  /v1/interviews/messages:
    post:
      operationId: post_v1_interviews_messages
      tags:
      - Interviews
      summary: Send a message in a 1:1 interview with an AI persona.
      x-source: https://www.askyouraudience.ai/docs/reference
      parameters:
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
        description: Client-generated request ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1InterviewsMessagesRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1InterviewsMessagesResponse'
      x-evidence:
        kind: documentation
  /v1/panels/resolve:
    post:
      operationId: post_v1_panels_resolve
      tags:
      - Panels
      summary: Resolve an audience panel from a brief, panel ID, or explicit persona IDs.
      x-source: https://www.askyouraudience.ai/docs/reference
      parameters:
      - name: X-Request-Id
        in: header
        required: false
        schema:
          type: string
        description: Optional client-generated request ID for tracing.
      - name: X-AYA-Workspace-Id
        in: header
        required: true
        schema:
          type: string
        description: Required when your account belongs to multiple workspaces.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1PanelsResolveRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1PanelsResolveResponse'
      x-evidence:
        kind: documentation
  /v1/quick-pulse:
    post:
      operationId: post_v1_quick_pulse
      tags:
      - Quick Pulse
      summary: A lighter concept test using up to 3 personas.
      x-source: https://www.askyouraudience.ai/docs/reference
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          type: string
        description: Deduplicate retries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1QuickPulseRequest'
      responses:
        '202':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1QuickPulseResponse'
      x-evidence:
        kind: documentation
  /v1/webhooks/test:
    post:
      operationId: post_v1_webhooks_test
      tags:
      - Webhooks
      summary: Send a test event to a configured webhook endpoint to verify your integration.
      x-source: https://www.askyouraudience.ai/docs/reference
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1WebhooksTestRequest'
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1WebhooksTestResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostV1AssetsAnalyzeRequest:
      type: object
      properties:
        imageBase64:
          type: string
          description: Base64-encoded image data.
        mimeType:
          type: string
          description: e.g. image/png, image/jpeg.
        brief:
          type: string
          description: Audience brief for context.
        platform:
          type: string
          description: Target platform (instagram, facebook, etc).
        concept:
          type: string
          description: Concept description for the asset.
      required:
      - imageBase64
      - mimeType
    PostV1AssetsAnalyzeResponse:
      type: object
      properties:
        job_id:
          type: string
        status:
          type: string
    PostV1ConceptTestsRequest:
      type: object
      properties:
        brief:
          type: string
        concept:
          type: string
    PostV1FocusGroupsSessionsRequest:
      type: object
      properties:
        groupId:
          type: string
          description: Saved focus group or panel id.
        panelId:
          type: string
          description: Alias for groupId when callers already use panel language.
        brief:
          type: string
          description: Research brief and discussion context.
        objective:
          type: string
          description: What the session should resolve.
        questions:
          type: string
          description: Optional supplied discussion questions.
        packageType:
          type: string
          description: Session package label. Defaults to Custom Objective.
      required:
      - brief
    PostV1FocusGroupsSessionsResponse:
      type: object
      properties:
        job_id:
          type: string
        status:
          type: string
        session_id:
          type: string
        result_url:
          type: string
    PostV1InterviewsRequest:
      type: object
      properties:
        panelId:
          type: string
          description: Saved panel used to select the best-fit interview participant.
        brief:
          type: string
          description: Research brief and interview context.
        topic:
          type: string
          description: Short interview topic.
        objective:
          type: string
          description: What the interview should learn.
        maxQuestions:
          type: integer
          description: Maximum generated or supplied questions.
        engine:
          type: string
          description: '"vertex" | "gemini" Preferred execution engine.'
      required:
      - panelId
      - brief
    PostV1InterviewsResponse:
      type: object
      properties:
        job_id:
          type: string
        status:
          type: string
        participant:
          type: object
        result_url:
          type: string
    PostV1InterviewsMessagesRequest:
      type: object
      properties:
        personaId:
          type: string
          description: The persona to interview.
        interviewId:
          type: string
          description: Continue an existing interview session.
        mode:
          type: string
          description: '"reply" | "suggest" | "summarize" Response mode. Defaults to reply.'
        history:
          type: string
          description: Prior conversation messages.
      required:
      - personaId
    PostV1InterviewsMessagesResponse:
      type: object
      properties:
        response:
          type: string
    PostV1PanelsResolveRequest:
      type: object
      properties:
        panelId:
          type: string
          description: Reference a saved panel by ID.
        brief:
          type: string
          description: Natural-language audience brief — AYA selects matching personas.
        selectedPersonas:
          type: string
          description: Explicit persona IDs to use.
        limit:
          type: integer
          description: Max personas to return.
        strict:
          type: boolean
          description: If true, only return exact matches.
        includePersonas:
          type: boolean
          description: Include full persona objects in response.
    PostV1PanelsResolveResponse:
      type: object
      properties:
        persona_ids:
          type: string
        personas:
          type: object
        panel:
          type: object
    PostV1QuickPulseRequest:
      type: object
      properties:
        concept:
          type: string
          description: The concept to quick-test.
        brief:
          type: string
          description: Audience brief.
      required:
      - concept
    PostV1QuickPulseResponse:
      type: object
      properties:
        job_id:
          type: string
        status:
          type: string
    PostV1WebhooksTestRequest:
      type: object
      properties:
        webhookId:
          type: string
          description: The webhook to test.
        event:
          type: string
          description: Event type to simulate.
      required:
      - webhookId
      - event
    PostV1WebhooksTestResponse:
      type: object
      properties:
        webhook_id:
          type: string
        delivery_id:
          type: string
        event:
          type: string
        response_code:
          type: integer
        delivered:
          type: boolean
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
security:
- apiKey: []
tags:
- name: Assets
- name: Concept Tests
- name: Focus Groups
- name: Interviews
- name: Oauth
- name: Panels
- name: Quick Pulse
- name: Webhooks