Developer overview

The d5s developer surface is a beta HTTP API for operating workspace resources and following agent execution. The same core resources used by the app are available in the OpenAPI contract: projects, sessions, agents, automations, dashboards, files, connectors, skills, sharing, usage, and audit operations.

Beta boundary

The contract is currently beta. Use the generated OpenAPI description as the source of exact paths and schemas. Endpoint names, payloads, and authentication restrictions may change before a stable version is declared.

Workspace search

GET /api/v1/search searches the active workspace across sessions, agents, projects, automations, and dashboards. Agent matches use the agent name, persona, and description; only active agents are returned. An agent is represented once as an agent result rather than duplicated as its continuing session, and its id opens the agent resource directly. Matching, limits, and the complete response schema remain defined by the generated OpenAPI contract.

Marketing form boundary

The public OpenAPI contract also contains POST /api/public/contact so the d5s marketing site can submit an email address and message without opening a local mail client. This route is unauthenticated, honeypot-protected, and rate-limited. It sends accepted enquiries through the configured email service without storing their content in the application database.

This marketing-only route is not a general integration endpoint. Visitors should use the contact form; application integrations should use the authenticated workspace APIs described below.

Workspace owners and admins create API keys in Settings → API keys. The secret is shown only when created. Store it in a secret manager; revocation takes effect immediately. API keys currently use wildcard workspace scope and act through the access of the user who created them. Some sensitive user-owned configuration writes—including agent autonomy and connector grants—require an interactive user token and cannot be performed with an API key.

Interactive sign-in starts at GET /api/v1/login/authorize and always uses the hosted AuthKit flow. AuthKit presents the enabled sign-in methods and owns provider-specific verification, multi-factor, and organization-selection challenges. Browser clients can preserve navigation in state; native mobile and Desktop clients use the PKCE parameters described by OpenAPI. After a Desktop callback, the backend serves a non-cacheable browser completion page that opens the app with the opaque PKCE-bound exchange code; reloading its clean completion URL does not replay the provider callback. Clients cannot select an identity provider through the d5s authorization endpoint.

On a regional deployment, login establishes a local user session but does not silently create an organization. GET /api/v1/users/me/regions returns the current cell plus the active and signup-eligible region labels. It does not return user activity, organization names, memberships, or a claim about where the user has data. POST /api/v1/users/me/claim-region creates the personal organization only in the current signup-eligible cell.

The workspace update operation changes the display name without changing the workspace slug. It requires workspace Owner or Admin access through an interactive user token; workspace API keys cannot call it. Use the OpenAPI description for the current path, request schema, and generated client method.

Workspace deletion is also interactive-user-only and intentionally split into readiness, verification-code, schedule, and cancellation operations. An explicit workspace Owner or Admin can read readiness and cancel a schedule; only the current workspace Owner can request the email code and schedule deletion. Personal workspaces are protected, every readiness count must be zero, and scheduling starts a 48-hour cooling-off period rather than deleting immediately. Use the OpenAPI description for the exact workspace-deletion paths and schemas.

Native account and notification operations

Native clients revoke their refresh token through the logout operation using the current access token and the refresh token in the request body. Use the generated OpenAPI contract for the exact request. The refresh token must belong to the signed-in user; repeating a valid logout is safe. A temporary failure is not confirmation that revocation succeeded. Browser cookie logout continues to work without that body.

Notification device registration and preference operations require the signed-in user's token, not a workspace API key. Registering a device does not subscribe it to every agent: agent preferences are explicit and require current access. Disable the device before discarding the credentials used to sign out.

The separate retirement operation accepts an opaque, device-bound proof when native authentication has expired. Treat it as a secret with one purpose: retiring that device's notifications. It cannot read preferences, register a device, subscribe to an agent, or authorize workspace work. Use OpenAPI for the current operations and generated request and response types. Failed notification retirement can be retried separately from interactive sign-in and local session invalidation. A stale retirement proof is not an authentication credential. If notification session verification is temporarily unavailable during refresh, interactive access can recover while notifications are disabled; enable notifications again after verification is available. Confirmed token revocation still rejects refresh.

Organization control plane

The signed-in user has a self-scoped privacy read and update operation whose request contains only require_no_training. It cannot name another user. Organization Owners and Admins use the organization privacy update to set the same requirement for all members. Both operations return the stored preference, record changes in the audit log, reject unknown fields, and default to normal routing. Use the OpenAPI description for the exact paths, authentication requirements, and generated client methods.

