> ## Documentation Index
> Fetch the complete documentation index at: https://sidenet.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Add dataset items

> Appends up to 500 items. Each item is one prompt the agent will answer (`input`), with an optional expected answer (`groundTruth`) for the scorers that compare against one, optional per-item `requestContext` (a thread to pin the item to, prompt variables for that row) and free-form `metadata`. Adding bumps the dataset version.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/datasets/{id}/items
openapi: 3.1.0
info:
  title: Sidenet API
  version: 1.0.0
  description: >-
    Sidenet HTTP endpoints exposed by the Sidenet Studio. All routes require an
    api key that can be generated through the studio in studio.sidenet.ai.
servers:
  - url: https://api.sidenet.ai
security:
  - bearerAuth: []
paths:
  /v1/datasets/{id}/items:
    post:
      tags:
        - Datasets
      summary: Add dataset items
      description: >-
        Appends up to 500 items. Each item is one prompt the agent will answer
        (`input`), with an optional expected answer (`groundTruth`) for the
        scorers that compare against one, optional per-item `requestContext` (a
        thread to pin the item to, prompt variables for that row) and free-form
        `metadata`. Adding bumps the dataset version.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: ds_orders_v3
          description: Dataset id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  items:
                    type: object
                    required:
                      - input
                    properties:
                      input:
                        description: >-
                          The prompt the agent is given for this item. A string
                          is one user message; an array of `{ role, content }`
                          messages sets up a multi-turn prompt whose last
                          message is the turn the agent answers.
                        oneOf:
                          - type: string
                          - type: array
                            items:
                              type: object
                              properties:
                                role:
                                  type: string
                                  enum:
                                    - user
                                    - assistant
                                    - system
                                content:
                                  type: string
                        example: Can I get a refund on an order I placed yesterday?
                      groundTruth:
                        description: >-
                          The expected answer, for scorers that compare against
                          one (answer similarity, faithfulness, …). A string is
                          the usual shape; an object is accepted for structured
                          outputs.
                        oneOf:
                          - type: string
                          - type: object
                            additionalProperties: true
                        example: >-
                          Yes — orders can be refunded within 14 days. Ask for
                          the order number.
                      requestContext:
                        type: object
                        description: >-
                          Per-item run settings. `threadId` pins the item to a
                          conversation thread (several items sharing one thread
                          form one conversation; run those with maxConcurrency
                          1). `variables` fills the {{placeholders}} in the
                          agent's prompt blocks for this item, merged over the
                          run-level `variables` leaf by leaf. No other keys are
                          accepted.
                        properties:
                          threadId:
                            type: string
                            example: conversation-42
                          variables:
                            type: object
                            additionalProperties: true
                            example:
                              account.tier: enterprise
                      metadata:
                        type: object
                        additionalProperties: true
                        description: >-
                          Free-form labels for the item (a category, a source
                          ticket, …). Passed to scorers as additional context.
                        example:
                          category: refunds
                  example:
                    - input: Can I get a refund on an order I placed yesterday?
                      groundTruth: >-
                        Yes — orders can be refunded within 14 days. Ask for the
                        order number.
                      metadata:
                        category: refunds
                    - input:
                        - role: user
                          content: I placed an order yesterday
                        - role: assistant
                          content: Got it — what would you like to do with it?
                        - role: user
                          content: Cancel it and refund me
                      groundTruth: >-
                        Confirms the cancellation window and asks for the order
                        number.
      responses:
        '201':
          description: The added items and the new dataset version
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        datasetId:
                          type: string
                        version:
                          type: integer
                          description: >-
                            Dataset version this revision of the item belongs
                            to.
                        input:
                          description: As sent.
                        groundTruth:
                          nullable: true
                        requestContext:
                          type: object
                          nullable: true
                        metadata:
                          type: object
                          nullable: true
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                  version:
                    type: integer
                    description: The dataset version these items first appear in.
              example:
                items:
                  - id: dsi_2c7e91b4
                    datasetId: ds_orders_v3
                    version: 2
                    input: Can I get a refund on an order I placed yesterday?
                    groundTruth: >-
                      Yes — orders can be refunded within 14 days. Ask for the
                      order number.
                    requestContext: null
                    metadata:
                      category: refunds
                    createdAt: '2026-08-04T10:31:48.006Z'
                    updatedAt: '2026-08-04T10:31:48.006Z'
                version: 2
        '400':
          description: Invalid body, or an item failed validation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The class of failure.
                  details:
                    type: string
                    description: What specifically went wrong.
        '404':
          description: No such dataset in this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The class of failure.
                  details:
                    type: string
                    description: What specifically went wrong.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Organization API key, generated in studio.sidenet.ai. Backend only —
        never in a browser.

````