> ## Documentation Index > Fetch the complete documentation index at: https://docs.heybee.app/llms.txt > Use this file to discover all available pages before exploring further. # Create Sample > Create a sample after uploading the file. The file must already be uploaded to the path returned by GET /upload-url. ## OpenAPI ````yaml /openapi.json post /v1/experiments/{experiment_id}/samples openapi: 3.1.0 info: description: Customer-owned evaluation lifecycle API. title: HeyBee Public API version: 1.0.0 servers: - description: Production url: https://api.heybee.app security: [] paths: /v1/experiments/{experiment_id}/samples: post: tags: - Samples summary: Create Sample description: >- Create a sample after uploading the file. The file must already be uploaded to the path returned by GET /upload-url. operationId: create_sample_v1_experiments__experiment_id__samples_post parameters: - in: path name: experiment_id required: true schema: format: uuid title: Experiment Id type: string - in: header name: authorization required: false schema: anyOf: - type: string - type: 'null' title: Authorization - in: header name: X-API-Key required: false schema: anyOf: - type: string - type: 'null' title: X-Api-Key requestBody: content: application/json: schema: $ref: '#/components/schemas/SampleCreate' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/SampleResponse' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - BearerAuth: [] - ApiKeyAuth: [] components: schemas: SampleCreate: description: Request to create a sample after upload. example: anchor_value: Hello, how are you? file_path: experiments/exp123/sample456.mp3 is_exam_only: false parameters: model: v2 temperature: 0.7 suggestion_id: 550e8400-e29b-41d4-a716-446655440000 properties: anchor: anyOf: - $ref: '#/components/schemas/AnchorRef' - type: 'null' anchor_id: anyOf: - format: uuid type: string - type: 'null' title: Anchor Id anchor_value: anyOf: - type: string - type: 'null' description: >- Value of the anchor field for this sample (required if experiment has anchor_field) title: Anchor Value candidate: anyOf: - $ref: '#/components/schemas/CandidateRef' - type: 'null' candidate_id: anyOf: - format: uuid type: string - type: 'null' title: Candidate Id candidate_key: anyOf: - maxLength: 128 minLength: 1 type: string - type: 'null' title: Candidate Key candidate_label: anyOf: - type: string - type: 'null' title: Candidate Label candidate_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Candidate Metadata content_hash: anyOf: - type: string - type: 'null' title: Content Hash file_path: description: Path to the uploaded file in storage (bucket-relative) title: File Path type: string ingestion_batch_id: anyOf: - format: uuid type: string - type: 'null' title: Ingestion Batch Id is_exam_only: default: false description: >- Whether this sample should only be used for exam/quality-control pairs title: Is Exam Only type: boolean parameters: anyOf: - additionalProperties: true type: object - type: 'null' description: Parameter values for this sample title: Parameters source_manifest_row: anyOf: - type: integer - type: 'null' title: Source Manifest Row source_sample_id: anyOf: - format: uuid type: string - type: 'null' description: >- Optional lineage reference when this sample is cloned from another sample title: Source Sample Id suggestion_id: anyOf: - format: uuid type: string - type: 'null' description: Optional generation suggestion ID used to produce this sample title: Suggestion Id required: - file_path title: SampleCreate type: object SampleResponse: description: Sample response. properties: anchor_id: anyOf: - format: uuid type: string - type: 'null' title: Anchor Id anchor_text: anyOf: - type: string - type: 'null' title: Anchor Text anchor_value: anyOf: - type: string - type: 'null' title: Anchor Value asset_id: anyOf: - format: uuid type: string - type: 'null' title: Asset Id availability_status: default: active title: Availability Status type: string candidate_id: anyOf: - format: uuid type: string - type: 'null' title: Candidate Id candidate_key: anyOf: - type: string - type: 'null' title: Candidate Key candidate_label: anyOf: - type: string - type: 'null' title: Candidate Label candidate_metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Candidate Metadata comparisons: anyOf: - type: integer - type: 'null' title: Comparisons content: anyOf: - additionalProperties: true type: object - type: 'null' title: Content content_hash: anyOf: - type: string - type: 'null' title: Content Hash content_origin: default: local_storage title: Content Origin type: string created_at: format: date-time title: Created At type: string elo_rating: anyOf: - type: number - type: 'null' title: Elo Rating experiment_id: format: uuid title: Experiment Id type: string file_path: title: File Path type: string file_url: anyOf: - type: string - type: 'null' description: Signed download URL (short-lived) title: File Url id: format: uuid title: Id type: string ingestion_batch_id: anyOf: - format: uuid type: string - type: 'null' title: Ingestion Batch Id is_exam_only: default: false title: Is Exam Only type: boolean losses: anyOf: - type: integer - type: 'null' title: Losses mean_score: anyOf: - type: number - type: 'null' title: Mean Score output_type: enum: - text - image - audio - video title: Output Type type: string parameters: anyOf: - additionalProperties: true type: object - type: 'null' title: Parameters remote: anyOf: - additionalProperties: true type: object - type: 'null' title: Remote score_count: default: 0 title: Score Count type: integer source_kind: default: local enum: - local - huggingface title: Source Kind type: string source_manifest_row: anyOf: - type: integer - type: 'null' title: Source Manifest Row source_sample_id: anyOf: - format: uuid type: string - type: 'null' title: Source Sample Id suggestion_id: anyOf: - format: uuid type: string - type: 'null' title: Suggestion Id thumbnail_url: anyOf: - type: string - type: 'null' description: Signed thumbnail URL (short-lived) title: Thumbnail Url wins: anyOf: - type: integer - type: 'null' title: Wins required: - id - experiment_id - output_type - file_path - anchor_value - parameters - created_at title: SampleResponse type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object AnchorRef: description: Inline anchor reference used by ingestion-compatible sample creation. properties: type: pattern: ^(text|image|audio|video)$ title: Type type: string value: minLength: 1 title: Value type: string required: - type - value title: AnchorRef type: object CandidateRef: description: Inline candidate metadata used by ingestion-compatible sample creation. properties: key: maxLength: 128 minLength: 1 title: Key type: string label: anyOf: - type: string - type: 'null' title: Label metadata: anyOf: - additionalProperties: true type: object - type: 'null' title: Metadata required: - key title: CandidateRef type: object ValidationError: properties: loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object securitySchemes: BearerAuth: bearerFormat: Supabase JWT scheme: bearer type: http ApiKeyAuth: in: header name: X-API-Key type: apiKey ````