API Reference spatio_sdk v0.0.2

API calls for all endpoints tagged Account.

API calls for all endpoints tagged Actions.

API calls for all endpoints tagged Agents.

API calls for all endpoints tagged Apps.

API calls for all endpoints tagged Calendar.

API calls for all endpoints tagged Calls.

API calls for all endpoints tagged Channels.

API calls for all endpoints tagged Connections.

API calls for all endpoints tagged Contacts.

API calls for all endpoints tagged Conversations.

API calls for all endpoints tagged DirectMessages.

API calls for all endpoints tagged Files.

API calls for all endpoints tagged Folders.

API calls for all endpoints tagged Inbox.

API calls for all endpoints tagged Keybindings.

API calls for all endpoints tagged Logos.

API calls for all endpoints tagged Mail.

API calls for all endpoints tagged Misc.

API calls for all endpoints tagged Models.

API calls for all endpoints tagged NativeDM.

API calls for all endpoints tagged Navigation.

API calls for all endpoints tagged Notes.

API calls for all endpoints tagged Notifications.

API calls for all endpoints tagged OAuth.

API calls for all endpoints tagged Organizations.

API calls for all endpoints tagged PersonalAccessTokens.

API calls for all endpoints tagged Platforms.

API calls for all endpoints tagged Realtime.

API calls for all endpoints tagged Recommendations.

API calls for all endpoints tagged Records.

API calls for all endpoints tagged Repo.

API calls for all endpoints tagged Resources.

API calls for all endpoints tagged Routines.

API calls for all endpoints tagged Search.

API calls for all endpoints tagged Settings.

API calls for all endpoints tagged Sheets.

API calls for all endpoints tagged Slides.

API calls for all endpoints tagged Tasks.

API calls for all endpoints tagged Terminal.

API calls for all endpoints tagged Workspaces.

Handle Tesla connections for Spatio.

Helper functions for deserializing responses into models

One of the candidates returned alongside an ambiguous_account error so the client can prompt the user to pick a target account.

Per-account failure attached to AccountStatus.error inside a fan-out Envelope. code is machine-readable and stable across releases for the canonical values (auth_expired, rate_limited, provider_5xx, timeout); unknown is a fallback and should not be relied on.

GET /v1/accounts returns {accounts_by_platform, total_accounts} on production today. Schema kept open until the consumers migrate to a flat accounts array.

Subscription summary. tier is the canonical billing tier (uppercased: FREE, PRO, MAX, ENTERPRISE); display_name is the lowercase user-facing label.

Outcome of one connected account's contribution to a fan-out call. Every connection that participated appears in Envelope.accounts exactly once, regardless of whether it succeeded, errored, or returned zero items.

Per-tier capability + quota envelope. Numeric quotas use 0/-1 idioms; treat large negatives as "unlimited."

Today's usage counters. Snapshot reflects the in-memory rollup; counts reset at UTC midnight.

Action manifest entry surfaced by the agent platform. The inputType/outputType references point at internal Go types; treat them as opaque labels.

Stored agent configuration (system prompt + tool selection). User-defined agents and preconfigured agents share this shape.

LLM conversation tracked by the agent platform (distinct from /v1/conversations which is the renderer-driven sidebar persistence).

Identity bundle returned to the agent at SessionStart. One round-trip provides user + current org/workspace + connected accounts so the agent doesn't fish on its first turn.

Free-trial agent-task gate. allowed is the only field clients must check before issuing a turn. Paid users get paid: true, allowed: true with the count fields null.

Returned when the caller's request matches more than one connected account and no accountId query param disambiguates which one to target. The accounts array enumerates the candidates so the client can prompt the user to pick.

Standard error envelope returned by 4xx and 5xx responses across the SpatioAPI. Some endpoints attach extra machine-readable fields (code, accounts, requiresPassword, etc.) — those are documented on the individual operation.

Locally-built prototype app rendered in an Electron <webview>. projectPath is the on-disk root; file ops are scoped to it.

Inline attachment payload for send, reply, and draft requests. data is the raw bytes base64-encoded by the JSON encoder.

Attachment metadata; binary fetched via the attachment endpoint.

