Rapidata SampleGeneration API

openapi: 3.0.4
info:
  title: Rapidata Asset SampleGeneration API
  description: The API for the Rapidata Asset service
  version: v1
servers:
- url: https://api.rapidata.ai/
tags:
- name: SampleGeneration
  x-displayName: SampleGeneration
paths:
  /benchmark/{benchmarkId}/sample-generation:
    post:
      tags:
      - SampleGeneration
      summary: Starts an asynchronous sample generation run.
      parameters:
      - name: benchmarkId
        in: path
        description: The benchmark whose participants should run their faucets.
        required: true
        schema:
          type: string
      requestBody:
        description: The generation configuration.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSampleGenerationEndpoint_Input'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSampleGenerationEndpoint_Output'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden
      security:
      - OpenIdConnect:
        - openid
        - profile
        - email
        - offline_access
  /benchmark/sample-generation/{sampleGenerationId}:
    get:
      tags:
      - SampleGeneration
      summary: Returns the current status and progress of a sample generation request.
      parameters:
      - name: sampleGenerationId
        in: path
        description: The id of the sample generation request.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSampleGenerationEndpoint_Output'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden
      security:
      - OpenIdConnect:
        - openid
        - profile
        - email
        - offline_access
  /benchmark/sample-generation/{sampleGenerationId}/items:
    get:
      tags:
      - SampleGeneration
      summary: Returns the per-item audit trail for a sample generation request.
      parameters:
      - name: sampleGenerationId
        in: path
        description: The id of the sample generation request.
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: The 1-based page index.
        schema:
          type: integer
        x-parameter-group: page
      - name: page_size
        in: query
        description: The number of items per page.
        schema:
          type: integer
        x-parameter-group: page
      - name: sort
        in: query
        description: Sort fields. Prefix with - for descending order (e.g. -created_at).
        schema:
          type: array
          items:
            enum:
            - created_at
            - -created_at
            - prompt_identifier
            - -prompt_identifier
            type: string
        x-parameter-group: sort
      - name: status
        in: query
        description: Filter by status.
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            eq:
              type: string
            neq:
              type: string
            gt:
              type: string
            gte:
              type: string
            lt:
              type: string
            lte:
              type: string
            contains:
              type: string
            starts_with:
              type: string
            ends_with:
              type: string
            in:
              type: array
              items:
                type: string
            not_contains:
              type: string
        x-parameter-group: filters
      - name: participant_id
        in: query
        description: Filter by participant_id.
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            eq:
              type: string
            neq:
              type: string
            gt:
              type: string
            gte:
              type: string
            lt:
              type: string
            lte:
              type: string
            contains:
              type: string
            starts_with:
              type: string
            ends_with:
              type: string
            in:
              type: array
              items:
                type: string
            not_contains:
              type: string
        x-parameter-group: filters
      - name: prompt_identifier
        in: query
        description: Filter by prompt_identifier.
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            eq:
              type: string
            neq:
              type: string
            gt:
              type: string
            gte:
              type: string
            lt:
              type: string
            lte:
              type: string
            contains:
              type: string
            starts_with:
              type: string
            ends_with:
              type: string
            in:
              type: array
              items:
                type: string
            not_contains:
              type: string
        x-parameter-group: filters
      - name: created_at
        in: query
        description: Filter by created_at.
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            eq:
              type: string
            neq:
              type: string
            gt:
              type: string
            gte:
              type: string
            lt:
              type: string
            lte:
              type: string
            contains:
              type: string
            starts_with:
              type: string
            ends_with:
              type: string
            in:
              type: array
              items:
                type: string
            not_contains:
              type: string
        x-parameter-group: filters
      - name: logic
        in: query
        description: 'How to combine the field filters: "and" (default) requires every filter to match, "or" requires any of them to match.'
        schema:
          enum:
          - and
          - or
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSampleGenerationItemsEndpoint_PagedResultOfOutput'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden
      security:
      - OpenIdConnect:
        - openid
        - profile
        - email
        - offline_access
  /benchmark/{benchmarkId}/sample-generations:
    get:
      tags:
      - SampleGeneration
      summary: Lists historical sample generation runs for the given benchmark.
      description: Results are sorted by creation time (newest first) by default.
      parameters:
      - name: benchmarkId
        in: path
        description: The id of the benchmark whose sample generations should be listed.
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: The 1-based page index.
        schema:
          type: integer
        x-parameter-group: page
      - name: page_size
        in: query
        description: The number of items per page.
        schema:
          type: integer
        x-parameter-group: page
      - name: sort
        in: query
        description: Sort fields. Prefix with - for descending order (e.g. -created_at).
        schema:
          type: array
          items:
            enum:
            - created_at
            - -created_at
            type: string
        x-parameter-group: sort
      - name: status
        in: query
        description: Filter by status.
        style: deepObject
        explode: true
        schema:
          type: object
          properties:
            eq:
              type: string
            neq:
              type: string
            gt:
              type: string
            gte:
              type: string
            lt:
              type: string
            lte:
              type: string
            contains:
              type: string
            starts_with:
              type: string
            ends_with:
              type: string
            in:
              type: array
              items:
                type: string
            not_contains:
              type: string
        x-parameter-group: filters
      - name: logic
        in: query
        description: 'How to combine the field filters: "and" (default) requires every filter to match, "or" requires any of them to match.'
        schema:
          enum:
          - and
          - or
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuerySampleGenerationsByBenchmarkEndpoint_PagedResultOfOutput'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden
      security:
      - OpenIdConnect:
        - openid
        - profile
        - email
        - offline_access
  /benchmark/sample-generation/{sampleGenerationId}/retry:
    post:
      tags:
      - SampleGeneration
      summary: Re-queues failed items of a sample generation so they run again.
      description: "When no item ids are supplied, every failed item of the generation is retried. Item ids that\n do not belong to the generation or are not in a failed state are ignored. Returns the ids\n that were re-queued; a generation with no failed items yields an empty result."
      parameters:
      - name: sampleGenerationId
        in: path
        description: The id of the sample generation request.
        required: true
        schema:
          type: string
      requestBody:
        description: Optional payload restricting the retry to specific item ids.
        content:
          application/json:
            schema:
              type: object
              oneOf:
              - $ref: '#/components/schemas/RetrySampleGenerationEndpoint_Input'
              nullable: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrySampleGenerationEndpoint_Output'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '401':
          description: Unauthenticated
        '403':
          description: Forbidden
      security:
      - OpenIdConnect:
        - openid
        - profile
        - email
        - offline_access
