{"openapi":"3.1.0","info":{"title":"staticfiles.ai API","version":"1.0","description":"Agent artifact hosting for small static HTML/CSS/JS/JSON/Markdown bundles."},"servers":[{"url":"https://staticfiles.ai/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/artifacts":{"post":{"operationId":"publishArtifact","summary":"Publish a new artifact (§8.3).","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Stable key for this agent run; dedupes retried writes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishRequest"}}}},"responses":{"201":{"description":"Artifact created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublishResponse"}}}},"400":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/artifacts/{id}":{"get":{"operationId":"getArtifactStatus","summary":"Get artifact status (§8.4).","parameters":[{"name":"id","in":"path","required":true,"description":"Artifact id (e.g. k7Qm2Xp9).","schema":{"type":"string"}}],"responses":{"200":{"description":"Artifact status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"404":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"extendArtifactExpiry","summary":"Extend artifact expiry (§8.7).","parameters":[{"name":"id","in":"path","required":true,"description":"Artifact id (e.g. k7Qm2Xp9).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchRequest"}}}},"responses":{"200":{"description":"Updated artifact status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"}}}},"400":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteArtifact","summary":"Delete an artifact (§8.6).","parameters":[{"name":"id","in":"path","required":true,"description":"Artifact id (e.g. k7Qm2Xp9).","schema":{"type":"string"}}],"responses":{"200":{"description":"Artifact deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"401":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/artifacts/{id}/versions":{"post":{"operationId":"updateArtifact","summary":"Publish a new version of an artifact (§8.5).","parameters":[{"name":"id","in":"path","required":true,"description":"Artifact id (e.g. k7Qm2Xp9).","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Stable key for this agent run; dedupes retried writes.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRequest"}}}},"responses":{"201":{"description":"New version created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateResponse"}}}},"400":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/capabilities":{"get":{"operationId":"getCapabilities","summary":"Service capabilities + limits (§8.1).","responses":{"200":{"description":"Capabilities document.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilitiesResponse"}}}},"401":{"description":"Error (§10 model).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key: Authorization: Bearer sfai_..."}},"schemas":{"Provenance":{"type":"object","properties":{"agent":{"type":"string"},"agent_run_id":{"type":"string"},"task":{"type":"string"},"source":{"type":"string"}}},"PublishFileInput":{"type":"object","required":["path","content_type","content"],"properties":{"path":{"type":"string","maxLength":256},"content_type":{"type":"string","enum":["text/html","text/css","text/javascript","application/javascript","application/json","text/plain","text/markdown","image/svg+xml"]},"encoding":{"type":"string","enum":["utf8","base64"]},"content":{"type":"string"}}},"PublishRequest":{"type":"object","required":["entrypoint","files"],"properties":{"name":{"type":"string"},"entrypoint":{"type":"string"},"ttl_seconds":{"type":"integer","default":604800,"maximum":2592000},"routing":{"type":"string","enum":["strict","spa"],"default":"strict"},"visibility":{"type":"string","enum":["unlisted"],"default":"unlisted"},"provenance":{"$ref":"#/components/schemas/Provenance"},"files":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/PublishFileInput"}}}},"PublishLimits":{"type":"object","required":["max_total_bytes","max_files","max_ttl_seconds"],"properties":{"max_total_bytes":{"type":"integer"},"max_files":{"type":"integer"},"max_ttl_seconds":{"type":"integer"}}},"PublishResponse":{"type":"object","required":["artifact_id","version","url","entrypoint_url","manifest_url","status_url","expires_at","sha256","manage_token","delete_url","limits"],"properties":{"artifact_id":{"type":"string"},"version":{"type":"integer"},"url":{"type":"string","format":"uri"},"entrypoint_url":{"type":"string","format":"uri"},"manifest_url":{"type":"string","format":"uri"},"status_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"sha256":{"type":"string"},"manage_token":{"type":"string"},"delete_url":{"type":"string","format":"uri"},"limits":{"$ref":"#/components/schemas/PublishLimits"}}},"StatusResponse":{"type":"object","required":["artifact_id","status","version","url","created_at","expires_at","bytes","file_count","sha256"],"properties":{"artifact_id":{"type":"string"},"status":{"type":"string","enum":["active","expired","deleted","disabled"]},"version":{"type":"integer"},"url":{"type":"string","format":"uri"},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"bytes":{"type":"integer"},"file_count":{"type":"integer"},"sha256":{"type":"string"},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"UpdateRequest":{"type":"object","required":["files"],"properties":{"entrypoint":{"type":"string"},"ttl_seconds":{"type":"integer","maximum":2592000},"routing":{"type":"string","enum":["strict","spa"]},"files":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/PublishFileInput"}}}},"UpdateResponse":{"type":"object","required":["artifact_id","version","url","manifest_url","previous_version","expires_at","sha256"],"properties":{"artifact_id":{"type":"string"},"version":{"type":"integer"},"url":{"type":"string","format":"uri"},"manifest_url":{"type":"string","format":"uri"},"previous_version":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"},"sha256":{"type":"string"}}},"PatchRequest":{"type":"object","required":["ttl_seconds"],"properties":{"ttl_seconds":{"type":"integer","maximum":2592000}}},"DeleteResponse":{"type":"object","required":["artifact_id","status","deleted_at"],"properties":{"artifact_id":{"type":"string"},"status":{"type":"string","enum":["deleted"]},"deleted_at":{"type":"string","format":"date-time"}}},"CapabilitiesResponse":{"type":"object","required":["service","version","purpose","api","openapi","mcp","artifact_host","default_ttl_seconds","max_ttl_seconds","max_total_bytes","max_file_bytes","max_files","max_versions","allowed_content_types","blocked_types","routing_modes","visibility_modes","required_headers"],"properties":{"service":{"type":"string"},"version":{"type":"string"},"purpose":{"type":"string","enum":["agent_artifact_hosting"]},"api":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"artifact_host":{"type":"string","format":"uri"},"default_ttl_seconds":{"type":"integer"},"max_ttl_seconds":{"type":"integer"},"max_total_bytes":{"type":"integer"},"max_file_bytes":{"type":"integer"},"max_files":{"type":"integer"},"max_versions":{"type":"integer"},"allowed_content_types":{"type":"array","items":{"type":"string"}},"blocked_types":{"type":"array","items":{"type":"string"}},"routing_modes":{"type":"array","items":{"type":"string"}},"visibility_modes":{"type":"array","items":{"type":"string"}},"required_headers":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable","docs_url"],"properties":{"code":{"type":"string","enum":["unauthorized","forbidden","rate_limited","payload_too_large","too_many_files","file_type_blocked","invalid_path","missing_entrypoint","entrypoint_not_html","ttl_too_long","artifact_not_found","artifact_expired","artifact_deleted","idempotency_conflict","internal_error","bad_request","validation_failed","not_found","method_not_allowed"]},"message":{"type":"string"},"retryable":{"type":"boolean"},"docs_url":{"type":"string","format":"uri"}}}}},"ArtifactManifest":{"type":"object","description":"Served at the artifact host; schema: https://staticfiles.ai/schemas/artifact-manifest-v1.json.","required":["schema","service","artifact_id","version","url","entrypoint","routing","created_at","expires_at","visibility","total_bytes","sha256","files"],"properties":{"schema":{"type":"string","const":"https://staticfiles.ai/schemas/artifact-manifest-v1.json"},"service":{"type":"string"},"artifact_id":{"type":"string"},"version":{"type":"integer"},"url":{"type":"string","format":"uri"},"entrypoint":{"type":"string"},"routing":{"type":"string","enum":["strict","spa"]},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"visibility":{"type":"string","enum":["unlisted"]},"total_bytes":{"type":"integer","maximum":5242880},"sha256":{"type":"string"},"provenance":{"$ref":"#/components/schemas/Provenance"},"files":{"type":"array","items":{"type":"object","required":["path","content_type","bytes","sha256"],"properties":{"path":{"type":"string"},"content_type":{"type":"string"},"bytes":{"type":"integer","maximum":1048576},"sha256":{"type":"string"}}}}}}}}}