ReferenceAPI ReferenceLanding Zones

Landing Zones

Landing zones are standalone file drop areas for raw data uploads. They provide a structured way to ingest external files (CSV, JSON, Parquet) into the platform before pipeline processing. Files are stored in S3 at {namespace}/landing/{zoneName}/{filename}.

Landing zones can be connected to pipelines via triggers — when a file is uploaded, it can automatically trigger a bronze pipeline to ingest the data.

Endpoints

MethodEndpointDescription
GET/api/v1/landing-zonesList all landing zones
POST/api/v1/landing-zonesCreate a landing zone
GET/api/v1/landing-zones/{ns}/{name}Get landing zone details
PUT/api/v1/landing-zones/{ns}/{name}Update a landing zone
DELETE/api/v1/landing-zones/{ns}/{name}Delete a landing zone
GET/api/v1/landing-zones/{ns}/{name}/filesList files in a zone
POST/api/v1/landing-zones/{ns}/{name}/filesUpload a file
GET/api/v1/landing-zones/{ns}/{name}/files/{id}Get file metadata
DELETE/api/v1/landing-zones/{ns}/{name}/files/{id}Delete a file
GET/api/v1/landing-zones/{ns}/{name}/samplesList sample files
POST/api/v1/landing-zones/{ns}/{name}/samplesUpload a sample file
DELETE/api/v1/landing-zones/{ns}/{name}/samples/{filename}Delete a sample file
GET/api/v1/landing-zones/{ns}/{name}/lifecycleGet lifecycle settings
PUT/api/v1/landing-zones/{ns}/{name}/lifecycleUpdate lifecycle settings

List Landing Zones

GET /api/v1/landing-zones

Returns a list of all landing zones with file statistics (file count and total size).

Query Parameters

ParameterTypeDefaultDescription
namespacestring—Filter by namespace

Request

curl "http://localhost:8080/api/v1/landing-zones?namespace=default"

Response — 200 OK

{
  "zones": [
    {
      "id": "zone-uuid",
      "namespace": "default",
      "name": "raw-uploads",
      "description": "CSV files from partners",
      "file_count": 5,
      "total_bytes": 51200,
      "created_at": "2026-02-13T10:00:00Z",
      "updated_at": "2026-02-13T10:00:00Z"
    }
  ],
  "total": 1
}

Response Fields

FieldTypeDescription
zonesarrayList of landing zone objects
zones[].idstringZone UUID
zones[].namespacestringNamespace
zones[].namestringZone name
zones[].descriptionstringZone description
zones[].file_countintegerNumber of files in the zone
zones[].total_bytesintegerTotal size of all files in bytes
zones[].created_atstringISO 8601 creation timestamp
zones[].updated_atstringISO 8601 last update timestamp
totalintegerTotal number of zones

Create Landing Zone

POST /api/v1/landing-zones

Creates a new landing zone. The zone’s S3 prefix is created automatically.

Request Body

FieldTypeRequiredDescription
namespacestringYesTarget namespace
namestringYesZone name (lowercase, alphanumeric, hyphens)
descriptionstringNoHuman-readable description

Request

curl -X POST http://localhost:8080/api/v1/landing-zones \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "default",
    "name": "raw-uploads",
    "description": "CSV files from partners"
  }'

Response — 201 Created

{
  "id": "zone-uuid",
  "namespace": "default",
  "name": "raw-uploads",
  "description": "CSV files from partners",
  "created_at": "2026-02-13T10:00:00Z"
}

Error Responses

StatusCodeDescription
400INVALID_ARGUMENTMissing or invalid namespace/name
409ALREADY_EXISTSA zone with the same namespace and name already exists

Get Landing Zone

GET /api/v1/landing-zones/{ns}/{name}

Returns detailed information about a single landing zone, including file statistics.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Request

curl http://localhost:8080/api/v1/landing-zones/default/raw-uploads

Response — 200 OK

Returns the full landing zone object (same shape as items in the list response).

Error Responses

StatusCodeDescription
404NOT_FOUNDLanding zone not found

Update Landing Zone

PUT /api/v1/landing-zones/{ns}/{name}