components:
  schemas:
    GetSampleGenerationItemsEndpoint_Output:
      required:
      - id
      - sampleGenerationId
      - participantId
      - benchmarkPromptId
      - promptIdentifier
      - sampleCount
      - status
      - attemptCount
      - sampleIds
      - createdAt
      type: object
      properties:
        id:
          type: string
          description: The id of the generation item.
        sampleGenerationId:
          type: string
          description: The id of the parent sample generation.
        participantId:
          type: string
          description: The participant whose faucet is producing this sample.
        benchmarkPromptId:
          type: string
          description: The benchmark prompt this item targets.
        promptIdentifier:
          type: string
          description: The identifier of the prompt being generated.
        sampleCount:
          type: integer
          description: How many samples this item produces for its (participant, prompt) pair.
          format: int32
        status:
          allOf:
          - $ref: '#/components/schemas/SampleGenerationItemStatus'
          description: The current status of this item.
        attemptCount:
          type: integer
          description: Number of delivery attempts that have been made on this item.
          format: int32
        providerRequestId:
          type: string
          description: Provider-side request id used to correlate with the provider's logs.
          nullable: true
        failureReason:
          type: string
          description: Failure reason if the item is in a failed state.
          nullable: true
        sampleIds:
          allOf:
          - type: array
            items:
              type: string
          description: The ids of the samples created from this item once it succeeds.
        createdAt:
          type: string
          description: When the item was created.
          format: date-time
    GetSampleGenerationItemsEndpoint_PagedResultOfOutput:
      required:
      - total
      - page
      - pageSize
      - items
      type: object
      properties:
        total:
          type: integer
          format: int64
        page:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/GetSampleGenerationItemsEndpoint_Output'
        totalPages:
          type: integer
          format: int32
    RetrySampleGenerationEndpoint_Input:
      type: object
      properties:
        itemIds:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: "The specific item ids to retry. When omitted or empty, every failed item of the\n generation is retried."
    QuerySampleGenerationsByBenchmarkEndpoint_PagedResultOfOutput:
      required:
      - total
      - page
      - pageSize
      - items
      type: object
      properties:
        total:
          type: integer
          format: int64
        page:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/QuerySampleGenerationsByBenchmarkEndpoint_Output'
        totalPages:
          type: integer
          format: int32
    ValidationProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    CreateSampleGenerationEndpoint_Input:
      required:
      - samplesPerPrompt
      type: object
      properties:
        samplesPerPrompt:
          type: integer
          description: How many samples to request per matching prompt (1 to 16).
          format: int32
        participantIds:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: "Restrict generation to specific participants. Defaults to all participants\n in the benchmark that have a configured faucet."
        promptIdentifiers:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: "Restrict generation to specific prompt identifiers.\n Defaults to every prompt in the benchmark."
        tags:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: Restrict generation to prompts having at least one of these tags.
    QuerySampleGenerationsByBenchmarkEndpoint_Output:
      required:
      - id
      - benchmarkId
      - status
      - samplesPerPrompt
      - totalCount
      - completedCount
      - failedCount
      - ownerId
      - ownerMail
      - createdAt
      type: object
      properties:
        id:
          type: string
          description: The id of the sample generation request.
        benchmarkId:
          type: string
          description: The benchmark this generation belongs to.
        status:
          allOf:
          - $ref: '#/components/schemas/SampleGenerationStatus'
          description: The current status of the generation.
        samplesPerPrompt:
          type: integer
          description: How many samples are being generated per prompt.
          format: int32
        totalCount:
          type: integer
          description: The total number of items queued.
          format: int32
        completedCount:
          type: integer
          description: The number of items that have succeeded so far.
          format: int32
        failedCount:
          type: integer
          description: The number of items that have failed.
          format: int32
        participantIdFilter:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: Optional participant id filter that was applied when this generation was created.
        promptIdentifierFilter:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: Optional prompt identifier filter that was applied.
        tagsFilter:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: Optional tag filter that was applied.
        ownerId:
          type: string
          description: The id of the customer that started this generation.
          format: uuid
        ownerMail:
          type: string
          description: The mail of the customer that started this generation.
        createdAt:
          type: string
          description: When the generation was created.
          format: date-time
    GetSampleGenerationEndpoint_Output:
      required:
      - id
      - benchmarkId
      - status
      - samplesPerPrompt
      - totalCount
      - completedCount
      - failedCount
      - ownerId
      - ownerMail
      - createdAt
      type: object
      properties:
        id:
          type: string
          description: The id of the sample generation request.
        benchmarkId:
          type: string
          description: The benchmark this generation belongs to.
        status:
          allOf:
          - $ref: '#/components/schemas/SampleGenerationStatus'
          description: The current status of the generation.
        samplesPerPrompt:
          type: integer
          description: How many samples are being generated per prompt.
          format: int32
        totalCount:
          type: integer
          description: The total number of items queued.
          format: int32
        completedCount:
          type: integer
          description: The number of items that have succeeded so far.
          format: int32
        failedCount:
          type: integer
          description: The number of items that have failed.
          format: int32
        participantIdFilter:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: Optional participant id filter that was applied when this generation was created.
        promptIdentifierFilter:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: Optional prompt identifier filter that was applied.
        tagsFilter:
          allOf:
          - type: array
            items:
              type: string
            nullable: true
          description: Optional tag filter that was applied.
        ownerId:
          type: string
          description: The id of the customer that started this generation.
          format: uuid
        ownerMail:
          type: string
          description: The mail of the customer that started this generation.
        createdAt:
          type: string
          description: When the generation was created.
          format: date-time
    CreateSampleGenerationEndpoint_Output:
      required:
      - id
      - totalCount
      - skippedParticipantIds
      type: object
      properties:
        id:
          type: string
          description: The id of the created sample generation request.
        totalCount:
          type: integer
          description: The total number of generation items that were queued.
          format: int32
        skippedParticipantIds:
          allOf:
          - type: array
            items:
              type: string
          description: "Participants that matched the selection but were skipped because they have no faucet\n configured. Empty when explicit participant ids were supplied."
    SampleGenerationStatus:
      enum:
      - Pending
      - Processing
      - Completed
      - CompletedWithFailures
      - Failed
      - Cancelled
    SampleGenerationItemStatus:
      enum:
      - Pending
      - Running
      - Succeeded
      - Failed
    RetrySampleGenerationEndpoint_Output:
      required:
      - retriedCount
      - retriedItemIds
      type: object
      properties:
        retriedCount:
          type: integer
          description: How many failed items were re-queued.
          format: int32
        retriedItemIds:
          allOf:
          - type: array
            items:
              type: string
          description: The ids of the items that were re-queued.
  securitySchemes:
    OpenIdConnect:
      type: openIdConnect
      description: OpenID Connect connection flow
      openIdConnectUrl: https://auth.rapidata.ai/.well-known/openid-configuration
