# HQ

## Docs

- [HQ API](https://docs.hq.zone/index.md): Intelligence on a handle — the HTTP API for HQ's roster of @mentionable specialists.
- [Authentication](https://docs.hq.zone/get-started/authentication.md): Authenticate with a personal access token, or the OAuth 2.1 flow for apps acting on a user's behalf.
- [Quickstart](https://docs.hq.zone/get-started/quickstart.md): Make your first authenticated calls and talk to an agent.
- [How HQ works](https://docs.hq.zone/concepts/how-hq-works.md): The architecture behind HQ: a roster of specialists, a real isolated machine per conversation, and qOS — the agentic OS we built in Rust.
- [qOS — the agentic operating system](https://docs.hq.zone/concepts/qos.md): qOS is the operating system HQ built for agents, in Rust, top to bottom — a data layer of its own systems rather than a stack of stapled-together APIs.
- [Models & inference](https://docs.hq.zone/concepts/models.md): How HQ routes every agent call across the frontier and serves the sensitive, high-volume work on its own GPUs — one model layer beneath qOS.
- [Web & browser control](https://docs.hq.zone/concepts/browser.md): How HQ specialists research the live web and drive a real browser — including the user's own browser — to finish work on sites with no API.
- [Memory that compounds](https://docs.hq.zone/concepts/memory.md): What HQ remembers between sessions, how specialists arrive knowing your workspace, and the controls you have to view, correct, delete, or freeze what they know.
- [Security, isolation & trust](https://docs.hq.zone/concepts/security.md): How HQ keeps real work safe: a hardware-isolated machine per conversation, bound identity and a tamper-evident audit log, EU or US data residency, and independent certification.
- [Stream a chat (SSE)](https://docs.hq.zone/guides/streaming-chat.md): Send a message and read the agent's reply live over Server-Sent Events.
- [Configure HQ agents](https://docs.hq.zone/guides/agents.md): List, create, update, enable/disable, default, and equip agents with skills, MCP servers, and avatars over the HQ API.
- [Extend agents with integrations](https://docs.hq.zone/guides/integrations.md): Browse the catalog and install MCP servers, skills, and Slack channels for your workspace, then attach them to an agent.
- [Connect your own MCP servers](https://docs.hq.zone/guides/connectors.md): Bring MCP servers HQ doesn't ship in its catalog — a public URL via a custom integration, or a server inside your private network via an outbound mTLS connector.
- [Work with the documents library](https://docs.hq.zone/guides/documents.md): Upload, classify, list, search, download, update, and delete the user-curated documents in your workspace.
- [Store structured data in tables](https://docs.hq.zone/guides/tables.md): Create typed tables, write and query rows, evolve the schema, and export to CSV — a governed, multi-tenant data store your agents and your team share.
- [Schedule a recurring agent run](https://docs.hq.zone/guides/schedules.md): Create autonomous schedules that fire an agent on a cron or RRULE trigger, then list, pause, fire on demand, and tear them down.
- [Work with artifacts](https://docs.hq.zone/guides/artifacts.md): List, download, archive, and delete the files (artifacts) an agent produces.
- [Publish and share surfaces (apps)](https://docs.hq.zone/guides/surfaces.md): List a conversation's surfaces, list the workspace app catalog, mint a time-limited share link, change visibility, and delete or restore an app.
- [Agent email: inbox, drafts, and triage](https://docs.hq.zone/guides/email.md): Give an agent an email address, then review, approve, send, or discard the replies it drafts — plus assign unrouted mail and clear quarantine.
- [Inbox and notifications](https://docs.hq.zone/guides/notifications.md): Read and manage HQ's two in-app surfaces: your personal inbox and the workspace notification center.
- [Onboard a workspace](https://docs.hq.zone/guides/onboarding.md): Walk a new workspace through the onboarding wizard: check status, validate a business domain, confirm it, and complete onboarding.
- [OAuth 2.1 with PKCE](https://docs.hq.zone/guides/oauth.md): Register a client, run the authorization-code + PKCE flow, and manage access, refresh, introspection, and revocation against HQ as the authorization server.
- [API conventions](https://docs.hq.zone/api/conventions.md): Base URL, versioning, data formats, IDs, and the patterns shared across every HQ endpoint.
- [Errors](https://docs.hq.zone/api/errors.md): How HQ reports failures: the error body shape and the status codes you'll see.
- [Scopes](https://docs.hq.zone/api/scopes.md): The resource:action permission vocabulary that tokens and OAuth clients grant from.
- [Rate limits](https://docs.hq.zone/api/rate-limits.md): Where HQ throttles requests, and how to handle a 429.
- [Generate a client (SDK)](https://docs.hq.zone/api/generate-a-client.md): Generate a typed client for any language from HQ's OpenAPI spec.
- [OAuth authorization endpoint](https://docs.hq.zone/api-reference/auth/oauth-authorize.md): Starts an OAuth 2.1 authorization-code flow with PKCE, where HQ acts as the authorization server. Requires an active HQ browser session; if the caller is not signed in they are redirected to HQ sign-in and back. Validates the client_id against the client registry, checks that redirect_uri is on the…
- [OAuth token endpoint](https://docs.hq.zone/api-reference/auth/oauth-token.md): Exchanges an authorization code or a refresh token for tokens, accepting either application/x-www-form-urlencoded or application/json. For grant_type=authorization_code it verifies PKCE (S256 code_verifier against the stored challenge) and that client_id and redirect_uri match the original authoriza…
- [OAuth 2.0 Device Authorization Request (RFC 8628 §3.1-3.2)](https://docs.hq.zone/api-reference/auth/oauth-device-authorization.md): Starts a device-code flow with PKCE. Returns a `device_code` the client polls `/v1/oauth/token` with (grant_type=urn:ietf:params:oauth:grant-type:device_code) and a short `user_code` the user approves at `verification_uri`. No HQ session is required here - the user authenticates later, on the verifi…
- [Introspect a token](https://docs.hq.zone/api-reference/auth/oauth-introspect.md): RFC 7662 token introspection: the calling client authenticates (client_id, plus client_secret for confidential clients) and submits a token to check, as form or JSON. Returns active true only for a token that the authenticated client itself issued and that is neither revoked nor expired, along with…
- [Revoke a token](https://docs.hq.zone/api-reference/auth/oauth-revoke.md): RFC 7009 token revocation: the calling client authenticates (client_id, plus client_secret for confidential clients) and submits a token to revoke, as form or JSON. If the token belongs to the authenticating client, it and its entire refresh family (the paired access and refresh tokens plus all rota…
- [Register an OAuth client](https://docs.hq.zone/api-reference/auth/register-client.md): OAuth 2.1 Dynamic Client Registration (RFC 7591). Registration is authenticated: the caller must present a valid HQ session or token, and the resulting client is owned by that user. Validates the submitted JSON metadata (redirect URIs must be https or http loopback with no fragment; scopes must be k…
- [Get an OAuth client](https://docs.hq.zone/api-reference/auth/get-client.md): RFC 7592 read of a dynamically registered OAuth client identified by client_id in the path. Authenticated with the client's registration_access_token as a Bearer token (not an HQ session). Returns the client's current metadata including redirect URIs, name, token_endpoint_auth_method, grant and resp…
- [Update an OAuth client](https://docs.hq.zone/api-reference/auth/update-client.md): RFC 7592 update of a dynamically registered OAuth client identified by client_id in the path, authenticated with the client's registration_access_token as a Bearer token. Re-validates and replaces the mutable metadata (name, redirect URIs, and requestable scopes); the client type and its secret life…
- [Delete an OAuth client](https://docs.hq.zone/api-reference/auth/delete-client.md): RFC 7592 deregistration of a dynamically registered OAuth client identified by client_id in the path, authenticated with the client's registration_access_token as a Bearer token. Soft-disables the client so it can no longer be used, returning 204 No Content on success.
- [Get the signed-in user](https://docs.hq.zone/api-reference/me/get-me.md): The caller's own self-view, scoped to their identity: an identity block (display name, email, locale, timezone, admin/bot flags, connected-workspace source, profile-consent state, and clock/timezone display preferences), an optional persona block summarizing the user's distilled profile (`null` if n…
- [Update my profile](https://docs.hq.zone/api-reference/me/update-me.md): `PATCH /v1/api/me` - update the caller's own profile preferences (clock format + timezone). Self-scoped: the caller is resolved from the session headers (the same pair `me` reads), so it can only ever write its own row. Either field may be omitted; only the supplied ones change.
- [Upload my avatar](https://docs.hq.zone/api-reference/me/upload-my-avatar.md): `POST /v1/api/me/avatar` - the caller uploads their own profile image. Mirrors the agent-avatar upload: base64 in, decoded + validated locally, then handed to the internal artifacts publisher (Trove), and the resulting internal download URL is stored as the caller's `workspace_users.image_url`. Self…
- [List the workspaces the signed-in person can reach](https://docs.hq.zone/api-reference/me/my-workspaces.md): Returns every workspace the caller's verified email can sign into (policy-passing - the same `signin_decision` gate as sign-in), with the active (current-session) one flagged. This is the read-only foundation of the cross-tenant workspace switcher (P1); re-scoping the session to another workspace (t…
- [Create a new workspace](https://docs.hq.zone/api-reference/me/create-workspace.md): Greenfield-creates a brand-new tenant owned by the caller and switches the session into it - the authenticated, in-product counterpart to the public magic-link `/v1/auth/signup` funnel. Shares the exact same atomic provisioning (`signup::provision_email_tenant`), so the new workspace gets the identi…
- [Switch the active workspace](https://docs.hq.zone/api-reference/me/switch-workspace.md): Re-scopes the session to another workspace the caller can reach (workspace switcher P2). Verifies the caller's verified email has a policy-passing membership in the target - the identical `signin_decision` gate as sign-in, so this never grants access a fresh sign-in wouldn't - then re-mints the vaul…
- [Erase my own data](https://docs.hq.zone/api-reference/me/erase-me.md): `POST /v1/api/me/erase` - self-erasure. Any authenticated user can request this on their own data. No admin role required.
- [List agents](https://docs.hq.zone/api-reference/agents/list-agents.md): Returns every agent configured in the caller's workspace, including each agent's slug, display name, description, system-prompt instructions, personality settings (tone, verbosity, cautions, languages), aliases, runtime profile, selected model, default flag, status, and avatar URL. Results are scope…
- [Create an agent](https://docs.hq.zone/api-reference/agents/create-agent.md): Creates a new agent in the caller's workspace from the supplied slug, display name, and optional description, instructions, personality settings, aliases, runtime profile, model, avatar URL, and initial enabled skill/MCP subsets, returning the created agent. The slug and aliases must be lowercase 2-…
- [Update an agent](https://docs.hq.zone/api-reference/agents/update-agent.md): Updates the named agent's editable fields (slug, display name, description, instructions, tone, verbosity, cautions, languages, aliases, runtime profile, model, avatar URL) and returns the updated agent; only the fields you send are changed, and an explicit null clears nullable fields back to their…
- [Enable an agent](https://docs.hq.zone/api-reference/agents/enable-agent.md): Re-enables a previously disabled agent by setting its status back to enabled, restoring routing on all surfaces, and returns the re-enabled agent. Idempotent: calling it on an already-enabled agent is a no-op. Returns 404 if the agent is not in the caller's workspace. Admin only.
- [Disable an agent](https://docs.hq.zone/api-reference/agents/disable-agent.md): Disables the named agent by setting its status to disabled so it no longer routes on any surface, and returns the now-disabled agent. The default agent cannot be disabled; promote another agent to default first (returns 400). Returns 404 if the agent is not in the caller's workspace. Admin only.
- [Set the default agent](https://docs.hq.zone/api-reference/agents/set-default.md): Promotes the named agent to be the workspace's default agent, atomically clearing the default flag from whichever agent previously held it, and returns the now-default agent. The target must be enabled; a disabled agent cannot be made default (returns 400). Returns 404 if the agent is not in the cal…
- [Upload an agent avatar](https://docs.hq.zone/api-reference/agents/upload-avatar.md): `POST /v1/agents/{id}/avatar` - admin uploads an avatar image. Mirrors the business_profile_api logo upload: base64 in, decoded + validated locally, then handed to the internal artifacts publisher which writes Trove + the row. Resulting download URL is stored as the agent's `avatar_url`.
- [Generate an agent avatar](https://docs.hq.zone/api-reference/agents/generate-avatar.md): `POST /v1/agents/{id}/avatar/generate` - admin-triggered xAI image generation. The optional `prompt` describes the desired look; it seeds the subject and is wrapped in the house illustration style + safety rails, then the image is stored in Trove and set as the agent's `avatar_url`. Synchronous (a f…
- [Suggest agent instructions](https://docs.hq.zone/api-reference/agents/suggest-instructions.md): `POST /v1/agents/{id}/suggest-instructions`
- [List an agent's skills](https://docs.hq.zone/api-reference/agents/list-skills.md): Returns the agent's enabled skill subset as a list of skill slugs. An empty list means the agent uses all skills installed for the workspace. Returns 404 if the agent is not in the caller's workspace. Requires the agents:read scope.
- [Replace an agent's skills](https://docs.hq.zone/api-reference/agents/replace-skills.md): Replaces the agent's enabled skill subset with the supplied list of skill slugs and returns the new subset; sending an empty list resets the agent to use all installed skills. Every requested slug must be a skill currently installed for the workspace, otherwise the request is rejected (returns 400).…
- [List an agent's MCP servers](https://docs.hq.zone/api-reference/agents/list-mcp.md): Returns the agent's enabled MCP-server subset as a list of server slugs. An empty list means the agent uses all MCP servers installed for the workspace. Returns 404 if the agent is not in the caller's workspace. Requires the agents:read scope.
- [Replace an agent's MCP servers](https://docs.hq.zone/api-reference/agents/replace-mcp.md): Replaces the agent's enabled MCP-server subset with the supplied list of server slugs and returns the new subset; sending an empty list resets the agent to use all installed MCP servers. Every requested slug must be an MCP server currently installed for the workspace, otherwise the request is reject…
- [List models](https://docs.hq.zone/api-reference/agents/list-models.md): Lists the models that can be selected in the agent editor, each with its slug, display name, family, runtime profile, vendor, and whether it is the runtime's default. Pass the optional runtime query parameter (claude-sdk, openai-agents, or opencode) to restrict the list to one runtime profile; other…
- [List conversations](https://docs.hq.zone/api-reference/conversations/list-conversations.md): Returns a paginated list of the caller's conversations within their workspace, by default newest-activity first. Each row includes the conversation id, channel, mode, last-activity time, title, a short preview of the latest message, the associated agent, an optional attached app, a delivered-artifac…
- [Create a conversation](https://docs.hq.zone/api-reference/conversations/create-conversation.md): Creates a new web conversation bound to a chosen agent and returns its identifiers so the client can navigate to the new thread and begin sending messages. Scoped to the caller's workspace; the agent_id must belong to the caller's workspace (otherwise 404). The caller is added as the conversation ow…
- [Get a conversation](https://docs.hq.zone/api-reference/conversations/get-conversation.md): Returns metadata for a single conversation the caller can access, including its title, mode (standard or fast), originating channel, surface type, whether it is read-only, the associated agent (id, slug, display name, avatar), and a directory of participants referenced in the thread. Scoped to the c…
- [Rename a conversation](https://docs.hq.zone/api-reference/conversations/rename-conversation.md): PATCH /v1/api/conversations/{id} - participant renames the conversation. A non-empty title is pinned (title_is_custom = true) so the title.derive worker never overwrites it; an empty title clears both so the conv falls back to auto-derivation. Admin-view callers are intentionally NOT allowed to rena…
- [Delete a conversation](https://docs.hq.zone/api-reference/conversations/delete-conversation.md): Permanently deletes a conversation and cascades teardown of its backing app surfaces, sandbox resources, messages, and related records. Scoped to the caller's workspace and conversations they participate in. By default the conversation's delivered artifacts are detached and kept (still downloadable…
- [Post a message to a conversation](https://docs.hq.zone/api-reference/conversations/post-message.md): `POST /v1/api/conversations/{id}/messages` -- Phase A.4 (#726).
- [List conversation messages](https://docs.hq.zone/api-reference/conversations/list-messages.md): Returns the conversation's transcript as a sequence-ordered list of journal rows, each carrying its direction, kind, JSON payload, sequence number, turn id, timestamp, and resolved author name/avatar; this is the cold-load companion to the live event stream. Optional query parameters filter the resu…
- [Stream conversation events](https://docs.hq.zone/api-reference/conversations/stream.md): Opens a Server-Sent Events stream of a conversation's live turn activity, emitting named events (agent token, tool, and final event kinds, plus stale when the client has lagged and done when the turn closes) each carrying a JSON data payload and an incrementing id sequence. Resume after a disconnect…
- [Interrupt the active turn](https://docs.hq.zone/api-reference/conversations/interrupt.md): `POST /v1/api/conversations/{id}/interrupt` - the user-facing "Stop". Fires the in-flight turn's abort token: the turn's stream loop breaks, the RunTurn gRPC drops, the vsock to the in-VM adapter tears down, and the adapter hits EOF and interrupts its SDK - the agent actually halts (Claude-CLI Esc).…
- [Nudge a conversation](https://docs.hq.zone/api-reference/conversations/nudge.md): Buffers an extra text message to be delivered to an agent turn that is currently in progress on the conversation, returning whether it was buffered and how many nudges are now pending. The caller must be a participant of the conversation (404 otherwise), and there must be an active turn to nudge, ot…
- [Start a fast ask](https://docs.hq.zone/api-reference/conversations/new-ask.md): Create an empty `mode='fast'` conversation and return its id. The Studio "New ask" button calls this, then navigates to the thread; the first message runs on the fast lane because the conversation is fast.
- [Promote a fast session](https://docs.hq.zone/api-reference/conversations/promote.md): Promotes a lightweight fast (quick-ask) conversation into a full standard conversation, binding it to the workspace's default agent so subsequent turns run in the full agent environment seeded with the existing transcript. The caller must be a participant of the conversation (returns 403 otherwise).…
- [List conversation artifacts](https://docs.hq.zone/api-reference/conversations/list-conversation-artifacts.md): Lists the delivered artifacts for a single conversation in chronological order. Scoped to the caller's workspace and accessible conversations; workspace admins may pass view=admin to view another member's conversation. Each entry includes the artifact id, name, content type, size, a sensitive flag,…
- [Download conversation artifacts](https://docs.hq.zone/api-reference/conversations/download-conversation-artifacts.md): Streams a ZIP archive (application/zip) containing all of the conversation's delivered artifacts. Scoped to the caller's workspace and conversations they participate in. Colliding filenames are de-duplicated within the archive. Returns 404 when the conversation has no artifacts to download.
- [List artifacts](https://docs.hq.zone/api-reference/conversations/list-artifacts.md): Lists delivered artifacts (agent-produced deliverables) visible to the caller across their workspace, newest first and capped at 500. A caller sees artifacts from conversations they participate in, plus detached artifacts (whose conversation was deleted) that they originally produced; system assets…
- [Delete an artifact](https://docs.hq.zone/api-reference/conversations/delete-artifact.md): Permanently deletes a delivered artifact and its stored bytes. Authorized like the artifact listing: the caller must participate in the artifact's conversation, or, once detached, be the artifact's original producer (otherwise 403). Deleting an attached artifact also removes it from the conversation…
- [Download an artifact](https://docs.hq.zone/api-reference/conversations/download-artifact.md): Downloads the bytes of the named artifact, streamed back with the artifact's original Content-Type and a Content-Disposition: attachment header carrying its filename. Scoped to the caller's own workspace: an artifact belonging to another workspace returns 404.
- [List conversation surfaces](https://docs.hq.zone/api-reference/conversations/list-surfaces.md): Lists the live application surfaces (apps) attached to a conversation, excluding destroyed ones, ordered by most recent activity. Scoped to the caller's workspace and accessible conversations; workspace admins may pass view=admin to inspect another member's conversation. Each surface includes its id…
- [Share a surface](https://docs.hq.zone/api-reference/conversations/share-surface.md): Mints a time-limited signed share URL for an app surface that the caller can hand out, without making the surface publicly visible. Scoped to the caller's workspace, and the caller must be able to access the surface's backing conversation. The optional ttl_secs sets the validity window, defaulting t…
- [Set surface visibility](https://docs.hq.zone/api-reference/conversations/set-visibility.md): Sets an app surface's visibility to either private or public, controlling whether its bare URL works for anyone. Scoped to the caller's workspace, and the caller must be able to access the surface's backing conversation. Rejects values other than private or public with 400. Returns the surface id, t…
- [Restore a surface](https://docs.hq.zone/api-reference/conversations/restore-surface.md): Initiates restoration of a previously paused or archived app surface so it can run again. Scoped to the caller's workspace, and the caller must be able to access the surface's backing conversation. Returns the surface id and the restore outcome. Returns 404 if the surface is not found in the caller'…
- [Delete a surface](https://docs.hq.zone/api-reference/conversations/delete-surface.md): Deletes an app surface, stopping it and releasing its resources. Scoped to the caller's workspace; a workspace admin may delete any app in the workspace, while a non-admin must participate in the surface's backing conversation. Returns the surface id and the deletion outcome. Returns 404 if the surf…
- [List apps](https://docs.hq.zone/api-reference/conversations/list-apps.md): Returns the workspace's catalog of persistent app surfaces, visible to any member of the workspace, excluding destroyed apps and ordered by most recent activity. Each app includes its id, slug, state, visibility (public or private), run mode, declared port, originating conversation id (null if that…
- [Deliver an artifact to a channel](https://docs.hq.zone/api-reference/conversations/deliver-artifact.md): Pushes one of a conversation's delivered artifacts into a Slack channel the HQ bot belongs to. Used from the Studio when a file the agent produced in a web conversation needs to reach Slack (the automatic reply-to-source mirror only fires for Slack-born turns). The file is uploaded to Slack natively…
- [List documents](https://docs.hq.zone/api-reference/documents/list-documents.md): Returns the documents visible to the caller, newest first, along with the distinct categories and tags across that visible set for building filter sidebars. Visibility is enforced per request: team-scoped documents are seen by everyone in the workspace, private ones only by their owner, and channel-…
- [Search documents](https://docs.hq.zone/api-reference/documents/search-documents.md): Performs a case-insensitive substring search over the filename, caption, summary, and tags of documents the caller can see, returning matches newest first. Visibility rules are the same as the list endpoint (private, channel, and team scopes). Accepts a required q query parameter and an optional lim…
- [Upload a document](https://docs.hq.zone/api-reference/documents/upload-document.md): Uploads a document by sending its bytes inline as base64 in the JSON body (capped at roughly 12 MiB of file content), together with filename, content type, scope (private, channel, or team; defaults to private), and optional channel_id, category, tags, and caption. The operation is content-addressed…
- [Upload a document (multipart)](https://docs.hq.zone/api-reference/documents/upload-multipart.md): Uploads a single document as multipart/form-data, intended for browser drag-and-drop and accepting larger files than the inline JSON path (up to 64 MiB). The file bytes go in a part named file (or body), with optional text fields scope (private, channel, or team; defaults to private), channel_id, ca…
- [Get a document](https://docs.hq.zone/api-reference/documents/get-document.md): Returns the full metadata for a single document by id, including its filename, content type, size, SHA-256 hash, scope, owner, category, tags, caption, summary, classification status and confidence, detected language and document date, extracted reference numbers and entities, and a download URL. Th…
- [Update a document](https://docs.hq.zone/api-reference/documents/update-document.md): Updates the editable metadata of a document: its scope, channel assignment, category, tags, and caption. Only fields present in the request body are changed; for channel_id, category, and caption, an explicit null clears the value while omitting the field leaves it untouched. Only the document's own…
- [Download a document](https://docs.hq.zone/api-reference/documents/download-document.md): Streams back the raw bytes of a document as a file attachment, setting the original filename, content type, and content length, with a short private cache lifetime. The document is only served if it is visible to the caller under the same private/channel/team visibility rules as the read endpoints;…
- [Reclassify a document](https://docs.hq.zone/api-reference/documents/reclassify.md): Force the classifier worker to take another swing at this document. Owner-only. Resets `classification_status` to `queued`, zeros the rescue retry counter, and re-emits `hq.<tenant>.document.created` so a worker picks it up. Useful when the model returned a bad category, the upload arrived before th…
- [Delete a document](https://docs.hq.zone/api-reference/documents/delete-document.md): Moves a document to Trash (soft-delete) by default - the bytes are kept and `POST /v1/api/documents/{id}/restore` brings it back. Pass `?purge=true` to delete it permanently; the stored file content is then removed only when no other document in the workspace references the same bytes, so deduplicat…
- [Restore a trashed document](https://docs.hq.zone/api-reference/documents/restore-document.md): Brings a soft-deleted document back from Trash (clears `deleted_at`). If the folder it lived in has since been trashed, it is restored to the root of its scope instead. Owner-only. Returns the restored document. Requires documents:write.
- [List folders](https://docs.hq.zone/api-reference/documents/list-folders.md): Returns every folder the caller can see (their private folders, all team folders, and the folders of channels they belong to), flat - the client builds the tree from `parent_id`. Each row carries a live `doc_count`. Requires documents:read.
- [Create a folder](https://docs.hq.zone/api-reference/documents/create-folder.md): Creates a folder in one of the caller's roots. `scope='channel'` requires a `channel_id` the caller belongs to; a `parent_id`, if given, must be a visible folder of the same scope. Names are unique within a parent + scope. Requires documents:write.
- [Trash or permanently delete a folder](https://docs.hq.zone/api-reference/documents/delete-folder.md): Soft-deletes a folder and everything under it (descendant folders + the documents they hold travel to Trash together, like Drive/Dropbox). Restore with `POST /v1/api/folders/{id}/restore`. Pass `?purge=true` to permanently delete an already-trashed folder: the subtree folders + their documents are h…
- [Rename or move a folder](https://docs.hq.zone/api-reference/documents/update-folder.md): Renames and/or reparents a folder within its scope. A new parent must be a visible folder of the same scope and may not be the folder itself or one of its descendants (no cycles). Private folders are owner-only; team/channel folders are editable by any member. Requires documents:write.
- [Restore a trashed folder](https://docs.hq.zone/api-reference/documents/restore-folder.md): Brings a folder and its trashed subtree (descendant folders + their documents) back from Trash. If the folder's own parent is still trashed, it is restored to the root of its scope. Requires documents:write.
- [List facts about me](https://docs.hq.zone/api-reference/memory/list-facts.md): Returns the facts the assistant currently remembers about the calling user, scoped to the caller's own account. Each fact includes its id, text, type, confidence, the agent that asserted it, when it was asserted, and the source conversation id. The response also includes a distilled one-paragraph pe…
- [Correct a fact about me](https://docs.hq.zone/api-reference/memory/correct-fact.md): Corrects one of the assistant's remembered facts about the calling user by superseding it with a user-supplied replacement (1 to 4096 characters), preserving the original fact's type, confidence, agent, and source. The fact must currently be active and about the caller. Returns the id of the superse…
- [Forget a fact about me](https://docs.hq.zone/api-reference/memory/forget-fact.md): Forgets one of the assistant's remembered facts about the calling user, marking it superseded with no replacement so it is no longer surfaced. Idempotent: returns a status of "forgotten" when the fact was active, or "already_superseded_or_unknown" when it was already gone or never existed (no error…
- [List freezable agents](https://docs.hq.zone/api-reference/memory/list-freezable-agents.md): Returns every enabled agent in the caller's workspace alongside the calling user's own freeze state for each: whether it is frozen, when it was frozen, and the reason. Intended to drive a per-user "agents that can read your memory" toggle list. Scoped to the caller's own account.
- [List memory freezes](https://docs.hq.zone/api-reference/memory/list-freezes.md): Returns the list of agents the calling user has frozen out of their memory, each with the agent slug, the optional reason given, and when the freeze was created, ordered most recent first. Scoped to the caller's own account.
- [Freeze an agent's memory](https://docs.hq.zone/api-reference/memory/freeze.md): Freezes the named agent out of the calling user's memory, revoking that agent's ability to read facts about the caller. Accepts an optional reason. Idempotent: re-freezing updates the stored reason and timestamp. Returns the agent slug with frozen set to true. Scoped to the caller's own account.
- [Unfreeze an agent's memory](https://docs.hq.zone/api-reference/memory/unfreeze.md): Unfreezes the named agent for the calling user, re-granting that agent's ability to read facts about the caller. Idempotent. Returns the agent slug with frozen set to false. Scoped to the caller's own account.
- [List tables](https://docs.hq.zone/api-reference/tables/list-tables.md)
- [Create a table](https://docs.hq.zone/api-reference/tables/create-table.md)
- [Get a table with its fields](https://docs.hq.zone/api-reference/tables/get-table.md)
- [Delete a table](https://docs.hq.zone/api-reference/tables/delete-table.md)
- [Add a field to a table](https://docs.hq.zone/api-reference/tables/add-field.md)
- [Drop a field](https://docs.hq.zone/api-reference/tables/drop-field.md)
- [Insert rows](https://docs.hq.zone/api-reference/tables/insert-rows.md)
- [Query rows](https://docs.hq.zone/api-reference/tables/query-rows.md)
- [Update a row](https://docs.hq.zone/api-reference/tables/update-row.md)
- [Delete a row](https://docs.hq.zone/api-reference/tables/delete-row.md)
- [Export a table as CSV](https://docs.hq.zone/api-reference/tables/export-table-csv.md): Streams the table's live rows as a UTF-8 CSV attachment (RFC 4180, BOM for Excel, formula-injection defanged). Keyset-paged server-side so the response is constant-memory and never capped at the grid's page size. Full export (no filters) in v1. Requires the tables:read scope.
- [List schedules](https://docs.hq.zone/api-reference/schedules/list-schedules.md): Lists scheduled automated runs along with a total count for pagination. By default (scope=mine) it returns only the caller's own schedules; scope=workspace returns all schedules in the workspace and is admin only (returns 403 otherwise), optionally narrowed to one owner via owner_user_id. Results ca…
- [Create a schedule](https://docs.hq.zone/api-reference/schedules/create-schedule.md): Creates a new schedule that periodically runs an agent with a given prompt and delivery target, according to the supplied trigger. If agent_id is omitted the workspace's default enabled agent is used, and a non-existent agent_id returns 404. The new schedule is owned by the caller. Returns 201 with…
- [Get a schedule](https://docs.hq.zone/api-reference/schedules/get-schedule.md): Returns the full detail of a single schedule by id, including its name, description, trigger, run arguments, current lifecycle state, fire and failure counts, last and next fire times, and a link to the conversation from its most recent run. The schedule is only returned if the caller owns it or is…
- [Update a schedule](https://docs.hq.zone/api-reference/schedules/update-schedule.md): Updates an existing schedule's name, description, trigger, or run arguments; only the fields supplied are changed, and an explicit null description clears it while omitting it keeps the current value. Only the schedule's owner or an admin may update it (others receive 403). Returns an acknowledgemen…
- [Pause a schedule](https://docs.hq.zone/api-reference/schedules/pause-schedule.md): Pauses an active schedule so it stops firing until resumed. Only the schedule's owner or an admin may pause it (others receive 403). Returns an ok acknowledgement. Requires the schedules:write scope.
- [Resume a schedule](https://docs.hq.zone/api-reference/schedules/resume-schedule.md): Resumes a previously paused schedule so it begins firing again, returning the newly computed next fire time when the schedule was successfully resumed. Only the schedule's owner or an admin may resume it (others receive 403). Requires the schedules:write scope.
- [Fire a schedule now](https://docs.hq.zone/api-reference/schedules/fire-now.md): Triggers an immediate run of the schedule without waiting for its next scheduled time, leaving the regular firing cadence unchanged. Only the schedule's owner or an admin may fire it (others receive 403). Returns an ok acknowledgement. Requires the schedules:write scope.
- [Cancel a schedule](https://docs.hq.zone/api-reference/schedules/cancel-schedule.md): Cancels a schedule and archives it, stopping all future runs while retaining its history. Only the schedule's owner or an admin may cancel it (others receive 403). Returns an ok acknowledgement. Requires the schedules:write scope.
- [Erase an archived schedule](https://docs.hq.zone/api-reference/schedules/erase-schedule.md): Permanently erase an archived schedule. Owner or admin only; engine refuses to erase non-archived rows so the operator must hit the Cancel button first. Past `hq_flow.instances` rows survive with `schedule_id = NULL` (ON DELETE SET NULL on the FK).
- [List schedule owners](https://docs.hq.zone/api-reference/schedules/list-owners.md): `GET /v1/api/schedules/owners` (admin) - distinct schedule owners in the workspace with a count each. Powers the admin "filter by user" dropdown so it lists only users who actually have schedules (not every member), and stays bounded regardless of how many schedules exist.
- [List inbox messages](https://docs.hq.zone/api-reference/notifications/list-inbox.md): Returns a paginated page of the caller's personal in-app inbox messages (agent-delivered notifications such as scheduled-task digests), with each message's title, body, source and read state, plus the total matching count, the workspace-wide unread count for the nav badge, and the current page and p…
- [Mark an inbox message read](https://docs.hq.zone/api-reference/notifications/mark-inbox-read.md): Marks one of the caller's inbox messages as read, preserving the original read timestamp if it was already read. Scoped to the caller's own inbox; returns 404 if the message does not exist or is not theirs.
- [Mark an inbox message unread](https://docs.hq.zone/api-reference/notifications/mark-inbox-unread.md): Marks one of the caller's inbox messages as unread by clearing its read timestamp. Scoped to the caller's own inbox; returns 404 if the message does not exist or is not theirs.
- [Mark all inbox messages read](https://docs.hq.zone/api-reference/notifications/mark-all-inbox-read.md): Marks all of the caller's unread inbox messages as read. Scoped to the caller's own inbox and idempotent (returns ok even when nothing was unread).
- [Delete an inbox message](https://docs.hq.zone/api-reference/notifications/delete-inbox.md): Permanently deletes one of the caller's inbox messages. Scoped to the caller's own inbox; returns 404 if the message does not exist or is not theirs.
- [List notifications](https://docs.hq.zone/api-reference/notifications/list-notifications.md): Returns the caller's in-app notification center: up to 100 non-dismissed notifications (newest first), each with its kind, title, body, optional call-to-action, severity and status, plus a count of how many are still unread for the bell badge. Scoped to the caller's workspace and includes both notif…
- [Mark a notification read](https://docs.hq.zone/api-reference/notifications/mark-notification-read.md): Marks a single notification as read and records the read time. Scoped to the caller's workspace and to notifications addressed to the caller or workspace-wide; only affects a notification currently in the unread state and always returns ok.
- [Mark all notifications read](https://docs.hq.zone/api-reference/notifications/mark-all-notifications-read.md): Marks all of the caller's unread notifications as read and returns the number updated. Scoped to the caller's workspace and to notifications addressed to the caller or workspace-wide.
- [Dismiss a notification](https://docs.hq.zone/api-reference/notifications/dismiss-notification.md): Dismisses a single notification so it no longer appears in the notification list, recording the dismiss time. Scoped to the caller's workspace and to notifications addressed to the caller or workspace-wide; always returns ok.
- [Register a device for push](https://docs.hq.zone/api-reference/notifications/register-device-token.md): Upserts the caller's APNs device token for the current workspace. Idempotent per `(token, tenant)`: a re-register from the same device updates the owning user, platform, bundle id, environment and refreshes `last_seen_at`.
- [Unregister a device token](https://docs.hq.zone/api-reference/notifications/delete-device-token.md): Removes the caller-tenant's registration for this device token (called on sign-out). Scoped to the caller's workspace; APNs feedback prunes the rest.
- [Get connection status](https://docs.hq.zone/api-reference/integrations/connect-status.md): Returns the workspace's integration connection state and recommendations in one payload: whether Slack and Microsoft Teams are connected (with team/org name when available), the browser-extension download and web-store URLs (null until published), the list of suggested or accepted integration/skill…
- [Browser connect](https://docs.hq.zone/api-reference/integrations/browser-connect.md)
- [Ask using the user's browser](https://docs.hq.zone/api-reference/integrations/browser-ask.md): The dedicated browser path. The extension's "use my browser" button POSTs here, PAT-authed (the same token the WebSocket uses). This is the ONLY entry that runs an agent scoped to the local-browser tools (computer_*) + the browser prompt - normal chat (web / Slack) never sees them, because hq:comput…
- [List Slack channels](https://docs.hq.zone/api-reference/integrations/list-channels.md): Lists the Slack channels the HQ bot is a member of (each with id, name, and whether it is private), which is also the set of channels HQ can post to, for use in pickers such as the schedule editor. The response includes a connected flag that is false when the workspace has no active Slack installati…
- [List joinable Slack channels](https://docs.hq.zone/api-reference/integrations/list-joinable-channels.md): `GET /v1/api/slack/channels/joinable` (admin). Public channels HQ is NOT a member of - the ones the admin can self-join with one click. Private channels are intentionally excluded: Slack forbids a bot from self-joining them, so they need an `/invite @HQ` from a member.
- [Join a Slack channel](https://docs.hq.zone/api-reference/integrations/join-channel.md): `POST /v1/api/slack/channels/{id}/join` (admin). Self-joins HQ to a public channel via `conversations.join`. Idempotent on Slack's side (joining a channel you're already in just succeeds).
- [Get the MCP catalog](https://docs.hq.zone/api-reference/integrations/mcp-catalog.md): Returns the full catalog of available MCP integration servers along with the calling workspace's install state for each. For every active server it reports static metadata (display name, description, category, publisher, transport, trust tier, version, credential model, and any featured ranking) plu…
- [List an MCP server's tools](https://docs.hq.zone/api-reference/integrations/mcp-catalog-tools.md): Returns the captured tool list (name + one-line description) for one catalog server, scoped to the caller's workspace for custom (`t:`) backends. Empty until the backend's schema has been captured. Admin only.
- [Get an MCP catalog icon](https://docs.hq.zone/api-reference/integrations/mcp-icon.md): Returns the SVG brand icon for the given MCP server as image/svg+xml. The response is public, immutable, and long-cached; a 404 is returned when the server has no icon or is not active.
- [Install an MCP server](https://docs.hq.zone/api-reference/integrations/install-mcp.md): Installs or re-enables an MCP integration for the caller's workspace, marking it active and enabled. Servers using a tenant credential model (tenant_api_key or tenant_oauth) require a credential reference in the request, which must be provisioned beforehand. Accepts an optional per-tenant config blo…
- [Set an MCP server API key](https://docs.hq.zone/api-reference/integrations/set-mcp-key.md): Stores an API key credential for an MCP server and installs/enables it in one call, for servers whose credential model is tenant_api_key only. The scope may be team (shared across the workspace, the default) or user (private to the caller); the chosen scope must be among the server's allowed scopes,…
- [Uninstall an MCP server](https://docs.hq.zone/api-reference/integrations/uninstall-mcp.md): Disables an MCP integration for the caller's workspace, setting it to not enabled (this works even for servers enabled by default with no prior explicit install). Also clears any stored tenant credential for that server so a later re-install must supply a fresh one. Returns the slug with enabled set…
- [Add a custom MCP](https://docs.hq.zone/api-reference/integrations/mcp-custom-create.md): Provisions a private custom MCP integration for the caller's workspace from a pasted server URL. The server is re-probed and must be self-serve connectable; the workspace custom-integration policy is enforced first. A private catalog entry is created and, for open (no-auth) servers, enabled immediat…
- [Probe a custom MCP URL](https://docs.hq.zone/api-reference/integrations/mcp-custom-probe.md): Dry-run discovery for a pasted MCP server URL: detects the server's authentication method (none, API key, or OAuth), reports whether the workspace can finish connecting it self-serve, and previews the server's tool list - without writing anything. The URL is checked against the workspace's custom-in…
- [Get the custom-MCP policy](https://docs.hq.zone/api-reference/integrations/mcp-custom-policy-get.md): Returns the caller's workspace policy for self-serve custom MCP integrations: whether custom integrations are enabled, the allow-list and block-list of domains, and whether newly added integrations require admin approval before agents can use them. Admin only; scoped to the caller's own workspace.
- [Update the custom-MCP policy](https://docs.hq.zone/api-reference/integrations/mcp-custom-policy-put.md): Replaces the caller's workspace policy for self-serve custom MCP integrations: toggles whether custom integrations are allowed at all, sets the allow-list and block-list of domains (each normalized to a bare host), and sets whether newly added integrations must be approved by an admin before agents…
- [Set a custom MCP's daily call cap](https://docs.hq.zone/api-reference/integrations/mcp-custom-limits.md): Sets or clears the per-day call cap for one of the caller's workspace's custom integrations; a null or zero value removes the cap (uncapped). Only integrations owned by the caller's own workspace can be limited here. Admin only. Returns 204 No Content.
- [Approve a custom MCP](https://docs.hq.zone/api-reference/integrations/mcp-custom-approve.md): Approves a custom integration that is held for review (either on first add under an approval-required policy, or after its tool set changed since the last approval). The currently-captured tool set is recorded as the approved baseline and the integration is re-activated so agents can use it again. O…
- [Remove a custom MCP](https://docs.hq.zone/api-reference/integrations/mcp-custom-delete.md): Deletes a custom integration the caller's workspace previously added, along with its install rows, stored credentials, and per-agent enablement. Only integrations owned by the caller's own workspace (slug prefix `t:`) can be removed here; vetted platform/third-party integrations cannot. Admin only.…
- [List connectors](https://docs.hq.zone/api-reference/integrations/connector-list.md): Returns every connector registered in the caller's workspace, newest first, with each connector's id, name, status, last-seen timestamp, and creation time. Admin only; scoped to the caller's own workspace.
- [Create a connector](https://docs.hq.zone/api-reference/integrations/connector-create.md): Registers a new connector for the caller's workspace and returns a one-time enrollment token (shown only here, never stored) along with the tunnel address and server name the connector agent dials out to. Admin only; scoped to the caller's own workspace.
- [Enroll a connector](https://docs.hq.zone/api-reference/integrations/connector-enroll.md): Completes connector enrollment: the connector agent presents its one-time enrollment token and a PEM-encoded certificate signing request, and receives a CA-signed client certificate, the CA certificate, and the tunnel address it should dial. This endpoint is public and authenticated only by the one-…
- [Register a private MCP behind a connector](https://docs.hq.zone/api-reference/integrations/connector-add-mcp.md): Registers a private MCP server reached through the given connector and installs it (enabled) for the caller's workspace. The MCP is exposed at the connector's local base path (defaulting to `/mcp`) and may carry an optional per-day call cap. Returns the generated catalog slug for the new integration…
- [Revoke a connector](https://docs.hq.zone/api-reference/integrations/connector-revoke.md): Revokes the given connector in the caller's workspace: its certificate fingerprint and any pending enrollment token are cleared so no new mTLS sessions can be established, and live sessions drop on their next reconnect. Admin only; scoped to the caller's own workspace. Returns 204 No Content.
- [Get the skills catalog](https://docs.hq.zone/api-reference/integrations/skills-catalog.md): Returns the full catalog of available skills along with the calling workspace's install state for each. For every active skill it reports metadata (display name, description, category, publisher, runtime profile, version, trust tier, and any featured ranking), whether it is system-locked (always on)…
- [Get skill content](https://docs.hq.zone/api-reference/integrations/skill-content.md): Returns the full content of a skill pack, including its SKILL.md (listed first) and any additional files, with the skill's display name, description, runtime profile, and trust tier. Inline text files include their UTF-8 contents; large external assets are listed but returned with empty content. The…
- [Get a skill icon](https://docs.hq.zone/api-reference/integrations/skill-icon.md): Returns the SVG icon for the given skill as image/svg+xml. The response is public, immutable, and long-cached; a 404 is returned when the skill has no icon or is not active.
- [Install a skill](https://docs.hq.zone/api-reference/integrations/install-skill.md): Installs or re-enables a skill for the caller's workspace, marking it active and enabled. Accepts an optional per-tenant config blob. System-locked skills cannot be installed this way (they are always on) and unknown or inactive slugs return 404. Idempotent: re-installing updates the existing entry…
- [Upload a skill](https://docs.hq.zone/api-reference/integrations/upload-skill.md): Creates a workspace-owned skill from caller-supplied content. The body may be either inline markdown (wrapped automatically as SKILL.md) or a multi-file pack of base64-encoded files that must include a SKILL.md at the root. The display name must be 3 to 60 characters of letters, digits, spaces, hyph…
- [Uninstall a skill](https://docs.hq.zone/api-reference/integrations/uninstall-skill.md): Disables a skill for the caller's workspace, opting it out even if it is enabled by default with no prior explicit install. System-locked skills cannot be disabled (they are always on). Returns the slug with enabled set to false. Admin only; scoped to the caller's own workspace.
- [Delete a skill](https://docs.hq.zone/api-reference/integrations/delete-skill.md): Permanently deletes a workspace-owned skill and its install records. Only the caller's own tenant skills (those whose slug carries the tenant prefix) and only workspace-authored (T3) skills may be deleted; attempting to delete a platform skill or another tenant's skill is forbidden. Returns the slug…
- [Accept a recommendation](https://docs.hq.zone/api-reference/integrations/accept-recommendation.md): Marks the named recommendation as accepted and returns its new status. Scoped to the caller's workspace, so an id from another workspace returns 404. Accepting currently records intent only and does not yet perform the underlying integration connect or skill enable. Requires the agents:write scope.
- [Dismiss a recommendation](https://docs.hq.zone/api-reference/integrations/dismiss-recommendation.md): Marks the named recommendation as dismissed and returns its new status. Scoped to the caller's workspace, so an id from another workspace returns 404. Requires the agents:write scope.
- [Connect Slack to the current workspace](https://docs.hq.zone/api-reference/integrations/connect-slack-install.md): Begins binding a Slack workspace to the caller's EXISTING tenant (the already-signed-in admin's workspace). Unlike the public, invite-gated `/get-started/slack` landing - which provisions a brand-new tenant from the install - this authenticated entry attaches the Slack workspace the admin authorizes…
- [Download the Teams app package](https://docs.hq.zone/api-reference/integrations/connect-teams-package.md): Streams the HQ Microsoft Teams app package (manifest zip) for an admin to upload to their Teams org catalog / sideload. The file path is configured by `HQ_TEAMS_APP_PACKAGE`; unconfigured or missing -> 404. Admin only. The package is the same for every org (the bind happens via the Microsoft sign-in…
- [Connect Microsoft Teams to the current workspace](https://docs.hq.zone/api-reference/integrations/connect-teams-start.md): Begins binding a Microsoft Teams org to the caller's EXISTING tenant. Teams has no install redirect HQ controls (unlike Slack), so this starts a verified "Sign in with Microsoft" (Entra OIDC): the callback records a `teams_bind_claims` row tying the admin's AAD org (`tid`) + user (`oid`) to this HQ…
- [List Microsoft Teams channels](https://docs.hq.zone/api-reference/integrations/list-teams-channels.md): Lists the standard Teams channels HQ can post to (each with team_id, channel_id, and name), sourced from the workspace corpus catalog the Teams crawl populates, for use in pickers such as the schedule editor. The response includes a connected flag that is false when the workspace has no active Teams…
- [Search the public MCP ecosystem (Discover)](https://docs.hq.zone/api-reference/integrations/mcp-directory-search.md): Read-only search over the wild MCP directory - public servers that exist in the open ecosystem, NOT the integrations this workspace runs. Each hit notes whether it is hostable (addable as a custom integration). Admin only; 503s when the directory database is not configured.
- [Public MCP directory size (Discover landing)](https://docs.hq.zone/api-reference/integrations/mcp-directory-stats.md): Read-only counts over the wild MCP directory for the Discover empty-state. Admin only; 503s when the directory database is not configured.
- [Get my billing usage](https://docs.hq.zone/api-reference/billing/my-usage.md): Billing usage for the caller's own tenant (billing B1). Session-scoped (resolved from the workspace + user headers) and admin-gated - credits and spend are workspace-admin information. Reuses the same projection as the operator route `/v1/admin/usage`; see `crate::usage_admin::summarize`.
- [Start a checkout session](https://docs.hq.zone/api-reference/billing/checkout.md): Starts a subscription upgrade by creating a checkout session for the named plan and returns a hosted checkout URL to redirect the customer to. Workspace admin only. The plan_slug must reference an active plan that has a configured price (otherwise 400); the actual plan provisioning happens asynchron…
- [Buy a credit pack](https://docs.hq.zone/api-reference/billing/topup.md): Buy a one-time credit pack (billing D). Available to ANY tier - a free-tier account gets a Stripe customer minted on demand, same as checkout. The `+topup` lands in credit_ledger when Stripe fires `checkout.session.completed` (mode=payment) at the webhook; the ledger stays authoritative.
- [Open the billing portal](https://docs.hq.zone/api-reference/billing/portal.md): Creates a hosted billing-portal session for the caller's workspace and returns its URL, where an admin can manage payment methods, view invoices, and change or cancel the subscription. Workspace admin only. Works even for workspaces that have never purchased (a billing customer is created on demand)…
- [List API tokens](https://docs.hq.zone/api-reference/tokens/list-tokens.md): Lists the authenticated caller's own live personal access tokens. Scoped to the caller's manually created tokens that are not revoked and not expired; OAuth-issued access and refresh tokens (those tied to a client) are deliberately excluded. Each entry includes the token id, name, kind, granted scop…
- [Create an API token](https://docs.hq.zone/api-reference/tokens/create-token.md): Creates a new personal access token for the authenticated caller, returning the plaintext token exactly once (it cannot be retrieved again) along with its id, name, scopes, and optional expiry. Accepts a name, an optional list of capability scopes (resource:action, e.g. documents:read; omitting scop…
- [Revoke an API token](https://docs.hq.zone/api-reference/tokens/revoke-token.md): Revokes one of the authenticated caller's own personal access tokens, identified by its id in the path. The revocation takes effect immediately. Scoped to the caller's own tokens, so it cannot revoke another user's token. Returns a revoked flag, or 404 if no matching live token belongs to the caller…
- [List token scopes](https://docs.hq.zone/api-reference/tokens/list-scopes.md): Returns the vocabulary of resource:action capability scopes a personal access token can be minted with. Each entry lists the scope string, a human-readable description of what it allows, and a requires_admin flag indicating whether granting it requires the admin role. Requires authentication.
- [List OAuth apps](https://docs.hq.zone/api-reference/tokens/list-oauth-apps.md): Lists the OAuth applications the authenticated caller has registered, scoped to the caller's own active (non-disabled) apps. Each entry includes the client_id, name, client_type (public for PKCE-only or confidential for clients with a secret), redirect_uris, requestable scopes, and creation timestam…
- [Create an OAuth app](https://docs.hq.zone/api-reference/tokens/create-app.md): Registers a new OAuth application owned by the authenticated caller, validating the supplied client metadata (redirect URIs must be https or http loopback with no fragment, scopes must be known capability scopes). Returns the created app including its client_id and, for confidential clients, a clien…
- [Update an OAuth app](https://docs.hq.zone/api-reference/tokens/update-app.md): Updates the mutable metadata (name, redirect URIs, and requestable scopes) of an OAuth app owned by the authenticated caller, identified by client_id in the path. The client type and secret lifecycle are fixed at registration and cannot be changed here. New metadata is validated with the same rules…
- [Delete an OAuth app](https://docs.hq.zone/api-reference/tokens/delete-app.md): Disables (deregisters) an OAuth app owned by the authenticated caller, identified by client_id in the path. Once disabled the client can no longer be used and its issued tokens stop working. Returns a deleted flag, or 404 if the caller does not own an active app with that client_id.
- [List OAuth authorizations](https://docs.hq.zone/api-reference/tokens/list-authorizations.md): Lists the third-party OAuth applications the authenticated caller has authorized (consented to). Each entry includes the client_id, app name, client_type, an active flag indicating whether the app is still registered and enabled, the union of scopes the user has granted it, and timestamps for when i…
- [Revoke an OAuth authorization](https://docs.hq.zone/api-reference/tokens/revoke-authorization.md): Revokes the authenticated caller's authorization for a third-party OAuth app, identified by client_id in the path. This removes the consent and immediately revokes all of that app's live access and refresh tokens for this user, so the app's next API call fails and it must request authorization again…
- [Get onboarding status](https://docs.hq.zone/api-reference/onboarding/onboarding-status.md): Returns the current onboarding state for the caller's workspace: whether onboarding has been completed, whether the business domain has been confirmed, the configured business domain if any, and a wizard track value (slack, teams, or web) indicating which onboarding flow applies. Scoped to the calle…
- [Check a domain](https://docs.hq.zone/api-reference/onboarding/check-domain.md): `GET /v1/api/onboarding/domain/check?domain=` - live pre-check for the wizard so a typo is caught before submit. Returns the normalized host + whether it has a valid shape + whether it resolves.
- [Set onboarding domain](https://docs.hq.zone/api-reference/onboarding/set-domain.md): Sets and confirms the workspace's business domain during onboarding. The submitted value is normalized to a bare hostname and validated for shape and live DNS resolution, rejecting typos, unresolvable domains, and private or internal addresses with a 400; on success the domain is recorded as confirm…
- [Complete onboarding](https://docs.hq.zone/api-reference/onboarding/complete-onboarding.md): Marks the caller's workspace as having completed onboarding, which lifts the onboarding gate that otherwise blocks normal API access for a new workspace. The operation is idempotent: it only sets the completion timestamp if onboarding was not already complete. Admin only (returns 403 otherwise). Ret…
- [List help articles](https://docs.hq.zone/api-reference/help/help-articles.md): `GET /v1/help/articles` - every article's metadata (slug, title, category, order, summary), for the Help & Docs browse view. Global corpus.
- [Get a help article](https://docs.hq.zone/api-reference/help/help-article.md): `GET /v1/help/articles/{slug}` - one article's full markdown body.
- [Search the help corpus](https://docs.hq.zone/api-reference/help/help-search.md): `GET /v1/help/search?q=...` - hybrid search: Torque BM25 (lexical) UNION pgvector ANN (dense), fused + ordered by a cross-encoder reranker, best chunk per article. The same recall stack workspace search uses. Degrades to dense-only, lexical-only, or a Postgres FTS fallback if a backend is down.
- [Create a help article (operator)](https://docs.hq.zone/api-reference/help/help-create-article.md): `POST /v1/help/articles` - create a new article. Operator-only. The new row is chunked + embedded + indexed before this returns.
- [Update a help article (operator)](https://docs.hq.zone/api-reference/help/help-update-article.md): `PUT /v1/help/articles/{slug}` - replace an article's fields. Operator-only. Re-chunked + re-embedded + re-indexed before returning.
- [Delete a help article (operator)](https://docs.hq.zone/api-reference/help/help-delete-article.md): `DELETE /v1/help/articles/{slug}` - remove an article. Operator-only. Its chunks cascade-delete and the Torque index is reconciled before returning.
- [List users](https://docs.hq.zone/api-reference/admin/list-users.md): Returns the workspace's user directory as a paginated list, each entry including external id, source connector and workspace, display and real name, email, title, timezone, locale, admin/bot/guest/deleted flags, profile-consent state, last-seen time, sign-in access, admin-role override, and origin (…
- [Add a user by email](https://docs.hq.zone/api-reference/admin/add-user.md): `POST /v1/api/users` - add a member by email (no Slack/Teams needed). Creates (or re-activates) a `workspace_users` row on the tenant's synthetic `direct` source with `origin='email'`, `signin_access='allowed'`, then mints a magic-link invite. Returns the link when no transactional email sender is w…
- [Get a user](https://docs.hq.zone/api-reference/admin/get-user.md): `GET /v1/api/users/{id}` - one user (admin-only, tenant-scoped) for the detail page. Reuses USER_SELECT; bots/deleted are NOT excluded here (a deep link to an erased user must still resolve so the detail can show its state).
- [Update a user's access](https://docs.hq.zone/api-reference/admin/update-user.md): `PATCH /v1/api/users/{id}` - set one user's sign-in access and/or tenant-admin role. Admin-only, tenant-scoped: the UPDATE is joined through the tenant slug so an admin can only ever touch a user in their OWN workspace. Either field may be omitted (only the supplied ones change).
- [Resend a user invite](https://docs.hq.zone/api-reference/admin/resend-invite.md): `POST /v1/api/users/{id}/resend` - re-send the magic-link invite to a pending email member. Admin-only, tenant-scoped.
- [Revoke a pending invite](https://docs.hq.zone/api-reference/admin/revoke-invite.md): `DELETE /v1/api/users/{id}` - revoke a PENDING email invite (added by email, not yet signed in). Hard-deletes the row (no data to keep). Active members (signed in, or Slack/Teams) are NOT deletable here - that's the erasure flow. Admin-only, tenant-scoped.
- [Erase another user (admin)](https://docs.hq.zone/api-reference/admin/erase-user.md): `POST /v1/admin/users/{id}/erase` - admin-erasure on behalf of another user. Requires `is_admin = TRUE` on the caller's row. Refuses self-erase via this route (use /v1/api/me/erase) so the audit trail consistently records `actor == subject` only for the explicit self path.
- [Get workspace settings](https://docs.hq.zone/api-reference/admin/get-settings.md): Returns the workspace-level settings an admin controls. Admin only. Includes the connected source's id, kind, and display name (read-only), the persona-distillation mode and per-user consent mode, the corpus history window in days, the sign-in mode and whether guest sign-in is allowed, and proactive…
- [Update workspace settings](https://docs.hq.zone/api-reference/admin/update-settings.md): Updates the workspace-level settings an admin controls and returns the full updated settings. Admin only. Any subset of fields may be supplied; omitted fields are left unchanged, and for the nudge timezone and fallback language an empty string reverts to the default. Validates allowed values and ran…
- [Check whether a workspace handle is free (admin).](https://docs.hq.zone/api-reference/admin/workspace-slug-available.md): Validates format + reserved words and checks global uniqueness across BOTH the URL registry (`tenants.slug`) and the email registry (`tenant_email_slug`), so the handle works for the URL and the email address alike. Advisory only - `set_slug` re-checks atomically.
- [Set / rename the workspace handle (admin).](https://docs.hq.zone/api-reference/admin/set-workspace-slug.md): Renames `tenants.slug` (the URL handle) and realiases the email slug to match, keeping the old email address routing for a continuity window. The SPA reloads into `/<new>/`; stale `/<old>/` links self-heal via the email-keyed session. Re-validates atomically; the `tenants.slug` unique constraint is…
- [Get business profile](https://docs.hq.zone/api-reference/admin/get-profile.md): Returns the workspace's business profile, including its configured domain, the most recently crawled summary, brand palette, fonts, logo, crawl status and any last error, plus company enrichment (industry, segment, size hint) and detected technology signals ordered by confidence. The response also l…
- [Update business profile](https://docs.hq.zone/api-reference/admin/update-profile.md): Updates the workspace's business profile and returns the refreshed profile in the same shape as the GET endpoint. Admin only. Each field may be set, cleared (to re-expose the auto-discovered value), or left untouched; manual overrides persist across future automatic refreshes. Changing the domain to…
- [Upload business logo](https://docs.hq.zone/api-reference/admin/upload-logo.md): Uploads a business logo supplied inline as base64 and returns the refreshed business profile. Admin only. Accepts PNG, JPEG, SVG, WebP and GIF up to 4 MiB; the stored logo becomes a manual override of the auto-discovered logo and is served from a stable HQ-hosted URL.
- [Refresh business profile](https://docs.hq.zone/api-reference/admin/refresh-profile.md): Queues an immediate re-crawl of the workspace's business profile and returns 202 with a queued status. Admin only. The refresh is skipped silently if the workspace has not yet confirmed its domain.
- [List email endpoints](https://docs.hq.zone/api-reference/admin/list-endpoints.md): Lists the workspace's inbound email endpoints (custom inboxes plus the HQ-managed workspace mailbox), each with its configuration and per-endpoint counters: total messages, items needing attention, inbound received, outbound replies, awaiting-review, unrouted and escalated counts, and a reply-langua…
- [Create email endpoint](https://docs.hq.zone/api-reference/admin/create-endpoint.md): Creates a new inbound email endpoint (custom inbox) and returns it with its counters. Admin only. The localpart must be valid and not reserved or equal to the workspace mailbox; 'agent' (plane=agent) endpoints require a handler agent belonging to the workspace, while 'light' quick-reply endpoints mu…
- [Get email endpoint](https://docs.hq.zone/api-reference/admin/get-endpoint.md): Returns a single inbound email endpoint by id, with its full configuration and per-endpoint counters (message totals, attention items, disposition counts and reply-language distribution). Admin only and scoped to the caller's workspace; an unknown or cross-workspace id returns 404.
- [Update email endpoint](https://docs.hq.zone/api-reference/admin/update-endpoint.md): Updates the configurable behavior of an inbound email endpoint and returns the refreshed endpoint with counters. Admin only and scoped to the caller's workspace. Omitted fields keep their current values, supplying allow_patterns replaces the allowlist wholesale, and the localpart and kind cannot be…
- [Delete email endpoint](https://docs.hq.zone/api-reference/admin/delete-endpoint.md): Deletes an inbound email endpoint by id. Admin only and scoped to the caller's workspace. The HQ-managed workspace mailbox cannot be deleted (400), and an unknown or cross-workspace id returns 404.
- [List emails awaiting review](https://docs.hq.zone/api-reference/admin/list-review.md): Returns the three actionable email triage queues - awaiting-review, unrouted and quarantined - each capped at 200 items, plus a count of each. The awaiting-review queue is scoped to the caller (or all workspace mail for admins), while the unrouted and quarantined queues are admin-only and come back…
- [List email activity](https://docs.hq.zone/api-reference/admin/list-activity.md): Returns a paginated feed of inbound and outbound email messages decorated with their endpoint, plane and a deep-link to the conversation thread, along with the total count for pagination. Admins see all workspace mail while a regular member sees only mail bound to them. Supports optional filtering b…
- [Get email badge count](https://docs.hq.zone/api-reference/admin/get-badge.md): Returns the navigation badge count of email items needing a human, broken down into awaiting-review, unrouted and quarantined plus their sum. Scoped to the caller: a non-admin sees only their own awaiting-review items, while the unrouted and quarantined counts are admin-only and report zero for non-…
- [Get email message content](https://docs.hq.zone/api-reference/admin/get-message.md): `GET /v1/api/email/messages/{id}/content` - the full inbound email for the detail view. Headers + decoded bodies are fetched on demand from Sentio (the raw EML is never stored); attachment metadata comes from the mirror, with a Trove `artifact_id` for download when the attachment was materialized.
- [Send an email reply](https://docs.hq.zone/api-reference/admin/send-reply.md): Approve (and optionally edit) the drafted reply on an `awaiting_review` item: send it through the same `email.reply` MCP path the agent uses, then settle the item to `handled`. The body comes from the request (the UI pre-fills it with the draft from the rendered transcript and lets a human edit befo…
- [Discard a reply draft](https://docs.hq.zone/api-reference/admin/discard-draft.md): Discard an `awaiting_review` draft without sending: settle to `handled`.
- [Assign an unrouted email](https://docs.hq.zone/api-reference/admin/assign-email.md): Assign a handler to an `unrouted` item and re-drive it. Admin-only. Sets the message's agent (and, when the mail hit a handler-less mailbox endpoint, the endpoint's agent too, so future mail routes), then re-emits the routed event via the outbox so the worker drives a turn. The re-drive forces the a…
- [Download an email attachment](https://docs.hq.zone/api-reference/admin/download-attachment.md): `GET /v1/api/email/messages/{id}/attachments/{attachment_id}/download` - the raw bytes of one attachment, for the admin viewer's inline preview + download (the read-half reuses the shared FilePreview renderer). Fetch-on-view from Sentio (never stored). The message is tenant-scoped here, and Sentio s…
- [Get quarantined email content](https://docs.hq.zone/api-reference/admin/get-quarantine.md): `GET /v1/api/email/quarantine/{id}/content` - view a quarantined message before accept/reject. Same fetch-on-view of the raw EML; attachments aren't materialized until accept, so the list is empty here.
- [Accept a quarantined email](https://docs.hq.zone/api-reference/admin/accept-quarantine.md): Accepts a pending quarantined inbound email, marking it accepted, and returns an ok flag with an optional explanatory note. Admin only. Optionally binds the sender to a named workspace user (required to clear an unknown-sender quarantine) so their future mail routes; when the destination is now reac…
- [Reject a quarantined email](https://docs.hq.zone/api-reference/admin/reject-quarantine.md): Reject a quarantined mail: mark it `admin_reject` (terminal). Admin-only.
- [Update workspace mailbox](https://docs.hq.zone/api-reference/admin/update-mailbox.md): Changes the localpart of the workspace outbound mailbox, the address all agents send from, renaming both the workspace setting and its system endpoint together. Admin only. The localpart must be lowercase alphanumerics with '.' or '-' separators (max 63 chars) and is rejected if it is reserved or al…
- [List audit log](https://docs.hq.zone/api-reference/admin/list-audit.md): Returns a paginated, recency-first list of audit-log events for the caller's own workspace, newest first. Admin only. Supports optional filtering by event kind, outcome, actor kind, agent id, and conversation id, a free-text query matched against the event target and intent, a lookback window in day…
- [Verify audit chain](https://docs.hq.zone/api-reference/admin/verify-audit.md): Re-walks the workspace's tamper-evident audit hash chain and reports whether it is intact. Admin only. Checks the most recent entries (the limit query parameter defaults to 10000 and is clamped to 1-100000), recomputing each entry's hash and verifying it links to its predecessor. Returns whether the…
- [Assign a review-reply item to a user](https://docs.hq.zone/api-reference/admin/assign-email-owner.md): Admin-only. Attributes a `review_reply` item (a reply to the team / default sender) to a workspace user, moving it into that user's review queue. Does NOT drive a turn or re-inject the reply into agent context - it only sets the reviewer. Use it to triage the Unassigned bucket.
- [Reopen a reviewed email reply](https://docs.hq.zone/api-reference/admin/reopen-email-reply.md): Flips a reviewed (`handled`) review-reply item back to the review queue - recovers a mis-clicked Done. Owner-or-admin, and only an item that was a review reply (`review_owner_id` set) and is currently `handled`.
- [Mark a review-reply item reviewed](https://docs.hq.zone/api-reference/admin/review-reply-done.md): Clears a `review_reply` item from the review queue (sets it `handled`). The owner of the item (or an admin) may clear it, once a human has dealt with the reply. Does not touch agent context.
- [List the caller's assigned email replies](https://docs.hq.zone/api-reference/admin/list-my-email-replies.md): The member "Email replies" surface: replies attributed to the caller (review_owner_id), filtered by `reviewed` - false (default) = to-review, true = already reviewed. Owner-scoped to the caller's own items.
- [List runs](https://docs.hq.zone/api-reference/runs/list-runs.md): Lists schedule runs (one row per executed fire) newest-first, with a total for pagination. scope=mine (default) returns only runs of the caller's own schedules; scope=workspace returns all runs in the workspace and is admin only (403 otherwise). status filters to all (default), active (created/runni…
- [Cancel a run](https://docs.hq.zone/api-reference/runs/cancel-run.md): Cancels a run still in flight (created/running/suspended) - sets it to cancelled, stamps finished_at, and drops its pending timers/awakeables. A no-op (ok=false) if the run already finished. The caller must own the run's schedule or be an admin (404 if the run isn't visible). Requires the schedules:…
- [Search conversations](https://docs.hq.zone/api-reference/search/search-conversations.md): Full-transcript hybrid search (lexical BM25 + dense vector, reciprocal-rank fused, then cross-encoder reranked) over the caller's conversations within their workspace. Returns message-level hits - each carries the conversation, the matched message's sequence number (a jump-to-message deep link), a h…

## OpenAPI Specs

- [openapi](https://api.hq.zone/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.