The organization update operation changes the display name without changing the organization slug. It accepts a typed name of 1 to 255 characters, trims surrounding whitespace, and rejects unknown fields. Active organization Owners and Admins can call it with an interactive user token; ordinary members, non-members, and workspace API keys cannot. A successful change records an organization audit event. Use the OpenAPI description for the exact path, request schema, response, and generated client method.

Organization Owners and Admins can use the organization endpoints to list the workspace portfolio, create a workspace, transfer workspace ownership, and create, change, or revoke explicit user and group workspace grants. Organization Owners and Admins, plus Owners and Admins of the target workspace, can send a workspace invitation that grants the selected Member or Admin role in that exact workspace. Personal workspaces reject invitations. Organization membership alone does not grant workspace content access. These control-plane endpoints require an interactive user token; workspace API keys cannot call them. Use the OpenAPI description for the exact /api/v1/organizations/{organization_id}/workspaces paths and schemas.

Each workspace portfolio row includes aggregate member and agent counts. If the caller is also a member of that workspace, member_previews returns up to three people with canonical avatar state and agent_previews returns up to three agent ids and names. Both arrays are empty when the organization manager has no workspace membership, so organization-level administration does not expose that workspace's roster. Compare each array length with its aggregate count to represent additional identities.

Workspace model policy

The workspace model-policy response includes enabled models, the default model, and reasoning defaults. Model availability is derived from the organization's current plan and policy. Submit model and reasoning choices through the published update operation; provider selection is not a client control. Use OpenAPI for the exact response fields and update schema.

For a new Free workspace, default_model_id and the only entry in enabled_model_ids are gpt-5.6-luna. New paid workspaces start with gpt-5.6-luna, gpt-5.6-terra, gemini-3.7-flash, grok-4.5, and deepseek-v4-pro, in that order. Paid EU cloud workspaces with Bedrock access also enable the production Claude models served through Amazon Bedrock in the EU. Reads project a saved policy through the current plan. A downgrade therefore returns only Luna, while a later upgrade restores the saved paid-plan policy without rewriting it.

If a selected model cannot run under the current plan and policy, admission is refused. Integrations must not implicitly select a different model or geography to bypass a refusal.

The organization member update operation also accepts a nullable whole-cent spend limit. A non-negative value sets the limit and null clears it. Organization Owners can update any member's limit. Organization Admins can update ordinary members, but cannot update themselves or another manager.

Personal workspace setup

Regional sign-in and personal workspace creation are separate operations. A signed-in user can claim an available region to create or reuse their personal workspace. An optional workspace name applies only when creating it; a retry preserves the existing name and returns the personal workspace destination. Onboarding preferences also store optional discovery attribution alongside completion state. Use the generated OpenAPI schemas for the request constraints, supported choices, and response fields.

Billing and entitlements

The organization billing summary and entitlement responses expose current seat quantities, prices, and feature keys. The summary also reports whether the consumer withdrawal action is available. The withdrawal read returns the server-owned eligibility or submitted acknowledgement. The preview operation renders the exact statement for confirmation, the submit operation accepts that statement with the consumer name, acknowledgement email, and a client idempotency key, and the acknowledgement retry operation never resubmits the withdrawal. These organization-scoped endpoints require an active organization membership, with billing administration restricted to Owners and Admins. Use the generated OpenAPI description for exact fields and Plans and credits for the commercial model.

A credit top-up checkout returns a redirect URL and Checkout Session id. An organization-scoped read reports whether that purchase has completed and the credited amount. Use the generated OpenAPI description for the exact response and polling contract.

An interrupted Pro-to-Max upgrade request is safe to retry with the same organization. If Stripe already applied that upgrade, the retry completes the local plan and included-credit update and returns the original granted amount without charging or granting credits again.

Team creation uses destination-local draft, create, and activation operations. Choose the organization region before the first call; when it differs from the current cell, continue at that cell's /create-team entry point. Only then does a draft read return the caller's one reusable empty team, if they have one. A create call takes the team name, the standard and premium seat counts, and a client-supplied idempotency key, and returns the organization plus a Stripe Checkout URL. For seats-on-joining setup, first read the onboarding offer and send explicit acceptance of the displayed price and promotional terms with the owner-seat request. Use the generated OpenAPI schemas for current request and offer fields. The backend refuses this call when its cell is not signup-eligible, before any organization, billing, or Stripe write. An activation call, made after checkout returns, reports the subscription state and provisions the team's first workspace exactly once. The idempotency key is scoped to the caller: replaying it returns the same organization and reuses a known live checkout session. A different seat mix is refused. Expired promotional terms require a new review, and an unresolved checkout attempt can require reconciliation before another session is issued. Two requests that overlap under one key converge on that same response rather than one of them failing. Each owner keeps at most one draft team per cell, so an abandoned checkout is resumed rather than duplicated. These calls require an interactive user token.

