Getting started

Authentication

Every /api/v1/* request requires a Bearer token. Tokens are issued by OCPL IT — your contact at OCPL provisions one for you and delivers it over a secure channel. Send it on every request:

Authorization: Bearer ezfy_xxxxxxxxxxxxxxxxxxxxxxxxxx

Keep the key secret; it's your full credential. If it leaks, ask OCPL to rotate it — the old key is revoked instantly and a new one issued in the same minute.

Your first API call

Create a static-file short link. Paste in the path of a file already in the OCPL S3 bucket (your contact will give you the path), and the response will tell you the recipient-facing short URL.

curl -X POST https://ez.fyi/api/v1/links \
  -H "Authorization: Bearer ezfy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_ref": "links/2026/06/q2-invoice.pdf",
    "content_type": "application/pdf",
    "label": "Q2 invoice",
    "tags": ["doc-type:invoice", "fiscal-year:2026-27"]
  }'

The response contains the slug, the full URL, the creation timestamp, and the canonical (lower-cased, deduped) tag list:

{
  "slug": "aB3_x9Qz2k",
  "url": "https://ez.fyi/aB3_x9Qz2k",
  "created_at": "2026-06-01T08:14:23.402Z",
  "tags": ["doc-type:invoice", "fiscal-year:2026-27"]
}

Send the url to the recipient through your own channel (email, WhatsApp, SMS). When they open it, the file streams from S3 with the URL bar staying on https://ez.fyi/aB3_x9Qz2k — no redirect, no internal storage path leaks.

For Postman or Bruno, paste /api/v1/openapi.json into your tool's "Import OpenAPI" dialog — both tools generate a working collection in one click.

Versioning & stability

v1 is stable. Additive changes (new optional fields, new endpoints, new error codes) ship without notice. Removals or renames will only happen under a new major version (/api/v2/*), with at least 6 months of overlap during which both versions work. Endpoints scheduled for removal are flagged with deprecated: true in the OpenAPI document.

The full per-change history lives at /docs/changelog; the project narrative lives at /backlogs.