Skip to the page
Conch
DocsGitHub

Reference

The app's API

The web app talks to Conch over HTTP and one WebSocket. A script with an access key can use the same doors.

This is the app's own API, at protocol version 7 today. It moves with the app, so treat it as a map and not a promise. Every body is checked against the schemas in packages/protocol, on both sides.

curl -H "Authorization: Bearer conch_…" http://localhost:4317/api/state

Make the key with conch key. Changes that grant trust also need a password or key from the last ten minutes.

Over HTTP

/api/access

  • GET/
  • DELETE/
  • PUT/approval
  • PATCH/devices/:id
  • DELETE/devices/:id
  • POST/devices/:id/sign-out
  • POST/fix
  • POST/keys
  • DELETE/keys/:id
  • POST/pairing
  • POST/passkeys
  • PATCH/passkeys/:id
  • DELETE/passkeys/:id
  • POST/passkeys/options
  • PUT/password
  • DELETE/requests/:code
  • POST/requests/:code/approve
  • DELETE/sessions
  • DELETE/sessions/:id
  • POST/verify

/api/activity

  • GET/

/api/artifacts

  • GET/
  • GET/:id
  • PATCH/:id
  • DELETE/:id
  • PUT/:id/draft
  • POST/:id/live-data
  • DELETE/:id/live-data/:host
  • POST/:id/refresh
  • POST/:id/versions
  • GET/:id/versions/:n
  • GET/:id/versions/:n/download
  • GET/:id/versions/:n/frame
  • GET/:id/versions/:n/live-data
  • POST/:id/versions/:n/live-data

/api/attachments

  • GET/:id
  • DELETE/:id

/api/auth

  • GET/
  • POST/hello
  • POST/hello/finish
  • POST/passkey
  • POST/sign-in
  • POST/sign-out

/api/background

  • GET/
  • PUT/
  • PUT/after-logout
  • PUT/keep-awake
  • POST/shortcut
  • PUT/tray

/api/backups

  • GET/
  • POST/
  • GET/:id
  • DELETE/:id
  • GET/:id/download
  • GET/:id/preview
  • POST/:id/restore
  • DELETE/pending
  • PATCH/settings

/api/browser

  • GET/
  • POST/:id/control
  • PUT/backend
  • DELETE/backend/:kind
  • GET/live
  • POST/repair
  • PATCH/settings
  • GET/shots/:id/:shot
  • DELETE/sites/:site
  • POST/wipe

/api/capabilities

  • GET/

/api/channels

  • GET/
  • POST/
  • GET/:id
  • PATCH/:id
  • DELETE/:id
  • PUT/:id/groups/:groupId
  • DELETE/:id/groups/:groupId
  • GET/:id/hook
  • POST/:id/pair
  • DELETE/:id/people/:personId
  • POST/:id/repair
  • POST/:id/requests/:personId
  • GET/:id/teams-app
  • POST/:id/test
  • PUT/:id/token
  • POST/check
  • GET/door
  • PUT/door
  • DELETE/door
  • POST/door/address
  • POST/door/check
  • POST/door/tailscale
  • GET/email/gmail
  • POST/email/gmail
  • GET/imessage
  • POST/imessage/open
  • POST/link
  • GET/link/:id
  • DELETE/link/:id

/api/commands

  • GET/
  • PUT/:name
  • DELETE/:name

/api/conch-apps

  • GET/
  • GET/:id
  • PATCH/:id
  • DELETE/:id
  • POST/:id/call
  • GET/:id/export
  • GET/:id/icon
  • GET/:id/pages/:page/frame
  • GET/:id/publish
  • POST/:id/publish
  • POST/:id/rollback
  • PATCH/:id/settings
  • GET/:id/update
  • POST/:id/update
  • GET/:id/update/icon
  • GET/community
  • POST/drafts/:draftId/call
  • GET/drafts/:draftId/icon
  • GET/drafts/:draftId/pages/:page/frame
  • POST/install
  • POST/offers/:offerId/accept
  • POST/offers/:offerId/decline
  • GET/packages/:packageId/:appId/icon
  • POST/pick
  • POST/preview

