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 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.

Organization control plane

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 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.

Integration model

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"

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. 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.
5. 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.
6. 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.
7. Stop active work or cancel a queued turn through the session lifecycle endpoints.
8. 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.

Scheduled and persistent work

Automations expose create, update, Run now, and run-history operations. Each fire creates a new session. Agents expose one lifetime session plus manual wake, heartbeat configuration, task-specific scheduled wakeups, capabilities, and channels, but autonomy and capability mutations are intentionally more tightly authenticated.

Dashboards expose refresh runs, version history, and restore. The application currently emphasizes manual dashboard refresh even though schedule fields exist in the beta schema.

Webhook-triggered delivery is not currently part of the public contract. To implement a conditional external trigger today, evaluate the condition in your service and call Run now on a manual automation only when agent work is needed.

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, and paginated ledger activity. Member analytics attribute work to the durable user ID recorded on the ledger, enrich active organization members with their current profile and avatar, and exclude unattributed internal work. 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 root-agent ID on the usage ledger, then show the agent's current live name. Once that ID is recorded, deleting the agent keeps a separate historical bucket with a null name. Member and agent totals cover the complete requested window, while their daily buckets are bounded to its most recent 366 days. Both responses expose the returned bucket period and whether it was truncated, so clients can distinguish the chart window from full-window totals. The per-agent response intentionally excludes non-agent work and legacy ledger rows without agent attribution; organization summary and model timeseries endpoints remain the complete usage view. Organization Owners and Admins can filter and sort the ledger server-side, and can request the complete member, model, and payment-source facet values for a date window. Unattributed member usage is represented separately from known member ids in the activity ledger.

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 recorded by the worker. It does not count listing, failed loading, or unsuccessful tool calls. Use the current OpenAPI description for the exact usage paths, query parameters, and response schemas.

Integration rules

• Treat session events as the execution record; do not infer completion from an HTTP request alone.
• 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.