studiomeyer-io Search API

openapi: 3.2.0
info:
  title: StudioMeyer Memory REST Search API
  version: 3.47.0
  description: Tenant Memory data API. This specification covers search, learning, decisions, entities, account information, export, backfill and public API discovery. Signup, import, billing, admin, license and OAuth flows and MCP JSON-RPC are not described here. Bearer keys provide the operations available to the account; separate read/write OAuth permissions are not implemented. Send JSON bodies of at most 1 MiB. Use the exact documented paths without appended query parameters.
servers:
- url: https://memory.studiomeyer.io
security:
- bearerAuth: []
- oauth2:
  - memory
tags:
- name: Search
paths:
  /api/search:
    post:
      operationId: searchMemory
      summary: Search the authenticated account memory
      description: Free accounts use unified search without paid agentic search or reranking. Paid accounts use agentic search unless agentic is false. Exact tags match all requested tags on learning, decision and skill records. An empty or whitespace-only query is allowed only with tags. Tags must be non-blank and contain no NUL characters. Tagged requests require limit from 1 to 100 and rerankTopK from 3 to 20 when supplied. Search normally reinforces retrieved memories. readOnly=true or trackUsage=false suppresses these incidental writes only when tags are supplied; these options are not OAuth access permissions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchInput'
      responses:
        '200':
          description: Matching memories and optional retrieval metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Invalid input or secret detected in submitted content.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing, invalid or expired Bearer key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Account email is unverified or the tenant is inactive.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Daily API quota or stored-data limit reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Search
components:
  schemas:
    SearchInput:
      type: object
      properties:
        query:
          type: string
        project:
          type: string
        agentId:
          type: string
        tags:
          type: array
          items:
            type: string
            minLength: 1
            maxLength: 200
            x-max-utf16-code-units: 200
            description: Non-blank exact tag, no NUL characters. Maximum 200 UTF-16 code units as enforced by the server; astral characters such as emoji count as two units. JSON Schema maxLength counts Unicode characters and cannot enforce this additional JavaScript length bound by itself.
            allOf:
            - pattern: \S
            - pattern: ^[^\u0000]*$
          minItems: 1
          maxItems: 20
        limit:
          type: integer
        types:
          type: array
          items:
            type: string
            enum:
            - decision
            - learning
            - session
            - skill
            - evolution
            - entity
        recencyWeight:
          type: number
        memoryType:
          type: string
          enum:
          - episodic
          - semantic
          - all
        agentic:
          type: boolean
        rerank:
          type: boolean
        rerankTopK:
          type: integer
        asOf:
          type: string
          format: date-time
        dateRangeStart:
          type: string
          description: ISO date or date-time; used together with dateRangeEnd.
        dateRangeEnd:
          type: string
          description: ISO date or date-time. Date-only values include the full UTC day.
        expand:
          type: boolean
        noiseFilter:
          type: boolean
        includeArchived:
          type: boolean
        includeEphemeral:
          type: boolean
        readOnly:
          type: boolean
        trackUsage:
          type: boolean
      required:
      - query
      allOf:
      - if:
          required:
          - tags
        then:
          properties:
            limit:
              type: integer
              minimum: 1
              maximum: 100
            rerankTopK:
              type: integer
              minimum: 3
              maximum: 20
        else:
          properties:
            query:
              type: string
              pattern: \S
    SearchResult:
      type: object
      properties:
        type:
          type: string
          enum:
          - decision
          - learning
          - session
          - skill
          - evolution
          - entity
        id:
          type: string
        date:
          type: string
          format: date-time
        content:
          type: string
        category:
          type: string
        project:
          type:
          - string
          - 'null'
        tags:
          type: array
          items:
            type: string
        relevance:
          type: number
        recency:
          type: number
        rank:
          type: number
        matchMethod:
          type: string
        confidence:
          type: number
        verified:
          type: boolean
        rrfScore:
          type: number
        importanceScore:
          type: number
        lifecycleState:
          type: string
        agentId:
          type: string
        validFrom:
          type: string
          format: date-time
        validTo:
          type:
          - string
          - 'null'
          format: date-time
        ingestedAt:
          type: string
          format: date-time
        superseded:
          type: boolean
        memoryType:
          type: string
          enum:
          - episodic
          - semantic
        explanation:
          type: object
          additionalProperties: true
      required:
      - type
      - id
      - date
      - content
      - relevance
      - recency
      - rank
      - matchMethod
    SearchResponse:
      type: object
      properties:
        success:
          const: true
        count:
          type: integer
        abstain:
          type: boolean
        answerConfidence:
          type: number
        abstainNote:
          type: string
        rerankProvider:
          type: string
        rerankMs:
          type: number
        tagFilter:
          type: object
          properties:
            tags:
              type: array
              items:
                type: string
            match:
              const: all
            supportedTypes:
              type: array
              items:
                type: string
                enum:
                - learning
                - decision
                - skill
          required:
          - tags
          - match
          - supportedTypes
        queryExpansion:
          type: object
          properties:
            subQueries:
              type: array
              items:
                type: string
            isListQuery:
              type: boolean
            isTemporalComputation:
              type: boolean
            expandedKeywords:
              type: array
              items:
                type: string
          required:
          - subQueries
          - isListQuery
          - isTemporalComputation
          - expandedKeywords
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
      required:
      - success
      - count
      - abstain
      - results
    Error:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
        code:
          type: string
        plan:
          type: string
        upgrade:
          type: string
        observation:
          type: string
      required:
      - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Tenant API key in the Authorization header.
    oauth2:
      type: oauth2
      description: OAuth 2.1 authorization code with PKCE (S256). The memory scope grants full account access; separate read/write permissions are not implemented.
      flows:
        authorizationCode:
          authorizationUrl: https://memory.studiomeyer.io/authorize
          tokenUrl: https://memory.studiomeyer.io/token
          scopes:
            memory: Full access to the authenticated account memory operations.
externalDocs:
  description: Public REST endpoint inventory
  url: https://memory.studiomeyer.io/api
x-api-version: 3.0.0
x-coverage:
  complete: false
  excluded:
  - signup
  - import
  - billing
  - admin
  - licenses
  - OAuth
  - MCP JSON-RPC