The activation response returns the first workspace's slug only to a caller who can open that workspace. The workspace belongs to the organization owner who bought the team, and organization membership never grants workspace content access, so another manager polling activation gets the active state with no slug. Until a team's subscription is active, creating another workspace in it through the organization workspace endpoint is refused with a conflict. An existing workspace can remain while the team is inactive.

If a team uses seats on joining, request an invitation seat quote before authorizing additional capacity. Only an organization Owner or Admin can authorize the joining charge and individual seat's monthly price. Sending records consent without charging; acceptance applies any needed seat before granting membership and the selected workspace access. Quotes and free reservations have separate deadlines, and an expired free authorization never becomes paid without new consent. Existing team members require no extra seat. Retry an interrupted acceptance as directed; an unresolved billing result can block competing billing changes until reconciliation. Use OpenAPI for exact quote, invitation, and error contracts and Plans and credits for user-facing terms.

Integration model

MCP authorization servers can identify the regional d5s OAuth client through the public GET /api/v1/oauth/mcp/client-metadata.json document. It contains the d5s client name, app URL, exact callback URI, and public-client grant metadata; it contains no workspace data, token, or client secret. Application integrations do not call this endpoint during ordinary workspace API use.

Workspace API requests use the v1 base path, a Bearer token, and the active workspace id:

curl "$D5S_API_URL/api/v1/projects" \
  -H "Authorization: Bearer $D5S_API_KEY" \
  -H "X-Workspace-Id: $D5S_WORKSPACE_ID"

Existing workspace connector credentials become available to a new project by default, and a new credential becomes available to existing projects. The project activation resource is the runtime grant for one exact credential: delete it to turn the connector off for that project, and create it to turn the connector back on. Creation is idempotent when the same active grant already exists; an archived record preserves an explicit project opt-out across credential reconnects. d5s leaves incompatible authentication schemes for the same external host inactive rather than exposing both to one project.

A basic chat integration follows this lifecycle:

1. Create a session with POST /api/v1/sessions. Omit project_id to let d5s create an unlisted project, or pass a project id to reuse its context.
2. Upload any session files and retain their ids.
3. Send work with POST /api/v1/sessions/{session_id}/messages. The response returns a durable turn_id, admission status, and optional queue position.
4. To compact eligible older context without a normal assistant run, call POST /api/v1/sessions/{session_id}/compact while the session is idle. A queued response includes the command turn id; nothing_to_compact means no model call was admitted.
5. Bootstrap a conversation with lightweight GET /api/v1/sessions/{session_id}/metadata and bounded GET /api/v1/sessions/{session_id}/events. The initial page contains the newest turns; events within each page are chronological. Use the exclusive before_seq cursor for older pages. turn_limit defaults to 12 and accepts up to 200.
6. On the first history request, set include_overview=true when the client needs a lightweight navigation index across every authorized turn. Later pages should omit it.
7. Open one GET /api/v1/sessions/{session_id}/stream connection for the live tail, with Last-Event-ID set to the REST page's latest_seq. Persist the latest sequence and use it when reconnecting.
8. Stop active work or cancel a queued turn through the session lifecycle endpoints.
9. Read messages, aggregates, files, artifacts, and terminal state from the owning session or resource.

The message payload accepts content, up to 20 uploaded file ids, optional model and reasoning overrides, disabled tools, and deep-research mode. A successful admission does not mean the model has completed; wait for a terminal event.

Managed-email recipient operations under /api/v1/email/{contact_id} require an interactive user token with recorded email verification matching the account’s current address. They do not require workspace membership or X-Workspace-Id. Contact IDs are locators, never access credentials: each email and attachment is checked against successful sends to that verified address. Workspace access requests grant no membership; existing invitations must still be explicitly accepted through the normal seat-aware flow.

Conversational agent setup

Agent-creation drafts keep a signed-in creator’s setup conversation separate from runnable agent sessions. Where draft identity preparation is available, repeating that operation reuses the same inactive agent. Finishing setup activates that identity with the reviewed configuration. A prepared identity is not permission to submit work: draft agents cannot obtain a working session or run tasks, and ordinary agent listings exclude them. Setup history remains creator-only after activation.

