# API Documentation — A Contract-First Export Service

## Document Directory

This paste contains 4 documents:

- [README.md](https://marke.st/p/01M33QJ9HPSR82BE86TARDH78G/README.md) ← (current)
- [openapi.yaml](https://marke.st/p/01M33QJ9HPSR82BE86TARDH78G/openapi.yaml) (code)
- [client.py](https://marke.st/p/01M33QJ9HPSR82BE86TARDH78G/client.py) (code)
- [fixtures/completed.json](https://marke.st/p/01M33QJ9HPSR82BE86TARDH78G/fixtures/completed.json) (code)

---

## README.md

# Paperplane Export API

### Accept the work now. Deliver the file when it is ready.

**API DESIGN EXAMPLE / OPENAPI + PYTHON + JSON**

> **Fictional service.** This is a contract and documentation example, not a running API. The `.invalid` server address is intentional. No API keys, accounts, or customer information are included.

## The workflow

```text
POST /v1/exports ──202──> queued job
                              │
GET /v1/exports/{id} ──────────┤
                              └──> completed job + result reference
```

A client requests a CSV or JSON export, receives an identifier, and checks its status. This example returns a result reference rather than inventing a working download link.

## Endpoints

| Method | Path | Success | Purpose |
|---|---|---|---|
| `POST` | `/v1/exports` | `202 Accepted` | Request a new export |
| `GET` | `/v1/exports/{id}` | `200 OK` | Read its current state |

### Request

```http
POST /v1/exports
Content-Type: application/json
Authorization: Bearer YOUR_OWN_TEST_TOKEN

{"format":"csv","dataset":"sample-orders"}
```

`YOUR_OWN_TEST_TOKEN` is a placeholder, not a credential. Use a token issued by your own implementation; do not paste real tokens into public documentation.

### Accepted response

```json
{
  "id": "exp_demo_001",
  "status": "queued",
  "format": "csv",
  "result_ref": null
}
```

## State model

| State | Terminal? | Result reference |
|---|---|---|
| `queued` | No | `null` |
| `running` | No | `null` |
| `completed` | Yes | A non-empty reference |
| `failed` | Yes | `null` |

The application must enforce valid transitions and field relationships. The compact schema illustrates the payload shapes; it is not a complete authorization or workflow engine.

## Failure behavior

A malformed request returns `400`; a missing or invalid credential returns `401`; a job outside the caller's visible set is treated as not found (`404`); exceeding the service's chosen rate limit returns `429` with `Retry-After` when available. These are **design choices for this fictional API**, not claims about Marke.st's API.

The sample intentionally does not promise automatic POST retries or idempotency. A client should not repeat a timed-out creation request unless its own service implements a documented deduplication contract.

## Files to explore

[OpenAPI contract](openapi.yaml) · [Python creation client](client.py) · [Example terminal response](fixtures/completed.json)

The client uses a caller-supplied HTTPS base URL and token. It makes one request with a timeout and prints the response. It does not poll or retry. Review it before pointing it at a service.

## Reference

This sample deliberately uses [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0.html), a defined specification version, rather than claiming to use the latest version.

---
*Published with [Marke.st](https://marke.st). Keep the narrative, contract, and client example together.*