Updates a landing zone’s mutable fields. This is a partial update.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Request Body

FieldTypeRequiredDescription
descriptionstringNoUpdated description
ownerstringNoOwner user ID
expected_schemastringNoExpected column schema (e.g., id:int,name:varchar,amount:decimal)

Request

curl -X PUT http://localhost:8080/api/v1/landing-zones/default/raw-uploads \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "owner": "user-id",
    "expected_schema": "id:int,name:varchar,amount:decimal"
  }'

Response — 200 OK

Returns the full landing zone object with updated fields.

Error Responses

StatusCodeDescription
400INVALID_ARGUMENTInvalid request body
404NOT_FOUNDLanding zone not found

Delete Landing Zone

DELETE /api/v1/landing-zones/{ns}/{name}

Deletes a landing zone and all its files from S3 (including the _samples/ folder), then removes the zone from the database.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Request

curl -X DELETE http://localhost:8080/api/v1/landing-zones/default/raw-uploads

Response — 204 No Content

No response body.

Error Responses

StatusCodeDescription
404NOT_FOUNDLanding zone not found

List Files

GET /api/v1/landing-zones/{ns}/{name}/files

Lists all files uploaded to a landing zone.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Request

curl http://localhost:8080/api/v1/landing-zones/default/raw-uploads/files

Response — 200 OK

{
  "files": [
    {
      "id": "file-uuid",
      "zone_id": "zone-uuid",
      "filename": "20260213_100500_orders.csv",
      "s3_path": "default/landing/raw-uploads/20260213_100500_orders.csv",
      "size_bytes": 1024,
      "content_type": "text/csv",
      "uploaded_at": "2026-02-13T10:05:00Z"
    }
  ],
  "total": 5
}

Response Fields

FieldTypeDescription
filesarrayList of file objects
files[].idstringFile UUID
files[].zone_idstringParent zone UUID
files[].filenamestringFilename (with timestamp prefix)
files[].s3_pathstringFull S3 path
files[].size_bytesintegerFile size in bytes
files[].content_typestringMIME type
files[].uploaded_atstringISO 8601 upload timestamp
totalintegerTotal number of files

Error Responses

StatusCodeDescription
404NOT_FOUNDLanding zone not found

Upload File

POST /api/v1/landing-zones/{ns}/{name}/files

Uploads a file to a landing zone via multipart form data. The filename is taken from the multipart header and prepended with a UTC timestamp to avoid collisions. Maximum file size is 32 MB.

When triggers are configured, file uploads asynchronously evaluate matching landing_zone_upload and file_pattern triggers.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Form Fields

FieldTypeRequiredDescription
filebinaryYesFile to upload

Request

curl -X POST http://localhost:8080/api/v1/landing-zones/default/raw-uploads/files \
  -F "file=@/local/path/to/orders.csv"

Response — 201 Created

{
  "id": "file-uuid",
  "zone_id": "zone-uuid",
  "filename": "20260213_100500_orders.csv",
  "s3_path": "default/landing/raw-uploads/20260213_100500_orders.csv",
  "size_bytes": 1024,
  "content_type": "text/csv",
  "uploaded_at": "2026-02-13T10:05:00Z"
}

Filenames are automatically prefixed with a UTC timestamp (YYYYMMDD_HHMMSS_) to prevent collisions when multiple files with the same name are uploaded. The original filename is preserved after the prefix.

Error Responses

StatusCodeDescription
400INVALID_ARGUMENTMissing file form field
404NOT_FOUNDLanding zone not found
413INVALID_ARGUMENTFile exceeds 32 MB size limit

Get File Metadata

GET /api/v1/landing-zones/{ns}/{name}/files/{id}

Returns metadata for a single file.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name
idstringFile UUID

Request

curl http://localhost:8080/api/v1/landing-zones/default/raw-uploads/files/file-uuid

Response — 200 OK

Returns the full file metadata object (same shape as items in the list response).

Error Responses

StatusCodeDescription
404NOT_FOUNDFile or landing zone not found

Delete File

DELETE /api/v1/landing-zones/{ns}/{name}/files/{id}

