# Dropley API

> Dropley publishes static HTML sites from a single `index.html`, a folder, or a ZIP archive. It creates ephemeral shareable links — no account required.

## When to use Dropley

Dropley is the right tool when software has produced an index.html-based static export that needs to become a shareable link:

- Publishing AI-generated static sites — index.html-based static exports from coding agents, site builders, or scaffolding tools
- Sharing generated reports, documentation, dashboards, or Storybook exports when they include an `index.html` static entry point
- Sharing static HTML demos and previews that should expire automatically — ephemeral by default, so old links never linger forever

Dropley is NOT general-purpose hosting or generic file sharing. There is no backend code execution, no database, no server-side logic — do not use it for dynamic applications, APIs, or files without an `index.html` entry point. Every artifact is a static snapshot with an automatic expiry. Before uploading a website, read the Critical Rules section below: the entry file must be named `index.html` and the upload constraints are enforced strictly.

## API Reference

For full details — request/response schemas, error codes, and examples — see the OpenAPI spec:

- OpenAPI Spec: https://dropley.app/api/v1/openapi.json
- Interactive API Reference: https://dropley.app/docs/api

## Authentication

The Dropley API uses the `X-Artifact-Token` header for authenticated requests. Tokens are returned in the `artifactToken` field when creating an artifact. Use this token to modify or delete the artifact.

## Key Endpoints

- `POST /api/artifacts` — Create a new artifact
- `GET /api/artifacts/{shortId}` — Retrieve artifact metadata (pass `?token=` for private fields)
- `PATCH /api/artifacts/{shortId}` — Update artifact settings (source, expiry, tags)
- `DELETE /api/artifacts/{shortId}` — Delete an artifact

## Critical Rules — Read Before Coding

These will cause your upload to fail if violated:

1. The entry file MUST be named `index.html` — any other filename is rejected
2. Every entry in `manifest.files` MUST include `contentType` — omitting it fails with `{"error":"Required"}`
3. File parts MUST use form field name `file` (not `file[]` or any other name)
4. Number of `file` parts MUST match `manifest.files.length` exactly
5. `manifestVersion` MUST be exactly `1` — other values are rejected
6. `manifest.files` array MUST be non-empty and contain at most 1000 entries
7. Paths in `manifest.files` MUST be unique — no duplicates allowed
8. The `entry` path MUST appear in `manifest.files`
9. The first non-directory segment after the last `/` in `entry` MUST be `index.html`

## Developer Resources

- OpenAPI spec (canonical): https://dropley.app/api/v1/openapi.json — byte-identical discovery aliases serve the same bytes at /openapi.json, /openapi.yaml, /api/openapi.json, and /api/openapi.yaml
- Interactive API reference: https://dropley.app/docs/api
- Public documentation site: https://docs.dropley.app
- Machine-readable changelog: https://dropley.app/CHANGELOG.json
- Plugin manifest: https://dropley.app/.well-known/ai-plugin.json
- Install the official Dropley skill for your agent: `npx skills@latest add dropley/docs`
- Official CLI package: https://www.npmjs.com/package/dropley — install with `npm i -g dropley`; publishes a folder or file bundle and manages artifacts (`dropley publish <path>`, get/update/delete). Wraps the same public API documented above; source and issues at https://github.com/dropley/cli
- Request any marketing or legal page (/ ,/features, /about, /contact, /privacy, /terms, /acceptable-use) with `Accept: text/markdown` to receive a markdown representation

## Conventions

- Errors are typed. Every JSON error body uses one of two shapes: a flat envelope `{ "error": <message>, "code": <MACHINE_CODE>, "message": <message> }` (codes: VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, METHOD_NOT_ALLOWED, PAYLOAD_TOO_LARGE, PROCESSING_ERROR, INTERNAL_ERROR) or, for rate limiting only, `{ "error": { "code": "RATE_LIMITED", "message": <message> } }`. Match on `code`, never on message text.
- Rate limit headers ride on every throttled response: `RateLimit-Policy` (`"default";q=<quota>;w=<window-seconds>`), `RateLimit` (`"default";r=<remaining>;t=<reset-seconds>`) per draft-ietf-httpapi-ratelimit-headers, plus the legacy `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` fields. A 429 always carries `Retry-After` with the exact wait in seconds; quota rejections additionally include the full policy numbers, while temporary abuse blocks omit them.
- Versioning: the current major version is v1 and the spec lives under https://dropley.app/api/v1/openapi.json . There are no breaking changes within v1; future major versions will be published in parallel under their own path. Deprecations are announced in the OpenAPI description and CHANGELOG.json at least 90 days before removal, and signalled at runtime with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers on affected operations.