/api/conversations

  • GET/
  • GET/:id
  • PATCH/:id
  • DELETE/:id
  • POST/:id/capped
  • POST/:id/compact
  • POST/:id/offers/:offerId/accept
  • POST/:id/offers/:offerId/dismiss
  • POST/:id/questions/:questionId/answer
  • POST/:id/release
  • POST/:id/skills/:skillId/stop-holding
  • PUT/:id/spend-limit
  • POST/:id/suggestions/:catalogId/dismiss
  • POST/bulk

/api/doctor

  • GET/
  • POST/check
  • POST/repair

/api/engine

  • GET/
  • PUT/api-key
  • DELETE/api-key
  • POST/login
  • POST/login/cancel
  • POST/login/code

/api/first-job

  • GET/
  • POST/

/api/folders

  • GET/
  • POST/
  • PATCH/:id
  • DELETE/:id

/api/gateway

  • POST/quit
  • POST/restart

/api/google

  • GET/
  • DELETE/accounts/:id
  • POST/accounts/:id/check
  • POST/apps/:app/use
  • POST/configure
  • POST/connect
  • GET/flows/:id
  • DELETE/flows/:id
  • POST/flows/:id/complete
  • POST/import
  • POST/mail/password
  • GET/mail/reusable
  • POST/mail/reuse

/api/healed

  • GET/

/api/health

  • GET/

/api/here

  • POST/
  • POST/link

/api/import

  • GET/
  • POST/
  • GET/:source
  • POST/:source/slack
  • GET/slack
  • POST/undo

/api/integrations

  • GET/
  • POST/
  • GET/:id
  • PATCH/:id
  • DELETE/:id
  • POST/:id/cancel
  • POST/:id/check
  • POST/:id/connect
  • POST/adopt
  • GET/catalog/:catalogId/needs
  • POST/catalog/:catalogId/needs/:needId/install
  • POST/catalog/:catalogId/needs/:needId/open
  • GET/external

/api/learning

  • GET/
  • POST/answer
  • PUT/chats/:id
  • POST/never/remove
  • POST/past/forget
  • POST/recap/seen
  • PUT/spending

/api/live-data

  • GET/

/api/local

  • GET/
  • PUT/model
  • POST/pull
  • POST/pull/cancel
  • POST/pull/pause
  • POST/start

/api/mcp

  • GET/
  • POST/clients
  • PATCH/clients/:id
  • DELETE/clients/:id
  • PUT/remote

/api/memories

  • GET/
  • POST/
  • PATCH/:id
  • DELETE/:id
  • POST/:id/keep
  • GET/export
  • POST/restore
  • GET/search

/api/memory

  • GET/index
  • POST/index/model
  • POST/index/rebuild
  • GET/tidy
  • POST/tidy
  • POST/tidy/answer

/api/models

  • GET/

/api/needs

  • GET/:needId
  • POST/:needId/:action

/api/phone

  • GET/address
  • POST/address

/api/pick

  • POST/

/api/profile

  • GET/avatar
  • PUT/avatar
  • DELETE/avatar
  • POST/understand

/api/providers

  • GET/
  • POST/:id/check
  • PUT/:id/key
  • DELETE/:id/key
  • POST/:id/login
  • POST/:id/signin
  • POST/:id/use
  • POST/found/:id/use
  • POST/servers
  • PATCH/servers/:id
  • DELETE/servers/:id
  • POST/servers/probe

/api/push

  • GET/
  • POST/answer
  • POST/subscriptions
  • PATCH/subscriptions/:id
  • DELETE/subscriptions/:id
  • POST/subscriptions/renew
  • POST/test

/api/routines

  • GET/
  • POST/
  • GET/:id
  • PATCH/:id
  • DELETE/:id
  • POST/:id/run
  • POST/:id/secret
  • GET/people
  • POST/preview
  • GET/spending
  • PUT/spending
  • POST/spending/keep-paused
  • POST/when/preview

/api/safety

  • GET/

/api/search

  • GET/
  • GET/preview
  • POST/repair

/api/settings

  • PATCH/