While a setup reply is processing, a signed-in client can follow the draft’s generated streaming operation instead of repeatedly reading it. Each data event is the creator-owned public draft snapshot, and reconnecting reloads current state. The private execution session behind setup is not a client resource and is not included in these snapshots. Use the generated OpenAPI description for current draft operations, revision checks, authentication restrictions, and response schemas.

Recover an interrupted agent send

For a persistent agent session using batch-replan admission, a signed-in user client can assign the optional client request ID described in the generated message schema before sending. Keep that ID with the exact submitted payload until the response is confirmed. If the connection drops, resend both to the same workspace and session with the same signed-in user. A previously accepted request returns its original accepted receipt and turn ID without admitting a second message. Current access is checked again on every replay.

Preserve the submitted fields exactly, including whether optional fields were omitted. Reusing the ID with a different payload is a conflict; do not silently allocate another ID to conceal it. A genuinely new message needs a new ID. Sessions using FIFO admission reject keyed sends, so this recovery contract does not apply to every chat or execution mode. Omitting the ID retains the existing send behavior.

An accepted receipt confirms that d5s accepted the message. It does not confirm execution or completion. Follow the returned turn through session history and streaming, even if a retry returns the same receipt after the run has already finished. See Sessions and runs.

Replace a native message

The session message-edit operation is available when Message editing is enabled for the signed-in user. Use the generated API reference for its request and response fields. The original admission settings must be available so editing preserves tool restrictions. Only the original author can replace an eligible native message; the operation cannot remove a tail containing other authors, external-channel messages, or system instructions.

An edit is rejected before stopping work if the conversation has pending queued inputs. Cancel those inputs explicitly before retrying the edit.

Keep the same request identity and payload while retrying a stopping response or recovering a lost response. A successful replay returns the original acceptance receipt without submitting another correction. Saving replaces the selected message and its subsequent conversation; it preserves completed actions and usage. Refresh any cached transcript and overview when the session stream signals a conversation rewind.

Scheduled and persistent work

Automations expose create, update, Run now, and run-history operations, plus optional people assignments, result handovers, delivery confirmations, and review records. Each automation run creates a new session. Agents expose a continuing session, manual and scheduled wakeups, capabilities, and channels. Their meeting-history operation returns active calls separately from paginated completed calls, and their meeting-preferences operation sets the instruction used for future transcript follow-up turns. Meeting detail and history schemas include structured admission evidence when known, so clients can distinguish lobby expiry or a host refusal from a less-specific join failure; use the generated schema for the exact fields and values. An API-key integration can reset an idle agent's conversation when it needs a clean reusable fixture; this clears transcript events, child runs, and compacted context in place after usage is ledgered while preserving the eternal session, agent, project state, files, sandbox, model preference, mailbox, and Slack, Telegram, or Discord setup. Reset is rejected while work is active. Telegram lifecycle endpoints manage a bot connection with the required workspace and agent permissions; browser linking requires explicit confirmation. Signed-in workspace members with permission to view the agent can read its Telegram connection summary, including public bot names and status. Agent-email endpoints manage provider-specific mailboxes, a default mailbox for new email, incoming and outgoing address rules, blocked senders, the optional incoming reply exception, contacts, and retained activity. Unknown-sender quarantine bypass authority is represented only by the policy's trusted-sender rules. The deprecated contact-response trust field remains temporarily for compatibility, is always false, and grants no authority. Existing policies remain in effect until explicitly changed. Channel-management writes require an interactive user token. Use the generated OpenAPI contract for supported operations, authentication, and schemas.

Automation handovers can be filtered to specific run IDs. Match results by run ID when combining them with run history; the lists can have different ordering. Returned handovers still depend on the caller's current access to each run. Use the generated OpenAPI contract for the filter and pagination parameters.

Automation proposals have a shared confirmation outcome. Confirmation uses the retained proposal in its source conversation and the signed-in person's permissions. Concurrent confirmations and retries return the same decision. Deleting the created automation does not make the original proposal reusable. Use the generated OpenAPI contract for the confirmation and outcome operations.

Dashboards expose refresh runs, version history, and restore.

Dedicated Teams identity management, where available, requires an interactive organization administrator with workspace administration access. Creation, installation readiness, and channel activation are distinct states; do not infer a verified destination from app creation alone. Use the generated OpenAPI contract for lifecycle operations and schemas, and Teams agent setup for the supported standard-channel workflow.