Type-specific payload for a block. Fields populated depend on Block.type. All fields are optional at the schema level; the runtime enforces the per-type contract. Note: this object uses snake_case keys to match the JSON the Go providers.BlockContent struct emits and accepts. Other parts of the SpatioAPI use camelCase; blocks are the exception because the block model is shared with external Notion-like providers whose canonical wire format is snake_case.

Single-account list response for GET /v1/notes/{id}/blocks. Unlike GET /v1/notes, block listing always targets one account so it does not fan out — total is the count for the current page slice.

Discriminator for block types. The structure of content varies by type (e.g. paragraph carries richText; code carries richText + language; image carries url + caption + altText).

Partial-success envelope for bulkArchiveEmails.

Soft-deletes by default (moves to provider trash). Set permanent: true to hard-delete.

Partial-success envelope for bulkDeleteEmails.

Either fileIds (with optional parallel accountIds) for multi-file delete, or fileId (with optional accountId) for the single-file fallback. fileIds wins when both are set.

Either populate taskIds (with optional parallel accountIds) for multi-task delete, or taskId (with optional accountId) for the single-task fallback. taskIds wins when both are set.

Partial-success envelope. success is true only when zero failures; affectedCount is the deleted count; taskIds lists the ids that succeeded; failed lists per-id errors.

Partial-success envelope for bulk delete/move.

Bulk shorthand for setting read state on many messages at once. messageIds accepts an array; the production handler also accepts a bare string for renderer-compat but the spec models the array shape only. read defaults to true when omitted.

Partial-success envelope for bulkMarkEmailsRead. updated is a count (not an array — distinct from archive/delete which return the actual id list). The failed-row shape uses id (also distinct — renderer-compat legacy).

Move multiple files to one target folder. targetFolderId is the canonical name; folderId is accepted as a renderer-compat alias.

Apply the same updates payload to every id. Same parallel AccountIDs convention as bulk delete.

Generic platform-operation envelope used by Calendar list/create/ update/delete responses. data is operation-specific: - listEvents: ListEventsData - createEvent / updateEvent: Event - deleteEvent: empty / metadata-only

Metadata about one registered calendar provider.

Registered calendar providers. Returned regardless of whether the caller has connected any.

Returned by POST /v1/calendar/sync. Status code is 202 by default (sync jobs queued); 200 when called with ?wait=true and all jobs finish within the 10-second polling budget.

A single cell. value is the JSON-serializable cell contents; interpretation is provider-specific.

A chat conversation. The same struct backs both group channels (type: channel | private) and direct-message threads (type: im | mpim); the Channels and DirectMessages HTTP surfaces filter on type to give each its dedicated URL space.

Body for join/leave operations.

One entry in GET /actions. Action ids are dotted (e.g. direct-messages.send, channels.list); the executeAction endpoint accepts the id with a free-form params object.

Block-level manifest for a chunked-uploaded file. Returned by GET /v1/files/{id}/manifest. Only meaningful for files uploaded via the chunked path; legacy uploads return 404.

Threaded comment on a note. Top-level comments have parentCommentId: null; replies set it to the parent comment's id. blockId anchors the comment to a specific block; comments without a blockId are note-level ("general") comments.

Response for POST and PATCH on a comment.

Single-comment response (GET …/comments/:commentId).

Video/phone conference details. type is canonical (spatio, meet, zoom, teams); other provider-specific values are accepted as opaque strings. The Spatio invite email pipeline only fires for native events or events with type: spatio.

GET /v1/connections/user returns {connections, user_id} (the per-provider connected-account list). Schema kept open pending a normalize-to-accounts migration.

Atomic check+increment. Returns the updated counter on success; returns 402 on trial_expired and 429 on daily_limit_exceeded (the body in error cases is the ApiError envelope).

Snake-case wire format (legacy).

LLM conversation persisted by the platform-service. Stored in snake_case at the wire (legacy DTO; predates the camelCase rest of the API). Treat field names as authoritative.

Renderer-curated "core action" entry. These are the keyboard + command-palette surfaced actions; superset of the platform-tagged agent actions. Schema kept open since the platform metadata varies by category.

