Push API

The push API lets a vendor’s own system do what the upload page does, without a person logging in. It uses the same upload path, registry, audit and processing.

Base address: https://<your lake address>/api/v1/push. In the web app, the Push API guide page shows the live reference for the address you opened it from.

1. Get a push key

A vendor (or an admin) opens API keys (admin: the vendor’s Push API tab) and makes a key. Choose the narrowest scope that works:

Scope	The key may
folder	send files to that one folder only (least privilege; best for a scheduled job)
project	create folders in that project, send to any folder in it
vendor	create projects and folders, send to any folder of the vendor

The key looks like chdcp_ followed by 48 hex characters. It is shown once. Only a hash is stored, so a lost key is replaced, not recovered. Keys last 180 days by default and a vendor may have at most 20 active keys. A leaked key can only write raw files; it can never read data.

Store it in an environment variable, never in a script:

export CHDCP_KEY='chdcp_...'

2. The calls

All calls send Authorization: Bearer $CHDCP_KEY. Codes (not numeric ids) go in the address, and the vendor is always the key’s own.

Call	What it does
GET /whoami	Shows your vendor, the key’s scope and expiry, and what it may do
PUT /projects/{project}	Creates the project, or returns it if it exists (201 first time, 200 after). Body optional: {"name": "Readable name"}
PUT /projects/{project}/folders/{folder}	Creates the folder, or returns it
POST /projects/{project}/folders/{folder}/files?name=<file name>	Sends one file. The file is the request body, raw bytes, no multipart form
GET /projects/{project}/folders/{folder}/files	Lists the newest files of the folder
GET /projects/{project}/folders/{folder}/files/{id}	Status of one file

3. Send a file

BASE=https://lake.example.com/api/v1/push      # your address

# test the key
curl -H "Authorization: Bearer $CHDCP_KEY" "$BASE/whoami"

# make the project and folder (safe to repeat)
curl -X PUT -H "Authorization: Bearer $CHDCP_KEY" "$BASE/projects/readings"
curl -X PUT -H "Authorization: Bearer $CHDCP_KEY" "$BASE/projects/readings/folders/daily"

# send a file
curl -X POST -H "Authorization: Bearer $CHDCP_KEY" \
     --data-binary @daily.csv "$BASE/projects/readings/folders/daily/files?name=daily.csv"

The answer (HTTP 201) describes the stored file:

{ "id": "8c1f...", "name": "daily.csv", "size": 20480, "sha256": "e3b0...",
  "status": "uploaded", "stage": null, "message": "", "uploadedAt": "2026-10-27T02:00:03Z" }

Compare sha256 with your own hash to be sure the file arrived intact. If the same content was sent before, the answer also has duplicateOf; the file is still kept.

4. Follow it

curl -H "Authorization: Bearer $CHDCP_KEY" "$BASE/projects/readings/folders/daily/files/8c1f..."

Wait until status is processed, or read message when it is failed.

5. Python example

import os, requests

KEY = os.environ["CHDCP_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
FILES = "https://lake.example.com/api/v1/push/projects/readings/folders/daily/files"

with open("daily.csv", "rb") as f:
    r = requests.post(FILES, params={"name": "daily.csv"}, headers=H, data=f, timeout=300)
r.raise_for_status()
print(requests.get(f"{FILES}/{r.json()['id']}", headers=H, timeout=30).json()["status"])

Errors

Code	Meaning
400	No name, an empty file, or a refused file type (programs such as .exe, .sh)
401	Missing, wrong, revoked or expired key
403	The key’s scope does not cover this project or folder, or it may not do this
404	The project or folder does not exist yet: create it first
413	The file is larger than the limit
429	Too many calls: the limit is 120 per minute per key. Wait and retry
502	Storage failed. Nothing was saved. Send again

Every call, including refused ones, is logged (without key material). The API cannot delete or overwrite files: use the web app for that.

Scheduling

Run the curl or Python snippet from cron (0 2 * * *) or from Windows Task Scheduler. The Automate button on a folder page generates these with your codes filled in.