> ## 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. # Create dataset > Creates a dataset, optionally with its first items. A dataset is the list of prompts (and expected answers) that POST /v1/experiments runs an agent over. Send `agentId` to record which agent it was written for; send `items` to fill it in the same call — the same shape POST /v1/datasets/{id}/items takes. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/datasets 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: post: tags: - Datasets summary: Create dataset description: >- Creates a dataset, optionally with its first items. A dataset is the list of prompts (and expected answers) that POST /v1/experiments runs an agent over. Send `agentId` to record which agent it was written for; send `items` to fill it in the same call — the same shape POST /v1/datasets/{id}/items takes. parameters: [] requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string example: Refund questions description: type: string example: Twelve refund questions with the policy answer for each agentId: type: string example: 6f1c0f4e-2b7a-4a51-9a2f-0c9d1b3e5a10 description: >- The agent this dataset is written for (agent id or agent version id). Informational. tags: type: array items: type: string example: - support - refunds metadata: type: object additionalProperties: true example: source: zendesk-export items: type: array description: Initial items, at most 500. 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. responses: '201': description: The created dataset and its items content: application/json: schema: type: object properties: dataset: type: object properties: id: type: string name: type: string description: type: string nullable: true agentId: type: string nullable: true description: >- The agent this dataset was written for, when one was set. Informational — an experiment names its agent explicitly. tags: type: array items: type: string metadata: type: object additionalProperties: true version: type: integer description: >- Bumped on every item change. Pin it on POST /v1/experiments to rerun exactly this content. itemCount: type: integer description: >- Items at the current version. Present on reads of one dataset. createdAt: type: string format: date-time updatedAt: type: string format: date-time 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 example: dataset: id: ds_orders_v3 name: Refund questions description: Twelve refund questions with the policy answer for each agentId: 6f1c0f4e-2b7a-4a51-9a2f-0c9d1b3e5a10 tags: - support - refunds metadata: {} version: 1 itemCount: 1 createdAt: '2026-08-04T10:22:05.117Z' updatedAt: '2026-08-04T10:31:48.006Z' items: - id: dsi_2c7e91b4 datasetId: ds_orders_v3 version: 1 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' '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: The agent does not exist 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. ````