{"openapi":"3.1.0","info":{"title":"Morph EFS API","description":"Create, mount, inspect, and delete Morph EFS filesystems through the public service API. All public endpoints require a Morph bearer token.","license":{"name":""},"version":"0.1.0"},"servers":[{"url":"https://efs.svc.cloud.morph.so","description":"Production"}],"paths":{"/v1/dashboard-sessions":{"post":{"tags":["Dashboard"],"summary":"Create a dashboard session","description":"Creates a short-lived browser handoff URL for the authenticated owner's Morph EFS dashboard. Morph API keys are never placed in browser URLs.","operationId":"create_dashboard_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDashboardSessionRequest"}}},"required":true},"responses":{"201":{"description":"Dashboard handoff URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardSession"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Filesystem not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]}},"/v1/filesystems":{"get":{"tags":["Filesystems"],"summary":"List filesystems","description":"Returns filesystems owned by the authenticated principal, ordered by the service response.","operationId":"list_filesystems","responses":{"200":{"description":"Owner-scoped filesystems","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilesystemList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]},"post":{"tags":["Filesystems"],"summary":"Create a filesystem","description":"Creates a named Morph EFS filesystem for the authenticated owner. Reusing an idempotency key returns the existing successful result for the same request.","operationId":"create_filesystem","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFilesystemRequest"}}},"required":true},"responses":{"201":{"description":"Filesystem created or reused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filesystem"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency conflict or lifecycle conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]}},"/v1/filesystems/{id}":{"get":{"tags":["Filesystems"],"summary":"Get a filesystem","description":"Returns a filesystem by id or by its owner-scoped name.","operationId":"get_filesystem","parameters":[{"name":"id","in":"path","description":"Filesystem id or owner-scoped filesystem name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filesystem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filesystem"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Filesystem not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]},"delete":{"tags":["Filesystems"],"summary":"Delete a filesystem","description":"Requests deletion for a filesystem identified by id or by its owner-scoped name.","operationId":"delete_filesystem","parameters":[{"name":"id","in":"path","description":"Filesystem id or owner-scoped filesystem name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filesystem delete accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Filesystem"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Filesystem not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]}},"/v1/filesystems/{id}/mount-sessions":{"post":{"tags":["Mount sessions"],"summary":"Create a mount session","description":"Creates a short-lived mount session for a ready filesystem and returns the runtime launch envelope required by compatible local clients.","operationId":"create_mount_session","parameters":[{"name":"id","in":"path","description":"Filesystem id or owner-scoped filesystem name","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMountSessionRequest"}}},"required":true},"responses":{"201":{"description":"Mount session runtime envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MountSession"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Filesystem not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Filesystem is not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]},"delete":{"tags":["Mount sessions"],"summary":"Revoke a filesystem mount session","description":"Revokes the active mount session associated with a filesystem id or owner-scoped filesystem name.","operationId":"delete_mount_session_for_filesystem","parameters":[{"name":"id","in":"path","description":"Filesystem id or owner-scoped filesystem name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Mount session revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MountSessionDeleteResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Filesystem not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]}},"/v1/filesystems/{id}/usage":{"get":{"tags":["Usage"],"summary":"Get filesystem usage","description":"Returns usage and active mount counts for a filesystem identified by id or owner-scoped name.","operationId":"get_filesystem_usage","parameters":[{"name":"id","in":"path","description":"Filesystem id or owner-scoped filesystem name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filesystem usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilesystemUsage"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Filesystem not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]}},"/v1/mount-sessions/{id}":{"delete":{"tags":["Mount sessions"],"summary":"Revoke a mount session","description":"Revokes a mount session by id. The request accepts either the owner bearer token or the short-lived runtime token issued for that session.","operationId":"delete_mount_session","parameters":[{"name":"id","in":"path","description":"Mount session id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Mount session revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MountSessionDeleteResponse"}}}},"400":{"description":"Invalid mount session id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"security":[{"bearer_auth":[]}]}}},"components":{"schemas":{"CreateDashboardSessionRequest":{"type":"object","properties":{"filesystem":{"type":["string","null"],"description":"Optional filesystem id or owner-scoped name to open in the dashboard.","example":"build-cache"}},"additionalProperties":false},"CreateFilesystemRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Owner-scoped filesystem name used for later lookups.","example":"build-cache"},"ttl_seconds":{"type":["integer","null"],"format":"int64","description":"Optional lifetime for the filesystem, in seconds.","example":3600,"minimum":0}},"additionalProperties":false},"CreateMountSessionRequest":{"type":"object","properties":{"mount_path":{"type":["string","null"],"description":"Optional local mount path requested by the caller.","example":"/mnt/morph/build-cache"},"ttl_seconds":{"type":["integer","null"],"format":"int64","description":"Optional mount-session lifetime, in seconds.","example":3600,"minimum":0}},"additionalProperties":false},"DashboardSession":{"type":"object","required":["url","expires_at_unix_seconds"],"properties":{"expires_at_unix_seconds":{"type":"integer","format":"int64","description":"Unix timestamp after which the handoff URL is no longer valid.","example":1717099500,"minimum":0},"url":{"type":"string","description":"Short-lived browser handoff URL.","example":"https://efs.svc.cloud.morph.so/web/efs/session/dsh_example"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Public error message for the failed request.","example":"filesystem not found"}}},"Filesystem":{"type":"object","required":["id","name","status","mount_path","created_at_unix_seconds","active_mounts"],"properties":{"active_mounts":{"type":"integer","description":"Number of active mount sessions.","example":1,"minimum":0},"created_at_unix_seconds":{"type":"integer","format":"int64","description":"Unix timestamp for when the filesystem was created.","example":1717099200,"minimum":0},"id":{"type":"string","description":"Stable filesystem identifier.","example":"fs_00000001"},"mount_path":{"type":"string","description":"Local path used by compatible runtimes.","example":"/mnt/morph/build-cache"},"name":{"type":"string","description":"Owner-scoped filesystem name.","example":"build-cache"},"status":{"type":"string","description":"Current lifecycle status.","example":"ready"},"ttl_seconds":{"type":["integer","null"],"format":"int64","description":"Optional lifetime configured for the filesystem, in seconds.","example":3600,"minimum":0}}},"FilesystemList":{"type":"object","required":["filesystems"],"properties":{"filesystems":{"type":"array","items":{"$ref":"#/components/schemas/Filesystem"},"description":"Filesystems visible to the authenticated owner."}}},"FilesystemUsage":{"type":"object","required":["filesystem_id","name","status","active_mounts"],"properties":{"active_mounts":{"type":"integer","description":"Number of active mount sessions.","example":1,"minimum":0},"bytes_used":{"type":["integer","null"],"format":"int64","description":"Last sampled byte count, when available.","example":1073741824,"minimum":0},"estimated_monthly_cost_cents":{"type":["integer","null"],"format":"int64","description":"Estimated monthly cost in cents, when available.","example":125,"minimum":0},"filesystem_id":{"type":"string","description":"Filesystem identifier.","example":"fs_00000001"},"name":{"type":"string","description":"Owner-scoped filesystem name.","example":"build-cache"},"sampled_at_unix_seconds":{"type":["integer","null"],"format":"int64","description":"Unix timestamp for the usage sample, when available.","example":1717099200,"minimum":0},"status":{"type":"string","description":"Current lifecycle status.","example":"ready"}}},"MountSession":{"type":"object","required":["mount_session_id","filesystem_id","name","mount_path","expires_at_unix_seconds","runtime_token","runtime"],"properties":{"expires_at_unix_seconds":{"type":"integer","format":"int64","description":"Unix timestamp after which the mount session is no longer valid.","example":1717102800,"minimum":0},"filesystem_id":{"type":"string","description":"Filesystem attached by this mount session.","example":"fs_00000001"},"mount_path":{"type":"string","description":"Local path selected for the mount session.","example":"/mnt/morph/build-cache"},"mount_session_id":{"type":"string","description":"Stable mount session identifier.","example":"ms_00000001"},"name":{"type":"string","description":"Owner-scoped filesystem name.","example":"build-cache"},"runtime":{"$ref":"#/components/schemas/RuntimeLaunch","description":"Runtime launch command for compatible local clients."},"runtime_token":{"type":"string","description":"Short-lived token used by the local runtime.","example":"rt_example"}}},"MountSessionDeleteResponse":{"type":"object","required":["mount_session_id","revoked"],"properties":{"mount_session_id":{"type":"string","description":"Revoked mount session identifier.","example":"ms_00000001"},"revoked":{"type":"boolean","description":"Whether a matching active mount session was revoked.","example":true}}},"RuntimeLaunch":{"type":"object","required":["binary","args"],"properties":{"args":{"type":"array","items":{"type":"string"},"description":"Arguments passed to the runtime executable."},"binary":{"type":"string","description":"Runtime executable name.","example":"morph-efs-runtime"}}}},"securitySchemes":{"bearer_auth":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Filesystems","description":"Create, inspect, list, and delete owner-scoped filesystems."},{"name":"Mount sessions","description":"Start and revoke filesystem mount sessions."},{"name":"Usage","description":"Inspect filesystem usage and active mount counts."},{"name":"Dashboard","description":"Open the owner-scoped Morph EFS dashboard."}]}