---
title: "Insert new Documents"
method: POST
path: "/api/v1/data/{provider}/{dataset}/"
tags: ["data"]
---

# Insert new Documents

`POST /api/v1/data/{provider}/{dataset}/`

## Request

- Base URL: `https://data.corva.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://data.corva.ai/api/v1/data/{provider}/{dataset}/`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

Insert 1–1000 documents. Supplied IDs are ignored unless the `X-Corva-App` header names an app in the client-ID allowlist. For those apps, regular collections preserve an optional `_id`, which must be a 24-character hexadecimal MongoDB ObjectId string; missing or null IDs are generated. Invalid IDs reject the whole request with HTTP 400 before insertion. Native time-series collections continue to ignore supplied IDs. Inserts never replace existing documents. Bulk write failures, including duplicate IDs, retain the HTTP 200 response with `inserted_ids`, `failed_count`, and `messages`.

## Path parameters

- `provider` string, required
- `dataset` string, required

## Request body

- union
  - DataCreate[]
    - `company_id` integer, nullable
    - `provider` string, nullable
    - `collection` string, nullable
    - `asset_id` integer, nullable: Asset ID. Required for time and depth based data.
    - `version` integer, required: Version of the data document
    - `app_version` integer, nullable: Version of the app that generated the data
    - `data` object
    - `timestamp` integer, nullable: Timestamp (epoch time). Required for time based data, optional for rest.
    - `log_identifier` string, nullable: Identifier to scope the data by app stream. Required for depth based data, optional for rest.
    - `measured_depth` number, nullable: Measured depth. Required for depth based data, optional for rest.
    - `metadata` TimeSeriesMetadata
      - `company_id` integer, nullable
      - `asset_id` integer, nullable
    - `stage_number` integer, nullable: Stage number for completion data
    - `datetime` string, date-time, nullable: ISO 8601 datetime string representation. Used as index inside time-series collections.
  - DataCreateWithMessageProduce: Input for data creation with message producing.
    - `data` DataCreate[], required
      - `company_id` integer, nullable
      - `provider` string, nullable
      - `collection` string, nullable
      - `asset_id` integer, nullable: Asset ID. Required for time and depth based data.
      - `version` integer, required: Version of the data document
      - `app_version` integer, nullable: Version of the app that generated the data
      - `data` object
      - `timestamp` integer, nullable: Timestamp (epoch time). Required for time based data, optional for rest.
      - `log_identifier` string, nullable: Identifier to scope the data by app stream. Required for depth based data, optional for rest.
      - `measured_depth` number, nullable: Measured depth. Required for depth based data, optional for rest.
      - `metadata` TimeSeriesMetadata
        - `company_id` integer, nullable
        - `asset_id` integer, nullable
      - `stage_number` integer, nullable: Stage number for completion data
      - `datetime` string, date-time, nullable: ISO 8601 datetime string representation. Used as index inside time-series collections.
    - `producer` MessageProduce, required
      - `app_connection_id` integer, required

## Response `200`

Successful Response

- DataCreateResult
  - `inserted_ids` string[]
  - `failed_count` integer
  - `messages` string[]

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/corva/apis/corva-data-api.md) - [All operations](https://skmtc.dev/corva/apis/corva-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/corva/apis/corva-data-api/revisions/f0426c267c36?raw)