This is page 3 of 3. Use http://codebase.md/matthewhand/mcp-openapi-proxy?lines=true&page={x} to view the full context.
# Directory Structure
```
├── .flake8
├── .github
│ └── workflows
│ ├── python-pytest.yml
│ └── testpypi.yaml
├── .gitignore
├── examples
│ ├── apis.guru-claude_desktop_config.json
│ ├── asana-claude_desktop_config.json
│ ├── box-claude_desktop_config.json
│ ├── elevenlabs-claude_desktop_config.json
│ ├── flyio-claude_desktop_config.json
│ ├── getzep-claude_desktop_config.json
│ ├── getzep.swagger.json
│ ├── glama-claude_desktop_config.json
│ ├── netbox-claude_desktop_config.json
│ ├── notion-claude_desktop_config.json
│ ├── render-claude_desktop_config.json
│ ├── slack-claude_desktop_config.json
│ ├── virustotal-claude_desktop_config.json
│ ├── virustotal.openapi.yml
│ ├── WIP-jellyfin-claude_desktop_config.json
│ └── wolframalpha-claude_desktop_config.json
├── LICENSE
├── mcp_openapi_proxy
│ ├── __init__.py
│ ├── handlers.py
│ ├── logging_setup.py
│ ├── openapi.py
│ ├── server_fastmcp.py
│ ├── server_lowlevel.py
│ ├── types.py
│ └── utils.py
├── pyproject.toml
├── README.md
├── sample_mcpServers.json
├── scripts
│ └── diagnose_examples.py
├── tests
│ ├── conftest.py
│ ├── fixtures
│ │ └── sample_openapi_specs
│ │ └── petstore_openapi_v3.json
│ ├── integration
│ │ ├── test_apisguru_integration.py
│ │ ├── test_asana_integration.py
│ │ ├── test_box_integration.py
│ │ ├── test_elevenlabs_integration.py
│ │ ├── test_example_configs.py
│ │ ├── test_fly_machines_integration.py
│ │ ├── test_getzep_integration.py
│ │ ├── test_integration_json_access.py
│ │ ├── test_jellyfin_public_demo.py
│ │ ├── test_netbox_integration.py
│ │ ├── test_notion_integration.py
│ │ ├── test_openapi_integration.py
│ │ ├── test_openwebui_integration.py
│ │ ├── test_petstore_api_existence.py
│ │ ├── test_render_integration_lowlevel.py
│ │ ├── test_render_integration.py
│ │ ├── test_slack_integration.py
│ │ ├── test_ssl_verification.py
│ │ ├── test_tool_invocation.py
│ │ ├── test_tool_prefix.py
│ │ ├── test_virustotal_integration.py
│ │ └── test_wolframalpha_integration.py
│ └── unit
│ ├── test_additional_headers.py
│ ├── test_capabilities.py
│ ├── test_embedded_openapi_json.py
│ ├── test_input_schema_generation.py
│ ├── test_mcp_tools.py
│ ├── test_openapi_spec_parser.py
│ ├── test_openapi_tool_name_length.py
│ ├── test_openapi.py
│ ├── test_parameter_substitution.py
│ ├── test_prompts.py
│ ├── test_resources.py
│ ├── test_tool_whitelisting.py
│ ├── test_uri_substitution.py
│ ├── test_utils_whitelist.py
│ └── test_utils.py
├── upload_readme_to_readme.py
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/examples/getzep.swagger.json:
--------------------------------------------------------------------------------
```json
1 | {
2 | "swagger": "2.0",
3 | "info": {
4 | "title": "Zep Memory API (V2)",
5 | "description": "OpenAPI specification for Zep API V2, covering Memory, Graph, Group, and User endpoints",
6 | "version": "2.0"
7 | },
8 | "host": "api.getzep.com",
9 | "basePath": "/api/v2",
10 | "schemes": ["https"],
11 | "securityDefinitions": {
12 | "ApiKeyAuth": {
13 | "type": "apiKey",
14 | "in": "header",
15 | "name": "Authorization",
16 | "description": "Header authentication in the format: Api-Key <token>"
17 | }
18 | },
19 | "security": [{"ApiKeyAuth": []}],
20 | "paths": {
21 | "/sessions": {
22 | "post": {
23 | "summary": "Add Session",
24 | "description": "Creates a new session.",
25 | "consumes": ["application/json"],
26 | "produces": ["application/json"],
27 | "parameters": [
28 | {
29 | "in": "body",
30 | "name": "body",
31 | "description": "Request body",
32 | "required": true,
33 | "schema": {
34 | "type": "object",
35 | "required": ["session_id", "user_id"],
36 | "properties": {
37 | "session_id": {"type": "string", "description": "Unique identifier of the session"},
38 | "user_id": {"type": "string", "description": "Unique identifier of the user associated with the session"},
39 | "fact_rating_instruction": {
40 | "type": "object",
41 | "description": "Deprecated",
42 | "properties": {
43 | "instruction": {"type": "string"},
44 | "examples": {
45 | "type": "object",
46 | "properties": {
47 | "high": {"type": "string"},
48 | "low": {"type": "string"},
49 | "medium": {"type": "string"}
50 | }
51 | }
52 | }
53 | },
54 | "metadata": {
55 | "type": "object",
56 | "description": "Deprecated",
57 | "additionalProperties": {}
58 | }
59 | }
60 | }
61 | }
62 | ],
63 | "responses": {
64 | "201": {
65 | "description": "Created",
66 | "schema": {"$ref": "#/definitions/Session"}
67 | },
68 | "400": {"description": "Memory Add Session Request Bad Request Error"},
69 | "500": {"description": "Memory Add Session Request Internal Server Error"}
70 | }
71 | }
72 | },
73 | "/sessions/{sessionId}": {
74 | "get": {
75 | "summary": "Get Session",
76 | "description": "Retrieves a session by ID.",
77 | "produces": ["application/json"],
78 | "parameters": [
79 | {
80 | "in": "path",
81 | "name": "sessionId",
82 | "description": "Unique identifier of the session",
83 | "required": true,
84 | "type": "string"
85 | }
86 | ],
87 | "responses": {
88 | "200": {
89 | "description": "Retrieved",
90 | "schema": {"$ref": "#/definitions/Session"}
91 | },
92 | "404": {"description": "Memory Get Session Request Not Found Error"},
93 | "500": {"description": "Memory Get Session Request Internal Server Error"}
94 | }
95 | }
96 | },
97 | "/sessions-ordered": {
98 | "get": {
99 | "summary": "Get Sessions",
100 | "description": "Retrieves all sessions with optional sorting and pagination.",
101 | "produces": ["application/json"],
102 | "parameters": [
103 | {
104 | "name": "page_number",
105 | "in": "query",
106 | "type": "integer",
107 | "description": "Page number for pagination, starting from 1",
108 | "required": false
109 | },
110 | {
111 | "name": "page_size",
112 | "in": "query",
113 | "type": "integer",
114 | "description": "Number of sessions per page",
115 | "required": false
116 | },
117 | {
118 | "name": "order_by",
119 | "in": "query",
120 | "type": "string",
121 | "description": "Field to order results by: created_at, updated_at, user_id, session_id",
122 | "required": false
123 | },
124 | {
125 | "name": "asc",
126 | "in": "query",
127 | "type": "boolean",
128 | "description": "Order direction: true for ascending, false for descending",
129 | "required": false
130 | }
131 | ],
132 | "responses": {
133 | "200": {
134 | "description": "Retrieved",
135 | "schema": {
136 | "type": "object",
137 | "properties": {
138 | "response_count": {"type": "integer"},
139 | "sessions": {"type": "array", "items": {"$ref": "#/definitions/Session"}},
140 | "total_count": {"type": "integer"}
141 | }
142 | }
143 | },
144 | "400": {"description": "Memory List Sessions Request Bad Request Error"},
145 | "500": {"description": "Memory List Sessions Request Internal Server Error"}
146 | }
147 | }
148 | },
149 | "/sessions/{sessionId}/memory": {
150 | "get": {
151 | "summary": "Get Session Memory",
152 | "description": "Retrieves memory for a given session.",
153 | "produces": ["application/json"],
154 | "parameters": [
155 | {
156 | "in": "path",
157 | "name": "sessionId",
158 | "description": "ID of the session to retrieve memory for",
159 | "required": true,
160 | "type": "string"
161 | },
162 | {
163 | "name": "lastn",
164 | "in": "query",
165 | "type": "integer",
166 | "description": "Number of most recent memory entries to retrieve",
167 | "required": false
168 | },
169 | {
170 | "name": "minRating",
171 | "in": "query",
172 | "type": "number",
173 | "format": "double",
174 | "description": "Minimum rating to filter relevant facts",
175 | "required": false
176 | }
177 | ],
178 | "responses": {
179 | "200": {
180 | "description": "Retrieved",
181 | "schema": {"$ref": "#/definitions/Memory"}
182 | },
183 | "404": {"description": "Memory Get Request Not Found Error"},
184 | "500": {"description": "Memory Get Request Internal Server Error"}
185 | }
186 | },
187 | "post": {
188 | "summary": "Add Memory to Session",
189 | "description": "Adds memory to a specified session.",
190 | "consumes": ["application/json"],
191 | "produces": ["application/json"],
192 | "parameters": [
193 | {
194 | "in": "path",
195 | "name": "sessionId",
196 | "description": "ID of the session to add memory to",
197 | "required": true,
198 | "type": "string"
199 | },
200 | {
201 | "in": "body",
202 | "name": "body",
203 | "description": "Request body",
204 | "required": true,
205 | "schema": {
206 | "type": "object",
207 | "required": ["messages"],
208 | "properties": {
209 | "messages": {
210 | "type": "array",
211 | "items": {
212 | "type": "object",
213 | "required": ["content", "role_type"],
214 | "properties": {
215 | "content": {"type": "string", "description": "Message content"},
216 | "role_type": {
217 | "type": "string",
218 | "description": "Role type (e.g., user, system)",
219 | "enum": ["assistant", "user", "system", "function", "norole"]
220 | },
221 | "metadata": {
222 | "type": "object",
223 | "description": "Message metadata",
224 | "additionalProperties": {}
225 | },
226 | "role": {"type": "string", "description": "Custom role of the sender (e.g., john, sales_agent)"},
227 | "token_count": {"type": "integer", "description": "Deprecated"}
228 | }
229 | }
230 | },
231 | "fact_instruction": {"type": "string", "description": "Deprecated"},
232 | "return_context": {"type": "boolean", "description": "Optionally return memory context for recent messages"},
233 | "summary_instruction": {"type": "string", "description": "Deprecated"}
234 | }
235 | }
236 | }
237 | ],
238 | "responses": {
239 | "200": {
240 | "description": "Successful",
241 | "schema": {
242 | "type": "object",
243 | "properties": {"context": {"type": "string"}}
244 | }
245 | },
246 | "500": {"description": "Memory Add Request Internal Server Error"}
247 | }
248 | },
249 | "delete": {
250 | "summary": "Delete Session",
251 | "description": "Deletes a session.",
252 | "produces": ["application/json"],
253 | "parameters": [
254 | {
255 | "in": "path",
256 | "name": "sessionId",
257 | "description": "ID of the session to delete",
258 | "required": true,
259 | "type": "string"
260 | }
261 | ],
262 | "responses": {
263 | "200": {
264 | "description": "Deleted",
265 | "schema": {
266 | "type": "object",
267 | "properties": {"message": {"type": "string"}}
268 | }
269 | },
270 | "404": {"description": "Memory Delete Request Not Found Error"},
271 | "500": {"description": "Memory Delete Request Internal Server Error"}
272 | }
273 | }
274 | },
275 | "/sessions/{sessionId}/messages": {
276 | "get": {
277 | "summary": "Get Messages for Session",
278 | "description": "Retrieves messages for a session.",
279 | "produces": ["application/json"],
280 | "parameters": [
281 | {
282 | "in": "path",
283 | "name": "sessionId",
284 | "description": "Session ID",
285 | "required": true,
286 | "type": "string"
287 | },
288 | {
289 | "name": "limit",
290 | "in": "query",
291 | "type": "integer",
292 | "description": "Limit the number of results returned",
293 | "required": false
294 | },
295 | {
296 | "name": "cursor",
297 | "in": "query",
298 | "type": "integer",
299 | "description": "Cursor for pagination",
300 | "required": false
301 | }
302 | ],
303 | "responses": {
304 | "200": {
305 | "description": "Retrieved",
306 | "schema": {
307 | "type": "object",
308 | "properties": {
309 | "messages": {"type": "array", "items": {"$ref": "#/definitions/Message"}},
310 | "row_count": {"type": "integer"},
311 | "total_count": {"type": "integer"}
312 | }
313 | }
314 | },
315 | "404": {"description": "Memory Get Session Messages Request Not Found Error"},
316 | "500": {"description": "Memory Get Session Messages Request Internal Server Error"}
317 | }
318 | }
319 | },
320 | "/sessions/{sessionId}/messages/classify": {
321 | "post": {
322 | "summary": "Classify Session",
323 | "description": "Classifies a session.",
324 | "consumes": ["application/json"],
325 | "produces": ["application/json"],
326 | "parameters": [
327 | {
328 | "in": "path",
329 | "name": "sessionId",
330 | "description": "Session ID",
331 | "required": true,
332 | "type": "string"
333 | },
334 | {
335 | "in": "body",
336 | "name": "body",
337 | "description": "Request body",
338 | "required": true,
339 | "schema": {
340 | "type": "object",
341 | "required": ["classes", "name"],
342 | "properties": {
343 | "classes": {
344 | "type": "array",
345 | "items": {"type": "string", "description": "Classes for classification"}
346 | },
347 | "name": {"type": "string", "description": "Name of the classifier"},
348 | "instruction": {"type": "string", "description": "Custom instruction for classification"},
349 | "last_n": {"type": "integer", "description": "Number of session messages to consider, defaults to 4"},
350 | "persist": {"type": "boolean", "description": "Deprecated, defaults to true"}
351 | }
352 | }
353 | }
354 | ],
355 | "responses": {
356 | "200": {
357 | "description": "Successful",
358 | "schema": {
359 | "type": "object",
360 | "properties": {
361 | "class": {"type": "string"},
362 | "label": {"type": "string"}
363 | }
364 | }
365 | },
366 | "404": {"description": "Memory Classify Session Request Not Found Error"},
367 | "500": {"description": "Memory Classify Session Request Internal Server Error"}
368 | }
369 | }
370 | },
371 | "/sessions/{sessionId}/messages/{messageUUID}": {
372 | "get": {
373 | "summary": "Get Message",
374 | "description": "Retrieves a specific message from a session.",
375 | "produces": ["application/json"],
376 | "parameters": [
377 | {
378 | "in": "path",
379 | "name": "sessionId",
380 | "description": "Soon to be deprecated, not needed",
381 | "required": true,
382 | "type": "string"
383 | },
384 | {
385 | "in": "path",
386 | "name": "messageUUID",
387 | "description": "UUID of the message",
388 | "required": true,
389 | "type": "string"
390 | }
391 | ],
392 | "responses": {
393 | "200": {
394 | "description": "Retrieved",
395 | "schema": {"$ref": "#/definitions/Message"}
396 | },
397 | "404": {"description": "Memory Get Session Message Request Not Found Error"},
398 | "500": {"description": "Memory Get Session Message Request Internal Server Error"}
399 | }
400 | }
401 | },
402 | "/graph": {
403 | "post": {
404 | "summary": "Add Data to Graph",
405 | "description": "Adds data to the graph. Limits vary by subscription tier; see pricing page.",
406 | "consumes": ["application/json"],
407 | "produces": ["application/json"],
408 | "parameters": [
409 | {
410 | "in": "body",
411 | "name": "body",
412 | "description": "Request body",
413 | "required": true,
414 | "schema": {
415 | "type": "object",
416 | "properties": {
417 | "data": {"type": "string", "description": "Optional data to add"},
418 | "group_id": {"type": "string", "description": "Optional group ID"},
419 | "type": {
420 | "type": "string",
421 | "enum": ["text", "json", "message"],
422 | "description": "Optional data type"
423 | },
424 | "user_id": {"type": "string", "description": "Optional user ID"}
425 | }
426 | }
427 | }
428 | ],
429 | "responses": {
430 | "202": {
431 | "description": "Accepted",
432 | "schema": {
433 | "type": "object",
434 | "properties": {"message": {"type": "string"}}
435 | }
436 | },
437 | "400": {"description": "Graph Add Request Bad Request Error"},
438 | "500": {"description": "Graph Add Request Internal Server Error"}
439 | }
440 | }
441 | },
442 | "/graph/add-fact-triple": {
443 | "post": {
444 | "summary": "Add Fact Triple",
445 | "description": "Adds a fact triple for a user or group.",
446 | "consumes": ["application/json"],
447 | "produces": ["application/json"],
448 | "parameters": [
449 | {
450 | "in": "body",
451 | "name": "body",
452 | "description": "Request body",
453 | "required": true,
454 | "schema": {
455 | "type": "object",
456 | "required": ["fact", "fact_name", "target_node_name"],
457 | "properties": {
458 | "fact": {"type": "string", "maxLength": 50, "description": "Fact relating the nodes"},
459 | "fact_name": {"type": "string", "minLength": 1, "maxLength": 50, "description": "Edge name in CAPS_SNAKE_CASE"},
460 | "target_node_name": {"type": "string", "maxLength": 50, "description": "Target node name"},
461 | "created_at": {"type": "string", "description": "Optional timestamp"},
462 | "expired_at": {"type": "string", "description": "Optional expiry time"},
463 | "fact_uuid": {"type": "string", "description": "Optional edge UUID"},
464 | "group_id": {"type": "string", "description": "Optional group ID"},
465 | "invalid_at": {"type": "string", "description": "Optional invalidation time"},
466 | "source_node_name": {"type": "string", "maxLength": 50, "description": "Optional source node name"},
467 | "source_node_summary": {"type": "string", "maxLength": 500, "description": "Optional source summary"},
468 | "source_node_uuid": {"type": "string", "description": "Optional source UUID"},
469 | "target_node_summary": {"type": "string", "maxLength": 500, "description": "Optional target summary"},
470 | "target_node_uuid": {"type": "string", "description": "Optional target UUID"},
471 | "user_id": {"type": "string", "description": "Optional user ID"},
472 | "valid_at": {"type": "string", "description": "Optional valid-from time"}
473 | }
474 | }
475 | }
476 | ],
477 | "responses": {
478 | "200": {
479 | "description": "Successful",
480 | "schema": {
481 | "type": "object",
482 | "properties": {
483 | "edge": {"$ref": "#/definitions/Edge"},
484 | "source_node": {"$ref": "#/definitions/Node"},
485 | "target_node": {"$ref": "#/definitions/Node"}
486 | }
487 | }
488 | },
489 | "400": {"description": "Graph Add Fact Triple Request Bad Request Error"},
490 | "500": {"description": "Graph Add Fact Triple Request Internal Server Error"}
491 | }
492 | }
493 | },
494 | "/graph/search": {
495 | "post": {
496 | "summary": "Search Graph",
497 | "description": "Performs a graph search query.",
498 | "consumes": ["application/json"],
499 | "produces": ["application/json"],
500 | "parameters": [
501 | {
502 | "in": "body",
503 | "name": "body",
504 | "description": "Request body",
505 | "required": true,
506 | "schema": {
507 | "type": "object",
508 | "required": ["query"],
509 | "properties": {
510 | "query": {"type": "string", "description": "Search query string"},
511 | "center_node_uuid": {"type": "string", "description": "Optional node to rerank around"},
512 | "group_id": {"type": "string", "description": "Optional group ID"},
513 | "limit": {"type": "integer", "default": 10, "maximum": 50, "description": "Maximum number of facts to retrieve"},
514 | "min_score": {"type": "number", "format": "double", "description": "Deprecated"},
515 | "mmr_lambda": {"type": "number", "format": "double", "description": "Maximal marginal relevance weighting"},
516 | "reranker": {
517 | "type": "string",
518 | "enum": ["rrf", "mmr", "node_distance", "episode_mentions", "cross_encoder"],
519 | "default": "rrf",
520 | "description": "Reranker type"
521 | },
522 | "scope": {
523 | "type": "string",
524 | "enum": ["edges", "nodes"],
525 | "default": "edges",
526 | "description": "Search scope"
527 | },
528 | "search_filters": {"type": "object", "description": "Optional search filters"},
529 | "user_id": {"type": "string", "description": "Optional user ID"}
530 | }
531 | }
532 | }
533 | ],
534 | "responses": {
535 | "200": {
536 | "description": "Successful",
537 | "schema": {
538 | "type": "object",
539 | "properties": {
540 | "edges": {"type": "array", "items": {"$ref": "#/definitions/Edge"}},
541 | "nodes": {"type": "array", "items": {"$ref": "#/definitions/Node"}}
542 | }
543 | }
544 | },
545 | "400": {"description": "Graph Search Request Bad Request Error"},
546 | "500": {"description": "Graph Search Request Internal Server Error"}
547 | }
548 | }
549 | },
550 | "/groups": {
551 | "post": {
552 | "summary": "Create Group",
553 | "description": "Creates a new group.",
554 | "consumes": ["application/json"],
555 | "produces": ["application/json"],
556 | "parameters": [
557 | {
558 | "in": "body",
559 | "name": "body",
560 | "description": "Request body",
561 | "required": true,
562 | "schema": {
563 | "type": "object",
564 | "required": ["group_id"],
565 | "properties": {
566 | "group_id": {"type": "string", "description": "Unique group identifier"},
567 | "description": {"type": "string", "description": "Optional description"},
568 | "fact_rating_instruction": {
569 | "type": "object",
570 | "properties": {
571 | "instruction": {"type": "string"},
572 | "examples": {
573 | "type": "object",
574 | "properties": {
575 | "high": {"type": "string"},
576 | "low": {"type": "string"},
577 | "medium": {"type": "string"}
578 | }
579 | }
580 | }
581 | },
582 | "name": {"type": "string", "description": "Optional group name"}
583 | }
584 | }
585 | }
586 | ],
587 | "responses": {
588 | "201": {
589 | "description": "Created",
590 | "schema": {"$ref": "#/definitions/Group"}
591 | },
592 | "400": {"description": "Group Add Request Bad Request Error"},
593 | "500": {"description": "Group Add Request Internal Server Error"}
594 | }
595 | }
596 | },
597 | "/groups-ordered": {
598 | "get": {
599 | "summary": "Get All Groups",
600 | "description": "Retrieves all groups with pagination.",
601 | "produces": ["application/json"],
602 | "parameters": [
603 | {
604 | "name": "pageNumber",
605 | "in": "query",
606 | "type": "integer",
607 | "description": "Page number, starting from 1",
608 | "required": false
609 | },
610 | {
611 | "name": "pageSize",
612 | "in": "query",
613 | "type": "integer",
614 | "description": "Number of groups per page",
615 | "required": false
616 | }
617 | ],
618 | "responses": {
619 | "200": {
620 | "description": "Retrieved",
621 | "schema": {
622 | "type": "object",
623 | "properties": {
624 | "groups": {"type": "array", "items": {"$ref": "#/definitions/Group"}},
625 | "row_count": {"type": "integer"},
626 | "total_count": {"type": "integer"}
627 | }
628 | }
629 | },
630 | "400": {"description": "Get Groups Ordered Request Bad Request Error"},
631 | "500": {"description": "Get Groups Ordered Request Internal Server Error"}
632 | }
633 | }
634 | },
635 | "/groups/{groupId}": {
636 | "get": {
637 | "summary": "Get Group",
638 | "description": "Retrieves a group by ID.",
639 | "produces": ["application/json"],
640 | "parameters": [
641 | {
642 | "in": "path",
643 | "name": "groupId",
644 | "type": "string",
645 | "required": true,
646 | "description": "Group ID"
647 | }
648 | ],
649 | "responses": {
650 | "200": {
651 | "description": "Retrieved",
652 | "schema": {"$ref": "#/definitions/Group"}
653 | },
654 | "404": {"description": "Get Groups Group ID Request Not Found Error"},
655 | "500": {"description": "Get Groups Group ID Request Internal Server Error"}
656 | }
657 | },
658 | "delete": {
659 | "summary": "Delete Group",
660 | "description": "Deletes a group.",
661 | "produces": ["application/json"],
662 | "parameters": [
663 | {
664 | "in": "path",
665 | "name": "groupId",
666 | "type": "string",
667 | "required": true,
668 | "description": "Group ID to delete"
669 | }
670 | ],
671 | "responses": {
672 | "200": {
673 | "description": "Deleted",
674 | "schema": {
675 | "type": "object",
676 | "properties": {"message": {"type": "string"}}
677 | }
678 | },
679 | "400": {"description": "Group Delete Request Bad Request Error"},
680 | "404": {"description": "Group Delete Request Not Found Error"},
681 | "500": {"description": "Group Delete Request Internal Server Error"}
682 | }
683 | },
684 | "patch": {
685 | "summary": "Update Group",
686 | "description": "Updates group information.",
687 | "consumes": ["application/json"],
688 | "produces": ["application/json"],
689 | "parameters": [
690 | {
691 | "in": "path",
692 | "name": "groupId",
693 | "type": "string",
694 | "required": true,
695 | "description": "Group ID to update"
696 | },
697 | {
698 | "in": "body",
699 | "name": "body",
700 | "description": "Update body",
701 | "required": true,
702 | "schema": {
703 | "type": "object",
704 | "properties": {
705 | "description": {"type": "string", "description": "Optional new description"},
706 | "fact_rating_instruction": {
707 | "type": "object",
708 | "properties": {
709 | "instruction": {"type": "string"},
710 | "examples": {
711 | "type": "object",
712 | "properties": {
713 | "high": {"type": "string"},
714 | "low": {"type": "string"},
715 | "medium": {"type": "string"}
716 | }
717 | }
718 | }
719 | },
720 | "name": {"type": "string", "description": "Optional new name"}
721 | }
722 | }
723 | }
724 | ],
725 | "responses": {
726 | "201": {
727 | "description": "Updated",
728 | "schema": {"$ref": "#/definitions/Group"}
729 | },
730 | "400": {"description": "Group Update Request Bad Request Error"},
731 | "404": {"description": "Group Update Request Not Found Error"},
732 | "500": {"description": "Group Update Request Internal Server Error"}
733 | }
734 | }
735 | },
736 | "/users": {
737 | "post": {
738 | "summary": "Add User",
739 | "description": "Creates a new user.",
740 | "consumes": ["application/json"],
741 | "produces": ["application/json"],
742 | "parameters": [
743 | {
744 | "in": "body",
745 | "name": "body",
746 | "description": "Request body",
747 | "required": true,
748 | "schema": {
749 | "type": "object",
750 | "properties": {
751 | "email": {"type": "string", "description": "Optional email address"},
752 | "fact_rating_instruction": {
753 | "type": "object",
754 | "description": "Optional fact rating instruction",
755 | "properties": {
756 | "instruction": {"type": "string"},
757 | "examples": {
758 | "type": "object",
759 | "properties": {
760 | "high": {"type": "string"},
761 | "low": {"type": "string"},
762 | "medium": {"type": "string"}
763 | }
764 | }
765 | }
766 | },
767 | "first_name": {"type": "string", "description": "Optional first name"},
768 | "last_name": {"type": "string", "description": "Optional last name"},
769 | "metadata": {
770 | "type": "object",
771 | "description": "Optional metadata",
772 | "additionalProperties": {}
773 | },
774 | "user_id": {"type": "string", "description": "Optional user identifier"}
775 | }
776 | }
777 | }
778 | ],
779 | "responses": {
780 | "201": {
781 | "description": "Created",
782 | "schema": {"$ref": "#/definitions/User"}
783 | },
784 | "400": {"description": "User Add Request Bad Request Error"},
785 | "500": {"description": "User Add Request Internal Server Error"}
786 | }
787 | }
788 | },
789 | "/users-ordered": {
790 | "get": {
791 | "summary": "Get Users",
792 | "description": "Retrieves all users with pagination.",
793 | "produces": ["application/json"],
794 | "parameters": [
795 | {
796 | "name": "pageNumber",
797 | "in": "query",
798 | "type": "integer",
799 | "description": "Page number, starting from 1",
800 | "required": false
801 | },
802 | {
803 | "name": "pageSize",
804 | "in": "query",
805 | "type": "integer",
806 | "description": "Number of users per page",
807 | "required": false
808 | }
809 | ],
810 | "responses": {
811 | "200": {
812 | "description": "Retrieved",
813 | "schema": {
814 | "type": "object",
815 | "properties": {
816 | "row_count": {"type": "integer"},
817 | "total_count": {"type": "integer"},
818 | "users": {"type": "array", "items": {"$ref": "#/definitions/User"}}
819 | }
820 | }
821 | },
822 | "400": {"description": "User List Ordered Request Bad Request Error"},
823 | "500": {"description": "User List Ordered Request Internal Server Error"}
824 | }
825 | }
826 | },
827 | "/users/{userId}": {
828 | "get": {
829 | "summary": "Get User",
830 | "description": "Retrieves a user by ID.",
831 | "produces": ["application/json"],
832 | "parameters": [
833 | {
834 | "in": "path",
835 | "name": "userId",
836 | "type": "string",
837 | "required": true,
838 | "description": "User ID"
839 | }
840 | ],
841 | "responses": {
842 | "200": {
843 | "description": "Retrieved",
844 | "schema": {"$ref": "#/definitions/User"}
845 | },
846 | "404": {"description": "User Get Request Not Found Error"},
847 | "500": {"description": "User Get Request Internal Server Error"}
848 | }
849 | },
850 | "delete": {
851 | "summary": "Delete User",
852 | "description": "Deletes a user.",
853 | "produces": ["application/json"],
854 | "parameters": [
855 | {
856 | "in": "path",
857 | "name": "userId",
858 | "type": "string",
859 | "required": true,
860 | "description": "User ID to delete"
861 | }
862 | ],
863 | "responses": {
864 | "200": {
865 | "description": "Deleted",
866 | "schema": {
867 | "type": "object",
868 | "properties": {"message": {"type": "string"}}
869 | }
870 | },
871 | "404": {"description": "User Delete Request Not Found Error"},
872 | "500": {"description": "User Delete Request Internal Server Error"}
873 | }
874 | },
875 | "patch": {
876 | "summary": "Update User",
877 | "description": "Updates user information.",
878 | "consumes": ["application/json"],
879 | "produces": ["application/json"],
880 | "parameters": [
881 | {
882 | "in": "path",
883 | "name": "userId",
884 | "type": "string",
885 | "required": true,
886 | "description": "User ID to update"
887 | },
888 | {
889 | "in": "body",
890 | "name": "body",
891 | "description": "Update body",
892 | "required": true,
893 | "schema": {
894 | "type": "object",
895 | "properties": {
896 | "email": {"type": "string", "description": "Optional email address"},
897 | "fact_rating_instruction": {
898 | "type": "object",
899 | "description": "Optional fact rating instruction",
900 | "properties": {
901 | "instruction": {"type": "string"},
902 | "examples": {
903 | "type": "object",
904 | "properties": {
905 | "high": {"type": "string"},
906 | "low": {"type": "string"},
907 | "medium": {"type": "string"}
908 | }
909 | }
910 | }
911 | },
912 | "first_name": {"type": "string", "description": "Optional first name"},
913 | "last_name": {"type": "string", "description": "Optional last name"},
914 | "metadata": {
915 | "type": "object",
916 | "description": "Optional metadata",
917 | "additionalProperties": {}
918 | }
919 | }
920 | }
921 | }
922 | ],
923 | "responses": {
924 | "200": {
925 | "description": "Updated",
926 | "schema": {"$ref": "#/definitions/User"}
927 | },
928 | "400": {"description": "User Update Request Bad Request Error"},
929 | "404": {"description": "User Update Request Not Found Error"},
930 | "500": {"description": "User Update Request Internal Server Error"}
931 | }
932 | }
933 | },
934 | "/users/{userId}/node": {
935 | "get": {
936 | "summary": "Get User Node",
937 | "description": "Retrieves a user’s graph node.",
938 | "produces": ["application/json"],
939 | "parameters": [
940 | {
941 | "in": "path",
942 | "name": "userId",
943 | "type": "string",
944 | "required": true,
945 | "description": "User ID for the node"
946 | }
947 | ],
948 | "responses": {
949 | "200": {
950 | "description": "Retrieved",
951 | "schema": {
952 | "type": "object",
953 | "properties": {"node": {"$ref": "#/definitions/Node"}}
954 | }
955 | },
956 | "404": {"description": "User Get Node Request Not Found Error"},
957 | "500": {"description": "User Get Node Request Internal Server Error"}
958 | }
959 | }
960 | },
961 | "/users/{userId}/sessions": {
962 | "get": {
963 | "summary": "Get User Sessions",
964 | "description": "Retrieves all sessions for a user.",
965 | "produces": ["application/json"],
966 | "parameters": [
967 | {
968 | "in": "path",
969 | "name": "userId",
970 | "type": "string",
971 | "required": true,
972 | "description": "User ID for sessions"
973 | }
974 | ],
975 | "responses": {
976 | "200": {
977 | "description": "Retrieved",
978 | "schema": {"type": "array", "items": {"$ref": "#/definitions/Session"}}
979 | },
980 | "500": {"description": "User Get Sessions Request Internal Server Error"}
981 | }
982 | }
983 | }
984 | },
985 | "definitions": {
986 | "Session": {
987 | "type": "object",
988 | "properties": {
989 | "classifications": {
990 | "type": "object",
991 | "additionalProperties": {"type": "string"}
992 | },
993 | "created_at": {"type": "string"},
994 | "deleted_at": {"type": "string"},
995 | "ended_at": {"type": "string"},
996 | "fact_rating_instruction": {
997 | "type": "object",
998 | "description": "Deprecated",
999 | "properties": {
1000 | "instruction": {"type": "string"},
1001 | "examples": {
1002 | "type": "object",
1003 | "properties": {
1004 | "high": {"type": "string"},
1005 | "low": {"type": "string"},
1006 | "medium": {"type": "string"}
1007 | }
1008 | }
1009 | }
1010 | },
1011 | "facts": {
1012 | "type": "array",
1013 | "items": {"type": "string"},
1014 | "description": "Deprecated"
1015 | },
1016 | "id": {"type": "integer"},
1017 | "metadata": {
1018 | "type": "object",
1019 | "description": "Deprecated",
1020 | "additionalProperties": {}
1021 | },
1022 | "project_uuid": {"type": "string"},
1023 | "session_id": {"type": "string"},
1024 | "updated_at": {"type": "string", "description": "Deprecated"},
1025 | "user_id": {"type": "string"},
1026 | "uuid": {"type": "string"}
1027 | }
1028 | },
1029 | "Message": {
1030 | "type": "object",
1031 | "properties": {
1032 | "content": {"type": "string", "description": "Message content"},
1033 | "role_type": {
1034 | "type": "string",
1035 | "description": "Role type (e.g., user, system)",
1036 | "enum": ["assistant", "user", "system", "function", "norole"]
1037 | },
1038 | "created_at": {"type": "string", "description": "Timestamp of message creation"},
1039 | "metadata": {
1040 | "type": "object",
1041 | "description": "Message metadata",
1042 | "additionalProperties": {}
1043 | },
1044 | "role": {"type": "string", "description": "Custom role of the sender (e.g., john, sales_agent)"},
1045 | "token_count": {"type": "integer", "description": "Deprecated"},
1046 | "updated_at": {"type": "string", "description": "Deprecated"},
1047 | "uuid": {"type": "string", "description": "Unique identifier of the message"}
1048 | }
1049 | },
1050 | "Memory": {
1051 | "type": "object",
1052 | "properties": {
1053 | "context": {"type": "string"},
1054 | "facts": {
1055 | "type": "array",
1056 | "items": {"type": "string"},
1057 | "description": "Deprecated: Use relevant_facts instead"
1058 | },
1059 | "messages": {
1060 | "type": "array",
1061 | "items": {"$ref": "#/definitions/Message"},
1062 | "description": "List of message objects; only last_n messages returned"
1063 | },
1064 | "metadata": {
1065 | "type": "object",
1066 | "description": "Deprecated",
1067 | "additionalProperties": {}
1068 | },
1069 | "relevant_facts": {
1070 | "type": "array",
1071 | "items": {
1072 | "type": "object",
1073 | "properties": {
1074 | "content": {"type": "string"},
1075 | "created_at": {"type": "string"},
1076 | "fact": {"type": "string"},
1077 | "uuid": {"type": "string"},
1078 | "expired_at": {"type": "string"},
1079 | "invalid_at": {"type": "string"},
1080 | "name": {"type": "string"},
1081 | "rating": {"type": "number", "format": "double"},
1082 | "source_node_name": {"type": "string"},
1083 | "target_node_name": {"type": "string"},
1084 | "valid_at": {"type": "string"}
1085 | }
1086 | },
1087 | "description": "Most relevant facts to recent session messages"
1088 | },
1089 | "summary": {
1090 | "type": "object",
1091 | "description": "Deprecated: Use context string instead",
1092 | "properties": {
1093 | "content": {"type": "string"},
1094 | "created_at": {"type": "string"},
1095 | "metadata": {"type": "object", "additionalProperties": {}},
1096 | "related_message_uuids": {"type": "array", "items": {"type": "string"}},
1097 | "token_count": {"type": "integer"},
1098 | "uuid": {"type": "string"}
1099 | }
1100 | }
1101 | }
1102 | },
1103 | "ClassificationResult": {
1104 | "type": "object",
1105 | "properties": {
1106 | "class": {"type": "string"},
1107 | "label": {"type": "string"}
1108 | }
1109 | },
1110 | "Edge": {
1111 | "type": "object",
1112 | "properties": {
1113 | "created_at": {"type": "string"},
1114 | "fact": {"type": "string"},
1115 | "name": {"type": "string"},
1116 | "source_node_uuid": {"type": "string"},
1117 | "target_node_uuid": {"type": "string"},
1118 | "uuid": {"type": "string"},
1119 | "episodes": {"type": "array", "items": {"type": "string"}},
1120 | "expired_at": {"type": "string"},
1121 | "invalid_at": {"type": "string"},
1122 | "valid_at": {"type": "string"}
1123 | }
1124 | },
1125 | "Node": {
1126 | "type": "object",
1127 | "properties": {
1128 | "created_at": {"type": "string"},
1129 | "name": {"type": "string"},
1130 | "summary": {"type": "string"},
1131 | "uuid": {"type": "string"},
1132 | "attributes": {"type": "object", "additionalProperties": {"type": "string"}},
1133 | "labels": {"type": "array", "items": {"type": "string"}}
1134 | }
1135 | },
1136 | "Group": {
1137 | "type": "object",
1138 | "properties": {
1139 | "created_at": {"type": "string"},
1140 | "description": {"type": "string"},
1141 | "external_id": {"type": "string", "description": "Deprecated"},
1142 | "fact_rating_instruction": {
1143 | "type": "object",
1144 | "properties": {
1145 | "instruction": {"type": "string"},
1146 | "examples": {
1147 | "type": "object",
1148 | "properties": {
1149 | "high": {"type": "string"},
1150 | "low": {"type": "string"},
1151 | "medium": {"type": "string"}
1152 | }
1153 | }
1154 | }
1155 | },
1156 | "group_id": {"type": "string"},
1157 | "id": {"type": "integer"},
1158 | "name": {"type": "string"},
1159 | "project_uuid": {"type": "string"},
1160 | "uuid": {"type": "string"}
1161 | }
1162 | },
1163 | "User": {
1164 | "type": "object",
1165 | "properties": {
1166 | "created_at": {"type": "string"},
1167 | "deleted_at": {"type": "string"},
1168 | "email": {"type": "string"},
1169 | "fact_rating_instruction": {
1170 | "type": "object",
1171 | "properties": {
1172 | "instruction": {"type": "string"},
1173 | "examples": {
1174 | "type": "object",
1175 | "properties": {
1176 | "high": {"type": "string"},
1177 | "low": {"type": "string"},
1178 | "medium": {"type": "string"}
1179 | }
1180 | }
1181 | }
1182 | },
1183 | "first_name": {"type": "string"},
1184 | "id": {"type": "integer"},
1185 | "last_name": {"type": "string"},
1186 | "metadata": {
1187 | "type": "object",
1188 | "description": "Deprecated",
1189 | "additionalProperties": {}
1190 | },
1191 | "project_uuid": {"type": "string"},
1192 | "session_count": {"type": "integer", "description": "Deprecated"},
1193 | "updated_at": {"type": "string", "description": "Deprecated"},
1194 | "user_id": {"type": "string"},
1195 | "uuid": {"type": "string"}
1196 | }
1197 | }
1198 | }
1199 | }
1200 |
```