Either body (preferred) or content (renderer parity with tasks) is required. Empty parentCommentId/blockId strings are treated as null.

The full token (prefix + secret) is returned ONLY on creation. Store it now or you'll have to recreate; the API never returns the secret again.

presentationId in the body is allowed but redundant when posting to /v1/slides/{id}/slides — the path id wins.

OAuth 2.1 (RFC 8414) + OpenID Connect Discovery 1.0 metadata. Same payload returned from both well-known paths.

Forward to either a DM (toDmId) or a channel (toChannelId); exactly one required.

Generic single-message wrapper used by reply/forward/attach responses. message is the resulting ChatMessage.

Mute either until a specific time (untilSeconds, Unix epoch) or forever (forever: true). At least one must be set.

reactions shape is provider-specific; treat as opaque.

A single email message. The provider/accountId provenance fields tell clients which connected mail account this row came from (Gmail, Outlook, etc.) so multi-account list responses can be merged sensibly client-side.

Body for POST /v1/notes/{id}/share. With setPassword: false, only the public flag is flipped — any existing password is preserved. With setPassword: true, the supplied password is applied (an empty string clears it).

Generic action-execute payload. Tool-specific shape lives in params.

Generic action-execute result envelope. Tool-specific shape lives in data.

Optional body for POST /v1/slides/{id}/export/pdf. Renderer posts pre-rasterized PNGs for slides that contain Fabric.js elements (the sidecar can't run Fabric server-side); slides without an entry are rendered from their layout + theme.

Response shape when the export was uploaded to R2 (?storage=r2). The streaming case (?storage=stream, default) returns a binary application/pdf body and is not modeled as a JSON schema.

Extracted text + structural metadata from a PDF (or other extraction-supported file type). pages is provider-shaped — treat as an opaque per-page object array. Endpoint returns 422 with code: extraction_unsupported when the underlying file isn't extractable.

Fan-out list response for GET /v1/files.

Aggregated {files, folders, accounts} envelope used by the renderer's file-browser. Calls ListFiles and ListFolders in parallel and merges the results — saves a round-trip when the UI shows both side-by-side.

Fan-out list response for GET /v1/files/folders.

A unified-feed item. Source-aware — category indicates which upstream platform (mail, dm, channel, mention, system) produced it; id is the inbox-item id (not the underlying message id).

A single JSON Web Key (RFC 7517 §4) — RSA public key.

Merged user-customized key binding.

List of emails across the selected accounts. provider is set on single-account calls; on fan-out it carries the value from the first contributing account (legacy behavior — clients should rely on the per-row provider field instead).

Shape of data when returned by listEvents. Wrapped inside a CalendarOperationResult — clients should access this as result.data after checking result.success.

Move a single file to a target folder. Pass folderId: null to move to the account root. Bulk moves use POST /v1/files/move.

A markdown note. Notes belong to exactly one connected account (accountId + provider). The native provider stores notes in the Spatio database; external providers (Notion, Google Keep, etc.) store them upstream and round-trip through Spatio.

Standard fan-out response for GET /v1/notes. Items aggregate notes across every connected account that contributed to the call; each contributing account contributes one accounts[] entry — including failed accounts, so the client can render which providers contributed and which errored without the call itself failing.

Organization summary used in list responses (GET /v1/organizations, GET /v1/organizations/{id}/workspaces). Returned with camelCase field names. NB: The single-org GET /v1/organizations/{id} returns a different shape (OrganizationDetailLegacy, PascalCase keys) today — see that schema for the wire-level reality. This is a known inconsistency the platform-service is expected to converge on the camelCase shape in a future cleanup.

Single-organization GET response. PascalCase keys — inconsistent with the rest of the API (anonymous-struct json-marshal in handler with no field tags). Documented as-is; a future cleanup pass will move this to camelCase via a versioned migration.

Inviter info. Returns either a bare user id (string) on legacy paths, or an object envelope {id, email, name, ...} on enriched responses. Treat as opaque.

Returned by GET /public/notes/{token} when the note is password-protected. requiresPassword is always true in this response; invalidPassword is true only when a password was supplied and rejected.

Curated featured agents — read-only, surfaced by the renderer's "preconfigured" picker. Not full Agent records; minimal display metadata only.

A slide deck. Presentations belong to one connected account (accountId + provider). Native deck storage lives in Spatio's DB; external providers (Google Slides, etc.) round-trip.

Returned by GET /invitations/{token} (unauthenticated). Lets the renderer show invitation details (workspace name, inviter, role) before the user signs in.

Returned by upload endpoints when the caller's storage quota is exhausted. code: quota_exceeded is reserved.

Agent-authored proposal that surfaces on the home feed. Status transitions: pending → accepted | dismissed | expired.

Org-scoped record-type definition. attribute_schema defines the per-record attributes; treated as opaque here.

Reply to a specific email. to/cc/bcc are optional — the platform falls back to the original sender / recipients when omitted.

A spreadsheet row. cells is a column-name → value map. Values are JSON primitives (string, number, boolean) or null; provider- specific richer types (formula, date) are encoded as strings.

In-memory substring search across the caller's files. Provider filtering isn't standardized across providers, so the platform lists up to ~500 files and filters locally — total is the pre-truncation count, not the global count.

Public share configuration for a note. Owner-only mutation; unauthenticated readers consume GET /public/notes/{token} instead.

A spreadsheet. Sheets belong to exactly one connected account (accountId + provider). The native provider stores sheets in the Spatio database; external providers (Google Sheets, Excel Online, etc.) round-trip through Spatio. data is a free-form bag for provider-specific blobs (cell matrices, formulas, formatting). Clients that walk rows / cells should use the dedicated row + cell endpoints; data is only meaningful when round-tripping with an external provider that embeds its native format here.

Fan-out response for GET /v1/sheets. items aggregates sheets across every connected account; accounts carries one row per contributing connection — including failures.

One canvas object on a slide — text box, shape, image, etc. content is renderer-specific JSON (e.g. fabric.js properties: text, fill, fontSize, src). Identified by a stable id so MCP / agent operations stay idempotent across retries.

OAuth/native integration descriptor. Open shape — categories add provider-specific capability flags. Treat unknown fields as additive.

A calendar event. Calendar uses snake_case JSON keys (different from Notes/Sheets/Slides/Tasks/Mail which use camelCase) — the surface predates the cross-platform convention.

A user file. Files belong to one connected file provider account (accountId + provider); native storage uses Spatio's block-store, external providers (Google Drive, Dropbox, etc.) round-trip through Spatio. Schema name is SpatioFile (not File) to avoid the java.io.File collision that breaks the Kotlin SDK generator when the schema is named File.

Lightweight ack returned by mutations that have no other body (DELETE /v1/notes/:id, block move, etc.).

A to-do / reminder / issue. Tasks belong to one connected account (accountId + provider). Native tasks store in Spatio's DB; external providers (Linear, GitHub Issues, Todoist, etc.) round-trip through Spatio.

Fan-out response for GET /v1/tasks.

Metadata about which task providers are connected and what the Tasks platform itself reports for its name + description.

Inline formatting flags for a RichTextObject.

Partial update — only fields present in the body are touched.

Either body (preferred) or content is required.

Partial update — every field optional.

Mark messages read/unread, star, or add/remove labels. All fields optional — only present fields are touched.

Sparse update. updates is a free-form map of fields to change; only keys present are applied. The server-side capability gate rejects fields that the underlying provider doesn't support.

Partial update.

Partial update. Every field is optional; only fields present in the body are touched. null for parentId clears the parent.

Partial update.

Toggle audio/video/screen-share state.

Partial update — every field optional.

Partial update — every field is optional.

Partial update — every field optional.

Partial update — every field optional.

Partial update — every field is optional. dueDate and parentTaskId are nullable: send null to clear, omit to leave untouched, send a value to set.

A workspace within an organization. Returned in list responses (GET /v1/workspaces, GET /v1/organizations/{id}/workspaces) and the single-get response (GET /v1/workspaces/{id}, wrapped in {workspace: ...}). settings shape varies by endpoint — sometimes a JSON object, sometimes a JSON-encoded string. Treat as opaque.

Compact org summary embedded on single-get responses.

Helper functions for building Tesla requests