neotoma 0.3.0 → 0.3.2

package/openapi.yaml

@@ -1,2071 +0,0 @@
-openapi: 3.1.0
-info:
-  title: Neotoma API
-  version: 1.0.0
-  description: REST API for Neotoma. Use with any HTTP client, including ChatGPT Actions, Claude, Cursor, MCP servers, CLI tools, and custom integrations.
-servers:
-  - url: https://mcp.neotoma.io
-    description: Set from NEOTOMA_HOST_URL when served by the API; default shown for static/codegen use.
-  - url: http://localhost:8080
-    description: Local development server
-security:
-  - bearerAuth: []
-components:
-  securitySchemes:
-    bearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT or base64url
-      description: |
-        Supported bearer tokens:
-        - MCP OAuth JWT (recommended for CLI and web clients)
-        - base64url-encoded Ed25519 public key (legacy encrypted responses)
-        Optional: Include request signature in Authorization header: "Bearer <public_key> Signature <signature>"
-  schemas:
-    FileUrlResponse:
-      type: object
-      properties:
-        url:
-          type: string
-          description: Signed URL for accessing the file
-    Error:
-      type: object
-      properties:
-        error:
-          type: string
-    ErrorEnvelope:
-      type: object
-      properties:
-        error_code:
-          type: string
-        message:
-          type: string
-        details:
-          type: object
-          additionalProperties: true
-        trace_id:
-          type: string
-        timestamp:
-          type: string
-          format: date-time
-    Entity:
-      type: object
-      properties:
-        id:
-          type: string
-        entity_type:
-          type: string
-        canonical_name:
-          type: string
-        user_id:
-          type: string
-        merged_to_entity_id:
-          type: string
-          nullable: true
-        merged_at:
-          type: string
-          format: date-time
-          nullable: true
-    EntitySnapshot:
-      type: object
-      properties:
-        entity_id:
-          type: string
-        entity_type:
-          type: string
-        schema_version:
-          type: string
-        snapshot:
-          type: object
-          additionalProperties: true
-        raw_fragments:
-          type: object
-          additionalProperties: true
-        provenance:
-          type: object
-          additionalProperties: true
-        computed_at:
-          type: string
-          format: date-time
-        observation_count:
-          type: integer
-        last_observation_at:
-          type: string
-          format: date-time
-    Source:
-      type: object
-      properties:
-        id:
-          type: string
-        content_hash:
-          type: string
-        mime_type:
-          type: string
-        storage_url:
-          type: string
-        file_size:
-          type: integer
-        original_filename:
-          type: string
-        created_at:
-          type: string
-          format: date-time
-        user_id:
-          type: string
-    Observation:
-      type: object
-      properties:
-        id:
-          type: string
-        entity_id:
-          type: string
-        entity_type:
-          type: string
-        schema_version:
-          type: string
-        source_id:
-          type: string
-          nullable: true
-        interpretation_id:
-          type: string
-          nullable: true
-        observed_at:
-          type: string
-          format: date-time
-        specificity_score:
-          type: number
-        source_priority:
-          type: integer
-        fields:
-          type: object
-          additionalProperties: true
-        user_id:
-          type: string
-    RelationshipSnapshot:
-      type: object
-      properties:
-        relationship_key:
-          type: string
-        relationship_type:
-          type: string
-        source_entity_id:
-          type: string
-        target_entity_id:
-          type: string
-        schema_version:
-          type: string
-        snapshot:
-          type: object
-          additionalProperties: true
-        computed_at:
-          type: string
-          format: date-time
-        observation_count:
-          type: integer
-        last_observation_at:
-          type: string
-          format: date-time
-        provenance:
-          type: object
-          additionalProperties: true
-        user_id:
-          type: string
-    TimelineEvent:
-      type: object
-      properties:
-        id:
-          type: string
-        event_type:
-          type: string
-        event_timestamp:
-          type: string
-          format: date-time
-        source_id:
-          type: string
-        entity_ids:
-          type: array
-          items:
-            type: string
-        properties:
-          type: object
-          additionalProperties: true
-    EntitySchema:
-      type: object
-      properties:
-        entity_type:
-          type: string
-        schema_version:
-          type: string
-        field_names:
-          type: array
-          items:
-            type: string
-        field_summary:
-          type: object
-          additionalProperties: true
-    Interpretation:
-      type: object
-      properties:
-        id:
-          type: string
-        source_id:
-          type: string
-        status:
-          type: string
-        created_at:
-          type: string
-          format: date-time
-        completed_at:
-          type: string
-          format: date-time
-    Stats:
-      type: object
-      properties:
-        entities:
-          type: integer
-        sources:
-          type: integer
-        observations:
-          type: integer
-        relationships:
-          type: integer
-        timeline_events:
-          type: integer
-    StoreRequest:
-      type: object
-      properties:
-        entities:
-          type: array
-          items:
-            type: object
-            additionalProperties: true
-        relationships:
-          type: array
-          description: |
-            Optional. Create relationships between entities in this request. Indices refer to the entities array (0-based).
-          items:
-            type: object
-            required: [relationship_type, source_index, target_index]
-            properties:
-              relationship_type:
-                type: string
-                enum: [PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF, DEPENDS_ON, SUPERSEDES, EMBEDS, works_at, owns, manages, part_of, related_to, depends_on, references, transacted_with, member_of, reports_to, located_at, created_by, funded_by, acquired_by, subsidiary_of, partner_of, competitor_of, supplies_to, contracted_with, invested_in]
-              source_index:
-                type: integer
-                minimum: 0
-              target_index:
-                type: integer
-                minimum: 0
-        source_priority:
-          type: integer
-        idempotency_key:
-          type: string
-          description: Required for structured path, optional for unstructured-only path.
-        file_idempotency_key:
-          type: string
-          description: Optional idempotency key for file path when sending structured + unstructured in one call.
-        file_content:
-          type: string
-          description: Base64-encoded file content (unstructured path)
-        file_path:
-          type: string
-          description: Local file path for server-local environments
-        mime_type:
-          type: string
-          description: Required with file_content, optional with file_path
-        original_filename:
-          type: string
-        interpret:
-          type: boolean
-          default: true
-        interpretation_config:
-          type: object
-          additionalProperties: true
-        user_id:
-          type: string
-      description: Unified store payload. Supports structured only, unstructured only, or both in one request.
-    StoreResponse:
-      type: object
-      properties:
-        structured:
-          $ref: '#/components/schemas/StoreStructuredResponse'
-        unstructured:
-          $ref: '#/components/schemas/StoreUnstructuredResponse'
-    StoreStructuredRequest:
-      type: object
-      required: [entities, idempotency_key]
-      properties:
-        entities:
-          type: array
-          items:
-            type: object
-            additionalProperties: true
-        relationships:
-          type: array
-          description: |
-            Optional. Create relationships between entities in this request. Indices refer to the entities array (0-based).
-            Enables one-call chat persistence: store [conversation, agent_message] with relationships [{ relationship_type: "PART_OF", source_index: 1, target_index: 0 }].
-          items:
-            type: object
-            required: [relationship_type, source_index, target_index]
-            properties:
-              relationship_type:
-                type: string
-                enum: [PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF, DEPENDS_ON, SUPERSEDES, EMBEDS, works_at, owns, manages, part_of, related_to, depends_on, references, transacted_with, member_of, reports_to, located_at, created_by, funded_by, acquired_by, subsidiary_of, partner_of, competitor_of, supplies_to, contracted_with, invested_in]
-              source_index:
-                type: integer
-                minimum: 0
-                description: Index into the entities array for the source entity
-              target_index:
-                type: integer
-                minimum: 0
-                description: Index into the entities array for the target entity
-        source_priority:
-          type: integer
-        idempotency_key:
-          type: string
-        user_id:
-          type: string
-        original_filename:
-          type: string
-          description: |
-            Optional. For agent-provided structured data, omit so the source has no filename (null).
-            Pass only when mirroring a real file name or when a display label is desired.
-    StoreStructuredResponse:
-      type: object
-      properties:
-        success:
-          type: boolean
-        entities:
-          type: array
-          items:
-            type: object
-            properties:
-              entity_id:
-                type: string
-              entity_type:
-                type: string
-              observation_id:
-                type: string
-    StoreUnstructuredRequest:
-      type: object
-      required: [file_content, mime_type]
-      properties:
-        file_content:
-          type: string
-          description: Base64-encoded file content
-        mime_type:
-          type: string
-          description: MIME type of the file
-        idempotency_key:
-          type: string
-          description: Optional idempotency key; if omitted, content hash is used
-        original_filename:
-          type: string
-        interpret:
-          type: boolean
-          default: true
-          description: Run AI interpretation after store
-        user_id:
-          type: string
-          format: uuid
-    StoreUnstructuredResponse:
-      type: object
-      properties:
-        source_id:
-          type: string
-        content_hash:
-          type: string
-        file_size:
-          type: integer
-        deduplicated:
-          type: boolean
-        interpretation:
-          type: object
-          additionalProperties: true
-        entity_ids:
-          type: array
-          items:
-            type: string
-    GetRelationshipSnapshotRequest:
-      type: object
-      required: [relationship_type, source_entity_id, target_entity_id]
-      properties:
-        relationship_type:
-          type: string
-          enum: [PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF, DEPENDS_ON, SUPERSEDES, EMBEDS, works_at, owns, manages, part_of, related_to, depends_on, references, transacted_with, member_of, reports_to, located_at, created_by, funded_by, acquired_by, subsidiary_of, partner_of, competitor_of, supplies_to, contracted_with, invested_in]
-        source_entity_id:
-          type: string
-        target_entity_id:
-          type: string
-    GetRelationshipSnapshotResponse:
-      type: object
-      required: [snapshot, observations]
-      properties:
-        snapshot:
-          $ref: '#/components/schemas/RelationshipSnapshot'
-        observations:
-          type: array
-          items:
-            type: object
-            properties:
-              id: { type: string }
-              source_id: { type: string }
-              observed_at: { type: string }
-              specificity_score: { type: number }
-              source_priority: { type: number }
-              metadata: { type: object }
-    OAuthInitiateRequest:
-      type: object
-      required: [connection_id]
-      properties:
-        connection_id:
-          type: string
-        client_name:
-          type: string
-        redirect_uri:
-          type: string
-    OAuthInitiateResponse:
-      type: object
-      properties:
-        auth_url:
-          type: string
-        connection_id:
-          type: string
-        expires_at:
-          type: string
-          format: date-time
-    OAuthStatusResponse:
-      type: object
-      properties:
-        status:
-          type: string
-        connection_id:
-          type: string
-paths:
-  /get_file_url:
-    get:
-      summary: Get signed file URL
-      description: Provide a storage path like "files/<source_id>/<filename>".
-      operationId: getFileUrl
-      parameters:
-        - in: query
-          name: file_path
-          required: true
-          schema: { type: string }
-        - in: query
-          name: expires_in
-          required: false
-          schema: { type: integer }
-      responses:
-        '200':
-          description: Signed URL
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/FileUrlResponse'
-        '400':
-          description: Invalid parameters
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/Error' }
-        '401':
-          description: Missing or invalid bearer token
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/Error' }
-
-  /health:
-    get:
-      summary: Health check
-      operationId: healthCheck
-      security: []
-      responses:
-        '200':
-          description: Server is healthy
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  ok:
-                    type: boolean
-
-  /openapi.yaml:
-    get:
-      summary: Get OpenAPI specification
-      operationId: getOpenApiSpec
-      security: []
-      responses:
-        '200':
-          description: OpenAPI specification in YAML
-          content:
-            application/yaml:
-              schema:
-                type: string
-
-  /server-info:
-    get:
-      summary: Get server info
-      operationId: getServerInfo
-      responses:
-        '200':
-          description: Server info
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /mcp/oauth/initiate:
-    post:
-      summary: Initiate MCP OAuth flow
-      operationId: mcpOAuthInitiate
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: { $ref: '#/components/schemas/OAuthInitiateRequest' }
-      responses:
-        '200':
-          description: OAuth initiation result
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/OAuthInitiateResponse' }
-        '400':
-          description: Invalid request
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/ErrorEnvelope' }
-
-  /mcp/oauth/authorize:
-    get:
-      summary: OAuth authorization endpoint
-      operationId: mcpOAuthAuthorize
-      parameters:
-        - in: query
-          name: redirect_uri
-          required: true
-          schema: { type: string }
-        - in: query
-          name: state
-          required: true
-          schema: { type: string }
-        - in: query
-          name: code_challenge
-          required: true
-          schema: { type: string }
-        - in: query
-          name: code_challenge_method
-          required: true
-          schema: { type: string }
-        - in: query
-          name: client_id
-          required: false
-          schema: { type: string }
-        - in: query
-          name: dev_stub
-          required: false
-          schema: { type: string }
-      responses:
-        '302':
-          description: Redirect to authorization URL
-
-  /mcp/oauth/token:
-    post:
-      summary: OAuth token exchange
-      operationId: mcpOAuthToken
-      requestBody:
-        required: true
-        content:
-          application/x-www-form-urlencoded:
-            schema:
-              type: object
-              properties:
-                grant_type:
-                  type: string
-                code:
-                  type: string
-      responses:
-        '200':
-          description: OAuth token response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  access_token:
-                    type: string
-                  token_type:
-                    type: string
-                  expires_in:
-                    type: integer
-        '400':
-          description: Token exchange error
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /me:
-    get:
-      summary: Get current authenticated user
-      operationId: getMe
-      responses:
-        '200':
-          description: Current user details
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  user_id:
-                    type: string
-                  email:
-                    type: string
-                  storage:
-                    type: object
-                    properties:
-                      storage_backend:
-                        type: string
-                        enum: [local]
-                      data_dir:
-                        type: string
-                      sqlite_db:
-                        type: string
-        '401':
-          description: Not authenticated
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/Error' }
-
-  /mcp/oauth/status:
-    get:
-      summary: Get OAuth connection status
-      operationId: mcpOAuthStatus
-      parameters:
-        - in: query
-          name: connection_id
-          required: true
-          schema: { type: string }
-      responses:
-        '200':
-          description: Connection status
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/OAuthStatusResponse' }
-        '400':
-          description: Invalid request
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/ErrorEnvelope' }
-
-  /mcp/oauth/connections:
-    get:
-      summary: List OAuth connections
-      operationId: mcpOAuthListConnections
-      responses:
-        '200':
-          description: Connection list
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  connections:
-                    type: array
-                    items:
-                      type: object
-                      additionalProperties: true
-        '401':
-          description: Unauthorized
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/Error' }
-
-  /mcp/oauth/connections/{connection_id}:
-    delete:
-      summary: Revoke OAuth connection
-      operationId: mcpOAuthRevokeConnection
-      parameters:
-        - in: path
-          name: connection_id
-          required: true
-          schema: { type: string }
-      responses:
-        '200':
-          description: Revoked
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  success:
-                    type: boolean
-
-  /.well-known/oauth-authorization-server:
-    get:
-      summary: OAuth 2.0 Authorization Server Metadata (RFC 8414)
-      operationId: oauthServerMetadata
-      responses:
-        '200':
-          description: Authorization server metadata
-          content:
-            application/json:
-              schema:
-                type: object
-
-  /.well-known/oauth-protected-resource:
-    get:
-      summary: OAuth 2.0 Protected Resource Metadata
-      operationId: oauthProtectedResource
-      responses:
-        '200':
-          description: Protected resource metadata
-          content:
-            application/json:
-              schema:
-                type: object
-
-  /mcp/oauth/callback:
-    get:
-      summary: OAuth callback endpoint
-      operationId: mcpOAuthCallback
-      parameters:
-        - in: query
-          name: code
-          schema: { type: string }
-        - in: query
-          name: state
-          schema: { type: string }
-      responses:
-        '302':
-          description: Redirect after OAuth callback
-
-  /mcp/oauth/key-auth:
-    get:
-      summary: Key-based authorization page (GET)
-      operationId: mcpOAuthKeyAuthGet
-      parameters:
-        - in: query
-          name: next
-          schema: { type: string }
-      responses:
-        '200':
-          description: Key auth HTML page
-          content:
-            text/html:
-              schema: { type: string }
-    post:
-      summary: Key-based authorization submission (POST)
-      operationId: mcpOAuthKeyAuthPost
-      requestBody:
-        content:
-          application/x-www-form-urlencoded:
-            schema:
-              type: object
-              properties:
-                next:
-                  type: string
-                key:
-                  type: string
-      responses:
-        '302':
-          description: Redirect after key auth
-
-  /mcp/oauth/local-login:
-    get:
-      summary: Local login for development (auto-creates dev user)
-      operationId: mcpOAuthLocalLogin
-      responses:
-        '302':
-          description: Redirect after local login
-
-  /mcp/oauth/register:
-    post:
-      summary: Dynamic Client Registration (RFC 7591)
-      operationId: mcpOAuthRegister
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                client_name:
-                  type: string
-                redirect_uris:
-                  type: array
-                  items: { type: string }
-      responses:
-        '201':
-          description: Client registered
-          content:
-            application/json:
-              schema:
-                type: object
-
-  /mcp/oauth/authorization-details:
-    get:
-      summary: Authorization details proxy
-      operationId: mcpOAuthAuthorizationDetails
-      responses:
-        '200':
-          description: Authorization details
-          content:
-            application/json:
-              schema:
-                type: object
-
-  /auth/dev-signin:
-    post:
-      summary: Dev-only sign-in endpoint (development mode only)
-      operationId: devSignIn
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                email:
-                  type: string
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Signed in
-          content:
-            application/json:
-              schema:
-                type: object
-
-  /entities/query:
-    post:
-      summary: Query entities
-      operationId: queryEntities
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                entity_type:
-                  type: string
-                search:
-                  type: string
-                limit:
-                  type: integer
-                offset:
-                  type: integer
-                include_merged:
-                  type: boolean
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Entity list
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  entities:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/EntitySnapshot'
-                  total:
-                    type: integer
-                  limit:
-                    type: integer
-                  offset:
-                    type: integer
-
-  /entities/{id}:
-    get:
-      summary: Get entity by ID
-      operationId: getEntityById
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema: { type: string }
-      responses:
-        '200':
-          description: Entity
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/EntitySnapshot' }
-        '404':
-          description: Entity not found
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/ErrorEnvelope' }
-
-  /entities/{id}/observations:
-    get:
-      summary: List observations for entity
-      operationId: getEntityObservations
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema: { type: string }
-      responses:
-        '200':
-          description: Observations
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  observations:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Observation'
-
-  /entities/{id}/relationships:
-    get:
-      summary: List relationships for entity
-      operationId: getEntityRelationships
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema: { type: string }
-      responses:
-        '200':
-          description: Relationships
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  relationships:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/RelationshipSnapshot'
-
-  /entities/merge:
-    post:
-      summary: Merge duplicate entities
-      operationId: mergeEntities
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                from_entity_id:
-                  type: string
-                to_entity_id:
-                  type: string
-                merge_reason:
-                  type: string
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Merge result
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  observations_moved:
-                    type: integer
-                  merged_at:
-                    type: string
-                    format: date-time
-
-  /sources:
-    get:
-      summary: List sources
-      operationId: listSources
-      parameters:
-        - in: query
-          name: user_id
-          required: false
-          schema: { type: string }
-        - in: query
-          name: search
-          required: false
-          schema: { type: string }
-        - in: query
-          name: mime_type
-          required: false
-          schema: { type: string }
-        - in: query
-          name: source_type
-          required: false
-          schema: { type: string }
-        - in: query
-          name: limit
-          required: false
-          schema: { type: integer }
-        - in: query
-          name: offset
-          required: false
-          schema: { type: integer }
-      responses:
-        '200':
-          description: Sources
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  sources:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Source'
-
-  /sources/{id}:
-    get:
-      summary: Get source by ID
-      operationId: getSourceById
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema: { type: string }
-      responses:
-        '200':
-          description: Source
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/Source' }
-
-  /observations:
-    get:
-      summary: List observations
-      operationId: listObservations
-      parameters:
-        - in: query
-          name: user_id
-          required: false
-          schema: { type: string }
-        - in: query
-          name: source_id
-          required: false
-          schema: { type: string }
-        - in: query
-          name: entity_id
-          required: false
-          schema: { type: string }
-        - in: query
-          name: limit
-          required: false
-          schema: { type: integer }
-        - in: query
-          name: offset
-          required: false
-          schema: { type: integer }
-      responses:
-        '200':
-          description: Observations
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  observations:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Observation'
-
-  /observations/query:
-    post:
-      summary: Query observations
-      operationId: queryObservations
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                entity_id:
-                  type: string
-                entity_type:
-                  type: string
-                limit:
-                  type: integer
-                offset:
-                  type: integer
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Observations
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  observations:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Observation'
-                  total:
-                    type: integer
-                  limit:
-                    type: integer
-                  offset:
-                    type: integer
-
-  /observations/create:
-    post:
-      summary: Create observation
-      operationId: createObservation
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              additionalProperties: true
-      responses:
-        '200':
-          description: Observation created
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /relationships:
-    get:
-      summary: List relationships
-      operationId: listRelationships
-      responses:
-        '200':
-          description: Relationships
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  relationships:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/RelationshipSnapshot'
-
-  /relationships/{id}:
-    get:
-      summary: Get relationship by ID
-      operationId: getRelationshipById
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema: { type: string }
-      responses:
-        '200':
-          description: Relationship
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/RelationshipSnapshot' }
-
-  /relationships/snapshot:
-    post:
-      summary: Get relationship snapshot with provenance
-      operationId: getRelationshipSnapshot
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: { $ref: '#/components/schemas/GetRelationshipSnapshotRequest' }
-      responses:
-        '200':
-          description: Relationship snapshot and observations
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/GetRelationshipSnapshotResponse' }
-
-  /timeline:
-    get:
-      summary: List timeline events
-      operationId: listTimeline
-      parameters:
-        - in: query
-          name: start_date
-          required: false
-          schema: { type: string }
-        - in: query
-          name: end_date
-          required: false
-          schema: { type: string }
-        - in: query
-          name: event_type
-          required: false
-          schema: { type: string }
-        - in: query
-          name: user_id
-          required: false
-          schema: { type: string }
-        - in: query
-          name: limit
-          required: false
-          schema: { type: integer }
-        - in: query
-          name: offset
-          required: false
-          schema: { type: integer }
-      responses:
-        '200':
-          description: Timeline events
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  events:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/TimelineEvent'
-
-  /timeline/{id}:
-    get:
-      summary: Get timeline event by ID
-      operationId: getTimelineById
-      parameters:
-        - in: path
-          name: id
-          required: true
-          schema: { type: string }
-        - in: query
-          name: user_id
-          required: false
-          schema: { type: string }
-      responses:
-        '200':
-          description: Timeline event
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  event:
-                    $ref: '#/components/schemas/TimelineEvent'
-
-  /schemas:
-    get:
-      summary: List entity schemas
-      operationId: listSchemas
-      parameters:
-        - in: query
-          name: user_id
-          required: false
-          schema: { type: string }
-      responses:
-        '200':
-          description: Schemas
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  schemas:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/EntitySchema'
-
-  /schemas/{entity_type}:
-    get:
-      summary: Get schema by entity type
-      operationId: getSchemaByEntityType
-      parameters:
-        - in: path
-          name: entity_type
-          required: true
-          schema: { type: string }
-      responses:
-        '200':
-          description: Schema
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/EntitySchema' }
-
-  /interpretations:
-    get:
-      summary: List interpretations
-      operationId: listInterpretations
-      parameters:
-        - in: query
-          name: user_id
-          required: false
-          schema: { type: string }
-        - in: query
-          name: source_id
-          required: false
-          schema: { type: string }
-        - in: query
-          name: limit
-          required: false
-          schema: { type: integer }
-        - in: query
-          name: offset
-          required: false
-          schema: { type: integer }
-      responses:
-        '200':
-          description: Interpretations
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  interpretations:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Interpretation'
-
-  /stats:
-    get:
-      summary: Get dashboard stats
-      operationId: getStats
-      parameters:
-        - in: query
-          name: user_id
-          required: false
-          schema: { type: string }
-      responses:
-        '200':
-          description: Stats
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/Stats' }
-
-  /store:
-    post:
-      summary: Store structured entities, unstructured files, or both
-      operationId: storeStructured
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: { $ref: '#/components/schemas/StoreRequest' }
-      responses:
-        '200':
-          description: Store result
-          content:
-            application/json:
-              schema:
-                oneOf:
-                  - { $ref: '#/components/schemas/StoreStructuredResponse' }
-                  - { $ref: '#/components/schemas/StoreUnstructuredResponse' }
-                  - { $ref: '#/components/schemas/StoreResponse' }
-
-  /store/unstructured:
-    post:
-      summary: Store unstructured file (raw upload with optional AI interpretation)
-      operationId: storeUnstructured
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema: { $ref: '#/components/schemas/StoreUnstructuredRequest' }
-      responses:
-        '200':
-          description: Store result with source_id and optional interpretation
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/StoreUnstructuredResponse' }
-
-  /get_entity_snapshot:
-    post:
-      summary: Get entity snapshot with provenance
-      operationId: getEntitySnapshot
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                entity_id:
-                  type: string
-      responses:
-        '200':
-          description: Entity snapshot
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/EntitySnapshot' }
-
-  /list_observations:
-    post:
-      summary: List observations for entity
-      operationId: listObservationsForEntity
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                entity_id:
-                  type: string
-                limit:
-                  type: integer
-                offset:
-                  type: integer
-      responses:
-        '200':
-          description: Observations
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  observations:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Observation'
-
-  /get_field_provenance:
-    post:
-      summary: Get field provenance
-      operationId: getFieldProvenance
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                entity_id:
-                  type: string
-                field:
-                  type: string
-      responses:
-        '200':
-          description: Provenance
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /create_relationship:
-    post:
-      summary: Create relationship
-      operationId: createRelationship
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              additionalProperties: true
-      responses:
-        '200':
-          description: Relationship created
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/RelationshipSnapshot' }
-
-  /list_relationships:
-    post:
-      summary: List relationships
-      operationId: listRelationshipsForEntity
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              additionalProperties: true
-      responses:
-        '200':
-          description: Relationships
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  relationships:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/RelationshipSnapshot'
-
-  /retrieve_entity_by_identifier:
-    post:
-      summary: Retrieve entity by identifier
-      description: Search for entity by name, email, or other identifier
-      operationId: retrieveEntityByIdentifier
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - identifier
-              properties:
-                identifier:
-                  type: string
-                  description: Identifier to search for (name, email, etc.)
-                entity_type:
-                  type: string
-                  description: Optional entity type to limit search
-      responses:
-        '200':
-          description: Entity search results
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  entities:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/Entity'
-                  total:
-                    type: integer
-        '400':
-          description: Invalid request
-          content:
-            application/json:
-              schema: { $ref: '#/components/schemas/ErrorEnvelope' }
-
-  /retrieve_related_entities:
-    post:
-      summary: Retrieve related entities
-      description: Get entities connected via relationships with n-hop traversal support
-      operationId: retrieveRelatedEntities
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - entity_id
-              properties:
-                entity_id:
-                  type: string
-                relationship_types:
-                  type: array
-                  items:
-                    type: string
-                direction:
-                  type: string
-                  enum: [inbound, outbound, both]
-                  default: both
-                max_hops:
-                  type: integer
-                  default: 1
-                include_entities:
-                  type: boolean
-                  default: true
-      responses:
-        '200':
-          description: Related entities
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /retrieve_graph_neighborhood:
-    post:
-      summary: Retrieve graph neighborhood
-      description: Get complete graph neighborhood including entities, relationships, sources, and events
-      operationId: retrieveGraphNeighborhood
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - node_id
-              properties:
-                node_id:
-                  type: string
-                node_type:
-                  type: string
-                  enum: [entity, source]
-                  default: entity
-                include_relationships:
-                  type: boolean
-                  default: true
-                include_sources:
-                  type: boolean
-                  default: true
-                include_events:
-                  type: boolean
-                  default: true
-                include_observations:
-                  type: boolean
-                  default: false
-      responses:
-        '200':
-          description: Graph neighborhood
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /delete_entity:
-    post:
-      summary: Delete entity
-      description: Soft delete entity (creates deletion observation, reversible)
-      operationId: deleteEntity
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - entity_id
-                - entity_type
-              properties:
-                entity_id:
-                  type: string
-                entity_type:
-                  type: string
-                reason:
-                  type: string
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Entity deleted
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /restore_entity:
-    post:
-      summary: Restore entity
-      description: Restore a soft-deleted entity
-      operationId: restoreEntity
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - entity_id
-                - entity_type
-              properties:
-                entity_id:
-                  type: string
-                entity_type:
-                  type: string
-                reason:
-                  type: string
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Entity restored
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /delete_relationship:
-    post:
-      summary: Delete relationship
-      description: Soft delete relationship (creates deletion observation, reversible)
-      operationId: deleteRelationship
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - relationship_type
-                - source_entity_id
-                - target_entity_id
-              properties:
-                relationship_type:
-                  type: string
-                  enum: [PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF, DEPENDS_ON, SUPERSEDES, EMBEDS, works_at, owns, manages, part_of, related_to, depends_on, references, transacted_with, member_of, reports_to, located_at, created_by, funded_by, acquired_by, subsidiary_of, partner_of, competitor_of, supplies_to, contracted_with, invested_in]
-                source_entity_id:
-                  type: string
-                target_entity_id:
-                  type: string
-                reason:
-                  type: string
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Relationship deleted
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /restore_relationship:
-    post:
-      summary: Restore relationship
-      description: Restore a soft-deleted relationship
-      operationId: restoreRelationship
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - relationship_type
-                - source_entity_id
-                - target_entity_id
-              properties:
-                relationship_type:
-                  type: string
-                  enum: [PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF, DEPENDS_ON, SUPERSEDES, EMBEDS, works_at, owns, manages, part_of, related_to, depends_on, references, transacted_with, member_of, reports_to, located_at, created_by, funded_by, acquired_by, subsidiary_of, partner_of, competitor_of, supplies_to, contracted_with, invested_in]
-                source_entity_id:
-                  type: string
-                target_entity_id:
-                  type: string
-                reason:
-                  type: string
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Relationship restored
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /analyze_schema_candidates:
-    post:
-      summary: Analyze schema candidates
-      description: Analyze raw_fragments to identify fields for schema promotion
-      operationId: analyzeSchemaCandidates
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                entity_type:
-                  type: string
-                user_id:
-                  type: string
-                min_frequency:
-                  type: integer
-                  default: 5
-                min_confidence:
-                  type: number
-                  default: 0.8
-      responses:
-        '200':
-          description: Schema candidates
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /get_schema_recommendations:
-    post:
-      summary: Get schema recommendations
-      description: Get schema update recommendations from raw_fragments analysis
-      operationId: getSchemaRecommendations
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - entity_type
-              properties:
-                entity_type:
-                  type: string
-                user_id:
-                  type: string
-                source:
-                  type: string
-                  enum: [raw_fragments, agent, inference, all]
-                status:
-                  type: string
-                  enum: [pending, approved, rejected]
-      responses:
-        '200':
-          description: Schema recommendations
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /update_schema_incremental:
-    post:
-      summary: Update schema incrementally
-      description: Add new fields to existing schema
-      operationId: updateSchemaIncremental
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - entity_type
-                - fields_to_add
-              properties:
-                entity_type:
-                  type: string
-                fields_to_add:
-                  type: array
-                  items:
-                    type: object
-                    required:
-                      - field_name
-                      - field_type
-                    properties:
-                      field_name:
-                        type: string
-                      field_type:
-                        type: string
-                        enum: [string, number, date, boolean, array, object]
-                      required:
-                        type: boolean
-                        default: false
-                      reducer_strategy:
-                        type: string
-                        enum: [last_write, highest_priority, most_specific, merge_array]
-                schema_version:
-                  type: string
-                user_specific:
-                  type: boolean
-                  default: false
-                user_id:
-                  type: string
-                activate:
-                  type: boolean
-                  default: true
-                migrate_existing:
-                  type: boolean
-                  default: false
-      responses:
-        '200':
-          description: Schema updated
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /register_schema:
-    post:
-      summary: Register schema
-      description: Register a new schema or schema version
-      operationId: registerSchema
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - entity_type
-                - schema_definition
-                - reducer_config
-              properties:
-                entity_type:
-                  type: string
-                schema_definition:
-                  type: object
-                  additionalProperties: true
-                reducer_config:
-                  type: object
-                  additionalProperties: true
-                schema_version:
-                  type: string
-                  default: "1.0"
-                user_specific:
-                  type: boolean
-                  default: false
-                user_id:
-                  type: string
-                activate:
-                  type: boolean
-                  default: false
-      responses:
-        '200':
-          description: Schema registered
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /reinterpret:
-    post:
-      summary: Reinterpret source
-      description: Re-run AI interpretation on existing source
-      operationId: reinterpret
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - source_id
-              properties:
-                source_id:
-                  type: string
-                interpretation_config:
-                  type: object
-                  additionalProperties: true
-      responses:
-        '200':
-          description: Source reinterpreted
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /interpret-uninterpreted:
-    post:
-      summary: Interpret uninterpreted sources
-      description: Re-run AI interpretation for sources that have no prior interpretation runs
-      operationId: interpretUninterpreted
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                limit:
-                  type: integer
-                  minimum: 1
-                  maximum: 100
-                  default: 50
-                dry_run:
-                  type: boolean
-                  default: false
-                user_id:
-                  type: string
-                interpretation_config:
-                  type: object
-                  additionalProperties: true
-      responses:
-        '200':
-          description: Uninterpreted sources processed
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /correct:
-    post:
-      summary: Create correction
-      description: Create high-priority correction observation
-      operationId: correct
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              required:
-                - entity_id
-                - entity_type
-                - field
-                - value
-                - idempotency_key
-              properties:
-                entity_id:
-                  type: string
-                entity_type:
-                  type: string
-                field:
-                  type: string
-                value: {}
-                idempotency_key:
-                  type: string
-                user_id:
-                  type: string
-      responses:
-        '200':
-          description: Correction created
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-
-  /get_authenticated_user:
-    post:
-      summary: Get authenticated user
-      description: Get authenticated user ID for current session
-      operationId: getAuthenticatedUser
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              type: object
-      responses:
-        '200':
-          description: User ID
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  user_id:
-                    type: string
-                  storage:
-                    type: object
-                    properties:
-                      storage_backend:
-                        type: string
-                        enum: [local]
-                      data_dir:
-                        type: string
-                      sqlite_db:
-                        type: string
-
-  /health_check_snapshots:
-    post:
-      summary: Health check snapshots
-      description: Check for stale entity snapshots
-      operationId: healthCheckSnapshots
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              type: object
-              properties:
-                auto_fix:
-                  type: boolean
-                  default: false
-      responses:
-        '200':
-          description: Health check results
-          content:
-            application/json:
-              schema:
-                type: object
-                additionalProperties: true
-