Sessions API

Manage OpenCode chat sessions

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

port · number · required

The OpenCode instance port number

Response

data · array

Array of session objects

Show Session object

id · string

Unique session identifier

title · string

Session title

parentID · string

Parent session ID if this is a forked session

createdAt · string

ISO 8601 timestamp of session creation

updatedAt · string

ISO 8601 timestamp of last update

Example

curl http://localhost:3000/api/opencode/3100/sessions

Response

[
  {
    "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

port · number · required

The OpenCode instance port number

Request Body

title · string

Session title (defaults to auto-generated title)

parentID · string

Parent session ID to fork from

Response

id · string

Unique session identifier

title · string

Session title

parentID · string

Parent session ID if forked

createdAt · string

ISO 8601 timestamp

Example

curl -X POST http://localhost:3000/api/opencode/3100/session/create \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New feature development"
  }'

Response

{
  "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

port · number · required

The OpenCode instance port number

id · string · required

The session ID

Response

id · string

Unique session identifier

title · string

Session title

parentID · string

Parent session ID if forked

createdAt · string

ISO 8601 timestamp

updatedAt · string

ISO 8601 timestamp

Example

curl http://localhost:3000/api/opencode/3100/session/sess_abc123

Response

{
  "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

port · number · required

The OpenCode instance port number

id · string · required

The session ID to delete

Response

success · boolean

Indicates if deletion was successful

Example

curl -X DELETE http://localhost:3000/api/opencode/3100/session/sess_abc123

Response

{
  "success": true
}

---

Get Session Messages

Retrieve all messages in a session.

GET /api/opencode/:port/session/:id/messages

Path Parameters

port · number · required

The OpenCode instance port number

id · string · required

The session ID

Response

messages · array

Array of message objects

Show Message object

id · string

Unique message identifier

role · string

Message role: user or assistant

content · string

Message content

timestamp · string

ISO 8601 timestamp

Example

curl http://localhost:3000/api/opencode/3100/session/sess_abc123/messages

Response

{
  "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

port · number · required

The OpenCode instance port number

id · string · required

The session ID

Request Body

text · string · required

The message text to send

model · object

Model configuration

Show Model object

providerID · string · required

AI provider ID (e.g., “anthropic”, “openai”)

modelID · string · required

Model ID (e.g., “claude-4.5-sonnet”, “gpt-4”)

agent · string

Agent name to use for this prompt

Response

messageId · string

ID of the created message

response · string

AI-generated response

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"
    }
  }'

Response

{
  "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"
}