Overview The Sessions API allows you to create, list, retrieve, and delete chat sessions, as well as send messages and retrieve conversation history.
List Sessions Retrieve all sessions for an OpenCode instance.
GET /api/opencode/:port/sessions
Path Parameters The OpenCode instance port number
Response Array of session objects Unique session identifier
Parent session ID if this is a forked session
ISO 8601 timestamp of session creation
ISO 8601 timestamp of last update
Example curl http://localhost:3000/api/opencode/3100/sessions
[ { "id" : "sess_abc123" , "title" : "Debug API endpoints" , "createdAt" : "2026-03-03T10:00:00.000Z" , "updatedAt" : "2026-03-03T10:30:00.000Z" }, { "id" : "sess_def456" , "title" : "Implement authentication" , "parentID" : "sess_abc123" , "createdAt" : "2026-03-03T11:00:00.000Z" , "updatedAt" : "2026-03-03T11:15:00.000Z" } ]
Create Session Create a new chat session.
POST /api/opencode/:port/session/create
Path Parameters The OpenCode instance port number
Request Body Session title (defaults to auto-generated title)
Parent session ID to fork from
Response Unique session identifier
Parent session ID if forked
Example curl -X POST http://localhost:3000/api/opencode/3100/session/create \ -H "Content-Type: application/json" \ -d '{ "title": "New feature development" }'
{ "id" : "sess_xyz789" , "title" : "New feature development" , "createdAt" : "2026-03-03T12:00:00.000Z" , "updatedAt" : "2026-03-03T12:00:00.000Z" }
Get Session Retrieve a specific session by ID.
GET /api/opencode/:port/session/:id
Path Parameters The OpenCode instance port number
Response Unique session identifier
Parent session ID if forked
Example curl http://localhost:3000/api/opencode/3100/session/sess_abc123
{ "id" : "sess_abc123" , "title" : "Debug API endpoints" , "createdAt" : "2026-03-03T10:00:00.000Z" , "updatedAt" : "2026-03-03T10:30:00.000Z" }
Delete Session Delete a session permanently.
DELETE /api/opencode/:port/session/:id
Path Parameters The OpenCode instance port number
Response Indicates if deletion was successful
Example curl -X DELETE http://localhost:3000/api/opencode/3100/session/sess_abc123
Get Session Messages Retrieve all messages in a session.
GET /api/opencode/:port/session/:id/messages
Path Parameters The OpenCode instance port number
Response Array of message objects Unique message identifier
Message role: user or assistant
Example curl http://localhost:3000/api/opencode/3100/session/sess_abc123/messages
{ "messages" : [ { "id" : "msg_001" , "role" : "user" , "content" : "Help me debug this API endpoint" , "timestamp" : "2026-03-03T10:00:00.000Z" }, { "id" : "msg_002" , "role" : "assistant" , "content" : "I'll help you debug that. Can you share the endpoint code?" , "timestamp" : "2026-03-03T10:00:05.000Z" } ] }
Send Prompt Send a message to a session and get an AI response.
POST /api/opencode/:port/session/:id/prompt
Path Parameters The OpenCode instance port number
Request Body Model configuration AI provider ID (e.g., “anthropic”, “openai”)
Model ID (e.g., “claude-4.5-sonnet”, “gpt-4”)
Agent name to use for this prompt
Response ID of the created message
Example curl -X POST http://localhost:3000/api/opencode/3100/session/sess_abc123/prompt \ -H "Content-Type: application/json" \ -d '{ "text": "Write a function to validate email addresses", "model": { "providerID": "anthropic", "modelID": "claude-4.5-sonnet" } }'
{ "messageId" : "msg_003" , "response" : "I'll create an email validation function for you..." }
Error Responses Session Not Found { "statusCode" : 404 , "message" : "Session not found" }
Invalid Port { "statusCode" : 500 , "message" : "Invalid port" }
Session ID Required { "statusCode" : 500 , "message" : "Session ID required" }
Message Text Required { "statusCode" : 500 , "message" : "Message text required" }