openapi: 3.1.0
info:
  title: TheAlterMeAI Knowledge Vault API
  version: 1.0.0
  description: |
    List, read, create, update, and delete one workspace's Knowledge Vault entries, and search them.
    Authenticate with `Authorization: Bearer emk_…`. `vault:read` lists, reads, and searches. `vault:write` creates, updates, and deletes.
    Listing and reading do not debit AI tokens. Search and indexing do. An empty search is HTTP 200 with a reason.
    Guide: https://thealtermeai.com/developers/knowledge
servers:
  - url: https://api.thealtermeai.com
paths:
  /api/v1/knowledge/pillars:
    get:
      summary: List pillars that accept an entry
      x-required-scopes: [vault:read]
      responses:
        "200":
          description: id, label, and intro for each entry pillar
        "403":
          description: Missing scope or feature disabled
  /api/v1/knowledge/entries:
    get:
      summary: List this workspace's entries
      description: Database read. Does not spend AI tokens. Sample rows are omitted.
      x-required-scopes: [vault:read]
      parameters:
        - name: pillarId
          in: query
          schema:
            type: string
            enum: [offers, proof, stories, objections-faqs, positioning, additional]
        - name: status
          in: query
          schema:
            type: string
            enum: [active, deprecated, all]
            default: active
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: entries, total, limit, and offset. Each entry includes content and indexed.
        "403":
          description: Missing scope or feature disabled
    post:
      summary: Add one entry to a pillar and index it
      x-required-scopes: [vault:write]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [pillarId, title, summary, content]
              properties:
                pillarId:
                  type: string
                  enum: [offers, proof, stories, objections-faqs, positioning, additional]
                title:
                  type: string
                summary:
                  type: string
                  maxLength: 500
                content:
                  type: string
                  description: Plain text or HTML. Plain text paragraphs are stored as HTML.
                tags:
                  type: array
                  items:
                    type: string
      responses:
        "201":
          description: Entry saved. indexed is false when the embedding could not run yet.
        "400":
          description: pillarId or a required field is invalid
        "403":
          description: Missing scope or feature disabled
  /api/v1/knowledge/entries/{id}:
    get:
      summary: Read one entry
      description: Does not spend AI tokens.
      x-required-scopes: [vault:read]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The entry, including content and indexed
        "404":
          description: Missing, another workspace, or a sample row
    patch:
      summary: Update one entry
      description: Changing title, summary, content, tags, or pillar re-indexes and can spend AI tokens. Status alone does not.
      x-required-scopes: [vault:write]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pillarId:
                  type: string
                  enum: [offers, proof, stories, objections-faqs, positioning, additional]
                title:
                  type: string
                summary:
                  type: string
                  maxLength: 500
                content:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                status:
                  type: string
                  enum: [active, deprecated]
      responses:
        "200":
          description: The updated entry
        "400":
          description: No field to update, or a field is invalid
        "404":
          description: Missing, another workspace, or a sample row
    delete:
      summary: Delete one entry
      x-required-scopes: [vault:write]
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: deleted true and the id
        "404":
          description: Missing, another workspace, or a sample row
  /api/v1/knowledge/search:
    post:
      summary: Search Knowledge Vault entries
      x-required-scopes: [vault:read]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query]
              properties:
                query:
                  type: string
                limit:
                  type: integer
                  minimum: 1
                  maximum: 20
                  default: 5
      responses:
        "200":
          description: Matches, or an empty list with reason no_entries, not_indexed, or no_match
        "402":
          description: Insufficient AI tokens
        "403":
          description: Missing scope or feature disabled