Usage analytics

Organization usage endpoints provide summary, daily model timeseries, daily successful-skill timeseries, per-member totals and daily buckets, per-agent totals and daily buckets, per-workspace totals and daily buckets, and paginated activity. Member analytics attribute work to a durable user ID, enrich active organization members with their current profile and avatar, and exclude usage without member attribution. Former, suspended, or missing users retain a separate ID bucket without live profile metadata.

Per-agent analytics attribute an agent's eternal session and nested sub-agent runs to a durable agent ID, then show the agent's current live name. Deleting the agent keeps its historical bucket without a current name. Per-workspace analytics use a durable workspace ID. The /api/v1/organizations/{organization_id}/usage/by-workspace response resolves current names and slugs only from that organization; unavailable workspace references keep separate historical buckets without live metadata. Member, agent, and workspace totals cover the complete requested window, while their daily buckets are bounded to its most recent 366 days. These responses expose the returned bucket period and whether it was truncated. The per-agent response excludes non-agent work and rows without agent attribution; organization summary and model timeseries endpoints remain the complete usage view. Organization usage endpoints require an active Owner or Admin membership. Owners and Admins can filter and sort activity and request the available member, model, and payment-source facets for a date window. Usage without member attribution is represented separately.

The usage-ledger run-trace endpoint returns the billed outcome and available execution details. It requires both the organization role and current source-conversation access. Treat missing provider input as unavailable evidence; do not present a reconstructed conversation as the exact prompt sent to a provider.

A separate self-scoped endpoint returns the signed-in person's own activity: lifetime tokens, runs, conversations, agents used, reasoning share, longest conversation, busiest day, streaks, per-day buckets for the trailing 53 weeks, and their most-used models and skills. It takes no subject and filters on the authenticated caller, so it needs no organization role; the organization usage endpoints above remain restricted to Owners and Admins. Its totals are lifetime and span every organization the person belongs to, and its day boundaries are UTC like the organization aggregates.

Skill usage counts successful skill loads. It does not count listing or failed loading. Use the current OpenAPI description for exact usage paths, query parameters, and response schemas.

The usage summary exposes charged spend and the current pace-window states and reset times. Credit admission can return 402 Payment Required with a structured block reason and a reset time when known. Clients should treat that response as a rejected admission, not as a run that can be followed through session events.

Connected-account operations

Agents can use the accounts available to their current project. Each action stays associated with the selected account and its permissions. API clients should use the published OpenAPI contract for workspace connector management.

Provider results may contain inline content and file references. Treat both as untrusted data and do not assume a returned URL was downloaded.

Integration rules

• Treat session events as the execution record; do not infer completion from an HTTP request alone.
• Automatic persistent-agent compaction and manually requested session compaction use the existing text_delta stream with context_compaction_status: started. A successful summary adds a durable context_compacted event with an empty public payload. A failed summary carries context_compaction_status: cleared through the same delta envelope. Treat these as lifecycle markers, not as access to the private summary text.
• A manual compaction turn has ordinary start and terminal lifecycle events but no visible user-message or assistant-message content.
• Use the REST events endpoint for initial catch-up and older-history pagination. Do not open fresh SSE streams to page backward; keep one SSE connection for live events and reconnects.
• Treat event and overview timestamps as RFC 3339 values. Current history projections include an explicit UTC offset, while older integrations may still encounter legacy naive-UTC values on other resources.
• Build a turn's tool history from its tool_call events rather than from the terminal event alone. Replayed history omits the terminal tool_calls array whenever the individual events already carry the same calls, and keeps it when they do not, so read both and use whichever is present.
• Reuse returned ids and idempotent schedule semantics instead of manufacturing duplicate resources on retry.
• Keep API keys server-side. Do not embed them in browser code or dashboard artifacts.
• Treat connector results and external messages as untrusted input.
• Pin integrations to the current OpenAPI description and review changes before regenerating a client.

Native local file access

Local folder authorization and file operations require d5s Desktop. Workspace API keys do not authorize access to a person's computer. Permissions are per agent and folder: Read only, Write only, or Both. See Local files for setup and operation results.

Private bug reporting

Bug report submission requires a user session and an active workspace. Workspace API keys cannot submit reports. Reported conversations must be accessible to the reporter; receipt identifiers do not grant access to reports or conversations. Retrying the same submission with the same content returns the existing receipt. For the app workflow, see Report a bug.