Conversations

Start a conversation

post/v1/conversations

Request

  • Base URL: https://api.shardflux.dev
  • URL: https://api.shardflux.dev/v1/conversations
  • Auth: HTTP bearer

Request body

project_idstring uuid

UUIDv7, lowercase canonical form.

from_conversation_idstring
repo_remotestring

The repository. Omitted: the project’s most recent repository (a new conversation then starts from the project hub, no folder needed), or the parent’s for a fork, spawn or join.

harness'claude' | 'codex' required
route'terminal' | 'acp' | 'codex-app' | 'codex-cloud' | 'claude-desktop' | 't3-ssh' required
namestring
titlestring
homeboolean

Start on your machine’s home, without a repository: the agent runs in /home/user on a computer from your machine environment and starts threads in the project’s repositories (mode new, route terminal).

mode'new' | 'fork' | 'spawn' | 'join' required
join_mode'reviewer' | 'worker'
parent_idstring
briefstring
modelstring

The model the harness starts with: an alias or full model name (opus, gpt-6.1-sol). Absent: the agent’s own default.

effortstring

The reasoning effort the harness starts with (low, medium, high, xhigh, max; Codex also ultra). Absent: the agent’s own default.

title_prefixstring nullable

The marker the conversation’s Claude session title starts with in claude.ai and the Claude app (“☁ Fix login bug · todo-app”): up to 16 characters on one line, an empty string for none. Absent or null: the default “☁ ”. A fork, spawn or join without one keeps its parent’s.

harness_session_idstring

Move a session in from a computer: the new conversation resumes this native session (a Claude Code session id or Codex thread id, a lowercase UUID), whose transcript the client places in the VM before it seeds the repository. Only with mode new and route terminal.

Response

Default Response

restoreobject nullable required

Changes

No recorded changes to this operation across all 1 revision of this API.