Deletes a file from both S3 and the database.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name
idstringFile UUID

Request

curl -X DELETE http://localhost:8080/api/v1/landing-zones/default/raw-uploads/files/file-uuid

Response — 204 No Content

No response body.

Error Responses

StatusCodeDescription
404NOT_FOUNDFile or landing zone not found

List Sample Files

GET /api/v1/landing-zones/{ns}/{name}/samples

Lists sample files stored in the _samples/ subfolder of the landing zone’s S3 prefix. Samples are curated reference files used for pipeline previews and schema inference — unlike regular uploads, they are not append-only.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Request

curl http://localhost:8080/api/v1/landing-zones/default/raw-uploads/samples

Response — 200 OK

{
  "files": [
    {
      "path": "default/landing/raw-uploads/_samples/sample.csv",
      "size": 512,
      "modified": "2026-02-13T10:00:00Z",
      "type": ""
    }
  ],
  "total": 1
}

Error Responses

StatusCodeDescription
404NOT_FOUNDLanding zone not found

Upload Sample File

POST /api/v1/landing-zones/{ns}/{name}/samples

Uploads a sample file via multipart form data. The filename is used as-is (no timestamp prefix). Uploading a sample with the same name as an existing one will overwrite it.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Form Fields

FieldTypeRequiredDescription
filebinaryYesSample file to upload

Request

curl -X POST http://localhost:8080/api/v1/landing-zones/default/raw-uploads/samples \
  -F "file=@/local/path/to/sample.csv"

Response — 201 Created

{
  "path": "default/landing/raw-uploads/_samples/sample.csv",
  "filename": "sample.csv",
  "size": 512,
  "status": "uploaded"
}

Error Responses

StatusCodeDescription
400INVALID_ARGUMENTMissing file form field
404NOT_FOUNDLanding zone not found
413INVALID_ARGUMENTFile exceeds 32 MB size limit

Delete Sample File

DELETE /api/v1/landing-zones/{ns}/{name}/samples/{filename}

Deletes a sample file from S3.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name
filenamestringSample filename

Request

curl -X DELETE http://localhost:8080/api/v1/landing-zones/default/raw-uploads/samples/sample.csv

Response — 204 No Content

No response body.

Error Responses

StatusCodeDescription
404NOT_FOUNDLanding zone or sample file not found

Get Lifecycle Settings

GET /api/v1/landing-zones/{ns}/{name}/lifecycle

Returns the lifecycle settings for a landing zone, which control automatic cleanup of processed files.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Request

curl http://localhost:8080/api/v1/landing-zones/default/raw-uploads/lifecycle

Response — 200 OK

{
  "processed_max_age_days": 30,
  "auto_purge": true
}

Response Fields

FieldTypeDescription
processed_max_age_daysintegerMaximum age (in days) for processed files before automatic cleanup
auto_purgebooleanWhether the reaper automatically deletes expired processed files

Error Responses

StatusCodeDescription
404NOT_FOUNDLanding zone not found

Update Lifecycle Settings

PUT /api/v1/landing-zones/{ns}/{name}/lifecycle

Updates the lifecycle settings for a landing zone.

Path Parameters

ParameterTypeDescription
nsstringNamespace
namestringZone name

Request Body

FieldTypeRequiredDescription
processed_max_age_daysintegerNoMaximum age for processed files (in days)
auto_purgebooleanNoEnable/disable automatic cleanup

Request

curl -X PUT http://localhost:8080/api/v1/landing-zones/default/raw-uploads/lifecycle \
  -H "Content-Type: application/json" \
  -d '{
    "processed_max_age_days": 14,
    "auto_purge": true
  }'

Response — 204 No Content

No response body.

Error Responses

StatusCodeDescription
400INVALID_ARGUMENTInvalid settings (e.g., negative age)
404NOT_FOUNDLanding zone not found

Lifecycle settings are enforced by the reaper daemon. When auto_purge is enabled, the reaper automatically deletes files older than processed_max_age_days from the landing zone during its periodic cleanup runs. See the Retention documentation for reaper configuration.

StorageTriggers