/api/skills

  • GET/
  • POST/
  • GET/:id
  • PATCH/:id
  • DELETE/:id
  • POST/:id/copy
  • POST/:id/describe
  • POST/:id/market/update
  • POST/:id/market/update/preview
  • POST/:id/trust-publisher
  • POST/draft
  • GET/market
  • POST/market/install
  • GET/market/listing
  • POST/market/preview
  • GET/market/updates
  • GET/publishers
  • DELETE/publishers/:fingerprint
  • GET/suggestions
  • POST/suggestions/dismiss
  • GET/suggestions/shelf
  • POST/suggestions/shelf
  • GET/suggestions/work
  • POST/write

/api/slack

  • POST/connect
  • GET/setup

/api/state

  • GET/

/api/tasks

  • GET/
  • POST/
  • DELETE/:id
  • POST/:id/continue
  • POST/:id/retry
  • POST/:id/stop

/api/terminal

  • GET/
  • POST/
  • DELETE/:id
  • POST/:id/ticket
  • GET/live
  • PATCH/settings

/api/tray

  • POST/quit
  • GET/status

/api/undo

  • POST/
  • GET/latest
  • POST/preview

/api/updates

  • GET/
  • POST/check
  • POST/conch
  • POST/conch/back
  • POST/look
  • POST/programs
  • POST/programs/:needId
  • PATCH/settings

/api/usage

  • GET/
  • PUT/budget

/api/vault

  • GET/
  • POST/breaches
  • POST/export
  • POST/import
  • POST/items
  • GET/items/:id
  • PUT/items/:id
  • PATCH/items/:id
  • GET/items/:id/history
  • DELETE/items/:id/passkeys/:passkeyId
  • POST/items/:id/reveal
  • POST/items/:id/totp
  • POST/lock
  • PATCH/lock
  • POST/purge
  • POST/requests/:id
  • POST/requests/:id/decline
  • POST/restore
  • PATCH/sources/:id
  • POST/sources/:id/copy
  • POST/sources/:id/lock
  • POST/sources/:id/sync
  • PATCH/sources/:id/sync
  • POST/sources/:id/transfer
  • POST/sources/:id/unlock
  • GET/sources/keepassxc/databases
  • GET/transfers/:jobId
  • POST/transfers/:jobId/cancel
  • POST/trash
  • POST/unlock

/api/voice

  • GET/
  • POST/model
  • POST/model/pause
  • POST/speak
  • GET/speech
  • POST/speech/:voice
  • DELETE/speech/:voice
  • POST/speech/:voice/pause
  • POST/transcribe
  • POST/wake
  • POST/wake/state

The live socket

One WebSocket at /ws carries everything that happens while you watch.

What the app sends

conversation.send
  • conversationId?string
  • clientMessageIdstring
  • textstring
  • attachments?string[]
  • options?object
conversation.configure
  • conversationIdstring
  • optionsobject
conversation.subscribe
  • conversationIdstring
  • afterSeq?number
conversation.unsubscribe
  • conversationIdstring
conversation.interrupt
  • conversationIdstring
permission.respond
  • conversationIdstring
  • permissionIdstring
  • decision'allow' | 'allow-always' | 'deny'
ping
Nothing else.
presence
  • visibleboolean

What Conch sends

hello
  • protocolVersionnumber
  • serverVersionstring
conversation.created
  • clientMessageIdstring
  • conversationobject
conversation.updated
  • conversationobject
conversation.deleted
  • conversationIdstring
folders.changed
  • foldersobject[]
conversation.event
  • eventobject
conversation.reset
  • conversationIdstring
conversation.synced
  • conversationIdstring
engine.status
  • statusobject
engine.login
  • loginobject
memory.changed
Nothing else.
learning.changed
Nothing else.
routine.changed
  • routineobject
routine.deleted
  • routineIdstring
routine.run
  • runobject
routines.spending
  • spendingobject
integration.changed
  • integrationobject
integration.deleted
  • integrationIdstring
skills.changed
Nothing else.
skills.offered
  • conversationIdstring
vault.changed
Nothing else.
usage.changed
  • usageobject
terminal.changed
Nothing else.
browser.status
  • statusobject
network.status
  • networkobject
doctor.report
  • reportobject
updates.changed
  • statusobject
channel.changed
  • channelobject
