API
Errors
Every error code the Obelism media agent API and MCP server answer with, as RFC 9457 problem JSON, and what to change before retrying the request.
Errors are RFC 9457 problem details, Content-Type: application/problem+json, never cached:
{
"type": "https://media.obelism.studio/docs/api/errors#unknown_space",
"title": "The space could not be resolved in this organization.",
"status": 404,
"code": "unknown_space",
"detail": "No space with this id in the organization that you may open.",
"hint": "List the organization’s spaces first (listSpaces)."
}Branch on code; detail and hint are for people and may change. Through MCP, a failed tool call returns the same JSON as its text.
invalid_request
400: Fix what detail names: a body that isn't a JSON object, a field of the wrong shape, a URL that isn't https or points at a private host, more than 20 tags.
unauthorized
401: Send a valid bearer token: a session token from www for the agent API, an OAuth access token for /mcp. Sign in again when it expired.
forbidden
403: Changing files takes an admin, developer or editor role in the Space. Ask an admin of the Organization.
unknown_organization
404: Check organizationId: list your Organizations first (listOrganizations).
unknown_space
404: Check spaceId: it must be a Space of the Organization you may open (listSpaces).
not_found
404: No file or folder with this id in the Space, or no endpoint at this path.
method_not_allowed
405: The endpoint exists, but not for this HTTP method. Check the method in the OpenAPI spec.
conflict
409: The change clashes with what is there: a folder that still holds folders or files, a folder name its siblings already have, a folder moved inside itself.
too_large
413: The file is larger than this way of adding one takes (50 MB from a URL). Upload it in the library instead.
rate_limited
429: More than 300 calls in a minute. Wait for Retry-After before sending more.
internal_error
500: Something broke on our side. Retry later.