# Syvon

> The Syvon platform API — manage workspaces, brands, and credits on the portal surface; read published agents, feeds, media, and run chat on the brain surface. Typed client SDK for @syvon/sdk.

## Docs

- [Introduction](https://docs.syvon.ai/introduction.md): Build on the Syvon platform. Manage your account with the portal surface, read published agents and run chat with the brain surface.
- [Quickstart](https://docs.syvon.ai/quickstart.md): From zero to your first Syvon API call in a few minutes. Mint a workspace key, install the SDK, and stream an agent chat reply.
- [Authentication](https://docs.syvon.ai/authentication.md): Two credentials, two surfaces. A portal API JWT for the management plane and a workspace API key for the read plane. One key never drives both.
- [Errors](https://docs.syvon.ai/errors.md): Every SDK error class, what it means, and the HTTP statuses you should handle. Failures are typed before they reach your catch block.
- [Platform Model](https://docs.syvon.ai/platform-model.md): Workspaces, users, brands, agents (projects), workflows, files, and posts. The tenancy model behind both API surfaces.
- [Workspace Structure](https://docs.syvon.ai/workspace-structure.md): The anatomy of a Syvon workspace — the folder tree on object storage, what each folder holds, file conventions, and which keys the brain read plane will serve.
- [Scope and Limits](https://docs.syvon.ai/scope.md): What the client API deliberately does not expose, and the supported path for generation and rendering from a client.
- [Installation](https://docs.syvon.ai/sdk/installation.md): Install the typed Syvon client SDK. Zero runtime dependencies, runs on Node 18+, browsers, Deno, Bun, and Cloudflare Workers.
- [The Client](https://docs.syvon.ai/sdk/client.md): new SyvonClient(options): the single entry point. Two surfaces, credential checks before the network, and .with() for token refresh.
- [Portal Surface](https://docs.syvon.ai/sdk/portal.md): client.portal: account, workspaces, members, brands, API keys, credits, flows, and the file index. User-scoped, needs the portal JWT.
- [Brain Surface](https://docs.syvon.ai/sdk/brain.md): client.brain: the published-agent read plane. Agent metadata, wrap/site config, files, items, feed, R2 streaming, and public chat. Workspace-scoped, needs sk_ws_…
- [Types](https://docs.syvon.ai/sdk/types.md): Every type exported from the @syvon/sdk package root. The shipped .d.ts files are the authoritative shapes.
- [Mint a portal API JWT](https://docs.syvon.ai/api-reference/auth/mint-a-portal-api-jwt.md): From a signed-in session (magic link / Google / Apple cookie). The JWT is user-scoped and lives ~1 hour; refresh via POST /api/auth/refresh.
- [The authenticated user's account](https://docs.syvon.ai/api-reference/portal/the-authenticated-users-account.md)
- [List the caller's workspaces (membership-scoped)](https://docs.syvon.ai/api-reference/portal/list-the-callers-workspaces-membership-scoped.md)
- [Create and activate an empty workspace](https://docs.syvon.ai/api-reference/portal/create-and-activate-an-empty-workspace.md): Plan-gated: returns 402 over the plan limit.
- [Fetch one workspace (member-only)](https://docs.syvon.ai/api-reference/portal/fetch-one-workspace-member-only.md)
- [Update workspace name/slug/settings (owner or admin only)](https://docs.syvon.ai/api-reference/portal/update-workspace-nameslugsettings-owner-or-admin-only.md)
- [PERMANENTLY delete a workspace and all of its R2 content](https://docs.syvon.ai/api-reference/portal/permanently-delete-a-workspace-and-all-of-its-r2-content.md)
- [Set a workspace as the caller's active workspace](https://docs.syvon.ai/api-reference/portal/set-a-workspace-as-the-callers-active-workspace.md)
- [List workspace members (member-only)](https://docs.syvon.ai/api-reference/portal/list-workspace-members-member-only.md)
- [DB-authoritative brand list](https://docs.syvon.ai/api-reference/portal/db-authoritative-brand-list.md)
- [API key metadata for the workspace (raw keys are never returned)](https://docs.syvon.ai/api-reference/portal/api-key-metadata-for-the-workspace-raw-keys-are-never-returned.md)
- [Mint a workspace API key (owner/admin + multi-workspace plan)](https://docs.syvon.ai/api-reference/portal/mint-a-workspace-api-key-owneradmin-+-multi-workspace-plan.md): Returns the raw sk_ws_… key ONCE. 402 with code API_KEYS_NOT_AVAILABLE on a single-workspace plan.
- [Revoke an API key](https://docs.syvon.ai/api-reference/portal/revoke-an-api-key.md)
- [The caller's credit balance](https://docs.syvon.ai/api-reference/portal/the-callers-credit-balance.md)
- [Paginated credit ledger entries](https://docs.syvon.ai/api-reference/portal/paginated-credit-ledger-entries.md)
- [List the workspace's workflows / flows](https://docs.syvon.ai/api-reference/portal/list-the-workspaces-workflows-flows.md)
- [The workspace's file index (workspace-relative R2 keys)](https://docs.syvon.ai/api-reference/portal/the-workspaces-file-index-workspace-relative-r2-keys.md)
- [Verify the workspace key resolves](https://docs.syvon.ai/api-reference/brain/verify-the-workspace-key-resolves.md)
- [Published agent metadata](https://docs.syvon.ai/api-reference/brain/published-agent-metadata.md): agentId is a Project id in the key's workspace. Slugs are not accepted. 404 for an unknown id or an agent outside the workspace.
- [The published presentation config (layout, greeting, theme)](https://docs.syvon.ai/api-reference/brain/the-published-presentation-config-layout-greeting-theme.md): Unpublished agents return neutral defaults. The parser never throws.
- [The published brand-site config (sitemap, nav, sections)](https://docs.syvon.ai/api-reference/brain/the-published-brand-site-config-sitemap-nav-sections.md): An empty pages array means "no site published".
- [The frozen workspace file index for the release](https://docs.syvon.ai/api-reference/brain/the-frozen-workspace-file-index-for-the-release.md)
- [The agent's active items](https://docs.syvon.ai/api-reference/brain/the-agents-active-items.md)
- [Workflow starter suggestions](https://docs.syvon.ai/api-reference/brain/workflow-starter-suggestions.md): Shape is workflow-defined.
- [Published feed posts (newest first, up to 120)](https://docs.syvon.ai/api-reference/brain/published-feed-posts-newest-first-up-to-120.md)
- [Stream a raw workspace R2 object](https://docs.syvon.ai/api-reference/brain/stream-a-raw-workspace-r2-object.md): Workspace-relative key. Only allowlisted prefixes (projects/, workflows/, config/, assets/, meta/, wrapper/, …) are reachable; others 403. Pipe the body; do not buffer large objects.
- [Public agent chat (NDJSON stream)](https://docs.syvon.ai/api-reference/brain/public-agent-chat-ndjson-stream.md): One JSON event per line; assemble the reply from event.text. The agent owner is billed for the turn. Pass a salted client hash for per-visitor rate limiting (never a raw IP). 429 when rate limited.
- [Chat Stream](https://docs.syvon.ai/guides/chat-stream.md): Consume the agent chat endpoint. NDJSON events, MDX replies, threading, per-visitor rate limiting, and billing behavior.
- [Media and Files](https://docs.syvon.ai/guides/media-files.md): Reading R2 media through the brain proxy. Key scoping rules, allowlisted prefixes, streaming vs buffering, and feed media fields.

## OpenAPI Specs

- [openapi](https://docs.syvon.ai/openapi.json)