channel.deleted
  • channelIdstring
channel.door
  • doorobject
healed
  • noteobject
backups.changed
Nothing else.
import.progress
  • donenumber
  • totalnumber
  • currentstring
conch-apps.changed
Nothing else.
artifact.changed
  • artifactobject
artifact.deleted
  • artifactIdstring
task.changed
  • taskobject
task.deleted
  • taskIdstring
voice.changed
  • statusobject
wake.stop
Nothing else.
access.changed
  • waitingnumber
address.changed
  • addressobject
pong
Nothing else.
error
  • code'bad-request' | 'engine-unavailable' | 'not-found' | 'busy' | 'internal'
  • messagestring
  • conversationId?string
  • clientMessageId?string

What a conversation is made of

A conversation is an append-only log. Each event has a seq; a client that reconnects says the last one it saw, and Conch replays the rest.

user.message
  • conversationIdstring
  • seqnumber
  • atnumber
  • messageIdstring
  • textstring
  • attachments?object[]
assistant.delta
  • conversationIdstring
  • seqnumber
  • atnumber
  • messageIdstring
  • kind'text' | 'thinking'
  • deltastring
assistant.done
  • conversationIdstring
  • seqnumber
  • atnumber
  • messageIdstring
tool.started
  • conversationIdstring
  • seqnumber
  • atnumber
  • toolUseIdstring
  • namestring
  • inputunknown
tool.finished
  • conversationIdstring
  • seqnumber
  • atnumber
  • toolUseIdstring
  • status'pending' | 'running' | 'success' | 'error'
  • output?string
  • durationMs?number
  • view?object
permission.requested
  • conversationIdstring
  • seqnumber
  • atnumber
  • permissionIdstring
  • toolUseId?string
  • toolNamestring
  • inputunknown
  • summarystring
  • browser?object
  • vault?object
  • taint?string
  • lasting?boolean
  • afterReading?boolean
  • once?boolean
permission.resolved
  • conversationIdstring
  • seqnumber
  • atnumber
  • permissionIdstring
  • decision'allow' | 'allow-always' | 'deny' | 'expired'
memory.saved
  • conversationIdstring
  • seqnumber
  • atnumber
  • memoryobject
memory.forgotten
  • conversationIdstring
  • seqnumber
  • atnumber
  • memoryIdstring
  • contentstring
  • memory?object
memory.decided
  • conversationIdstring
  • seqnumber
  • atnumber
  • memoryIdstring
  • keptboolean
  • content?string
  • edited?boolean
  • anyway?boolean
learning.noted
  • conversationIdstring
  • seqnumber
  • atnumber
  • reviewIdstring
  • itemsobject[]
learning.decided
  • conversationIdstring
  • seqnumber
  • atnumber
  • entryIdstring
  • state'undone' | 'kept' | 'dismissed' | 'gone'
taint
  • conversationIdstring
  • seqnumber
  • atnumber
  • sourceobject
  • toolUseId?string
chats.looked
  • conversationIdstring
  • seqnumber
  • atnumber
  • lookIdstring
  • action'search' | 'read'
  • query?string
  • close?boolean
  • chatsobject[]
files.changed
  • conversationIdstring
  • seqnumber
  • atnumber
  • changeSetIdstring
  • toolUseId?string
  • labelstring
  • filesobject[]
files.restored
  • conversationIdstring
  • seqnumber
  • atnumber
  • changeSetIdstring
  • direction'undo' | 'redo'
  • filesobject[]
artifact
  • conversationIdstring
  • seqnumber
  • atnumber
  • artifactIdstring
  • titlestring
  • kind'html' | 'markdown' | 'svg' | 'mermaid' | 'chart' | 'table'
  • versionnumber
  • action'created' | 'updated' | 'edited'
  • note?string
task
  • conversationIdstring
  • seqnumber
  • atnumber
  • taskIdstring
  • titlestring
  • kind'background' | 'helper'
  • state'queued' | 'running' | 'needs-you' | 'done' | 'unverified' | …
  • summary?string
  • by?string
status
  • conversationIdstring
  • seqnumber
  • atnumber
  • status'idle' | 'running' | 'awaiting-permission' | 'error'
