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    ![obtain a DEV API Key](https://user-images.githubusercontent.com/37842/172718105-bd93664e-76e0-477d-99c4-265dda0b06c5.png)\n\n  - You'll see the newly generated key in the same view\n    ![generated DEV API Key](https://user-images.githubusercontent.com/37842/172718151-e7fe26a0-9937-42e8-96c6-333acdab9e49.png)"