{ "components": { "schemas": { "AccountLimits": { "properties": { "default_ttl_seconds": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Drop lifetime in seconds before expiry; null means drops are permanent", "examples": [ 259200 ], "title": "Default Ttl Seconds" }, "max_size_bytes": { "description": "Maximum size of a single drop in bytes", "examples": [ 5242880 ], "title": "Max Size Bytes", "type": "integer" }, "max_storage_bytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Total account storage cap in bytes; null means no account-level cap", "examples": [ 2147483648 ], "title": "Max Storage Bytes" }, "name": { "description": "Plan tier the limits apply to", "examples": [ "free" ], "title": "Name", "type": "string" } }, "required": [ "name", "max_size_bytes", "default_ttl_seconds", "max_storage_bytes" ], "title": "AccountLimits", "type": "object" }, "AccountResponse": { "properties": { "created_at": { "description": "Account creation timestamp", "examples": [ "2026-05-23T12:00:00Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional public display name", "examples": [ "Ada Lovelace" ], "title": "Display Name" }, "email": { "description": "Primary email address for the account", "examples": [ "ada@example.com" ], "title": "Email", "type": "string" }, "id": { "description": "Stable account identifier", "examples": [ "acc_01hzz00000000000000000" ], "title": "Id", "type": "string" }, "limits": { "$ref": "#/components/schemas/AccountLimits", "description": "Active plan tier limits \u2014 use these to size a publish before uploading" }, "plan": { "description": "Active billing plan tier", "examples": [ "free" ], "title": "Plan", "type": "string" }, "status": { "description": "Account lifecycle status", "examples": [ "active" ], "title": "Status", "type": "string" } }, "required": [ "id", "email", "plan", "status", "created_at", "limits" ], "title": "AccountResponse", "type": "object" }, "Action": { "properties": { "code": { "description": "Machine-readable action code", "examples": [ "verify_email_otp" ], "title": "Code", "type": "string" }, "endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Relative API path for api actions", "examples": [ "/v1/auth/email/verify" ], "title": "Endpoint" }, "kind": { "description": "Action type: 'api' (call an endpoint), 'external' (upload to signed URL), 'human' (user action)", "examples": [ "api" ], "title": "Kind", "type": "string" }, "message": { "description": "Plain English explanation of the action", "examples": [ "Verify the 6-digit code sent to your email." ], "title": "Message", "type": "string" }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "HTTP method for api actions", "examples": [ "POST" ], "title": "Method" } }, "required": [ "code", "kind", "message" ], "title": "Action", "type": "object" }, "ActionResolve": { "properties": { "endpoint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Relative API path for agent-resolvable actions", "examples": [ "/v1/drops" ], "title": "Endpoint" }, "method": { "description": "HTTP method", "examples": [ "GET" ], "title": "Method", "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Absolute URL for human actions", "examples": [ "https://dropthis.app/pricing" ], "title": "Url" } }, "required": [ "method" ], "title": "ActionResolve", "type": "object" }, "ApiKeyCreatedResponse": { "properties": { "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account identifier associated with the key when returned during bootstrap", "examples": [ "acc_01hzz00000000000000000" ], "title": "Account Id" }, "created_at": { "description": "API key creation timestamp", "examples": [ "2026-05-23T12:00:00Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Stable API key identifier", "examples": [ "ak_01hzz00000000000000000" ], "title": "Id", "type": "string" }, "is_new_account": { "default": false, "description": "Whether creating the key also created a new account", "examples": [ false ], "title": "Is New Account", "type": "boolean" }, "key": { "description": "Raw API key secret, shown only once", "examples": [ "sk_live_abc123" ], "title": "Key", "type": "string" }, "key_last4": { "description": "Last four characters of the API key secret", "examples": [ "wxyz" ], "title": "Key Last4", "type": "string" }, "label": { "description": "Human-readable API key label", "examples": [ "CLI key" ], "title": "Label", "type": "string" }, "object": { "const": "api_key", "default": "api_key", "title": "Object", "type": "string" } }, "required": [ "id", "key_last4", "label", "created_at", "key" ], "title": "ApiKeyCreatedResponse", "type": "object" }, "ApiKeyListResponse": { "properties": { "data": { "description": "Active API keys for the authenticated account", "items": { "$ref": "#/components/schemas/ApiKeyResponse" }, "title": "Data", "type": "array" }, "object": { "const": "list", "default": "list", "title": "Object", "type": "string" } }, "required": [ "data" ], "title": "ApiKeyListResponse", "type": "object" }, "ApiKeyResponse": { "properties": { "created_at": { "description": "API key creation timestamp", "examples": [ "2026-05-23T12:00:00Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "id": { "description": "Stable API key identifier", "examples": [ "ak_01hzz00000000000000000" ], "title": "Id", "type": "string" }, "key_last4": { "description": "Last four characters of the API key secret", "examples": [ "wxyz" ], "title": "Key Last4", "type": "string" }, "label": { "description": "Human-readable API key label", "examples": [ "CLI key" ], "title": "Label", "type": "string" }, "object": { "const": "api_key", "default": "api_key", "title": "Object", "type": "string" } }, "required": [ "id", "key_last4", "label", "created_at" ], "title": "ApiKeyResponse", "type": "object" }, "CreateApiKeyRequest": { "properties": { "key_type": { "$ref": "#/components/schemas/KeyType", "default": "standard", "description": "Key category. `standard` keys (CLI/SDK/manual) share the per-account quota; `mcp_oauth` keys are minted by the MCP OAuth flow and have their own generous cap.", "examples": [ "standard" ] }, "label": { "description": "Human-readable API key label", "examples": [ "Production deploy key" ], "maxLength": 255, "minLength": 1, "title": "Label", "type": "string" } }, "required": [ "label" ], "title": "CreateApiKeyRequest", "type": "object" }, "CreateUploadFileRequest": { "properties": { "checksum_sha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional lowercase hex SHA-256 checksum for the file bytes. When provided, the signed upload target requires the matching x-amz-checksum-sha256 header (included in the returned headers) and storage rejects mismatched bytes; completion re-verifies the stored checksum.", "examples": [ "3a6eb0790f39ac87c94f3856b2dd2c5d110e6811602261a9a923d3bb23adc8b7" ], "title": "Checksum Sha256" }, "content_type": { "description": "MIME type the client must use when uploading bytes to the returned signed target.", "examples": [ "text/html" ], "title": "Content Type", "type": "string" }, "path": { "description": "Normalized POSIX path the file will have inside the staged artifact. Duplicate paths are rejected.", "examples": [ "index.html" ], "title": "Path", "type": "string" }, "size_bytes": { "description": "Declared byte size for this file; completion verifies the stored object size matches this value.", "examples": [ 204800 ], "title": "Size Bytes", "type": "integer" } }, "required": [ "path", "content_type", "size_bytes" ], "title": "CreateUploadFileRequest", "type": "object" }, "CreateUploadSessionRequest": { "properties": { "entry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Path of the entry file to serve first when the staged artifact is published.", "examples": [ "index.html" ], "title": "Entry" }, "files": { "description": "Manifest of files to upload before publishing. At least one file is required.", "examples": [ [ { "content_type": "text/html", "path": "index.html", "size_bytes": 204800 }, { "content_type": "application/javascript", "path": "assets/app.js", "size_bytes": 12000 } ] ], "items": { "$ref": "#/components/schemas/CreateUploadFileRequest" }, "title": "Files", "type": "array" }, "schema_version": { "default": 1, "description": "Upload manifest schema version. Version 1 is the only accepted value.", "examples": [ 1 ], "title": "Schema Version", "type": "integer" } }, "required": [ "files" ], "title": "CreateUploadSessionRequest", "type": "object" }, "CreateUploadSessionResponse": { "properties": { "expires_at": { "description": "Time when the upload session stops accepting normal completion attempts.", "examples": [ "2026-05-15T12:00:00Z" ], "format": "date-time", "title": "Expires At", "type": "string" }, "files": { "description": "Per-file direct storage upload targets for the declared manifest.", "examples": [ [ { "file_id": "file_000001", "object_key": "staging/acc_01hzz00000000000000000/upl_01hzz00000000000000000/files/000001", "path": "index.html", "upload": { "expires_at": "2026-05-15T12:00:00Z", "headers": { "content-type": "text/html" }, "strategy": "single_put", "url": "https://storage.example/upload/index.html" } } ] ], "items": { "$ref": "#/components/schemas/UploadTargetResponse" }, "title": "Files", "type": "array" }, "next_action": { "$ref": "#/components/schemas/Action", "default": { "code": "upload_files", "kind": "external", "message": "Upload each file to its signed URL, then complete the session." }, "description": "Next step after creating the upload session" }, "upload_id": { "description": "Stable upload session identifier to use for status, completion, cancellation, and publish calls.", "examples": [ "upl_01hzz00000000000000000" ], "title": "Upload Id", "type": "string" } }, "required": [ "upload_id", "expires_at", "files" ], "title": "CreateUploadSessionResponse", "type": "object" }, "DeploymentContentFile": { "properties": { "content_type": { "description": "Stored MIME type the file is served with", "examples": [ "text/html" ], "title": "Content Type", "type": "string" }, "path": { "description": "File path within the deployment, relative to its root", "examples": [ "index.html" ], "title": "Path", "type": "string" }, "size_bytes": { "description": "Stored file size in bytes", "examples": [ 1024 ], "title": "Size Bytes", "type": "integer" } }, "required": [ "path", "content_type", "size_bytes" ], "title": "DeploymentContentFile", "type": "object" }, "DeploymentContentManifest": { "description": "Manifest of one deployment's readable files (content read-back).\n\nFetch a single file's bytes with `?path=` on the same route.", "properties": { "deployment_id": { "description": "Deployment identifier", "examples": [ "dep_01hzz00000000000000000" ], "title": "Deployment Id", "type": "string" }, "drop_id": { "description": "Parent drop identifier", "examples": [ "drop_01hzz00000000000000000" ], "title": "Drop Id", "type": "string" }, "entry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Entry path served at the drop root", "examples": [ "index.html" ], "title": "Entry" }, "files": { "description": "Readable files in this deployment; pass files[].path as ?path= to download one", "items": { "$ref": "#/components/schemas/DeploymentContentFile" }, "title": "Files", "type": "array" }, "revision": { "description": "Content revision of this deployment", "examples": [ 2 ], "title": "Revision", "type": "integer" }, "size_bytes": { "description": "Total deployment size in bytes", "examples": [ 12345 ], "title": "Size Bytes", "type": "integer" }, "status": { "description": "Deployment lifecycle status", "examples": [ "published" ], "title": "Status", "type": "string" } }, "required": [ "drop_id", "deployment_id", "revision", "status", "size_bytes", "files" ], "title": "DeploymentContentManifest", "type": "object" }, "DropAction": { "properties": { "code": { "description": "Stable machine-readable action code", "examples": [ "expires_on_free_tier" ], "title": "Code", "type": "string" }, "kind": { "description": "Who can resolve: 'api' (agent) or 'human'", "examples": [ "human" ], "title": "Kind", "type": "string" }, "message": { "description": "Plain English explanation", "examples": [ "This drop expires in 7 days." ], "title": "Message", "type": "string" }, "priority": { "description": "'required' (blocks usage) or 'suggested' (caveat)", "examples": [ "suggested" ], "title": "Priority", "type": "string" }, "resolve": { "anyOf": [ { "$ref": "#/components/schemas/ActionResolve" }, { "type": "null" } ], "description": "How to resolve this action" } }, "required": [ "code", "kind", "priority", "message" ], "title": "DropAction", "type": "object" }, "DropDeploymentResponse": { "properties": { "classification_reason": { "description": "Bundle classifier reason code", "examples": [ "html_bundle" ], "title": "Classification Reason", "type": "string" }, "classification_version": { "description": "Bundle classifier version", "examples": [ 1 ], "title": "Classification Version", "type": "integer" }, "content_type": { "description": "Entry MIME type", "examples": [ "text/html" ], "title": "Content Type", "type": "string" }, "created_at": { "description": "Creation timestamp", "examples": [ "2026-05-23T12:00:00Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "drop_id": { "description": "Parent drop identifier", "examples": [ "drop_01hzz00000000000000000" ], "title": "Drop Id", "type": "string" }, "entry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Entry path served at the drop root", "examples": [ "index.html" ], "title": "Entry" }, "error_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure code when deployment failed", "examples": [ "upload_failed" ], "title": "Error Code" }, "error_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Failure message when deployment failed", "examples": [ "Storage upload failed" ], "title": "Error Message" }, "files": { "description": "Published file manifest", "examples": [ [ { "content_type": "text/html", "path": "index.html", "size_bytes": 1024 } ] ], "items": { "additionalProperties": true, "type": "object" }, "title": "Files", "type": "array" }, "id": { "description": "Stable deployment identifier", "examples": [ "dep_01hzz00000000000000000" ], "title": "Id", "type": "string" }, "published_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Public route metadata switch timestamp", "examples": [ "2026-05-23T12:00:06Z" ], "title": "Published At" }, "ready_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Files uploaded timestamp", "examples": [ "2026-05-23T12:00:05Z" ], "title": "Ready At" }, "render_mode": { "description": "Viewer render mode", "examples": [ "user_html" ], "title": "Render Mode", "type": "string" }, "revision": { "description": "Content revision for this drop", "examples": [ 2 ], "title": "Revision", "type": "integer" }, "size_bytes": { "description": "Total deployment size in bytes", "examples": [ 12345 ], "title": "Size Bytes", "type": "integer" }, "status": { "description": "Deployment lifecycle status", "examples": [ "published" ], "title": "Status", "type": "string" }, "storage_prefix": { "description": "Immutable storage prefix", "examples": [ "drops/drop_01hzz/rev-2" ], "title": "Storage Prefix", "type": "string" }, "warnings": { "description": "Bundle classification warnings", "examples": [ [ { "code": "large_asset", "message": "Large asset detected" } ] ], "items": { "additionalProperties": true, "type": "object" }, "title": "Warnings", "type": "array" } }, "required": [ "id", "drop_id", "revision", "status", "storage_prefix", "content_type", "render_mode", "size_bytes", "classification_version", "classification_reason", "created_at" ], "title": "DropDeploymentResponse", "type": "object" }, "DropResponse": { "properties": { "access_revision": { "description": "Monotonic access-control revision", "examples": [ 1 ], "title": "Access Revision", "type": "integer" }, "accessible": { "description": "Whether the drop is currently accessible", "examples": [ true ], "title": "Accessible", "type": "boolean" }, "badge_applied": { "description": "Whether a dropthis badge was injected", "examples": [ false ], "title": "Badge Applied", "type": "boolean" }, "content_revision": { "description": "Monotonic content deployment revision", "examples": [ 1 ], "title": "Content Revision", "type": "integer" }, "content_type": { "description": "Entry file MIME type", "examples": [ "text/html" ], "title": "Content Type", "type": "string" }, "created_at": { "description": "Creation timestamp", "examples": [ "2026-05-23T12:00:00Z" ], "format": "date-time", "title": "Created At", "type": "string" }, "deployment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Currently live deployment id", "examples": [ "dep_01hzz00000000000000000" ], "title": "Deployment Id" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "description": "Optional automatic expiry timestamp", "examples": [ "2026-06-23T12:00:00Z" ], "title": "Expires At" }, "id": { "description": "Stable drop identifier", "examples": [ "drop_01hzz00000000000000000" ], "title": "Id", "type": "string" }, "limitations": { "$ref": "#/components/schemas/Limitations", "description": "Caveats and suggested actions for this drop" }, "metadata": { "additionalProperties": true, "description": "Custom user or agent metadata stored with the drop", "examples": [ { "campaign": "fall-launch", "prompt_id": "msg_456" } ], "title": "Metadata", "type": "object" }, "noindex": { "description": "Whether search-engine indexing is disabled", "examples": [ false ], "title": "Noindex", "type": "boolean" }, "object": { "default": "drop", "description": "Object type discriminator", "examples": [ "drop" ], "title": "Object", "type": "string" }, "password_protected": { "description": "Whether a view password is set (the password itself is never returned)", "examples": [ false ], "title": "Password Protected", "type": "boolean" }, "persistent": { "description": "Whether this drop persists indefinitely", "examples": [ false ], "title": "Persistent", "type": "boolean" }, "render_mode": { "description": "Viewer render mode", "examples": [ "user_html" ], "title": "Render Mode", "type": "string" }, "revision": { "description": "Monotonic content/settings revision", "examples": [ 1 ], "title": "Revision", "type": "integer" }, "size_bytes": { "description": "Total published bundle size in bytes", "examples": [ 12345 ], "title": "Size Bytes", "type": "integer" }, "slug": { "description": "Public slug used in the drop URL", "examples": [ "summer-launch" ], "title": "Slug", "type": "string" }, "status": { "description": "Publishing lifecycle status", "examples": [ "published" ], "title": "Status", "type": "string" }, "tier": { "$ref": "#/components/schemas/TierInfo", "description": "Tier limits and characteristics for this drop" }, "title": { "description": "Human-readable drop title", "examples": [ "Summer Launch" ], "title": "Title", "type": "string" }, "url": { "description": "Permanent public URL for the drop", "examples": [ "https://dropthis.com/p/summer-launch" ], "title": "Url", "type": "string" }, "visibility": { "description": "Serving visibility", "examples": [ "public" ], "title": "Visibility", "type": "string" }, "warnings": { "description": "Bundle classification warnings", "examples": [ [ { "code": "external_script", "message": "External script detected" } ] ], "items": { "additionalProperties": true, "type": "object" }, "title": "Warnings", "type": "array" } }, "required": [ "id", "slug", "url", "title", "content_type", "visibility", "status", "revision", "content_revision", "access_revision", "size_bytes", "render_mode", "created_at", "noindex", "password_protected", "accessible", "persistent", "badge_applied", "tier", "limitations" ], "title": "DropResponse", "type": "object" }, "EmailOtpRequest": { "properties": { "email": { "description": "Email address that should receive the OTP", "examples": [ "ada@example.com" ], "format": "email", "title": "Email", "type": "string" } }, "required": [ "email" ], "title": "EmailOtpRequest", "type": "object" }, "EmailVerifyRequest": { "properties": { "code": { "description": "Six-digit one-time passcode from the email", "examples": [ "123456" ], "maxLength": 6, "minLength": 6, "pattern": "^\\d{6}$", "title": "Code", "type": "string" }, "email": { "description": "Email address that received the OTP", "examples": [ "ada@example.com" ], "format": "email", "title": "Email", "type": "string" } }, "required": [ "email", "code" ], "title": "EmailVerifyRequest", "type": "object" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object" }, "KeyType": { "description": "Why a key exists. Drives quota accounting: ``standard`` keys (CLI/SDK/manual) share the\nuser's small per-account cap; ``mcp_oauth`` keys are minted automatically by the remote MCP\nOAuth worker (one per connected client) and carry their own, far more generous cap.", "enum": [ "standard", "mcp_oauth" ], "title": "KeyType", "type": "string" }, "Limitations": { "properties": { "actions": { "description": "Caveats and suggested actions for this drop", "items": { "$ref": "#/components/schemas/DropAction" }, "title": "Actions", "type": "array" } }, "title": "Limitations", "type": "object" }, "ListDropDeploymentsResponse": { "properties": { "deployments": { "description": "Deployments for the drop", "items": { "$ref": "#/components/schemas/DropDeploymentResponse" }, "title": "Deployments", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yM1QxMjowMDowMFoiLCJpZCI6ImRlcF8ifQ==" ], "title": "Next Cursor" } }, "required": [ "deployments" ], "title": "ListDropDeploymentsResponse", "type": "object" }, "ListDropsResponse": { "properties": { "drops": { "description": "Drops owned by the authenticated account", "items": { "$ref": "#/components/schemas/DropResponse" }, "title": "Drops", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next drop of results", "examples": [ "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yM1QxMjowMDowMFoiLCJpZCI6ImRyb3BfIn0=" ], "title": "Next Cursor" } }, "required": [ "drops" ], "title": "ListDropsResponse", "type": "object" }, "OtpSentResponse": { "properties": { "expires_in": { "description": "Seconds until the OTP expires", "examples": [ 600 ], "title": "Expires In", "type": "integer" }, "next_action": { "$ref": "#/components/schemas/Action", "default": { "code": "verify_email_otp", "endpoint": "/v1/auth/email/verify", "kind": "api", "message": "Verify the 6-digit code sent to your email.", "method": "POST" }, "description": "Next step to complete authentication" }, "ok": { "const": true, "default": true, "title": "Ok", "type": "boolean" } }, "required": [ "expires_in" ], "title": "OtpSentResponse", "type": "object" }, "SessionResponse": { "properties": { "account_id": { "description": "Authenticated account identifier", "examples": [ "acc_01hzz00000000000000000" ], "title": "Account Id", "type": "string" }, "expires_in": { "description": "Seconds until the session token expires", "examples": [ 2592000 ], "title": "Expires In", "type": "integer" }, "is_new_account": { "default": false, "description": "Whether verification created a new account", "examples": [ false ], "title": "Is New Account", "type": "boolean" }, "object": { "const": "session", "default": "session", "title": "Object", "type": "string" }, "token": { "description": "Bearer session token", "examples": [ "sess_01hzz00000000000000000" ], "title": "Token", "type": "string" } }, "required": [ "token", "account_id", "expires_in" ], "title": "SessionResponse", "type": "object" }, "TierInfo": { "properties": { "badge": { "description": "Whether this tier injects a dropthis badge", "examples": [ true ], "title": "Badge", "type": "boolean" }, "max_size_bytes": { "description": "Maximum drop size in bytes", "examples": [ 5242880 ], "title": "Max Size Bytes", "type": "integer" }, "name": { "description": "Plan tier name", "examples": [ "free" ], "title": "Name", "type": "string" }, "persistent": { "description": "Whether drops persist indefinitely on this tier", "examples": [ false ], "title": "Persistent", "type": "boolean" }, "ttl_days": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Default TTL in days, null if persistent", "examples": [ 7 ], "title": "Ttl Days" } }, "required": [ "name", "max_size_bytes", "ttl_days", "persistent", "badge" ], "title": "TierInfo", "type": "object" }, "UpdateAccountRequest": { "additionalProperties": false, "properties": { "display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "New display name, or null to clear it", "examples": [ "Ada" ], "title": "Display Name" } }, "title": "UpdateAccountRequest", "type": "object" }, "UploadSessionFileResponse": { "properties": { "content_type": { "description": "Declared MIME type that completion checks against stored object metadata.", "examples": [ "text/html" ], "title": "Content Type", "type": "string" }, "file_id": { "description": "Server-assigned file identifier for this manifest entry.", "examples": [ "file_000001" ], "title": "File Id", "type": "string" }, "object_key": { "description": "Internal staging object key for the uploaded bytes; this is not a public URL.", "examples": [ "staging/acc_01hzz00000000000000000/upl_01hzz00000000000000000/files/000001" ], "title": "Object Key", "type": "string" }, "path": { "description": "Normalized path for this file inside the staged artifact.", "examples": [ "index.html" ], "title": "Path", "type": "string" }, "size_bytes": { "description": "Declared byte size that completion checks against the stored object size.", "examples": [ 204800 ], "title": "Size Bytes", "type": "integer" }, "verified": { "description": "Whether completion has verified that the staged object matches the manifest entry.", "examples": [ false ], "title": "Verified", "type": "boolean" } }, "required": [ "file_id", "path", "content_type", "size_bytes", "object_key", "verified" ], "title": "UploadSessionFileResponse", "type": "object" }, "UploadSessionResponse": { "properties": { "entry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Path of the entry file that will be served first after the staged artifact is published.", "examples": [ "index.html" ], "title": "Entry" }, "expires_at": { "description": "Time when the upload session stops accepting normal completion attempts.", "examples": [ "2026-05-15T12:00:00Z" ], "format": "date-time", "title": "Expires At", "type": "string" }, "files": { "description": "Manifest entries tracked by this upload session, including verification state.", "examples": [ [ { "content_type": "text/html", "file_id": "file_000001", "object_key": "staging/acc_01hzz00000000000000000/upl_01hzz00000000000000000/files/000001", "path": "index.html", "size_bytes": 204800, "verified": false } ] ], "items": { "$ref": "#/components/schemas/UploadSessionFileResponse" }, "title": "Files", "type": "array" }, "next_action": { "anyOf": [ { "$ref": "#/components/schemas/Action" }, { "type": "null" } ], "description": "Next step based on current upload session status", "readOnly": true }, "status": { "description": "Current upload session lifecycle state.", "examples": [ "created" ], "title": "Status", "type": "string" }, "upload_id": { "description": "Stable upload session identifier to pass to completion and later publish calls.", "examples": [ "upl_01hzz00000000000000000" ], "title": "Upload Id", "type": "string" } }, "required": [ "upload_id", "status", "expires_at", "files", "next_action" ], "title": "UploadSessionResponse", "type": "object" }, "UploadTargetResponse": { "properties": { "file_id": { "description": "Server-assigned file identifier for this manifest entry.", "examples": [ "file_000001" ], "title": "File Id", "type": "string" }, "object_key": { "description": "Internal staging object key for the uploaded bytes; this is not a public URL.", "examples": [ "staging/acc_01hzz00000000000000000/upl_01hzz00000000000000000/files/000001" ], "title": "Object Key", "type": "string" }, "path": { "description": "Normalized path for this file inside the staged artifact.", "examples": [ "index.html" ], "title": "Path", "type": "string" }, "upload": { "additionalProperties": true, "description": "Direct storage upload instructions. Send bytes to the returned URL with exactly the provided headers.", "examples": [ { "expires_at": "2026-05-15T12:00:00Z", "headers": { "content-type": "text/html" }, "strategy": "single_put", "url": "https://storage.example/upload/index.html" } ], "title": "Upload", "type": "object" } }, "required": [ "file_id", "path", "object_key", "upload" ], "title": "UploadTargetResponse", "type": "object" }, "ValidationError": { "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object" } }, "securitySchemes": { "HTTPBearer": { "scheme": "bearer", "type": "http" } } }, "info": { "title": "dropthis API", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/health": { "get": { "operationId": "health_health_get", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Successful Response" } }, "summary": "Health" } }, "/v1/account": { "delete": { "description": "Soft-delete the authenticated account and disable future access. Requires a durable sk_ API key; short-lived at_ session tokens are rejected (ADR 0053).", "operationId": "delete_account_v1_account_delete", "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "403": { "description": "Authenticated with an at_ session token, which cannot delete the account" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete account", "tags": [ "Account" ] }, "get": { "description": "Return profile, status, plan, and the active tier limits (max drop size, TTL, storage cap) for the authenticated account. Use `limits` to size a publish before uploading.", "operationId": "get_account_v1_account_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get account", "tags": [ "Account" ] }, "patch": { "description": "Update mutable profile fields for the authenticated account.", "operationId": "update_account_v1_account_patch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update account", "tags": [ "Account" ] } }, "/v1/api-keys": { "get": { "description": "List active API keys for the authenticated account. Raw key secrets are never returned.", "operationId": "list_api_keys_v1_api_keys_get", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyListResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List API keys", "tags": [ "API Keys" ] }, "post": { "description": "Create a durable sk_ API key for CLI, SDK, MCP, or automation use. The raw key is returned only once.", "operationId": "create_api_key_v1_api_keys_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreatedResponse" } } }, "description": "Successful Response" }, "403": { "description": "key_type=mcp_oauth is reserved for the dropthis MCP worker" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create API key", "tags": [ "API Keys" ] } }, "/v1/api-keys/{key_id}": { "delete": { "description": "Revoke an API key owned by the authenticated account. Missing, foreign, and already-revoked keys return not found.", "operationId": "revoke_api_key_v1_api_keys__key_id__delete", "parameters": [ { "description": "API key identifier to revoke", "in": "path", "name": "key_id", "required": true, "schema": { "description": "API key identifier to revoke", "title": "Key Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Revoke API key", "tags": [ "API Keys" ] } }, "/v1/auth/email/otp": { "post": { "description": "Send a six-digit email OTP for a short-lived session bootstrap.", "operationId": "request_email_otp_v1_auth_email_otp_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailOtpRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OtpSentResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Request email OTP", "tags": [ "Auth" ] } }, "/v1/auth/email/verify": { "post": { "description": "Verify an email OTP and issue a short-lived session token.", "operationId": "verify_email_otp_v1_auth_email_verify_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerifyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } }, "description": "Successful Response" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "summary": "Verify email OTP", "tags": [ "Auth" ] } }, "/v1/auth/session": { "delete": { "description": "Revoke the presented at_ session token. The token is rejected on all subsequent requests. API keys do not have sessions; revoke them via DELETE /v1/api-keys/{key_id}.", "operationId": "logout_v1_auth_session_delete", "responses": { "204": { "description": "Successful Response" }, "400": { "description": "Authenticated with an API key instead of an at_ session token" }, "401": { "description": "Missing or invalid authentication" } }, "security": [ { "HTTPBearer": [] } ], "summary": "End session", "tags": [ "Auth" ] } }, "/v1/drops": { "get": { "description": "Lists drops owned by the authenticated account using cursor pagination. Pass ?slug= to resolve a drop URL's slug back to its drop id: the filter is owner-scoped and returns 0 or 1 drops. Custom-domain URL resolution stays client-side for now (extract the slug from the URL before calling).", "operationId": "list_drops", "parameters": [ { "description": "Resolve a drop URL slug to its drop (owner-scoped; returns 0 or 1 drops). Use the drop id from the result for every other endpoint.", "in": "query", "name": "slug", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolve a drop URL slug to its drop (owner-scoped; returns 0 or 1 drops). Use the drop id from the result for every other endpoint.", "title": "Slug" } }, { "description": "Opaque cursor from the previous page of results", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from the previous page of results", "title": "Cursor" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Maximum number of results to return", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDropsResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "422": { "description": "Invalid request payload" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List drops", "tags": [ "Drops" ] }, "post": { "description": "Publishes a drop from a completed staged upload session or a server-fetched source_url, and returns a permanent drop URL.", "operationId": "create_drop", "parameters": [ { "description": "Unique string (v4 UUID recommended). Same key within 24h returns cached response.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Unique string (v4 UUID recommended). Same key within 24h returns cached response.", "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "examples": { "source_url": { "summary": "Publish from a URL", "value": { "options": { "title": "Imported" }, "source_url": "https://example.com/report.html" } }, "upload_id": { "summary": "Publish completed upload session", "value": { "options": { "title": "Uploaded distribution" }, "upload_id": "upl_01hzz00000000000000000" } } }, "schema": { "oneOf": [ { "description": "Publish a completed staged upload session.", "properties": { "metadata": { "additionalProperties": true, "description": "Custom user or agent metadata stored with the drop", "example": { "campaign": "summer-launch", "prompt_id": "msg_123" }, "type": "object" }, "options": { "additionalProperties": false, "description": "Drop settings (dropthis-owned serving behavior) applied at publish", "properties": { "domain": { "description": "Hostname of a custom domain registered to this account (Pro plan). The drop is served at https://{slug}.{domain}/ instead of the shared pool. Publish-only: a drop never moves between domains after creation.", "example": "pages.example.com", "nullable": true, "type": "string" }, "expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "noindex": { "description": "Prevent search indexing", "nullable": true, "type": "boolean" }, "password": { "description": "Password required to view the drop. Not available on any current plan yet (coming with Pro) \u2014 setting it returns 403.", "nullable": true, "type": "string" }, "title": { "default": "Untitled", "example": "Summer Launch", "type": "string" }, "visibility": { "default": "public", "enum": [ "public", "unlisted" ], "type": "string" } }, "type": "object" }, "upload_id": { "example": "upl_01hzz00000000000000000", "type": "string" } }, "required": [ "upload_id" ], "type": "object" }, { "description": "Publish by fetching a public URL server-side (SSRF-protected, single URL).", "properties": { "metadata": { "additionalProperties": true, "description": "Custom user or agent metadata stored with the drop", "example": { "campaign": "summer-launch", "prompt_id": "msg_123" }, "type": "object" }, "options": { "additionalProperties": false, "description": "Drop settings (dropthis-owned serving behavior) applied at publish", "properties": { "domain": { "description": "Hostname of a custom domain registered to this account (Pro plan). The drop is served at https://{slug}.{domain}/ instead of the shared pool. Publish-only: a drop never moves between domains after creation.", "example": "pages.example.com", "nullable": true, "type": "string" }, "expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "noindex": { "description": "Prevent search indexing", "nullable": true, "type": "boolean" }, "password": { "description": "Password required to view the drop. Not available on any current plan yet (coming with Pro) \u2014 setting it returns 403.", "nullable": true, "type": "string" }, "title": { "default": "Untitled", "example": "Summer Launch", "type": "string" }, "visibility": { "default": "public", "enum": [ "public", "unlisted" ], "type": "string" } }, "type": "object" }, "source_url": { "example": "https://example.com/report.html", "format": "uri", "type": "string" } }, "required": [ "source_url" ], "type": "object" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DropResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "403": { "description": "Plan quota exceeded" }, "413": { "description": "source_url content exceeds the size limit" }, "422": { "description": "Invalid request payload" }, "502": { "description": "source_url could not be fetched" }, "504": { "description": "source_url fetch timed out" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Publish a drop", "tags": [ "Drops" ] } }, "/v1/drops/{drop_id}": { "delete": { "description": "Soft-deletes a drop and removes its published edge content.", "operationId": "delete_drop", "parameters": [ { "description": "Stable drop identifier", "in": "path", "name": "drop_id", "required": true, "schema": { "description": "Stable drop identifier", "title": "Drop Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Drop not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Delete a drop", "tags": [ "Drops" ] }, "get": { "description": "Returns owner-visible metadata for one drop. Drops owned by another account return 404.", "operationId": "get_drop", "parameters": [ { "description": "Stable drop identifier", "in": "path", "name": "drop_id", "required": true, "schema": { "description": "Stable drop identifier", "title": "Drop Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DropResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Drop not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a drop", "tags": [ "Drops" ] }, "patch": { "description": "Updates drop settings (title, visibility, password, noindex, expiry) and metadata without creating a new deployment. The drop's content and URL are unchanged. Content updates use POST /v1/drops/{drop_id}/deployments.", "operationId": "update_drop", "parameters": [ { "description": "Stable drop identifier", "in": "path", "name": "drop_id", "required": true, "schema": { "description": "Stable drop identifier", "title": "Drop Id", "type": "string" } }, { "in": "header", "name": "If-Revision", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "If-Revision" } } ], "requestBody": { "content": { "application/json": { "examples": { "settings": { "summary": "Update title and visibility", "value": { "options": { "title": "Updated Launch", "visibility": "unlisted" } } } }, "schema": { "additionalProperties": false, "description": "Update drop settings and metadata. Content updates use POST /v1/drops/{drop_id}/deployments.", "properties": { "metadata": { "additionalProperties": true, "description": "Custom user or agent metadata stored with the drop", "example": { "campaign": "summer-launch", "prompt_id": "msg_123" }, "type": "object" }, "options": { "additionalProperties": false, "description": "Drop settings to update", "properties": { "expires_at": { "format": "date-time", "nullable": true, "type": "string" }, "noindex": { "nullable": true, "type": "boolean" }, "password": { "description": "Set or clear the drop password. Setting one is not available on any current plan yet (coming with Pro) and returns 403; clearing with null is allowed.", "nullable": true, "type": "string" }, "title": { "maxLength": 500, "nullable": true, "type": "string" }, "visibility": { "enum": [ "public", "unlisted" ], "nullable": true, "type": "string" } }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DropResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "403": { "description": "Plan quota exceeded" }, "404": { "description": "Drop not found" }, "409": { "description": "Revision conflict" }, "422": { "description": "Invalid request payload" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update drop settings", "tags": [ "Drops" ] } }, "/v1/drops/{drop_id}/content": { "get": { "description": "Owner-only read-back of the drop's CURRENT deployment. Returns a JSON manifest of the deployment's files (paths, sizes, content types, entry) by default; pass ?path= to download one file's exact stored bytes with its stored content type. Works regardless of any viewer password. For a historical content version use GET /v1/drops/{drop_id}/deployments/{deployment_id}/content.", "operationId": "get_drop_content", "parameters": [ { "description": "Stable drop identifier", "in": "path", "name": "drop_id", "required": true, "schema": { "description": "Stable drop identifier", "title": "Drop Id", "type": "string" } }, { "description": "Return this file's raw stored bytes (with its stored content type) instead of the JSON manifest. Must be one of the manifest's files[].path values.", "in": "query", "name": "path", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return this file's raw stored bytes (with its stored content type) instead of the JSON manifest. Must be one of the manifest's files[].path values.", "title": "Path" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentContentManifest" } } }, "description": "JSON manifest of the deployment's files, or the raw bytes of one file when ?path= is given" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Drop, deployment, or file path not found (deleted drops have no readable content)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read back current drop content", "tags": [ "Drops" ] } }, "/v1/drops/{drop_id}/deployments": { "get": { "description": "List immutable content deployments for one drop using cursor pagination.", "operationId": "list_drop_deployments", "parameters": [ { "description": "Stable drop identifier", "in": "path", "name": "drop_id", "required": true, "schema": { "description": "Stable drop identifier", "title": "Drop Id", "type": "string" } }, { "description": "Opaque cursor from the previous page of results", "in": "query", "name": "cursor", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque cursor from the previous page of results", "title": "Cursor" } }, { "description": "Maximum number of results to return", "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "description": "Maximum number of results to return", "maximum": 100, "minimum": 1, "title": "Limit", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDropDeploymentsResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Drop not found" }, "422": { "description": "Invalid request payload" } }, "security": [ { "HTTPBearer": [] } ], "summary": "List drop deployments", "tags": [ "Drops" ] }, "post": { "description": "Updates a drop's content by creating a new immutable deployment and making it current once publish succeeds. The drop's URL and settings are unchanged. Returns 200 with the updated parent drop (DropResponse), not the deployment record \u2014 the drop carries the URL and revision agents need next.", "operationId": "create_drop_deployment", "parameters": [ { "description": "Stable drop identifier", "in": "path", "name": "drop_id", "required": true, "schema": { "description": "Stable drop identifier", "title": "Drop Id", "type": "string" } }, { "in": "header", "name": "If-Revision", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "If-Revision" } }, { "description": "Unique string (v4 UUID recommended). Same key within 24h returns cached response.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Unique string (v4 UUID recommended). Same key within 24h returns cached response.", "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "examples": { "source_url": { "summary": "Deploy from a URL", "value": { "source_url": "https://example.com/report.html" } }, "upload_id": { "summary": "Deploy a completed upload session", "value": { "upload_id": "upl_01hzz00000000000000000" } } }, "schema": { "description": "Updates a drop's content only: a deployment ships a new content version and keeps the drop's URL and settings. Change settings (title, visibility, password, noindex, expiry, metadata) with PATCH /v1/drops/{drop_id} instead \u2014 sending them here is rejected.", "oneOf": [ { "additionalProperties": false, "description": "Deploy a completed staged upload session as a new content version.", "properties": { "upload_id": { "example": "upl_01hzz00000000000000000", "type": "string" } }, "required": [ "upload_id" ], "type": "object" }, { "additionalProperties": false, "description": "Deploy by fetching a public URL server-side (SSRF-protected, single URL).", "properties": { "source_url": { "example": "https://example.com/report.html", "format": "uri", "type": "string" } }, "required": [ "source_url" ], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DropResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "403": { "description": "Plan quota exceeded" }, "404": { "description": "Drop not found" }, "409": { "description": "Revision conflict" }, "413": { "description": "source_url content exceeds the size limit" }, "422": { "description": "Invalid request payload" }, "502": { "description": "source_url could not be fetched" }, "504": { "description": "source_url fetch timed out" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Update a drop's content", "tags": [ "Drops" ] } }, "/v1/drops/{drop_id}/deployments/{deployment_id}": { "get": { "description": "Return metadata for one immutable content deployment belonging to a drop.", "operationId": "get_drop_deployment", "parameters": [ { "description": "Stable drop identifier", "in": "path", "name": "drop_id", "required": true, "schema": { "description": "Stable drop identifier", "title": "Drop Id", "type": "string" } }, { "description": "Stable deployment identifier", "in": "path", "name": "deployment_id", "required": true, "schema": { "description": "Stable deployment identifier", "title": "Deployment Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DropDeploymentResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Drop not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get a drop deployment", "tags": [ "Drops" ] } }, "/v1/drops/{drop_id}/deployments/{deployment_id}/content": { "get": { "description": "Owner-only read-back of one immutable deployment's content. Returns a JSON manifest of its files (paths, sizes, content types, entry) by default; pass ?path= to download one file's exact stored bytes with its stored content type. Works for SUPERSEDED deployments too: downloading an old version's files and republishing them with POST /v1/drops/{drop_id}/deployments is the rollback path (decision 0052).", "operationId": "get_drop_deployment_content", "parameters": [ { "description": "Stable drop identifier", "in": "path", "name": "drop_id", "required": true, "schema": { "description": "Stable drop identifier", "title": "Drop Id", "type": "string" } }, { "description": "Stable deployment identifier", "in": "path", "name": "deployment_id", "required": true, "schema": { "description": "Stable deployment identifier", "title": "Deployment Id", "type": "string" } }, { "description": "Return this file's raw stored bytes (with its stored content type) instead of the JSON manifest. Must be one of the manifest's files[].path values.", "in": "query", "name": "path", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Return this file's raw stored bytes (with its stored content type) instead of the JSON manifest. Must be one of the manifest's files[].path values.", "title": "Path" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentContentManifest" } } }, "description": "JSON manifest of the deployment's files, or the raw bytes of one file when ?path= is given" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Drop, deployment, or file path not found (deleted drops have no readable content)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Read back a deployment's content", "tags": [ "Drops" ] } }, "/v1/uploads": { "post": { "description": "Create a staged upload session for local files, folders, binaries, or generated artifacts that should not be sent through inline publish. The request declares a file manifest before any bytes are uploaded; Dropthis validates plan limits, path safety, duplicate paths, entry file membership, and active upload-session caps. The response returns direct storage upload targets plus an upload_id; it does not create or mutate a drop until the client uploads bytes, completes the session, and publishes with POST /v1/drops or a deployment endpoint. Use Idempotency-Key when retrying session creation.", "operationId": "create_upload_session", "parameters": [ { "description": "Unique string (v4 UUID recommended). Same key within 24h returns cached response.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Unique string (v4 UUID recommended). Same key within 24h returns cached response.", "title": "Idempotency-Key" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadSessionRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUploadSessionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "403": { "description": "Plan quota exceeded" }, "409": { "description": "Upload session conflict or idempotency key reuse" }, "422": { "description": "Invalid upload manifest or verification failure" }, "429": { "description": "Too many active upload sessions" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Create upload session", "tags": [ "uploads" ] } }, "/v1/uploads/{upload_id}": { "delete": { "description": "Cancel an unpublished staged upload session and mark its staging objects for cleanup. This is for abandoning created, completed, failed, or expired sessions before they are consumed by publish; it returns no response body. Publishing or already published sessions cannot be cancelled because they may be tied to a durable drop or deployment. Unknown or cross-account upload IDs are always reported as not found.", "operationId": "cancel_upload_session", "parameters": [ { "description": "Upload session identifier returned by create_upload_session. Unknown or cross-account upload IDs return 404.", "in": "path", "name": "upload_id", "required": true, "schema": { "description": "Upload session identifier returned by create_upload_session. Unknown or cross-account upload IDs return 404.", "title": "Upload Id", "type": "string" } } ], "responses": { "204": { "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Upload session not found" }, "409": { "description": "Upload session conflict or idempotency key reuse" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Cancel upload session", "tags": [ "uploads" ] }, "get": { "description": "Return owner-visible status and manifest details for one staged upload session. Use this to recover file IDs, paths, object keys, verification state, and the entry file before completing or publishing. The endpoint does not list all uploads and does not refresh signed upload URLs; create a new upload session if the signed URLs have expired. Unknown or cross-account upload IDs are always reported as not found.", "operationId": "get_upload_session", "parameters": [ { "description": "Upload session identifier returned by create_upload_session. Unknown or cross-account upload IDs return 404.", "in": "path", "name": "upload_id", "required": true, "schema": { "description": "Upload session identifier returned by create_upload_session. Unknown or cross-account upload IDs return 404.", "title": "Upload Id", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Upload session not found" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } }, "description": "Validation Error" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Get upload session", "tags": [ "uploads" ] } }, "/v1/uploads/{upload_id}/complete": { "post": { "description": "Verify staged objects and mark an upload session complete so it can be published through POST /v1/drops or a deployment endpoint. Clients upload bytes directly to storage first using the signed targets from create_upload_session; this endpoint takes no request body. Completion checks object existence, size, content type, and any declared checksum_sha256 against the manifest and fails the session if verification does not match. Use Idempotency-Key when retrying completion; sessions past the completion grace window return 410.", "operationId": "complete_upload_session", "parameters": [ { "description": "Upload session identifier returned by create_upload_session. Unknown or cross-account upload IDs return 404.", "in": "path", "name": "upload_id", "required": true, "schema": { "description": "Upload session identifier returned by create_upload_session. Unknown or cross-account upload IDs return 404.", "title": "Upload Id", "type": "string" } }, { "description": "Unique string (v4 UUID recommended). Same key within 24h returns cached response.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "anyOf": [ { "maxLength": 64, "type": "string" }, { "type": "null" } ], "description": "Unique string (v4 UUID recommended). Same key within 24h returns cached response.", "title": "Idempotency-Key" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSessionResponse" } } }, "description": "Successful Response" }, "401": { "description": "Missing or invalid authentication" }, "404": { "description": "Upload session not found" }, "409": { "description": "Upload session conflict or idempotency key reuse" }, "410": { "description": "Upload session expired" }, "422": { "description": "Invalid upload manifest or verification failure" } }, "security": [ { "HTTPBearer": [] } ], "summary": "Complete upload session", "tags": [ "uploads" ] } } } }