x-tagGroups:
- name: Rapidata Asset API
  tags:
  - Asset
  - BatchUpload
- name: Rapidata Audience API
  tags:
  - Audience
  - Examples
- name: Rapidata Campaign API
  tags:
  - Cache
  - Campaign
  - ExternalAudience
- name: Rapidata Dataset API
  tags:
  - ContextShortening
  - Datapoints
  - Dataset
  - DatasetGroup
- name: Rapidata Flow API
  tags:
  - Flow
  - FlowItem
  - RankingFlow
  - RankingFlowItem
- name: Rapidata Identity API
  tags:
  - Rapidata.Identity.API
  - Client
  - Customer
  - Identity
  - Newsletter
  - Organization
  - Survey
- name: Rapidata Leaderboard API
  tags:
  - Benchmark
  - SampleGeneration
  - Faucet
  - Replicate
  - Leaderboard
  - Participant
  - Prompt
  - Sample
- name: Rapidata Order API
  tags:
  - Feedback
  - Job
  - Order
- name: Rapidata Payment API
  tags:
  - Billing
  - ExternalServicePrices
  - Reconciliation
  - Settings
  - VolumeDiscount
  - BillingAccount
  - Invoice
  - Payment
- name: Rapidata Pipeline API
  tags:
  - Pipeline
- name: Rapidata Rapid API
  tags:
  - CustomerRapid
  - GlobalText
  - Rapid
  - UserRapid
  - ValidationFeedback
- name: Rapidata Signal API
  tags:
  - Signal
- name: Rapidata Translation API
  tags:
  - Translation
- name: Rapidata Validation API
  tags:
  - ValidationSet
- name: Rapidata Workflow API
  tags:
  - Evaluation
  - GroupedRanking
  - Ranking
  - SimpleWorkflow
  - Workflow