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

# Create a record set

> Starts a chunked upload and returns the record set's id and `chunk_size`. POST the records in chunks, then seal it. A record set that is never sealed or never triggered expires automatically, along with its staged records.



## OpenAPI

````yaml /openapi.json post /record-sets
openapi: 3.1.0
info:
  title: GetDialed Flows API
  version: 0.1.0
servers:
  - url: https://api.getdialed.ai/flows
    description: Production
security: []
paths:
  /record-sets:
    post:
      tags:
        - record-sets
      summary: Create a record set
      description: >-
        Starts a chunked upload and returns the record set's id and
        `chunk_size`. POST the records in chunks, then seal it. A record set
        that is never sealed or never triggered expires automatically, along
        with its staged records.
      operationId: create_record_set_record_sets_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordSetCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordSetResponse'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              example:
                detail: Authentication required
        '403':
          description: Admin role required
          content:
            application/json:
              example:
                detail: Admin role required
        '422':
          description: Validation error (see body for field details)
          content:
            application/json:
              example:
                detail: Validation error
        '429':
          description: Rate limit exceeded — retry after the Retry-After header
          content:
            application/json:
              example:
                detail: Rate limit exceeded
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    RecordSetCreate:
      properties:
        chunk_size:
          type: integer
          title: Chunk Size
          description: >-
            Number of records in every chunk except the last. Fixed for the
            whole upload.
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Arbitrary labels stored with the record set and returned on read.
      type: object
      title: RecordSetCreate
      description: >-
        Start a chunked upload.


        Uploading records happens in three steps:


        1. Create a record set (this request). You get back an id and a
           `chunk_size`.
        2. `POST /record-sets/{record_set_id}/records` once per chunk, in any
        order,
           until every record has been sent.
        3. `POST /record-sets/{record_set_id}/seal` with the total number of
        records
           you sent. Sealing validates the count and finalises the upload's content
           hash.

        A sealed record set is then passed to a flow trigger as `record_set_id`.

        Each record set is used by exactly one trigger. Record sets that are
        never

        sealed, or never triggered, expire automatically along with their staged

        records.


        `chunk_size` is fixed for the whole upload and defaults to the largest
        chunk

        the API accepts. Every chunk except the final one must contain exactly
        this

        many records, because it is what turns a chunk index into each row's

        position in the set.
      example:
        chunk_size: 10000
        metadata:
          campaign: spring-2026
          source: crm-export.csv
    RecordSetResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        chunk_size:
          type: integer
          title: Chunk Size
        received_count:
          type: integer
          title: Received Count
        chunk_count:
          type: integer
          title: Chunk Count
        expected_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Expected Count
        content_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Hash
        batch_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Batch Id
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        sealed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Sealed At
        consumed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Consumed At
        staging_expires_at:
          type: string
          format: date-time
          title: Staging Expires At
      type: object
      required:
        - id
        - status
        - chunk_size
        - received_count
        - chunk_count
        - expected_count
        - content_hash
        - batch_id
        - metadata
        - created_at
        - updated_at
        - sealed_at
        - consumed_at
        - staging_expires_at
      title: RecordSetResponse
      description: >-
        A record set's manifest and current progress.


        `status` moves `open` -> `sealed` -> `consumed`: `open` accepts chunks,

        `sealed` is complete and ready to trigger, and `consumed` means a
        trigger

        has claimed it (each record set is used exactly once). `received_count`
        and

        `chunk_count` track what has arrived so far, `content_hash` identifies
        the

        sealed contents, `batch_id` points at the batch that consumed it, and

        `staging_expires_at` is when an untriggered record set and its staged

        records are reclaimed.
      example:
        chunk_count: 100
        chunk_size: 10000
        content_hash: 9f2c4e1b7a35d80c6e4f1a92b3c7d5e08f6a1b2c3d4e5f60718293a4b5c6d7e8
        created_at: '2026-07-27T12:00:00Z'
        expected_count: 1000000
        id: rs_0123456789abcdef
        metadata:
          campaign: spring-2026
        received_count: 1000000
        sealed_at: '2026-07-27T12:04:31Z'
        staging_expires_at: '2026-08-03T12:00:00Z'
        status: sealed
        updated_at: '2026-07-27T12:04:31Z'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````