HeyMarvin API

openapi: 3.1.0
info:
  title: HeyMarvin API
  version: '2026-10-28'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-10-28: 16 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; HeyMarvin has published no machine-readable contract that the
    pipeline could find. Engine: anthropic.'
  x-evidence-tiers:
    code-example: 3
    documentation: 13
    pages-with-code: 3
    pages-read: 5
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-10-28'
  x-generator: generate-contract-from-docs.py
  x-engine: anthropic
  x-sources:
  - https://docs.heymarvin.com/reference/files
  - https://docs.heymarvin.com/reference/surveys
  - https://docs.heymarvin.com/getting-started/access
  - https://docs.heymarvin.com/getting-started/rate-limits
  - https://docs.heymarvin.com/getting-started/token-lifecycle
servers:
- url: https://app.heymarvin.com
paths:
  /api/v1/developer/import/files:
    get:
      operationId: get_api_v1_developer_import_files
      tags:
      - Api
      summary: Lists files imported through this API, scoped to projects accessible to your API key, newest first.
      x-source: https://docs.heymarvin.com/reference/files
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
        description: Maximum number of results per page (default and max limit is 50)
      - name: offset
        in: query
        required: false
        schema:
          type: integer
        description: Number of results to skip for pagination
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DeveloperImportFilesResponse'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/files/initialize:
    post:
      operationId: post_api_v1_developer_import_files_initialize
      tags:
      - Api
      summary: Creates a wav record and returns a wav_key plus a presigned S3 upload URL.
      x-source: https://docs.heymarvin.com/reference/files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1DeveloperImportFilesInitializeRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DeveloperImportFilesInitializeResponse'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/files/{wavKey}/complete:
    post:
      operationId: post_api_v1_developer_import_files_wavKey_complete
      tags:
      - Api
      summary: Marvin checks that the object exists in S3, sets the file URL on the wav, and kicks off processing (transcription for audio/video,
        extraction for documents, etc.).
      x-source: https://docs.heymarvin.com/reference/files
      parameters:
      - name: wavKey
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DeveloperImportFilesWavkeyCompleteResponse'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/files/{wavKey}/status:
    get:
      operationId: get_api_v1_developer_import_files_wavKey_status
      tags:
      - Api
      summary: Returns the current processing status for the uploaded file.
      x-source: https://docs.heymarvin.com/reference/files
      parameters:
      - name: wavKey
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DeveloperImportFilesWavkeyStatusResponse'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/surveys:
    get:
      operationId: get_api_v1_developer_import_surveys
      tags:
      - Api
      summary: Lists surveys previously imported through this API that reached COMPLETED.
      x-source: https://docs.heymarvin.com/reference/surveys
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DeveloperImportSurveysResponse'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/surveys/initialize:
    post:
      operationId: post_api_v1_developer_import_surveys_initialize
      tags:
      - Api
      summary: Creates a survey upload and returns presigned S3 URLs for each CSV part.
      x-source: https://docs.heymarvin.com/reference/surveys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysInitializeRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysInitializeResponse'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/surveys/{uploadKey}/append:
    post:
      operationId: post_api_v1_developer_import_surveys_uploadKey_append
      tags:
      - Api
      summary: Add more rows to a survey previously imported through this API.
      x-source: https://docs.heymarvin.com/reference/surveys
      parameters:
      - name: uploadKey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysUploadkeyAppendRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysUploadkeyAppendResponse'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/surveys/{uploadKey}/complete:
    post:
      operationId: post_api_v1_developer_import_surveys_uploadKey_complete
      tags:
      - Api
      summary: Signals Marvin to verify uploads and start processing the survey.
      x-source: https://docs.heymarvin.com/reference/surveys
      parameters:
      - name: uploadKey
        in: path
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysUploadkeyCompleteResponse'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/surveys/{uploadKey}/media/register:
    post:
      operationId: post_api_v1_developer_import_surveys_uploadKey_media_register
      tags:
      - Api
      summary: After initialize, declare your media filenames to get a presigned S3 URL for each.
      x-source: https://docs.heymarvin.com/reference/surveys
      parameters:
      - name: uploadKey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysUploadkeyMediaRegisterRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysUploadkeyMediaRegisterRespons'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/surveys/{uploadKey}/media/{filename}/retry:
    post:
      operationId: post_api_v1_developer_import_surveys_uploadKey_media_filename_retry
      tags:
      - Api
      summary: Re-issue a presigned URL for a single media file.
      x-source: https://docs.heymarvin.com/reference/surveys
      parameters:
      - name: uploadKey
        in: path
        required: true
        schema:
          type: string
      - name: filename
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysUploadkeyMediaFilenameRetryRe'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/surveys/{uploadKey}/parts/{partNumber}/retry:
    post:
      operationId: post_api_v1_developer_import_surveys_uploadKey_parts_partNumber_retry
      tags:
      - Api
      summary: Re-issues a fresh presigned URL for a CSV part.
      x-source: https://docs.heymarvin.com/reference/surveys
      parameters:
      - name: uploadKey
        in: path
        required: true
        schema:
          type: string
      - name: partNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1DeveloperImportSurveysUploadkeyPartsPartnumberRetry'
      x-evidence:
        kind: documentation
  /api/v1/developer/import/surveys/{uploadKey}/status:
    get:
      operationId: get_api_v1_developer_import_surveys_uploadKey_status
      tags:
      - Api
      summary: Returns the current processing status for the survey upload.
      x-source: https://docs.heymarvin.com/reference/surveys
      parameters:
      - name: uploadKey
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1DeveloperImportSurveysUploadkeyStatusResponse'
      x-evidence:
        kind: documentation
  /api/v1/oauth/token:
    post:
      operationId: post_api_v1_oauth_token
      tags:
      - Api
      summary: POST /api/v1/oauth/token
      x-source: https://docs.heymarvin.com/getting-started/access
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s -X POST \"$BASE_URL/api/v1/oauth/token\"  -d \"grant_type=client_credentials\"  -d \"client_id=$CLIENT_ID\"  -d \"client_secret=$CLIENT_SECRET\"\
          \  -d \"scope=project:read file:write\"  | python3 -c \"import sys,json;print(json.load(sys.stdin)['access_token'])\")\n You'll get\
          \ back: json Copy {\n \"access_token\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"token_type\": \"bearer\",\n \"expires_in\": 3600,\n \"scope\"\
          : \"project:rea"
  /bucket:
    post:
      operationId: post_bucket
      tags:
      - Bucket
      summary: POST /bucket
      x-source: https://docs.heymarvin.com/reference/files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBucketRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBucketResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s -X POST \"$BASE_URL/api/v1/developer/import/files/initialize\"  -H \"Authorization: Bearer $TOKEN\"  -H \"Content-Type:\
          \ application/json\"  -d '{\n \"project_id\": 42,\n \"file_name\": \"customer-interview.mp4\"\n }' | python3 -m json.tool\n Parameters:\
          \ Field Type Required Description project_id integer Yes ID from the list projects response file_name string Yes Original filename including\
          \ extension (max "
  /bucket/developer-uploads/{developeruploadid}/a1b2c3d4-.../media.mp4:
    post:
      operationId: post_bucket_developer_uploads_developeruploadid_a1b2c3d4_media_mp4
      tags:
      - Bucket
      summary: POST /bucket/developer-uploads/{developerUploadId}/a1b2c3d4-.../media.mp4
      x-source: https://docs.heymarvin.com/reference/files
      parameters:
      - name: developeruploadid
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBucketDeveloperUploadsDeveloperuploadidA1B2C3D4MediaMp4R'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s -X POST \"$BASE_URL/api/v1/developer/import/files/$WAV_KEY/complete\"  -H \"Authorization: Bearer $TOKEN\" | python3\
          \ -m json.tool\n Response (200): json Copy {\n \"wav_key\": \"a1b2c3d4-...\",\n \"status\": \"processing\"\n}\n If the file is missing\
          \ from S3: json Copy {\n \"error\": \"File not found in S3. Upload the file before calling complete.\"\n}\n Idempotency: Calling complete\
          \ again when the file is already"
  /import/projects:
    get:
      operationId: get_import_projects
      tags:
      - Import
      summary: Resolves a project_id needed for file import operations.
      x-source: https://docs.heymarvin.com/reference/files
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiV1DeveloperImportFilesResponse:
      type: object
      properties:
        files:
          type: array
          description: List of file objects
        count:
          type: integer
          description: Total number of matching files
        next:
          type: string
          description: Full URL to the next page, or null when there isn't one
        previous:
          type: string
          description: Full URL to the previous page, or null when there isn't one
    PostApiV1DeveloperImportFilesInitializeRequest:
      type: object
      properties:
        project_id:
          type: integer
          description: ID from the list projects response
        file_name:
          type: string
          description: Original filename including extension (max 500 chars). Extension determines media type and content type.
      required:
      - project_id
      - file_name
    PostApiV1DeveloperImportFilesInitializeResponse:
      type: object
      properties:
        wav_key:
          type: string
          description: Unique identifier for the wav record
        upload_url:
          type: string
          description: Presigned S3 upload URL
        upload_fields:
          type: object
          description: Form fields required for S3 upload
        links:
          type: object
          description: Links to complete and status endpoints
    PostApiV1DeveloperImportFilesWavkeyCompleteResponse:
      type: object
      properties:
        wav_key:
          type: string
          description: Unique identifier for the wav record
        status:
          type: string
          description: Current processing status
    GetApiV1DeveloperImportFilesWavkeyStatusResponse:
      type: object
      properties:
        wav_key:
          type: string
          description: Unique identifier for the wav record
        name:
          type: string
          description: Original filename
        status:
          type: string
          description: Current processing status
        file_url:
          type: string
          description: S3 URL of the uploaded file
        created_at:
          type: string
          description: Timestamp when the file was created
    GetApiV1DeveloperImportSurveysResponse:
      type: object
      properties:
        surveys:
          type: array
        upload_key:
          type: string
        survey_key:
          type: string
        survey_name:
          type: string
        project_id:
          type: integer
        number_of_responses:
          type: integer
        num_parts:
          type: integer
        completed_at:
          type: string
    PostApiV1DeveloperImportSurveysInitializeRequest:
      type: object
      properties:
        project_id:
          type: integer
          description: ID from the list projects response
        name:
          type: string
          description: Survey name (max 200 chars)
        file_type:
          type: string
          description: Must be "CSV"
        num_parts:
          type: integer
          description: Number of CSV parts to upload (1–100)
        column_mapping:
          type: object
          description: Map CSV column names to types
        auto_map:
          type: boolean
          description: 'Use AI to auto-detect column types (default: false)'
        add_to_research_panel:
          type: boolean
          description: 'Add respondents to Research Panel (default: true)'
        media_config:
          type: object
          description: Enables respondent-level media linking
        idempotency_key:
          type: string
          description: Unique key to prevent duplicates (max 255 chars)
      required:
      - project_id
      - name
      - file_type
      - num_parts
    PostApiV1DeveloperImportSurveysInitializeResponse:
      type: object
      properties:
        survey_key:
          type: string
        upload_key:
          type: string
        status:
          type: string
        num_parts:
          type: integer
        upload_urls:
          type: array
        add_to_research_panel:
          type: boolean
        media_config:
          type: object
        links:
          type: object
    PostApiV1DeveloperImportSurveysUploadkeyAppendRequest:
      type: object
      properties:
        num_parts:
          type: integer
          description: Number of new CSV parts to upload (1–100)
      required:
      - num_parts
    PostApiV1DeveloperImportSurveysUploadkeyAppendResponse:
      type: object
      properties:
        survey_key:
          type: string
        upload_key:
          type: string
        status:
          type: string
        num_parts:
          type: integer
        upload_urls:
          type: array
        add_to_research_panel:
          type: boolean
        media_config:
          type: object
        links:
          type: object
    PostApiV1DeveloperImportSurveysUploadkeyCompleteResponse:
      type: object
      properties:
        upload_key:
          type: string
        status:
          type: string
        message:
          type: string
    PostApiV1DeveloperImportSurveysUploadkeyMediaRegisterRequest:
      type: object
      properties:
        files:
          type: array
          description: Media filenames to register (max 512 chars each). Must be unique within the request.
      required:
      - files
    PostApiV1DeveloperImportSurveysUploadkeyMediaRegisterRespons:
      type: object
      properties:
        media_files:
          type: array
        filename:
          type: string
        upload_url:
          type: string
        upload_fields:
          type: object
    PostApiV1DeveloperImportSurveysUploadkeyMediaFilenameRetryRe:
      type: object
      properties:
        filename:
          type: string
        upload_url:
          type: string
        upload_fields:
          type: object
    PostApiV1DeveloperImportSurveysUploadkeyPartsPartnumberRetry:
      type: object
      properties:
        part_number:
          type: integer
        upload_url:
          type: string
        upload_fields:
          type: object
        s3_key:
          type: string
    GetApiV1DeveloperImportSurveysUploadkeyStatusResponse:
      type: object
      properties:
        upload_key:
          type: string
        survey_key:
          type: string
        status:
          type: string
        file_type:
          type: string
        num_parts:
          type: integer
        parts:
          type: array
        processing:
          type: object
        error_details:
          type: object
        created_at:
          type: string
        completed_at:
          type: string
        media_files:
          type: array
    PostBucketRequest:
      type: object
      properties:
        project_id:
          type: integer
        file_name:
          type: string
    PostBucketResponse:
      type: object
      properties:
        wav_key:
          type: string
        upload_url:
          type: string
        upload_fields:
          type: object
          properties:
            key:
              type: string
            Content-Type:
              type: string
            x-amz-credential:
              type: string
            policy:
              type: string
            x-amz-signature:
              type: string
        links:
          type: object
          properties:
            complete:
              type: string
            status:
              type: string
    PostBucketDeveloperUploadsDeveloperuploadidA1B2C3D4MediaMp4R:
      type: object
      properties:
        wav_key:
          type: string
        status:
          type: string
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Bucket
- name: Import