turn.usage
  • conversationIdstring
  • seqnumber
  • atnumber
  • usageobject
  • context?object
turn.completed
  • conversationIdstring
  • seqnumber
  • atnumber
  • outcome'success' | 'interrupted' | 'error'
  • usage?object
  • error?string
  • problem?'signed-out' | 'unavailable' | 'limit' | 'key-locked' | 'too-long'
  • paused?object
  • restarted?object
  • engine?'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | string
  • model?string
  • cost?object
  • context?object
title
  • conversationIdstring
  • seqnumber
  • atnumber
  • titlestring
turn.capped
  • conversationIdstring
  • seqnumber
  • atnumber
  • limit'chat' | 'month'
  • spentUsdnumber
  • limitUsdnumber
  • raiseTonumber
  • switchTo?object
  • during?boolean
turn.capped.settled
  • conversationIdstring
  • seqnumber
  • atnumber
  • outcome'raised' | 'switched' | 'stopped'
spend.notice
  • conversationIdstring
  • seqnumber
  • atnumber
  • kind'budget-near' | 'pricier' | 'stopped'
  • messagestring
skill.used
  • conversationIdstring
  • seqnumber
  • atnumber
  • skillIdstring
  • namestring
  • titlestring
  • by'user' | 'assistant' | 'carried'
  • permissions?object
  • from?string
skill.hold.ended
  • conversationIdstring
  • seqnumber
  • atnumber
  • skillIdstring
  • titlestring
  • reason'you'
notice
  • conversationIdstring
  • seqnumber
  • atnumber
  • codestring
  • messagestring
options
  • conversationIdstring
  • seqnumber
  • atnumber
  • optionsobject
vault.request
  • conversationIdstring
  • seqnumber
  • atnumber
  • requestobject
browser.step
  • conversationIdstring
  • seqnumber
  • atnumber
  • stepobject
browser.handoff
  • conversationIdstring
  • seqnumber
  • atnumber
  • handoffobject
turn.held
  • conversationIdstring
  • seqnumber
  • atnumber
  • reason'offline'
turn.needs-apps
  • conversationIdstring
  • seqnumber
  • atnumber
  • needsobject[]
  • modelobject
  • switchTo?object
context.compacted
  • conversationIdstring
  • seqnumber
  • atnumber
  • summarystring
  • before?string
  • engine'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | string
  • model?string
  • turnsnumber
  • asked?boolean
turn.routed
  • conversationIdstring
  • seqnumber
  • atnumber
  • from'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | string
  • to'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | string
  • reason'offline' | 'limit'
  • messagestring
routine
  • conversationIdstring
  • seqnumber
  • atnumber
  • routineIdstring
  • action'proposed' | 'updated' | 'paused' | 'deleted'
  • titlestring
integration.issue
  • conversationIdstring
  • seqnumber
  • atnumber
  • integrationIdstring
  • namestring
  • catalogId?string
  • state'needs-auth' | 'error'
  • messagestring
integration.suggestion
  • conversationIdstring
  • seqnumber
  • atnumber
  • catalogIdstring
  • namestring
  • descriptionstring
  • color?string
integration.suggestion.dismissed
  • conversationIdstring
  • seqnumber
  • atnumber
  • catalogIdstring
offer
  • conversationIdstring
  • seqnumber
  • atnumber
  • offerobject
offer.resolved
  • conversationIdstring
  • seqnumber
  • atnumber
  • offerIdstring
  • outcome'accepted' | 'dismissed' | 'expired'
question
  • conversationIdstring
  • seqnumber
  • atnumber
  • questionobject
question.answered
  • conversationIdstring
  • seqnumber
  • atnumber
  • questionIdstring
  • answerobject | null
replies
  • conversationIdstring
  • seqnumber
  • atnumber
  • repliesobject[]
  • by'assistant' | 'conch'
conch-app.offer
  • conversationIdstring
  • seqnumber
  • atnumber
  • offerobject
conch-app.share
  • conversationIdstring
  • seqnumber
  • atnumber
  • shareobject
plan
  • conversationIdstring
  • seqnumber
  • atnumber
  • stepsobject[]