DEV Community agent_sessions API
The agent_sessions API from DEV Community — 2 operation(s) for agent_sessions.
OpenAPI Specification
openapi: 3.0.3
info:
title: Forem API V1 agent_sessions API
version: 1.0.0
description: "Access Forem articles, users and other resources via API.\n For a real-world example of Forem in action, check out [DEV](https://www.dev.to).\n All endpoints can be accessed with the 'api-key' header and a accept header, but\n some of them are accessible publicly without authentication.\n\n Dates and date times, unless otherwise specified, must be in\n the [RFC 3339](https://tools.ietf.org/html/rfc3339) format."
servers:
- url: https://dev.to/api
description: Production server
security:
- api-key: []
tags:
- name: agent_sessions
paths:
/api/agent_sessions:
get:
summary: list the authenticated user's agent sessions
tags:
- agent_sessions
description: 'This endpoint allows the client to list their own agent sessions.
Agent sessions are coding conversation transcripts uploaded from CLI tools like
[Claude Code](https://github.com/anthropics/claude-code). Use the
[Forem CLI plugin](https://github.com/forem/forem-cli-plugin) to upload sessions
from the command line.'
operationId: getAgentSessions
responses:
'200':
description: successful
content:
application/json:
example:
- id: 40
slug: session-a-jsq3q8
title: Session A
tool_name: claude_code
total_messages: 2
published: false
created_at: '2026-05-28T12:45:15-06:00'
updated_at: '2026-05-28T12:45:15-06:00'
url: http://forem.test/agent_sessions/session-a-jsq3q8
schema:
type: array
items:
$ref: '#/components/schemas/AgentSessionIndex'
'401':
description: unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
post:
summary: upload a new agent session
tags:
- agent_sessions
description: 'This endpoint allows the client to create a new agent session.
Sessions are created from pre-parsed and curated data (`curated_data` JSON) and
optionally linked to an S3-stored raw file via `s3_key`. Use the presign endpoint
to get an upload URL for the raw file first.
Use the [Forem CLI plugin](https://github.com/forem/forem-cli-plugin) to upload
sessions directly from the command line.'
operationId: createAgentSession
parameters: []
responses:
'201':
description: created
content:
application/json:
example:
id: 41
slug: my-claude-session-jg1xld
title: My Claude Session
tool_name: claude_code
total_messages: 2
published: false
created_at: '2026-05-28T12:45:15-06:00'
url: http://forem.test/agent_sessions/my-claude-session-jg1xld
schema:
$ref: '#/components/schemas/AgentSessionIndex'
'401':
description: unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'422':
description: unprocessable
content:
application/json:
example:
error: Missing session content. Provide 'curated_data' or 's3_key'.
status: 422
requestBody:
content:
application/json:
schema:
type: object
properties:
title:
type: string
description: Title for the session (auto-generated if omitted)
curated_data:
type: string
description: JSON string of curated session data with messages array and metadata.
s3_key:
type: string
description: S3 object key from presign endpoint (optional).
tool_name:
type: string
description: Tool that produced the session (e.g. claude_code, codex).
enum:
- claude_code
- codex
- gemini_cli
- github_copilot
- opencode
- pi
required:
- curated_data
/api/agent_sessions/{id}:
get:
summary: show details for an agent session
tags:
- agent_sessions
description: 'This endpoint allows the client to retrieve a single agent session by slug or ID.
Returns the full session including messages, curated selections, and slices.'
operationId: getAgentSessionById
parameters:
- name: id
in: path
required: true
description: The slug or ID of the agent session.
schema:
type: string
example: my-session-abc123
responses:
'200':
description: successful
content:
application/json:
example:
id: 42
slug: my-session-15rjsb
title: My Session
tool_name: claude_code
total_messages: 2
curated_count: 2
published: false
metadata:
tool_name: claude_code
total_messages: 2
messages:
- role: user
index: 0
content:
- text: Hello
type: text
- role: assistant
index: 1
content:
- text: Hi there
type: text
slices: []
created_at: '2026-05-28T12:45:15-06:00'
updated_at: '2026-05-28T12:45:15-06:00'
url: http://forem.test/agent_sessions/my-session-15rjsb
schema:
$ref: '#/components/schemas/AgentSessionShow'
'401':
description: unauthorized
content:
application/json:
example:
error: unauthorized
status: 401
'404':
description: not found
content:
application/json:
example:
error: not found
status: 404
components:
schemas:
AgentSessionShow:
description: Full representation of an agent session including messages and curation data
type: object
properties:
id:
type: integer
format: int64
slug:
type: string
title:
type: string
tool_name:
type: string
description: Tool that produced the session (e.g. claude_code, codex)
total_messages:
type: integer
format: int32
curated_count:
type: integer
format: int32
description: Number of curated messages selected for display
published:
type: boolean
metadata:
type: object
nullable: true
description: Session metadata (tool-specific)
messages:
type: array
items:
type: object
description: All normalized messages in the session
slices:
type: array
items:
type: object
description: Named slices grouping message ranges
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
url:
type: string
format: url
required:
- id
- slug
- title
- tool_name
- total_messages
- curated_count
- published
- messages
- slices
- created_at
- updated_at
- url
AgentSessionIndex:
description: Representation of an agent session returned in a list or after creation
type: object
properties:
id:
type: integer
format: int64
slug:
type: string
title:
type: string
tool_name:
type: string
description: Tool that produced the session (e.g. claude_code, codex)
total_messages:
type: integer
format: int32
published:
type: boolean
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
url:
type: string
format: url
required:
- id
- slug
- title
- tool_name
- total_messages
- published
- created_at
- url
securitySchemes:
api-key:
type: apiKey
name: api-key
in: header
description: "API Key authentication.\n\nAuthentication for some endpoints, like write operations on the\nArticles API require a DEV API key.\n\nAll authenticated endpoints are CORS disabled, the API key is intended for non-browser scripts.\n\n### Getting an API key\n\nTo obtain one, please follow these steps:\n\n - visit https://dev.to/settings/extensions\n - in the \"DEV API Keys\" section create a new key by adding a\n description and clicking on \"Generate API Key\"\n\n \n\n - You'll see the newly generated key in the same view\n "