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: treat it as a map, not a promise. Both sides check every body against the schemas in packages/protocol.
$
curl -H "Authorization: Bearer conch_…" http://localhost:4317/api/stateMake a key with conch key. Changes that grant trust also need a password or key entered in 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/:credentialId - DELETE
/passkeys/:credentialId - POST
/passkeys/options - PUT
/password - DELETE
/requests/:code - POST
/requests/:code/approve - DELETE
/sessions - DELETE
/sessions/:id - POST
/verify
/api/activity
- GET
/
/api/agents
- GET
/ - POST
/ - GET
/:id - PATCH
/:id - DELETE
/:id - PUT
/:id/avatar - GET
/:id/avatar/:imageId - GET
/avatar/generate - POST
/avatar/generate - PUT
/default - PUT
/order - GET
/outside - POST
/outside - DELETE
/outside/:id - POST
/outside/look
/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 - GET
/:id/view
/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/cards
- GET
/apps - POST
/send
/api/channels
- GET
/ - POST
/ - GET
/:id - PATCH
/:id - DELETE
/:id - PUT
/:id/call-passcode - DELETE
/:id/call-passcode - 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 - POST
/feishu/scan - GET
/feishu/scan/:id - DELETE
/feishu/scan/:id - GET
/imessage - POST
/imessage/open - POST
/link - GET
/link/:id - DELETE
/link/:id
/api/checkin
- GET
/ - PUT
/ - POST
/look - POST
/told/:id/forget
/api/clouds
- GET
/:id - PUT
/:id
/api/commands
- GET
/ - PUT
/:name - DELETE
/:name
/api/computer
- GET
/
/api/computer-use
- GET
/ - PATCH
/ - POST
/access - DELETE
/apps/:id - GET
/live - GET
/shot/:shot - POST
/stop
/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 - POST
/offers/:offerId/test - GET
/packages/:packageId/:appId/icon - POST
/packages/:packageId/:appId/test - POST
/pick - POST
/preview
/api/conversations
- GET
/ - GET
/:id - PATCH
/:id - DELETE
/:id - POST
/:id/capped - POST
/:id/clear - POST
/:id/clear/undo - POST
/:id/compact - GET
/:id/draft - PUT
/:id/draft - POST
/:id/explain - PUT
/:id/goal - POST
/:id/limit-back - POST
/:id/messages/:messageId - POST
/:id/offers/:offerId/accept - POST
/:id/offers/:offerId/dismiss - POST
/:id/questions/:questionId/answer - POST
/:id/release - POST
/:id/round/stop - POST
/:id/skills/:skillId/stop-holding - PUT
/:id/spend-limit - POST
/:id/suggestions/:catalogId/dismiss - POST
/:id/switch - GET
/:id/timeline - POST
/:id/waits/:waitId - POST
/bulk
/api/dashboards
- GET
/ - PUT
/ - GET
/grafana - GET
/preview - GET
/scrape-config - POST
/test - POST
/token
/api/doctor
- GET
/ - POST
/check - POST
/repair
/api/drafts
- GET
/
/api/engine
- GET
/ - PUT
/api-key - DELETE
/api-key - POST
/login - POST
/login/cancel - POST
/login/code
/api/fallback
- GET
/
/api/favicon
- GET
/
/api/finance
- GET
/history
/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/access - POST
/accounts/:id/check - POST
/apps/:app/use - POST
/configure - POST
/connect - GET
/flows/:id - DELETE
/flows/:id - POST
/flows/:id/claim - 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 - GET
/:source/agents/:id/face - POST
/:source/slack - GET
/chats - POST
/chats - DELETE
/chats - GET
/rest - POST
/rest/:agentId - 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/listen
- GET
/
/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/past-chats
- GET
/ - GET
/:id - POST
/:id/continue
/api/phone
- GET
/address - POST
/address
/api/pick
- POST
/ - POST
/folder - GET
/guess - GET
/list - GET
/places
/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 - GET
/approvals/:conversationId/:permissionId - POST
/subscriptions - PATCH
/subscriptions/:id - DELETE
/subscriptions/:id - POST
/subscriptions/renew - POST
/test
/api/relay
- GET
/ - PUT
/ - DELETE
/ - POST
/check - POST
/pair
/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/standing-orders
- GET
/ - POST
/ - PATCH
/:id - DELETE
/:id
/api/state
- GET
/
/api/tasks
- GET
/ - POST
/ - DELETE
/:id - POST
/:id/continue - POST
/:id/retry - POST
/:id/start-now - POST
/:id/stop
/api/terminal
- GET
/ - POST
/ - DELETE
/:id - POST
/:id/ticket - GET
/live - PATCH
/settings
/api/timezone
- PUT
/
/api/trajectories
- POST
/:action
/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 - PUT
/sources/1password/token - DELETE
/sources/1password/token - PUT
/sources/1password/vaults - 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
/api/workplaces
- GET
/ - PUT
/cloud-key - DELETE
/cloud-key
The live socket
One WebSocket at /ws carries everything that happens while you watch.
What the app sends
- conversation.send
conversationId?stringclientMessageIdstringtextstringattachments?string[]options?objectfolder?stringsteer?booleangoal?stringagentId?string
- conversation.configure
conversationIdstringoptionsobject
- conversation.subscribe
conversationIdstringafterSeq?number
- conversation.unsubscribe
conversationIdstring
- conversation.interrupt
conversationIdstring
- permission.respond
conversationIdstringpermissionIdstringdecision'allow' | 'allow-always' | 'deny'edit?objectchoice?stringrule?boolean
- ping
- Nothing else.
- presence
visibleboolean
- hello
protocolVersionnumberserverVersionstring
- conversation.created
clientMessageIdstringconversationobject
- conversation.updated
conversationobject
- conversation.deleted
conversationIdstring
- folders.changed
foldersobject[]
- agents.changed
listobject
- 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.link
linkobject
- channel.door
doorobject
- healed
noteobject
- backups.changed
- Nothing else.
- import.progress
donenumbertotalnumbercurrentstring
- conch-apps.changed
- Nothing else.
- artifact.changed
artifactobject
- artifact.deleted
artifactIdstring
- task.changed
taskobject
- task.deleted
taskIdstring
- task.capacity
capacityobject
- 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' | 'verify-required'messagestringconversationId?stringpermissionId?stringclientMessageId?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
conversationIdstringseqnumberatnumbermessageIdstringtextstringattachments?object[]
- assistant.delta
conversationIdstringseqnumberatnumbermessageIdstringkind'text' | 'thinking'deltastring
- assistant.done
conversationIdstringseqnumberatnumbermessageIdstring
- tool.started
conversationIdstringseqnumberatnumbertoolUseIdstringnamestringinputunknownlabel?object
- tool.finished
conversationIdstringseqnumberatnumbertoolUseIdstringstatus'pending' | 'running' | 'success' | 'error'output?stringdurationMs?numberview?objectwhere?objectlabel?objectapproval?'allowed' | 'always' | 'declined' | 'expired' | 'refused'
- tool.progress
conversationIdstringseqnumberatnumbertoolNamestringtoolUseId?stringprogress?numberstage?'queued' | 'generating' | 'finishing'estimated?truepreview?stringby?stringdetail?string
- script.run
conversationIdstringseqnumberatnumberrunIdstringtoolUseId?stringstate'running' | 'done' | 'failed' | 'stopped'titlestringscript?stringcallsnumbertallyobject[]progress?objectnote?stringresult?stringerror?stringstop?'time' | 'calls' | 'memory' | 'output' | 'you' | 'crash'startedAtnumberdurationMs?number
- script.call
conversationIdstringseqnumberatnumberrunIdstringcallIdstringstepnumbertoolstringinputstringstatus'running' | 'success' | 'error' | 'declined'output?stringdurationMs?number
- narration
conversationIdstringseqnumberatnumbertextstringtoolUseId?stringsource'rule' | 'provider' | 'model'
- story.titled
conversationIdstringseqnumberatnumberstoryIdstringheadlinestringoutcome?stringsource'rule' | 'provider' | 'model'
- permission.requested
conversationIdstringseqnumberatnumberpermissionIdstringtoolUseId?stringtoolNamestringinputunknownsummarystringtitle?stringdetail?stringcost?stringcaution?stringbrowser?objectvault?objecttaint?stringlasting?booleanalways?stringafterReading?booleanonce?booleaneditable?booleanscript?objectrule?string
- permission.resolved
conversationIdstringseqnumberatnumberpermissionIdstringdecision'allow' | 'allow-always' | 'deny' | 'expired'unanswered?numberkept?objectrule?string
- memory.saved
conversationIdstringseqnumberatnumbermemoryobject
- memory.forgotten
conversationIdstringseqnumberatnumbermemoryIdstringcontentstringmemory?object
- memory.decided
conversationIdstringseqnumberatnumbermemoryIdstringkeptbooleancontent?stringedited?booleananyway?boolean
- learning.noted
conversationIdstringseqnumberatnumberreviewIdstringitemsobject[]
- learning.decided
conversationIdstringseqnumberatnumberentryIdstringstate'undone' | 'kept' | 'dismissed' | 'gone'
- taint
conversationIdstringseqnumberatnumbersourceobjecttoolUseId?stringcarried?boolean
- chats.looked
conversationIdstringseqnumberatnumberlookIdstringaction'search' | 'read'query?stringclose?booleanchatsobject[]
- chats.listed
conversationIdstringseqnumberatnumberlistIdstringchatsobject[]working?number
- chat.message
conversationIdstringseqnumberatnumbermessageIdstringdirection'out' | 'in'kind'message' | 'stop'chatobjecttextstringstate'waiting' | 'read' | 'held' | 'refused' | 'dismissed'wakes?booleanwhy?string
- files.changed
conversationIdstringseqnumberatnumberchangeSetIdstringtoolUseId?stringlabelstringfilesobject[]
- files.restored
conversationIdstringseqnumberatnumberchangeSetIdstringdirection'undo' | 'redo'filesobject[]
- artifact
conversationIdstringseqnumberatnumberartifactIdstringtitlestringkind'html' | 'markdown' | 'svg' | 'mermaid' | 'chart' | 'table'versionnumberaction'created' | 'updated' | 'edited'note?string
- task
conversationIdstringseqnumberatnumbertaskIdstringtitlestringkind'background' | 'helper'state'queued' | 'running' | 'needs-you' | 'done' | 'unverified' | …summary?stringby?stringgroup?string
- wait
conversationIdstringseqnumberatnumberwaitobject
- status
conversationIdstringseqnumberatnumberstatus'idle' | 'running' | 'awaiting-permission' | 'error'
- turn.usage
conversationIdstringseqnumberatnumberusageobjectcontext?object
- turn.completed
conversationIdstringseqnumberatnumberoutcome'success' | 'interrupted' | 'error'usage?objecterror?stringproblem?'signed-out' | 'unavailable' | 'limit' | 'key-locked' | 'too-long'paused?objectrestarted?objectengine?'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | stringmodel?stringcost?objectcontext?object
- title
conversationIdstringseqnumberatnumbertitlestring
- turn.capped
conversationIdstringseqnumberatnumberlimit'chat' | 'month'spentUsdnumberlimitUsdnumberraiseTonumberswitchTo?objectduring?boolean
- turn.capped.settled
conversationIdstringseqnumberatnumberoutcome'raised' | 'switched' | 'stopped'
- spend.notice
conversationIdstringseqnumberatnumberkind'budget-near' | 'pricier' | 'stopped'messagestring
- skill.used
conversationIdstringseqnumberatnumberskillIdstringnamestringtitlestringby'user' | 'assistant' | 'carried'permissions?objectfrom?string
- skill.hold.ended
conversationIdstringseqnumberatnumberskillIdstringtitlestringreason'you'
- notice
conversationIdstringseqnumberatnumbercodestringmessagestring
- options
conversationIdstringseqnumberatnumberoptionsobject
- agent
conversationIdstringseqnumberatnumberagentIdstringnamestringfrom?objectround?object
- round
conversationIdstringseqnumberatnumberroundIdstringstate'started' | 'asking' | 'ended'speakers?object[]turns?numberreason?'done' | 'turns' | 'loop' | 'spend' | 'stopped' | …
- peer.message
conversationIdstringseqnumberatnumberroundId?stringoutsideIdstringnamestringtextstringfailed?boolean
- vault.request
conversationIdstringseqnumberatnumberrequestobject
- browser.step
conversationIdstringseqnumberatnumberstepobject
- browser.handoff
conversationIdstringseqnumberatnumberhandoffobject
- turn.held
conversationIdstringseqnumberatnumberreason'offline'
- turn.needs-apps
conversationIdstringseqnumberatnumberneedsobject[]modelobjectswitchTo?object
- context.compacted
conversationIdstringseqnumberatnumbersummarystringbefore?stringengine'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | stringmodel?stringturnsnumberasked?boolean
- context.cleared
conversationIdstringseqnumberatnumber
- context.restored
conversationIdstringseqnumberatnumberclearedSeqnumber
- goal
conversationIdstringseqnumberatnumbergoalstring | null
- turn.routed
conversationIdstringseqnumberatnumberfrom'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | stringto'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | stringreason'offline' | 'limit' | 'signed-out'messagestringfromModel?stringmodel?stringstayed?boolean
- limit.back
conversationIdstringseqnumberatnumberengine'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | stringuntil?number
- model.switched
conversationIdstringseqnumberatnumberfrom'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | stringfromModel?stringto'claude-code' | 'codex-cli' | 'codex-agent' | 'copilot' | 'gemini-cli' | … | stringmodel?stringmessagestringby'assistant' | 'person'note?string
- model.choices
conversationIdstringseqnumberatnumberchoicesobject[]request?string
- routine
conversationIdstringseqnumberatnumberroutineIdstringaction'proposed' | 'updated' | 'paused' | 'deleted'titlestring
- standing.order
conversationIdstringseqnumberatnumberorderIdstringtextstring
- integration.issue
conversationIdstringseqnumberatnumberintegrationIdstringnamestringcatalogId?stringstate'needs-auth' | 'error'messagestring
- integration.suggestion
conversationIdstringseqnumberatnumbercatalogIdstringnamestringdescriptionstringcolor?string
- integration.suggestion.dismissed
conversationIdstringseqnumberatnumbercatalogIdstring
- offer
conversationIdstringseqnumberatnumberofferobject
- offer.resolved
conversationIdstringseqnumberatnumberofferIdstringoutcome'accepted' | 'dismissed' | 'expired'
- question
conversationIdstringseqnumberatnumberquestionobject
- question.answered
conversationIdstringseqnumberatnumberquestionIdstringanswerobject | null
- replies
conversationIdstringseqnumberatnumberrepliesobject[]by'assistant' | 'conch'
- conch-app.offer
conversationIdstringseqnumberatnumberofferobject
- conch-app.share
conversationIdstringseqnumberatnumbershareobject
- plan
conversationIdstringseqnumberatnumberstepsobject[]