{"schemaVersion":1,"schema":{"id":"marly.agent-help","major":1,"revision":"2026-06-12","canonicalUrl":"https://marly.studio/help/agent.json","humanUrl":"https://marly.studio/help","compatibility":"additive-within-major"},"updatedAt":"2026-06-12","product":{"name":"marly.studio","url":"https://marly.studio","supportEmail":"support@marly.studio"},"discovery":{"llmsTxt":"https://marly.studio/llms.txt","sitemapXml":"https://marly.studio/sitemap.xml","robotsTxt":"https://marly.studio/robots.txt","wellKnown":"https://marly.studio/.well-known/marly-agent.json","wellKnownAlias":"https://marly.studio/.well-known/agent.json","mcpEndpoint":"https://marly.studio/api/mcp","settings":"https://marly.studio/settings","auth":"Ask the user to create a scoped token in Settings > Agent & MCP access. Send it as Authorization: Bearer <token>."},"agent":{"purpose":"Public machine-readable guidance for assistants helping users navigate marly.studio.","currentSurface":"Public documentation plus authenticated bearer-token agent and MCP routes for scoped job workflows.","allowedUse":["read public help and legal pages","guide users through upload, import, clip review, settings, and publishing workflows","use authenticated agent tokens only for granted scopes such as manifest, job list, job status, job results, URL import, and direct file upload","route account, privacy, billing, or stuck-job questions to support"],"restrictedUse":["do not publish clips, change billing, disconnect Google, or delete accounts through agent routes","do not claim access to private jobs, clips, channels, account state, plans, or billing state without a valid scoped bearer token","do not scrape private browser routes, persist signed media URLs, or bypass bearer, session, CSRF, account-status, admin, quota, or signed-access boundaries"]},"publicRoutes":[{"path":"/llms.txt","method":"GET","purpose":"plain-text public AI/agent discovery guide"},{"path":"/.well-known/marly-agent.json","method":"GET","purpose":"well-known public alias for this machine-readable guide"},{"path":"/.well-known/agent.json","method":"GET","purpose":"generic well-known public alias for this machine-readable guide"},{"path":"/","method":"GET","purpose":"brand and upload/import entry point"},{"path":"/help","method":"GET","purpose":"human-readable product help"},{"path":"/help/agent.json","method":"GET","purpose":"machine-readable public agent guidance"},{"path":"/legal","method":"GET","purpose":"privacy and terms"},{"path":"/donate","method":"GET","purpose":"optional one-time support payments without product entitlements"},{"path":"/api/livez","method":"GET","purpose":"minimal public liveness probe"}],"publicSeoRoutes":[{"id":"home","label":"Home","path":"/","purpose":"brand and upload/import entry point","url":"https://marly.studio","lastModified":"2026-06-13"},{"id":"legal","label":"Legal","path":"/legal","purpose":"privacy, terms, Google/YouTube disclosures, and data handling","url":"https://marly.studio/legal","lastModified":"2026-06-13"},{"id":"help","label":"Help","path":"/help","purpose":"human help, product boundaries, and public agent-discovery guide","url":"https://marly.studio/help","lastModified":"2026-06-12"},{"id":"donate","label":"Support","path":"/donate","purpose":"optional one-time support payments without product entitlements","url":"https://marly.studio/donate","lastModified":"2026-06-01"}],"authenticatedAgentRoutes":[{"path":"/api/agent/tokens","method":"POST","auth":"browser session + CSRF","purpose":"create a scoped agent bearer token after explicit consent"},{"path":"/api/agent/tokens/{grantId}","method":"DELETE","auth":"browser session + CSRF","purpose":"revoke a scoped agent bearer token"},{"path":"/api/agent/manifest","method":"GET","auth":"Bearer token with agent.manifest.read","purpose":"read the authenticated agent capability manifest"},{"path":"/api/agent/jobs","method":"GET","auth":"Bearer token with job.list.read","purpose":"list recent owned jobs with safe status fields"},{"path":"/api/agent/jobs/import","method":"POST","auth":"Bearer token with job.import.create","purpose":"create a supported video URL import using normal quota and validation rules"},{"path":"/api/agent/uploads/init","method":"POST","auth":"Bearer token with job.upload.create","purpose":"create a file upload job and receive a short-lived upload plan (single-part or multipart) or a relay target in relay-transport deployments"},{"path":"/api/agent/uploads/complete","method":"POST","auth":"Bearer token with job.upload.create","purpose":"complete an agent file upload after media validation"},{"path":"/api/agent/jobs/{jobId}/status","method":"GET","auth":"Bearer token with job.status.read","purpose":"read safe status metadata for one owned job"},{"path":"/api/agent/jobs/{jobId}/results","method":"GET","auth":"Bearer token with job.results.read plus job.status.read; clip details require clip.metadata.read","purpose":"read safe result metadata and optional safe clip metadata when granted"},{"path":"/api/mcp","method":"POST","auth":"Bearer token","purpose":"JSON-RPC MCP tool bridge for the same scoped agent capabilities"}],"privateBoundaries":{"api":"/api/* routes may require a browser session, CSRF token, scoped bearer token, account status check, admin state, or signed access URL.","media":"Signed media URLs are private, short-lived, and must not be persisted, shared, or treated as permanent public URLs.","mutations":"Agent URL import and file upload (direct single-part or direct multipart; app-relay single-part only in relay-transport deployments) are token-scoped and still use normal quota, validation, and ownership rules. Publishing, billing changes, Google disconnect, settings changes, and account deletion remain user/session-bound browser actions."},"triage":{"reportTypes":["upload","url_import","processing","clip_quality","publishing","automation","billing","account","privacy"],"minimumUsefulEvidence":{"jobIssues":["job ID","visible failure text","last visible stage"],"clipQualityIssues":["job ID","clip title or time range","what claim or edit is wrong"],"accountBillingIssues":["account email when relevant","visible billing/settings message"]},"neverRequest":["passwords","raw cookies","raw OAuth tokens","private keys","full payment card details","provider console secrets","permanent copies of signed media URLs"]},"jobStates":[{"state":"queued_or_uploaded","meaning":"accepted and waiting for validation or worker capacity"},{"state":"transcribing","meaning":"speech-to-text work is underway; local Whisper is the default path"},{"state":"analyzing","meaning":"moment selection and metadata generation are underway"},{"state":"extracting_or_uploading","meaning":"rendered clip media is being produced and made available"},{"state":"completed","meaning":"clips should be reviewable"},{"state":"failed","meaning":"use the visible failure reason and last stage; do not infer user fault without evidence"}],"troubleshooting":{"urlImport":"Retry once later for provider/network flake, then use direct upload when the user has rights to the source file. URL import failure does not imply upload/transcription/rendering is broken.","upload":"Unsupported file/signature failures should route users to a clean export in a common video container. Storage or relay failures are service-side symptoms.","clipQuality":"For bad titles or unsupported claims, compare generated copy against transcript/source evidence before changing thresholds or prompts.","publishing":"Expired or failed Google/YouTube authorization should route users to Settings to reconnect or refresh authorization."},"futureWork":{"mcp":"The current MCP bridge is authenticated, bearer-scoped, rate-limited, audited through repository operations, and separated from this public help document.","api":"The current agent API supports scoped manifest, job list, URL import, direct file upload (single-part, or multipart for large files, over both REST and MCP), relay file upload (single-part, in relay-transport deployments), job status, job results, and optional safe clip metadata. It does not support publishing, billing, Google disconnect, account deletion, admin actions, signed media read URLs, raw transcripts, or provider tokens.","nextSafeSlices":["clearer per-token activity and last-used review surfaces","explicit user confirmation before any future publish-capable agent workflow"]}}