feat: add scoped history and artifacts
This commit is contained in:
@@ -0,0 +1,635 @@
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user