{
  "openapi": "3.0.3",
  "info": {
    "title": "TJWater Agent history API",
    "version": "2",
    "description": "Agent owned history, topics and paginated visible-text search. Topics group chats within one verified user/data scope; they do not grant business permissions."
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/sessions": {
      "get": {
        "summary": "List and search owned conversations",
        "description": "Without pagination/filter parameters the legacy full-list behavior remains available. Paged calls sort updated_at and id descending; cursors are scoped to owner, project, purpose and title query.",
        "parameters": [
          {
            "name": "X-Project-Id",
            "in": "header",
            "required": false,
            "description": "Required for project scope; omit for personal scope",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "purpose",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "ordinary_chat",
                "task_collaboration",
                "task_execution"
              ],
              "default": "ordinary_chat"
            },
            "description": ""
          },
          {
            "name": "task_id",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": ""
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "Case-insensitive substring in session title or visible user/assistant message text, across all topics unless topic_id is specified."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 30
            },
            "description": ""
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 2048
            },
            "description": ""
          },
          {
            "name": "topic_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Optional topic UUID, or unclassified. Omitted means every topic plus unclassified in the verified scope."
          },
          {
            "name": "include_collaboration",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            },
            "description": "Include ordinary and manual task collaboration chats together; never task_execution. Default retains the explicit purpose filter."
          }
        ],
        "responses": {
          "200": {
            "description": "Owned history page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionPage"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor; reload when the message boundary changed"
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Session missing or outside the verified owner and scope"
          }
        }
      }
    },
    "/api/v1/session/{session_id}": {
      "get": {
        "summary": "Read owned conversation metadata and a recent message window",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Project-Id",
            "in": "header",
            "required": false,
            "description": "Required for project scope; omit for personal scope",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "message_limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 40
            },
            "description": "Omit to retain legacy full-history reads"
          }
        ],
        "responses": {
          "200": {
            "description": "Owned history page",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SessionSummary"
                    },
                    {
                      "type": "object",
                      "required": [
                        "messages"
                      ],
                      "properties": {
                        "messages": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        },
                        "message_page": {
                          "$ref": "#/components/schemas/MessagePagination"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor; reload when the message boundary changed"
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Session missing or outside the verified owner and scope"
          }
        }
      }
    },
    "/api/v1/session/{session_id}/messages": {
      "get": {
        "summary": "Read older owned messages in chronological order",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Project-Id",
            "in": "header",
            "required": false,
            "description": "Required for project scope; omit for personal scope",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 40
            },
            "description": ""
          },
          {
            "name": "before",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 2048
            },
            "description": "Opaque boundary from message_page.before_cursor; omitted for the latest page"
          }
        ],
        "responses": {
          "200": {
            "description": "Owned history page",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessagePage"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor; reload when the message boundary changed"
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Session missing or outside the verified owner and scope"
          }
        }
      }
    },
    "/api/v1/session/{session_id}/stream": {
      "get": {
        "summary": "Resume an owned session with a bounded initial snapshot",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "X-Project-Id",
            "in": "header",
            "required": false,
            "description": "Required for project scope; omit for personal scope",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "message_limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 40
            },
            "description": "Omit for legacy full snapshots"
          }
        ],
        "responses": {
          "200": {
            "description": "SSE: initial state carries messages, optional message_page, session_id, is_streaming and run_status; following events retain their existing contracts. Closing this subscription does not stop generation.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor; reload when the message boundary changed"
          },
          "401": {
            "description": "Authentication required"
          },
          "404": {
            "description": "Session missing or outside the verified owner and scope"
          }
        }
      }
    },
    "/api/v1/topics": {
      "get": {
        "responses": {
          "200": {
            "description": "Owned topics",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "topics": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Topic"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Topic"
                }
              }
            }
          },
          "400": {
            "description": "Invalid name"
          }
        }
      }
    },
    "/api/v1/topics/{topic_id}": {
      "parameters": [
        {
          "name": "topic_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "patch": {
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Renamed topic",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Topic"
                }
              }
            }
          },
          "404": {
            "description": "Topic not found"
          }
        }
      },
      "delete": {
        "description": "Removes the grouping; conversations are retained as unclassified.",
        "responses": {
          "204": {
            "description": "Removed"
          },
          "404": {
            "description": "Topic not found"
          }
        }
      }
    },
    "/api/v1/session/{session_id}/topic": {
      "parameters": [
        {
          "name": "session_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "patch": {
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "topic_id"
                ],
                "additionalProperties": false,
                "properties": {
                  "topic_id": {
                    "type": "string",
                    "format": "uuid",
                    "nullable": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Membership updated"
          },
          "400": {
            "description": "Invalid membership"
          },
          "404": {
            "description": "Owned session or topic not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "SessionSummary": {
        "type": "object",
        "required": [
          "id",
          "title"
        ],
        "additionalProperties": true,
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "is_streaming": {
            "type": "boolean"
          },
          "run_status": {
            "type": "string",
            "enum": [
              "running",
              "completed",
              "error",
              "aborted"
            ]
          },
          "topic_id": {
            "type": "string",
            "nullable": true
          },
          "topic_name": {
            "type": "string"
          },
          "search_snippet": {
            "type": "string",
            "description": "Visible body text excerpt; never tool arguments or reasoning."
          }
        }
      },
      "SessionPage": {
        "type": "object",
        "required": [
          "sessions",
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "sessions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SessionSummary"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "MessagePagination": {
        "type": "object",
        "required": [
          "has_more",
          "before_cursor"
        ],
        "properties": {
          "has_more": {
            "type": "boolean"
          },
          "before_cursor": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "MessagePage": {
        "type": "object",
        "required": [
          "messages",
          "message_page"
        ],
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "message_page": {
            "$ref": "#/components/schemas/MessagePagination"
          }
        }
      },
      "Topic": {
        "type": "object",
        "required": [
          "id",
          "name",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}