{"openapi":"3.1.0","info":{"title":"Obelism media agent API","version":"1.0.0","description":"The files of a space: the library every Obelism product shares. Send a session token from www as the bearer, or use the MCP server at /mcp. Reads take any role in the space; changes take an editor's."},"paths":{"/api/agent/organizations":{"get":{"operationId":"listOrganizations","summary":"List organizations","description":"The organizations you are a member of, with your role.","parameters":[],"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces":{"get":{"operationId":"listSpaces","summary":"List spaces","description":"The spaces of an organization you may open. A space is one site or project; its files are shared by its environments.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/files":{"get":{"operationId":"listFiles","summary":"List files","description":"Files of the space, newest first: one folder (folderId, empty for the root), or every folder when searching by name (query), tag or Shopify product (product).","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}},{"name":"folderId","in":"query","required":false,"description":"A folder, or empty for the root.","schema":{"type":"string"}},{"name":"query","in":"query","required":false,"description":"Part of the file name.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Files with this tag.","schema":{"type":"string"}},{"name":"product","in":"query","required":false,"description":"Files tagged with this Shopify product, by its GID (gid://shopify/Product/…).","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"At most this many (100 at most).","schema":{"type":"integer"}},{"name":"skip","in":"query","required":false,"description":"Skip this many.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}},"post":{"operationId":"uploadFile","summary":"Add a file from a URL","description":"Fetches a file from an https URL (50 MB at most, of the type it claims) into the space, in folderId or where the upload rules put it, with optional title, alt and tags.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"An https URL."},"folderId":{"type":["string","null"],"description":"A folder (listFolders), or null for the root."},"title":{"type":"object","additionalProperties":{"type":"string"},"description":"{ [locale]: text } in the space's locales."},"alt":{"type":"object","additionalProperties":{"type":"string"},"description":"{ [locale]: text } in the space's locales."},"tags":{"type":"array","items":{"type":"string"}}},"required":["url"]}}}},"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/files/{assetId}":{"get":{"operationId":"getFile","summary":"Get a file","description":"One file with its details, where content uses it, and originalUrl: the untouched original behind a link that lasts minutes.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}},{"name":"assetId","in":"path","required":true,"description":"The file (listFiles).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"post":{"operationId":"updateFile","summary":"Change a file's details","description":"Its title and alt text (per locale), focal point, tags (the whole list) or folder. Content using the file shows the change.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}},{"name":"assetId","in":"path","required":true,"description":"The file (listFiles).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"object","additionalProperties":{"type":"string"},"description":"{ [locale]: text } in the space's locales."},"alt":{"type":"object","additionalProperties":{"type":"string"},"description":"{ [locale]: text } in the space's locales."},"focalPoint":{"type":["object","null"],"properties":{"x":{"type":"number"},"y":{"type":"number"}},"description":"Where crops keep the image: { x, y }, each 0 to 1, or null."},"tags":{"type":"array","items":{"type":"string"}},"folderId":{"type":["string","null"],"description":"A folder (listFolders), or null for the root."}},"required":[]}}}},"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/folders":{"get":{"operationId":"listFolders","summary":"List folders","description":"Every folder of the space, with its parent and how many files it holds.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"post":{"operationId":"createFolder","summary":"Create a folder","description":"A folder in parentId, or at the root.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parentId":{"type":["string","null"],"description":"A folder (listFolders), or null for the root."}},"required":["name"]}}}},"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/folders/{folderId}":{"post":{"operationId":"changeFolder","summary":"Change a folder","description":"Renames it (name, unique among its siblings, 1 to 120 characters) and moves it (parentId, null for the root), either or both. A folder never moves inside itself or its own subtree, and nothing that a site links changes.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}},{"name":"folderId","in":"path","required":true,"description":"The folder (listFolders).","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name."},"parentId":{"type":["string","null"],"description":"A folder (listFolders), or null for the root."}},"required":[]}}}},"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/folders/{folderId}/delete":{"post":{"operationId":"deleteFolder","summary":"Delete a folder","description":"Only an empty one: a folder that still holds folders or files answers 409 (conflict).","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}},{"name":"folderId","in":"path","required":true,"description":"The folder (listFolders).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/move-files":{"post":{"operationId":"moveFiles","summary":"Move files","description":"Files into a folder, or the root. No URL changes.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assetIds":{"type":"array","items":{"type":"string"}},"folderId":{"type":["string","null"],"description":"A folder (listFolders), or null for the root."}},"required":["assetIds","folderId"]}}}},"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/shares":{"get":{"operationId":"listShares","summary":"List shares","description":"Links that open files to people outside the organization, with when each is open and how often it was opened; assetId keeps to the shares holding that file.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}},{"name":"assetId","in":"query","required":false,"description":"Only shares holding this file.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"post":{"operationId":"createShare","summary":"Share files","description":"A link that opens files (assetIds) or a folder (folderId) with a password, from startsAt (now) to endsAt (a week; a month at most). Answers the link and the password, which is never readable again: hand both to the user.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assetIds":{"type":"array","items":{"type":"string"}},"folderId":{"type":"string"},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"password":{"type":"string","description":"8 characters at least; one is made up when left out."}},"required":[]}}}},"responses":{"200":{"description":"OK"}}}},"/api/agent/organizations/{organizationId}/spaces/{spaceId}/rules":{"get":{"operationId":"listUploadRules","summary":"List upload rules","description":"The space's upload rules, in order: the first whose pattern matches a new file's name puts it in its folder and adds its tags.","parameters":[{"name":"organizationId","in":"path","required":true,"description":"The organization (listOrganizations).","schema":{"type":"string"}},{"name":"spaceId","in":"path","required":true,"description":"The space (listSpaces): one site or project.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}}}}