Design a contract people can trust.

What this example represents

This page describes an illustrative API contract. The endpoint paths, job identifier, and request headers below are design examples rather than a hosted ExportAPI.com service. Use them to discuss how your application should accept work, report progress, and provide an artifact.

Start by agreeing on the dataset boundary and caller permissions. A file format is only one field in that agreement. Reporting windows, selected columns, schema versions, ordering, and artifact retention shape what the caller can safely expect.

Accept a bounded export request

The example selects a named dataset, an explicit set of fields, a format, and a bounded time window. Define the meaning of the start and end boundaries in your own contract. Validate unsupported formats, unknown fields, and inaccessible accounts before scheduling work.

ILLUSTRATIVE REQUEST
POST /v1/exports
Idempotency-Key: customer-report-example

{
  "dataset": "customers",
  "format": "csv",
  "fields": [
    "customer_id",
    "name",
    "plan",
    "monthly_usd"
  ],
  "window": {
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-10-02T00:00:00Z"
  },
  "schema_version": "customer-export-v1"
}

An idempotency key can associate a repeated submission with one logical request. Define the scope of that key and how you handle reuse with different request content. Store the resolved request so a retry does not silently adopt new defaults or a changed schedule.

Make the lifecycle explicit

Choose states with meanings your callers can distinguish. The following lifecycle separates acceptance, execution, and a terminal outcome. Artifact availability has its own lifetime: a previously completed job can remain completed after its downloadable file has expired.

Document which transitions are allowed and which failures can retry. A retry may be another attempt on the same job; it should not create a second business obligation unless that behavior is intentional. Avoid displaying a precise percentage when the amount of remaining work is unknown.

Return status without exposing the file

A status response can describe the completed artifact without placing a long-lived public URL in every log and notification. In the example, the consumer knows that a CSV with three records is ready. A separate access check should govern retrieval in an implementation that handles private data.

ILLUSTRATIVE STATUS RESPONSE
GET /v1/exports/exp_example_001

{
  "job_id": "exp_example_001",
  "state": "completed",
  "record_count": 3,
  "artifact": {
    "format": "csv",
    "filename": "customers.csv",
    "download_available": true
  }
}

Include stable identifiers and machine-readable error codes. Keep the human explanation helpful but avoid leaking database details, storage credentials, or unrelated account information. Let operators connect a failed attempt to diagnostic records through a bounded reference.

Treat delivery as a separate outcome

Publish an artifact only after generation and required checks have finished. A completion webhook can notify a consumer, while a status record remains the durable reference for the job. Define how receivers verify events, recognize duplicates, and recover when notifications arrive late or repeat.

The webhook retry guide explains event handling. Read secure file delivery for artifact access, and pagination for complete exports for dataset traversal.