{
  "openapi": "3.1.0",
  "info": {
    "title": "TokST REST API",
    "version": "0.8.2",
    "description": "Authenticated persistent memory, workspace, Agent, and Session APIs. Full canonical specification: https://api.tokst.com/openapi.json"
  },
  "servers": [{ "url": "https://api.tokst.com" }],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "TokST API key or OAuth token" },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.tokst.com/oauth/authorize",
            "tokenUrl": "https://api.tokst.com/oauth/token",
            "scopes": { "mcp": "Use the TokST MCP tool surface" }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/memories": {
      "get": { "operationId": "listMemories", "summary": "List memories", "responses": { "200": { "description": "Success" } } },
      "post": {
        "operationId": "createMemory",
        "summary": "Create a Markdown memory",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["content"],
                "properties": {
                  "atlasId": { "type": "string" },
                  "workspaceId": { "type": "string" },
                  "title": { "type": "string" },
                  "type": { "type": "string", "enum": ["fact", "decision", "preference", "task", "architecture", "note"] },
                  "tags": { "type": "array", "items": { "type": "string" } },
                  "content": { "type": "string", "description": "Markdown memory content" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Created" } }
      }
    },
    "/v1/memories/search": {
      "post": {
        "operationId": "searchMemories",
        "summary": "Search memories",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string" },
                  "atlas_id": { "type": "string" },
                  "workspace_id": { "type": "string" },
                  "mode": { "type": "string", "enum": ["auto", "keyword", "semantic", "hybrid"] },
                  "limit": { "type": "integer", "minimum": 1, "maximum": 100 }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Success" } }
      }
    },
    "/v1/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List workspaces", "responses": { "200": { "description": "Success" } } } },
    "/v1/atlases": { "get": { "operationId": "listAtlases", "summary": "List Atlases", "responses": { "200": { "description": "Success" } } } },
    "/v1/sessions": { "get": { "operationId": "listSessions", "summary": "List Sessions", "responses": { "200": { "description": "Success" } } }, "post": { "operationId": "startSession", "summary": "Start Session", "responses": { "201": { "description": "Created" } } } },
    "/mcp": { "post": { "operationId": "tokstMcp", "summary": "TokST Streamable HTTP MCP endpoint", "responses": { "200": { "description": "MCP response" } } } }
  }
}