# Data Intake

> Store immutable source, selection, field, deduplication, purpose, and retention contracts without executing intake.

Canonical guide: <https://api.blackpearl.com/docs/data-intake>

Raw Markdown: <https://api.blackpearl.com/docs/raw/data-intake.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

Data Intake Specifications are Preview planning records. They freeze an allow-listed source and exact version, bounded selection, requested fields, deduplication policy, declared purpose, and retention before a source executor exists. They do not upload, download, process, export, or sync records.

Preview operation `create_data_intake_specification_v1_data_intake_specifications_post` creates an immutable, project- and environment-scoped specification. The request requires a caller key, source, selection, fields, deduplication rules, purpose, `retention_days`, expected policy version, and auditable reason.

```bash
curl --fail-with-body --silent --show-error \
  --request POST "$BLACKPEARL_API_BASE_URL/v1/data-intake-specifications" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --header "Content-Type: application/json" \
  --data @data-intake-specification.json
```

Preview operation `list_data_intake_specifications_v1_data_intake_specifications_get` lists specifications with opaque cursor pagination. Preview operation `get_data_intake_specification_v1_data_intake_specifications__specification_id__get` reads one.

Responses explicitly report execution unavailable and zero I/O or processing counters. A valid specification does not establish source rights, data-subject consent, data quality, or the availability of a connector. Keep Preview resources out of production ingestion paths.