{"openapi":"3.1.0","info":{"title":"artidrop API","version":"1.0.0","description":"The publishing layer for AI agents. Publish HTML, Markdown, or multi-file sites and get back a shareable URL. No login required.\n\nRate limits: 5 publishes/hour (anonymous) or 60/hour (authenticated), 300 reads/hour. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included on every response.\n\nFor full management (update, delete, list artifacts), use the MCP endpoint with an API key. See /.well-known/mcp.json for MCP discovery.","contact":{"name":"Artidrop","url":"https://artidrop.ai"}},"servers":[{"url":"https://artidrop.ai"}],"paths":{"/v1/artifacts":{"post":{"operationId":"publishArtifact","summary":"Publish content as a shareable URL","description":"Publish HTML or Markdown content. Returns a permanent URL. Authentication is optional — anonymous publishes are allowed (5/hour).","security":[{},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateArtifactRequest"}}}},"responses":{"201":{"description":"Artifact created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Validation error (empty content, invalid format, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artifacts/upload":{"post":{"operationId":"uploadSite","summary":"Upload a ZIP archive as a multi-file site","description":"Upload a ZIP file containing HTML, CSS, JS, images, and other assets as a complete site artifact. The ZIP must include an index.html at its root. Authentication is optional.","security":[{},{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"ZIP file containing the site"},"title":{"type":"string","maxLength":200,"description":"Site title"},"description":{"type":"string","maxLength":500,"description":"Short description"},"visibility":{"type":"string","enum":["public","unlisted","private"],"default":"unlisted"},"format":{"type":"string","enum":["markdown"],"description":"Set to 'markdown' to upload a markdown file with images as a ZIP bundle"}}}}}},"responses":{"201":{"description":"Site artifact created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"400":{"description":"Validation error (no index.html, invalid ZIP, too large, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artifacts/{id}":{"get":{"operationId":"getArtifact","summary":"Get artifact metadata","description":"Returns metadata for an artifact including its shareable URL and content URL. Public and unlisted artifacts are accessible without authentication. Private artifacts require authentication from the owner.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Artifact ID (art_xxx) or short ID (e.g. wV8i4fgdwP)","schema":{"type":"string"}}],"responses":{"200":{"description":"Artifact metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artifact"}}}},"403":{"description":"Private artifact, authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/artifacts/{id}/versions":{"get":{"operationId":"listVersions","summary":"List version history","description":"Returns all versions of an artifact with their sizes and timestamps.","security":[{},{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Artifact ID or short ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Version list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionList"}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/a/{shortId}":{"get":{"operationId":"getArtifactContent","summary":"Get artifact content (content-negotiated)","description":"Returns artifact content in the requested format. Use ?format=text for raw source, ?format=json for metadata + content, or omit for HTML. Also respects Accept headers (text/plain, application/json). Programmatic clients (curl, Python requests, etc.) automatically receive plain text.","parameters":[{"name":"shortId","in":"path","required":true,"description":"Artifact short ID (e.g. wV8i4fgdwP)","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"Response format override","schema":{"type":"string","enum":["text","json"]}}],"responses":{"200":{"description":"Artifact content. Content-Type depends on format: text/plain for text, application/json for json, text/html for default.","content":{"text/plain":{"schema":{"type":"string","description":"Raw HTML or Markdown source"}},"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Artifact"},{"type":"object","properties":{"content":{"type":"string","description":"Full HTML or Markdown content"}}}]}}}},"404":{"description":"Artifact not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"CreateArtifactRequest":{"type":"object","required":["content","format"],"properties":{"content":{"type":"string","minLength":1,"description":"HTML or Markdown content to publish"},"format":{"type":"string","enum":["html","markdown"],"description":"Content format"},"title":{"type":"string","maxLength":200,"description":"Artifact title (auto-extracted from content if omitted)"},"description":{"type":"string","maxLength":500,"description":"Short description (auto-extracted from content if omitted)"},"visibility":{"type":"string","enum":["public","unlisted","private"],"default":"unlisted","description":"public = indexed by search engines, unlisted = accessible via URL only, private = owner-only (requires authentication)"},"images":{"type":"array","description":"Images for markdown content. Each entry has a relative path and base64-encoded data.","items":{"type":"object","required":["path","data"],"properties":{"path":{"type":"string","description":"Relative path as referenced in the markdown (e.g., 'images/demo.png')"},"data":{"type":"string","description":"Base64-encoded image file data"}}}}}},"Artifact":{"type":"object","properties":{"id":{"type":"string","description":"Artifact ID (art_xxx)","examples":["art_a1b2c3d4"]},"url":{"type":"string","format":"uri","description":"Shareable artifact page URL"},"content_url":{"type":"string","format":"uri","description":"Direct content URL (for iframe embedding)"},"title":{"type":"string"},"description":{"type":"string"},"format":{"type":"string","enum":["html","markdown","site"]},"visibility":{"type":"string","enum":["public","unlisted","private"]},"version":{"type":"integer","description":"Current version number"},"size_bytes":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"owner":{"type":"object","properties":{"id":{"type":"string"}}}}},"Version":{"type":"object","properties":{"version":{"type":"integer"},"size_bytes":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"VersionList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Version"}},"total":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code","examples":["VALIDATION_ERROR","NOT_FOUND","RATE_LIMITED"]},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"object","description":"Additional context (e.g. field name, retry_after seconds)"}},"required":["code","message"]}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key with sk- prefix. Optional for publish, get, and versions. Create keys at https://artidrop.ai after logging in."}}}}