Innernet Memories API

openapi: 3.2.0
info:
  title: innernet Memories API
  version: '2026-06-11'
  description: 'Versioned memory for AI agents, over plain REST — at full parity with the hosted MCP server: every tool an AI client can call, an agent can call here, running the same handlers against the same memory.


    Start with **GET /v1/context** — pass the question you are actually trying to answer and innernet returns only what that question needs (focus, a few near-misses, the map by name) instead of the whole map.


    Families: **context** (projects → dimensions → captures: the versioned world-model innernet maintains), **memories** (a flat, namespaced store — scope rows to your own users, agents and runs), **versioning** (commits, branches, handoffs), **tasks**, **artifacts** (living documents), **personal memory** (disclosure-gated; `private` never crosses the wire), **agents** (a memory of its own for each agent you run, with settings, keys that reach only that agent, and a ledger) and **session**.


    GET /api/v1 returns a discovery document — what an agent reads to learn innernet without being handed documentation by a human.'
servers:
- url: https://innernet.live/api
security:
- bearerAuth: []
tags:
- name: Memories
paths:
  /v1/captures:
    post:
      summary: land a note without naming a project — innernet routes it and folds it in
      description: Mirrors the MCP tool `innernet_capture` — same handler, same result. Requires the `write` scope.
      tags:
      - Memories
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      operationId: postV1Captures
      x-operation-id-source: derived
  /v1/fetch:
    get:
      summary: one map flattened to a single readable document
      description: Mirrors the MCP tool `fetch` — same handler, same result. Requires the `read` scope.
      tags:
      - Memories
      parameters: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1Fetch
      x-operation-id-source: derived
  /v1/memories:
    post:
      operationId: addMemory
      summary: Add a memory
      description: Store a memory scoped to your application. Namespace it with user_id / agent_id / run_id to keep each of your end-users’ memories separate.
      tags:
      - Memories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - content
              properties:
                content:
                  type: string
                  maxLength: 32000
                user_id:
                  type: string
                  description: Your end-user id
                agent_id:
                  type: string
                run_id:
                  type: string
                project:
                  type: string
                  description: Optional innernet project slug to associate
                metadata:
                  type: object
                  additionalProperties: true
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  memory:
                    $ref: '#/components/schemas/Memory'
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listMemories
      summary: List memories
      tags:
      - Memories
      parameters:
      - name: user_id
        in: query
        schema:
          type: string
      - name: agent_id
        in: query
        schema:
          type: string
      - name: run_id
        in: query
        schema:
          type: string
      - name: project
        in: query
        schema:
          type: string
      - name: tag
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  memories:
                    type: array
                    items:
                      $ref: '#/components/schemas/Memory'
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/memories/{id}:
    get:
      operationId: getMemory
      summary: Get a memory
      tags:
      - Memories
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      operationId: updateMemory
      summary: Update a memory
      tags:
      - Memories
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
                tags:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteMemory
      summary: Delete a memory
      tags:
      - Memories
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/export:
    get:
      operationId: export
      summary: Export everything, as one archive
      description: 'Everything innernet holds for the key''s person, as a zip of one folder of markdown and json: every map (pages as markdown, cells, every commit, an AGENTS.md and CLAUDE.md), personal memory (each fact with its voice, disclosure class, sources and earlier versions), handoffs, tasks and artifacts. Personal facts leave as far as this key is cleared by the private ring; the rest are counted in manifest.json, never written. Each projects//project.json is a POST /v1/projects body. Mirrors the MCP tool `innernet_export` (with `format=json`). Requires the `read` scope.'
      tags:
      - Memories
      parameters:
      - name: project_slug
        in: query
        schema:
          type: string
        description: One map instead of everything
      - name: format
        in: query
        schema:
          type: string
          enum:
          - zip
          - json
          default: zip
        description: 'zip: the archive. json: its index (every file and its size, the counts), as innernet_export returns it'
      - name: paths
        in: query
        schema:
          type: string
        description: 'With format=json: comma-separated archive paths to return in full (up to 200,000 characters)'
      responses:
        '200':
          description: The archive (zip), or its index (json)
          content:
            application/zip:
              schema:
                type: string
                format: binary
            application/json:
              schema:
                type: object
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Memory:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type:
          - string
          - 'null'
          description: Your end-user namespace (not the innernet account)
        agent_id:
          type:
          - string
          - 'null'
        run_id:
          type:
          - string
          - 'null'
        project_slug:
          type:
          - string
          - 'null'
        content:
          type: string
        metadata:
          type: object
          additionalProperties: true
        tags:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
          required:
          - code
          - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key (innernet_…) minted in your dashboard under connections → api, or an OAuth 2.1 access token issued to an MCP client. Keys carry read and/or write scopes.