Build with the API

Idempotent requests

Retry an upload or a plan change safely, so a timeout never costs you twice.

Networks fail. You send an upload, the connection drops, and you do not know whether it arrived. If you simply send it again, you might upload the file twice and use two slots of your quota. An idempotency key makes retrying safe.

How to use it

Make up a UUID for each thing you intend to do, and send it in an Idempotency-Key header. If you have to retry, send the same key.

KEY=$(uuidgen)

curl https://gridline-data-analysis-app.duckdns.org/api/files \
  -H "Authorization: Bearer gl_live_YOUR_KEY" \
  -H "Idempotency-Key: $KEY" \
  -F "file=@sales-q3.csv"

# Timed out? Run exactly the same command again, with the same $KEY.

What happens

You send	Gridline does
A new key	Runs the request and remembers the answer.
The same key and the same request again	Runs nothing and replays the first answer, with the header `Idempotent-Replayed: true`.
The same key while the first request is still running	Answers `409`. Wait a moment and retry.
The same key for a different request	Answers `422`: a key is for one request.
A key that is not a UUID	Answers `400`.

"The same request" means the same endpoint, the same person, the same body and, for an upload, the same file bytes.

A request that failed is forgotten, so you can fix it and retry with the same key.
Answers are remembered for 24 hours. After that the same key is a new request.
A request that crashed part-way is released after 10 minutes, so a key is never stuck.
A replayed upload keeps its X-Gridline-Quota-Warning header, if it had one.

Where it works

POST /files: upload a file.
POST /files/{id}/versions: upload a new version.
PATCH /subscriptions/me: change plan (so a retry cannot bill the difference twice).
The upload_file and upload_file_version AI-agent tools, as idempotencyKey.