openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Omi Developer API",
    "description": "Programmatic access to your Omi data — memories, conversations, action items, and API keys. Build custom integrations, analytics dashboards, and automation workflows.",
    "version": "1.0.0",
    "contact": {
      "name": "Omi",
      "url": "https://omi.me"
    },
    "license": {
      "name": "MIT",
      "url": "https://github.com/BasedHardware/omi/blob/main/LICENSE"
    }
  },
  "servers": [
    {
      "url": "https://api.omi.me",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    { "name": "Memories", "description": "Read and write user memories — timeless facts, preferences, and insights." },
    { "name": "Conversations", "description": "Create and retrieve conversation transcripts with AI-generated summaries." },
    { "name": "Folders", "description": "Retrieve user-defined folders for organizing conversations." },
    { "name": "Action Items", "description": "Manage tasks and to-dos extracted from conversations or created manually." },
    { "name": "API Keys", "description": "Create, list, and revoke developer API keys." }
  ],
  "paths": {
    "/v1/dev/user/memories": {
      "get": {
        "operationId": "listMemories",
        "summary": "List memories",
        "description": "Retrieve your memories with optional filtering by category. Returns memories sorted by most recent first.",
        "tags": ["Memories"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of memories to return.",
            "schema": { "type": "integer", "default": 25 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of memories to skip for pagination.",
            "schema": { "type": "integer", "default": 0 }
          },
          {
            "name": "categories",
            "in": "query",
            "description": "Comma-separated list of categories to filter by (e.g. `interesting,system`).",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of memories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Memory" }
                },
                "example": [
                  {
                    "id": "mem_789ghi",
                    "content": "User is building an AI fitness app with personal trainer",
                    "category": "interesting",
                    "visibility": "private",
                    "tags": [],
                    "created_at": "2025-01-15T10:30:00Z",
                    "updated_at": "2025-01-15T10:30:00Z",
                    "manually_added": false,
                    "reviewed": false,
                    "user_review": null,
                    "edited": false
                  }
                ]
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createMemory",
        "summary": "Create memory",
        "description": "Create a new memory. Memories are timeless facts about the user — preferences, relationships, personal details, and notable insights.",
        "tags": ["Memories"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateMemory" },
              "example": {
                "content": "User prefers dark mode in all applications",
                "category": "system",
                "tags": ["preferences", "ui"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created memory.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Memory" },
                "example": {
                  "id": "mem_xyz789",
                  "content": "User prefers dark mode in all applications",
                  "category": "system",
                  "visibility": "private",
                  "tags": ["preferences", "ui"],
                  "created_at": "2025-12-06T10:35:00Z",
                  "updated_at": "2025-12-06T10:35:00Z",
                  "manually_added": true
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/dev/user/memories/batch": {
      "post": {
        "operationId": "createMemoriesBatch",
        "summary": "Create memories (batch)",
        "description": "Create multiple memories in a single request. Maximum 25 memories per batch.",
        "tags": ["Memories"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BatchCreateMemories" },
              "example": {
                "memories": [
                  { "content": "User prefers async communication over meetings", "category": "system" },
                  { "content": "User speaks fluent Japanese and French", "category": "interesting" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch creation result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BatchMemoriesResponse" },
                "example": {
                  "memories": [
                    { "id": "mem_001", "content": "User prefers async communication over meetings", "category": "system" },
                    { "id": "mem_002", "content": "User speaks fluent Japanese and French", "category": "interesting" }
                  ],
                  "created_count": 2
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/dev/user/memories/{memory_id}": {
      "delete": {
        "operationId": "deleteMemory",
        "summary": "Delete memory",
        "description": "Permanently delete a memory. This action cannot be undone.",
        "tags": ["Memories"],
        "parameters": [
          {
            "name": "memory_id",
            "in": "path",
            "required": true,
            "description": "The ID of the memory to delete.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Memory deleted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": { "success": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "patch": {
        "operationId": "updateMemory",
        "summary": "Update memory",
        "description": "Update a memory's content or visibility. At least one field must be provided.",
        "tags": ["Memories"],
        "parameters": [
          {
            "name": "memory_id",
            "in": "path",
            "required": true,
            "description": "The ID of the memory to update.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateMemory" },
              "example": {
                "content": "User strongly prefers dark mode in all applications",
                "visibility": "private"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated memory.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Memory" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/dev/user/folders": {
      "get": {
        "operationId": "listFolders",
        "summary": "List folders",
        "description": "Retrieve all folders for the authenticated user. This endpoint is strictly read-only and returns an empty list if the user has no folders yet. System folders (Work, Personal, Social) are initialized lazily through other paths (the mobile app opening the conversations screen, or the conversation post-processing pipeline), not by this endpoint.",
        "tags": ["Folders"],
        "parameters": [],
        "responses": {
          "200": {
            "description": "List of folders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Folder" }
                },
                "example": [
                  {
                    "id": "folder_uuid_work",
                    "name": "Work",
                    "description": "Work, business, professional, and career-related conversations",
                    "color": "#3B82F6",
                    "icon": "💼",
                    "created_at": "2025-01-15T10:00:00Z",
                    "updated_at": "2025-01-20T13:50:00Z",
                    "order": 0,
                    "is_default": false,
                    "is_system": true,
                    "category_mapping": "work",
                    "conversation_count": 12
                  }
                ]
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": {
            "description": "Insufficient permissions. Required scope: `conversations:read`.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "detail": "Insufficient permissions. Required scope: conversations:read" }
              }
            }
          }
        }
      }
    },
    "/v1/dev/user/conversations": {
      "get": {
        "operationId": "listConversations",
        "summary": "List conversations",
        "description": "Retrieve your conversation transcripts. Only returns completed, non-discarded conversations.",
        "tags": ["Conversations"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of conversations to return.",
            "schema": { "type": "integer", "default": 25 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of conversations to skip.",
            "schema": { "type": "integer", "default": 0 }
          },
          {
            "name": "start_date",
            "in": "query",
            "description": "Filter by start date (inclusive). ISO 8601 format.",
            "schema": { "type": "string", "format": "date-time" }
          },
          {
            "name": "end_date",
            "in": "query",
            "description": "Filter by end date (inclusive). ISO 8601 format.",
            "schema": { "type": "string", "format": "date-time" }
          },
          {
            "name": "include_transcript",
            "in": "query",
            "description": "Include full transcript segments in the response.",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "categories",
            "in": "query",
            "description": "Comma-separated list of conversation categories to filter by (e.g. `work,personal`). Matches conversations whose category is any of the listed values (OR semantics).",
            "schema": { "type": "string" }
          },
          {
            "name": "folder_id",
            "in": "query",
            "description": "Filter conversations by folder ID. Each conversation belongs to at most one folder, so this is a single-value filter. Must be a non-empty string.",
            "schema": { "type": "string", "minLength": 1 }
          },
          {
            "name": "starred",
            "in": "query",
            "description": "Filter by starred status. Pass `true` for starred conversations only, `false` for non-starred.",
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of conversations.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/Conversation" }
                },
                "example": [
                  {
                    "id": "conv_202",
                    "created_at": "2025-01-20T13:50:00Z",
                    "started_at": "2025-01-20T13:50:00Z",
                    "finished_at": "2025-01-20T14:10:00Z",
                    "language": "en",
                    "source": "omi",
                    "structured": {
                      "title": "Feature Discussion",
                      "overview": "Brainstorming session for new features",
                      "emoji": "💼",
                      "category": "business",
                      "action_items": [],
                      "events": []
                    }
                  }
                ]
              }
            }
          },
          "400": {
            "description": "Invalid `categories` value (must be a comma-separated list of valid `CategoryEnum` values).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "detail": "Invalid category 'foo' is not a valid CategoryEnum" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": {
            "description": "Insufficient permissions. Required scope: `conversations:read`.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" },
                "example": { "detail": "Insufficient permissions. Required scope: conversations:read" }
              }
            }
          },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      },
      "post": {
        "operationId": "createConversation",
        "summary": "Create conversation from text",
        "description": "Create a new conversation from text content. The text is processed through the full AI pipeline: discard detection, structured generation, action item extraction, memory extraction, app integration, and webhooks.",
        "tags": ["Conversations"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateConversation" },
              "example": {
                "text": "Meeting notes: Discussed Q1 goals. Action item: prepare budget by Friday.",
                "text_source": "other_text",
                "text_source_spec": "meeting_notes",
                "started_at": "2025-12-06T14:00:00+00:00",
                "language": "en"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversation created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ConversationResponse" },
                "example": {
                  "id": "conv_456",
                  "status": "completed",
                  "discarded": false
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/dev/user/conversations/{conversation_id}": {
      "get": {
        "operationId": "getConversation",
        "summary": "Get conversation",
        "description": "Retrieve a single conversation by ID, optionally including transcript segments.",
        "tags": ["Conversations"],
        "parameters": [
          {
            "name": "conversation_id",
            "in": "path",
            "required": true,
            "description": "The ID of the conversation to retrieve.",
            "schema": { "type": "string" }
          },
          {
            "name": "include_transcript",
            "in": "query",
            "description": "Include full transcript segments.",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "The conversation.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Conversation" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "patch": {
        "operationId": "updateConversation",
        "summary": "Update conversation",
        "description": "Update a conversation's title or discard status. At least one field must be provided.",
        "tags": ["Conversations"],
        "parameters": [
          {
            "name": "conversation_id",
            "in": "path",
            "required": true,
            "description": "The ID of the conversation to update.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateConversation" },
              "example": {
                "title": "Q1 Planning Meeting - Budget Discussion"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated conversation.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Conversation" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      },
      "delete": {
        "operationId": "deleteConversation",
        "summary": "Delete conversation",
        "description": "Permanently delete a conversation and its associated data. This action cannot be undone. Consider using PATCH with `discarded: true` to hide instead.",
        "tags": ["Conversations"],
        "parameters": [
          {
            "name": "conversation_id",
            "in": "path",
            "required": true,
            "description": "The ID of the conversation to delete.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation deleted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": { "success": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/dev/user/conversations/from-segments": {
      "post": {
        "operationId": "createConversationFromSegments",
        "summary": "Create conversation from transcript segments",
        "description": "Create a conversation from structured transcript segments with speaker diarization. Unlike text-based conversations, transcript segments are stored and can be retrieved with `include_transcript=true`.",
        "tags": ["Conversations"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateConversationFromSegments" },
              "example": {
                "transcript_segments": [
                  { "text": "Let's review the quarterly results", "speaker": "SPEAKER_00", "is_user": true, "start": 0.0, "end": 3.5 },
                  { "text": "Revenue is up 25% from last quarter", "speaker": "SPEAKER_01", "is_user": false, "start": 4.0, "end": 7.2 }
                ],
                "source": "phone",
                "language": "en"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Conversation created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ConversationResponse" },
                "example": {
                  "id": "conv_789",
                  "status": "completed",
                  "discarded": false
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/dev/user/action-items": {
      "get": {
        "operationId": "listActionItems",
        "summary": "List action items",
        "description": "Retrieve your action items (tasks/to-dos) with optional filtering.",
        "tags": ["Action Items"],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of items to return.",
            "schema": { "type": "integer", "default": 100 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Number of items to skip.",
            "schema": { "type": "integer", "default": 0 }
          },
          {
            "name": "completed",
            "in": "query",
            "description": "Filter by completion status.",
            "schema": { "type": "boolean" }
          },
          {
            "name": "conversation_id",
            "in": "query",
            "description": "Filter by associated conversation ID.",
            "schema": { "type": "string" }
          },
          {
            "name": "start_date",
            "in": "query",
            "description": "Filter by creation start date (inclusive).",
            "schema": { "type": "string", "format": "date-time" }
          },
          {
            "name": "end_date",
            "in": "query",
            "description": "Filter by creation end date (inclusive).",
            "schema": { "type": "string", "format": "date-time" }
          }
        ],
        "responses": {
          "200": {
            "description": "List of action items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ActionItem" }
                },
                "example": [
                  {
                    "id": "action_101",
                    "description": "Review budget proposal",
                    "completed": false,
                    "created_at": "2025-01-20T10:15:00Z",
                    "updated_at": "2025-01-20T10:15:00Z",
                    "due_at": null,
                    "completed_at": null,
                    "conversation_id": "conv_202"
                  }
                ]
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createActionItem",
        "summary": "Create action item",
        "description": "Create a new action item (task/to-do). Push notifications are sent to the Omi app if a `due_at` date is provided.",
        "tags": ["Action Items"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateActionItem" },
              "example": {
                "description": "Review pull request #123",
                "completed": false,
                "due_at": "2025-12-08T15:00:00+00:00"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created action item.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ActionItem" },
                "example": {
                  "id": "action_abc123",
                  "description": "Review pull request #123",
                  "completed": false,
                  "created_at": "2025-12-06T10:30:00Z",
                  "updated_at": "2025-12-06T10:30:00Z",
                  "due_at": "2025-12-08T15:00:00+00:00",
                  "completed_at": null,
                  "conversation_id": null
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/dev/user/action-items/batch": {
      "post": {
        "operationId": "createActionItemsBatch",
        "summary": "Create action items (batch)",
        "description": "Create multiple action items in a single request. Maximum 50 per batch.",
        "tags": ["Action Items"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BatchCreateActionItems" },
              "example": {
                "action_items": [
                  { "description": "Review Q1 report", "due_at": "2025-12-10T17:00:00Z" },
                  { "description": "Schedule team meeting" }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch creation result.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BatchActionItemsResponse" },
                "example": {
                  "action_items": [
                    { "id": "action_001", "description": "Review Q1 report" },
                    { "id": "action_002", "description": "Schedule team meeting" }
                  ],
                  "created_count": 2
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/dev/user/action-items/{action_item_id}": {
      "patch": {
        "operationId": "updateActionItem",
        "summary": "Update action item",
        "description": "Update an action item's description, completion status, or due date. Setting `completed: true` automatically sets `completed_at`.",
        "tags": ["Action Items"],
        "parameters": [
          {
            "name": "action_item_id",
            "in": "path",
            "required": true,
            "description": "The ID of the action item to update.",
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/UpdateActionItem" },
              "example": { "completed": true }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated action item.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ActionItem" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      },
      "delete": {
        "operationId": "deleteActionItem",
        "summary": "Delete action item",
        "description": "Permanently delete an action item. This action cannot be undone.",
        "tags": ["Action Items"],
        "parameters": [
          {
            "name": "action_item_id",
            "in": "path",
            "required": true,
            "description": "The ID of the action item to delete.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Action item deleted.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SuccessResponse" },
                "example": { "success": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/dev/keys": {
      "get": {
        "operationId": "listApiKeys",
        "summary": "List API keys",
        "description": "Retrieve all your developer API keys. Secret key values are not returned — only the prefix is shown.",
        "tags": ["API Keys"],
        "responses": {
          "200": {
            "description": "List of API keys.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": { "$ref": "#/components/schemas/ApiKey" }
                },
                "example": [
                  {
                    "id": "key_123abc",
                    "name": "My Analytics Dashboard",
                    "key_prefix": "omi_dev_abc123",
                    "created_at": "2025-01-15T10:30:00Z",
                    "last_used_at": "2025-01-20T14:22:00Z"
                  }
                ]
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "operationId": "createApiKey",
        "summary": "Create API key",
        "description": "Create a new developer API key. The full key is only returned once — store it securely immediately.",
        "tags": ["API Keys"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateApiKey" },
              "example": { "name": "My New Integration" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created API key with full secret.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ApiKeyCreated" },
                "example": {
                  "id": "key_789ghi",
                  "name": "My New Integration",
                  "key_prefix": "omi_dev_ghi789",
                  "key": "omi_dev_ghi789_full_secret_key_here",
                  "created_at": "2025-01-20T15:00:00Z",
                  "last_used_at": null
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" }
        }
      }
    },
    "/v1/dev/keys/{key_id}": {
      "delete": {
        "operationId": "revokeApiKey",
        "summary": "Revoke API key",
        "description": "Permanently revoke (delete) a specific API key. Any requests using this key will immediately stop working.",
        "tags": ["API Keys"],
        "parameters": [
          {
            "name": "key_id",
            "in": "path",
            "required": true,
            "description": "The ID of the key to revoke.",
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "204": {
            "description": "Key revoked successfully."
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Developer API key. Get one from **Settings → Developer → Create Key** in the Omi app. Keys are prefixed with `omi_dev_`."
      }
    },
    "schemas": {
      "Memory": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique identifier." },
          "content": { "type": "string", "description": "The memory content." },
          "category": { "type": "string", "enum": ["interesting", "system", "manual"], "description": "Memory category." },
          "visibility": { "type": "string", "enum": ["public", "private"], "description": "Visibility level." },
          "tags": { "type": "array", "items": { "type": "string" }, "description": "List of tags." },
          "created_at": { "type": "string", "format": "date-time", "description": "When the memory was created." },
          "updated_at": { "type": "string", "format": "date-time", "description": "When the memory was last updated." },
          "manually_added": { "type": "boolean", "description": "Whether the memory was added manually (via API or app)." },
          "reviewed": { "type": "boolean", "description": "Whether the memory has been reviewed." },
          "user_review": { "type": ["boolean", "null"], "description": "User's review decision." },
          "edited": { "type": "boolean", "description": "Whether the memory has been edited." }
        }
      },
      "CreateMemory": {
        "type": "object",
        "required": ["content"],
        "properties": {
          "content": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The memory content." },
          "category": { "type": "string", "enum": ["interesting", "system", "manual"], "description": "Memory category. Auto-categorized if not provided." },
          "visibility": { "type": "string", "enum": ["public", "private"], "default": "private", "description": "Visibility level." },
          "tags": { "type": "array", "items": { "type": "string" }, "description": "List of tags." }
        }
      },
      "UpdateMemory": {
        "type": "object",
        "properties": {
          "content": { "type": "string", "minLength": 1, "maxLength": 500, "description": "New memory content." },
          "visibility": { "type": "string", "enum": ["public", "private"], "description": "New visibility level." }
        }
      },
      "BatchCreateMemories": {
        "type": "object",
        "required": ["memories"],
        "properties": {
          "memories": { "type": "array", "items": { "$ref": "#/components/schemas/CreateMemory" }, "maxItems": 25, "description": "List of memories to create (max 25)." }
        }
      },
      "BatchMemoriesResponse": {
        "type": "object",
        "properties": {
          "memories": { "type": "array", "items": { "$ref": "#/components/schemas/Memory" } },
          "created_count": { "type": "integer", "description": "Number of memories created." }
        }
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique identifier." },
          "created_at": { "type": "string", "format": "date-time", "description": "When the conversation record was created." },
          "started_at": { "type": "string", "format": "date-time", "description": "When the conversation started." },
          "finished_at": { "type": "string", "format": "date-time", "description": "When the conversation ended." },
          "language": { "type": "string", "description": "Language code (e.g. `en`)." },
          "source": { "type": "string", "description": "Source device or app." },
          "structured": { "$ref": "#/components/schemas/StructuredData" },
          "transcript_segments": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/TranscriptSegment" },
            "description": "Transcript segments (only present when `include_transcript=true`)."
          },
          "geolocation": { "$ref": "#/components/schemas/Geolocation" },
          "folder_id": { "type": ["string", "null"], "description": "ID of the folder this conversation belongs to, or null if not in any folder." },
          "folder_name": { "type": ["string", "null"], "description": "Display name of the folder, or null if not in any folder." }
        }
      },
      "StructuredData": {
        "type": "object",
        "properties": {
          "title": { "type": "string", "description": "AI-generated title." },
          "overview": { "type": "string", "description": "Summary of the conversation." },
          "emoji": { "type": "string", "description": "Representative emoji." },
          "category": { "type": "string", "description": "Category (work, personal, etc.)." },
          "action_items": { "type": "array", "items": { "$ref": "#/components/schemas/ActionItemSummary" } },
          "events": { "type": "array", "items": { "type": "object" } }
        }
      },
      "ActionItemSummary": {
        "type": "object",
        "properties": {
          "description": { "type": "string" },
          "completed": { "type": "boolean" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "due_at": { "type": ["string", "null"], "format": "date-time" },
          "completed_at": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "TranscriptSegment": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Segment identifier." },
          "text": { "type": "string", "description": "The transcribed text." },
          "speaker_id": { "type": "integer", "description": "Numeric speaker identifier." },
          "speaker_name": { "type": "string", "description": "Human-readable speaker name." },
          "start": { "type": "number", "description": "Start timestamp in seconds." },
          "end": { "type": "number", "description": "End timestamp in seconds." }
        }
      },
      "Geolocation": {
        "type": "object",
        "properties": {
          "latitude": { "type": "number" },
          "longitude": { "type": "number" },
          "address": { "type": "string" },
          "google_place_id": { "type": "string" },
          "location_type": { "type": "string" }
        }
      },
      "CreateConversation": {
        "type": "object",
        "required": ["text"],
        "properties": {
          "text": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "The conversation text/transcript." },
          "text_source": { "type": "string", "enum": ["audio_transcript", "message", "other_text"], "default": "other_text", "description": "Source type." },
          "text_source_spec": { "type": "string", "description": "Additional source info (e.g. `email`, `slack`, `whatsapp`)." },
          "started_at": { "type": "string", "format": "date-time", "description": "When conversation started (defaults to now)." },
          "finished_at": { "type": "string", "format": "date-time", "description": "When conversation finished." },
          "language": { "type": "string", "default": "en", "description": "Language code." },
          "geolocation": { "$ref": "#/components/schemas/GeolocationInput" }
        }
      },
      "CreateConversationFromSegments": {
        "type": "object",
        "required": ["transcript_segments"],
        "properties": {
          "transcript_segments": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": { "$ref": "#/components/schemas/TranscriptSegmentInput" },
            "description": "List of transcript segments (1–500)."
          },
          "source": { "type": "string", "default": "external_integration", "description": "Source of conversation." },
          "started_at": { "type": "string", "format": "date-time", "description": "When conversation started." },
          "finished_at": { "type": "string", "format": "date-time", "description": "When conversation finished." },
          "language": { "type": "string", "default": "en", "description": "Language code." },
          "geolocation": { "$ref": "#/components/schemas/GeolocationInput" }
        }
      },
      "TranscriptSegmentInput": {
        "type": "object",
        "required": ["text", "start", "end"],
        "properties": {
          "text": { "type": "string", "description": "The spoken text." },
          "speaker": { "type": "string", "default": "SPEAKER_00", "description": "Speaker identifier (e.g. `SPEAKER_00`)." },
          "speaker_id": { "type": "integer", "description": "Numeric speaker ID." },
          "is_user": { "type": "boolean", "default": false, "description": "Whether this segment is from the user." },
          "person_id": { "type": "string", "description": "ID of known person speaking." },
          "start": { "type": "number", "description": "Start time in seconds." },
          "end": { "type": "number", "description": "End time in seconds." }
        }
      },
      "GeolocationInput": {
        "type": "object",
        "properties": {
          "latitude": { "type": "number" },
          "longitude": { "type": "number" }
        }
      },
      "UpdateConversation": {
        "type": "object",
        "properties": {
          "title": { "type": "string", "minLength": 1, "maxLength": 500, "description": "New title." },
          "discarded": { "type": "boolean", "description": "Whether the conversation is discarded." }
        }
      },
      "ConversationResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Conversation ID." },
          "status": { "type": "string", "description": "Processing status." },
          "discarded": { "type": "boolean", "description": "Whether the conversation was discarded." }
        }
      },
      "ActionItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique identifier." },
          "description": { "type": "string", "description": "The action item text." },
          "completed": { "type": "boolean", "description": "Whether completed." },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "due_at": { "type": ["string", "null"], "format": "date-time", "description": "Due date (null if not set)." },
          "completed_at": { "type": ["string", "null"], "format": "date-time", "description": "When completed (null if pending)." },
          "conversation_id": { "type": ["string", "null"], "description": "Associated conversation ID." }
        }
      },
      "CreateActionItem": {
        "type": "object",
        "required": ["description"],
        "properties": {
          "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "The action item description." },
          "completed": { "type": "boolean", "default": false, "description": "Whether completed." },
          "due_at": { "type": "string", "format": "date-time", "description": "Due date in ISO 8601 format." }
        }
      },
      "UpdateActionItem": {
        "type": "object",
        "properties": {
          "description": { "type": "string", "minLength": 1, "maxLength": 500, "description": "New description." },
          "completed": { "type": "boolean", "description": "New completion status." },
          "due_at": { "type": "string", "format": "date-time", "description": "New due date." }
        }
      },
      "BatchCreateActionItems": {
        "type": "object",
        "required": ["action_items"],
        "properties": {
          "action_items": { "type": "array", "items": { "$ref": "#/components/schemas/CreateActionItem" }, "maxItems": 50, "description": "List of action items to create (max 50)." }
        }
      },
      "BatchActionItemsResponse": {
        "type": "object",
        "properties": {
          "action_items": { "type": "array", "items": { "$ref": "#/components/schemas/ActionItem" } },
          "created_count": { "type": "integer", "description": "Number of action items created." }
        }
      },
      "ApiKey": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique key identifier." },
          "name": { "type": "string", "description": "Descriptive name." },
          "key_prefix": { "type": "string", "description": "First part of the key (for identification)." },
          "created_at": { "type": "string", "format": "date-time" },
          "last_used_at": { "type": ["string", "null"], "format": "date-time", "description": "When the key was last used." },

          "scopes": {
            "type": ["array", "null"],
            "items": { "type": "string" },
            "description": "Permission scopes assigned to the API key. Null for legacy keys (treated as read-only)."
          }
        }
      },
      "ApiKeyCreated": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "key_prefix": { "type": "string" },
          "key": { "type": "string", "description": "The full API key. **Only returned once during creation.**" },
          "created_at": { "type": "string", "format": "date-time" },
          "last_used_at": { "type": ["string", "null"], "format": "date-time" },

          "scopes": {
            "type": ["array", "null"],
            "items": { "type": "string" },
            "description": "Permission scopes assigned to the API key. Null for legacy keys (treated as read-only)."
          }
        }
      },
      "CreateApiKey": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": { "type": "string", "description": "Descriptive name for the key." },

          "scopes": {
           "type": "array",
           "items": {
             "type": "string",
             "enum": [
               "conversations:read", "conversations:write",
               "memories:read", "memories:write",
               "action_items:read", "action_items:write",
               "goals:read", "goals:write"
              ]
            },
            "description": "Optional scopes to assign. Defaults to read-only (conversations:read, memories:read, action_items:read, goals:read) if not provided."
          }
        }
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" }
        }
      },
      "Folder": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "description": "Unique identifier." },
          "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name of the folder." },
          "description": { "type": ["string", "null"], "maxLength": 500, "description": "Natural language description of what belongs in this folder." },
          "color": { "type": "string", "default": "#6B7280", "description": "Hex color code for the folder." },
          "icon": { "type": "string", "default": "folder", "description": "Emoji or icon identifier for the folder." },
          "created_at": { "type": "string", "format": "date-time", "description": "When the folder was created." },
          "updated_at": { "type": "string", "format": "date-time", "description": "When the folder was last updated." },
          "order": { "type": "integer", "default": 0, "description": "Display order index (lower = earlier)." },
          "is_default": { "type": "boolean", "default": false, "description": "Whether this is the default folder for unassigned conversations." },
          "is_system": { "type": "boolean", "default": false, "description": "True for category-based system folders (Work, Personal, Social)." },
          "category_mapping": { "type": ["string", "null"], "description": "Maps to a CategoryEnum value for backwards compatibility with category-based filtering." },
          "conversation_count": { "type": "integer", "default": 0, "description": "Number of non-discarded conversations in this folder." }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "detail": { "type": "string", "description": "Error description." }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Invalid or missing API key.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "detail": "Invalid API key" }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "detail": "Not found" }
          }
        }
      },
      "ValidationError": {
        "description": "Validation error.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "detail": "Validation error: content is required" }
          }
        }
      }
    }
  }
}