{
  "openapi": "3.1.0",
  "info": {
    "title": "saas-agents Developer API",
    "version": "1.0.0",
    "description": "Stable public Developer API contract. Internal Next.js, Platform and Supabase routes are intentionally excluded."
  },
  "servers": [{ "url": "https://saas.ha.knwl.me" }],
  "tags": [
    { "name": "Developer API credentials", "description": "Workspace API key lifecycle." },
    { "name": "Capabilities", "description": "Effective workspace capabilities for API clients." },
    { "name": "Agents", "description": "Workspace agents visible to API clients." },
    { "name": "Models", "description": "Workspace runtime models available to API clients." },
    { "name": "Projects", "description": "Workspace projects visible to API clients." },
    {
      "name": "Conversations",
      "description": "Workspace conversations owned by the API key creator."
    }
  ],
  "paths": {
    "/api/v1/credentials": {
      "post": {
        "tags": ["Developer API credentials"],
        "operationId": "createWorkspaceApiCredential",
        "summary": "Create a workspace Developer API key",
        "description": "Creates a workspace API key from an authenticated web session. The plaintext secret is returned exactly once and is never persisted for replay.",
        "security": [{ "sessionCookie": [] }],
        "x-rateLimit": {
          "key": "developer-api-credentials:{userId}",
          "limit": 30,
          "window": "60s"
        },
        "x-idempotency": {
          "supported": false,
          "reason": "The plaintext secret is returned exactly once and is never stored for replay."
        },
        "x-auditEvents": [
          { "name": "developer_api.credential.create", "plaintextSecretLogged": false }
        ],
        "x-mcp": false,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateCredentialRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Credential created. The secret is included once in this response only.",
            "headers": {
              "Cache-Control": { "schema": { "const": "no-store" } },
              "x-request-id": {
                "description": "Server-generated correlation id propagated by the edge proxy.",
                "schema": { "type": "string", "format": "uuid" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateCredentialResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/api/v1/capabilities": {
      "get": {
        "tags": ["Capabilities"],
        "operationId": "getDeveloperApiCapabilities",
        "summary": "Read the effective capabilities available to this API credential",
        "description": "Returns a no-store snapshot of effective product features, tool policy and file limits for a bearer Developer API credential.",
        "security": [{ "developerApiBearer": [] }],
        "x-requiredScopes": ["settings:read"],
        "x-rateLimit": {
          "key": "developer-api-capabilities:{clientIp}",
          "limit": 120,
          "window": "60s"
        },
        "x-idempotency": {
          "supported": false,
          "reason": "GET is safe and does not accept Idempotency-Key."
        },
        "x-auditEvents": [],
        "x-sideEffects": [
          {
            "name": "developer_api_credentials.last_used_at",
            "effect": "Updated after bearer and scope validation."
          }
        ],
        "x-mcp": true,
        "responses": {
          "200": {
            "description": "Effective capabilities snapshot.",
            "headers": {
              "Cache-Control": { "schema": { "const": "no-store" } },
              "x-request-id": {
                "description": "Server-generated correlation id propagated by the edge proxy.",
                "schema": { "type": "string", "format": "uuid" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CapabilitiesResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/InsufficientScope" },
          "429": { "$ref": "#/components/responses/RateOrQuotaLimited" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "503": { "$ref": "#/components/responses/BillingUnavailable" }
        }
      }
    },
    "/api/v1/agents": {
      "get": {
        "tags": ["Agents"],
        "operationId": "listAgents",
        "summary": "List workspace agents",
        "description": "Lists agents in the API key workspace so clients can pass a valid agentId when creating agent-mode conversations.",
        "security": [{ "developerApiBearer": [] }],
        "x-requiredScopes": ["agents:read"],
        "x-rateLimit": { "key": "developer-api-agents:{clientIp}", "limit": 120, "window": "60s" },
        "x-idempotency": {
          "supported": false,
          "reason": "GET is safe and does not accept Idempotency-Key."
        },
        "x-auditEvents": [],
        "x-sideEffects": [
          {
            "name": "developer_api_credentials.last_used_at",
            "effect": "Updated after bearer and scope validation."
          }
        ],
        "x-mcp": true,
        "responses": {
          "200": {
            "description": "Agent list.",
            "headers": {
              "Cache-Control": { "schema": { "const": "no-store" } },
              "x-request-id": {
                "description": "Server-generated correlation id propagated by the edge proxy.",
                "schema": { "type": "string", "format": "uuid" }
              }
            },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/AgentListResponse" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/InsufficientScope" },
          "429": { "$ref": "#/components/responses/RateOrQuotaLimited" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "503": { "$ref": "#/components/responses/BillingUnavailable" }
        }
      }
    },
    "/api/v1/models": {
      "get": {
        "tags": ["Models"],
        "operationId": "listModels",
        "summary": "List workspace runtime models",
        "description": "Lists effective runtime chat models available to the API key creator in this workspace, including the resolved default model.",
        "security": [{ "developerApiBearer": [] }],
        "x-requiredScopes": ["models:read"],
        "x-rateLimit": { "key": "developer-api-models:{clientIp}", "limit": 120, "window": "60s" },
        "x-idempotency": {
          "supported": false,
          "reason": "GET is safe and does not accept Idempotency-Key."
        },
        "x-auditEvents": [],
        "x-sideEffects": [
          {
            "name": "developer_api_credentials.last_used_at",
            "effect": "Updated after bearer and scope validation."
          }
        ],
        "x-mcp": true,
        "responses": {
          "200": {
            "description": "Runtime model list.",
            "headers": {
              "Cache-Control": { "schema": { "const": "no-store" } },
              "x-request-id": {
                "description": "Server-generated correlation id propagated by the edge proxy.",
                "schema": { "type": "string", "format": "uuid" }
              }
            },
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ModelListResponse" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/InsufficientScope" },
          "429": { "$ref": "#/components/responses/RateOrQuotaLimited" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "503": { "$ref": "#/components/responses/BillingUnavailable" }
        }
      }
    },
    "/api/v1/projects": {
      "get": {
        "tags": ["Projects"],
        "operationId": "listProjects",
        "summary": "List workspace projects",
        "description": "Lists active projects in the API key workspace. Responses are no-store and secret-free.",
        "security": [{ "developerApiBearer": [] }],
        "x-requiredScopes": ["projects:read"],
        "x-rateLimit": {
          "key": "developer-api-projects:{clientIp}",
          "limit": 120,
          "window": "60s"
        },
        "x-idempotency": {
          "supported": false,
          "reason": "GET is safe and does not accept Idempotency-Key."
        },
        "x-auditEvents": [],
        "x-sideEffects": [
          {
            "name": "developer_api_credentials.last_used_at",
            "effect": "Updated after bearer and scope validation."
          }
        ],
        "x-mcp": true,
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum projects to return, between 1 and 100.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "Project list.",
            "headers": {
              "Cache-Control": { "schema": { "const": "no-store" } },
              "x-request-id": {
                "description": "Server-generated correlation id propagated by the edge proxy.",
                "schema": { "type": "string", "format": "uuid" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProjectListResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/InsufficientScope" },
          "429": { "$ref": "#/components/responses/RateOrQuotaLimited" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "503": { "$ref": "#/components/responses/BillingUnavailable" }
        }
      }
    },
    "/api/v1/conversations": {
      "get": {
        "tags": ["Conversations"],
        "operationId": "listConversations",
        "summary": "List workspace conversations",
        "description": "Lists active conversations owned by the user that created the API key, across model-mode and agent-mode threads.",
        "security": [{ "developerApiBearer": [] }],
        "x-requiredScopes": ["conversations:read"],
        "x-rateLimit": {
          "key": "developer-api-conversations:{clientIp}",
          "limit": 120,
          "window": "60s"
        },
        "x-idempotency": {
          "supported": false,
          "reason": "GET is safe and does not accept Idempotency-Key."
        },
        "x-auditEvents": [],
        "x-sideEffects": [
          {
            "name": "developer_api_credentials.last_used_at",
            "effect": "Updated after bearer and scope validation."
          }
        ],
        "x-mcp": true,
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum conversations to return, between 1 and 100.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Conversation list.",
            "headers": {
              "Cache-Control": { "schema": { "const": "no-store" } },
              "x-request-id": {
                "description": "Server-generated correlation id propagated by the edge proxy.",
                "schema": { "type": "string", "format": "uuid" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ConversationListResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/InsufficientScope" },
          "429": { "$ref": "#/components/responses/RateOrQuotaLimited" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "503": { "$ref": "#/components/responses/BillingUnavailable" }
        }
      },
      "post": {
        "tags": ["Conversations"],
        "operationId": "createConversation",
        "summary": "Create a model-mode or agent-mode conversation",
        "description": "Creates an empty conversation. Idempotency-Key is mandatory; when conversationId is omitted, the server derives a deterministic conversation id from that key.",
        "security": [{ "developerApiBearer": [] }],
        "x-requiredScopes": ["conversations:write"],
        "x-rateLimit": {
          "key": "developer-api-conversations:{clientIp}",
          "limit": 120,
          "window": "60s"
        },
        "x-idempotency": { "supported": true, "header": "Idempotency-Key", "required": true },
        "x-auditEvents": [],
        "x-sideEffects": [
          {
            "name": "conversations.insert",
            "effect": "Creates a conversation row or returns the existing row for the same idempotency-derived id."
          }
        ],
        "x-mcp": false,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateConversationRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Conversation created or idempotently replayed.",
            "headers": {
              "Cache-Control": { "schema": { "const": "no-store" } },
              "x-request-id": {
                "description": "Server-generated correlation id propagated by the edge proxy.",
                "schema": { "type": "string", "format": "uuid" }
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ConversationResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/InsufficientScope" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateOrQuotaLimited" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "503": { "$ref": "#/components/responses/BillingUnavailable" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "developerApiBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Developer API key",
        "description": "Workspace Developer API key created from Settings."
      },
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "sb-*-auth-token",
        "description": "Supabase web session cookie. Used only for workspace admins creating API keys."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request payload.",
        "headers": {
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "Unauthorized": {
        "description": "Missing, invalid, expired or revoked credentials.",
        "headers": {
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "Forbidden": {
        "description": "Authenticated principal is not allowed to perform the operation.",
        "headers": {
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "NotFound": {
        "description": "Requested resource was not found in the credential workspace.",
        "headers": {
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      },
      "InsufficientScope": {
        "description": "Bearer credential is valid but does not include the required scope.",
        "headers": {
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/InsufficientScopeErrorResponse" }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. Retry after the advertised number of seconds.",
        "headers": {
          "Retry-After": { "schema": { "type": "string" } },
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/RateLimitedErrorResponse" }
          }
        }
      },
      "RateOrQuotaLimited": {
        "description": "Short-window rate limit or monthly billing quota exceeded. Retry after the advertised number of seconds.",
        "headers": {
          "Retry-After": { "schema": { "type": "string" } },
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                { "$ref": "#/components/schemas/RateLimitedErrorResponse" },
                { "$ref": "#/components/schemas/QuotaExceededErrorResponse" }
              ]
            }
          }
        }
      },
      "BillingUnavailable": {
        "description": "Billing entitlement lookup failed; request is rejected fail-closed.",
        "headers": {
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/BillingUnavailableErrorResponse" }
          }
        }
      },
      "InternalError": {
        "description": "Server-side failure. Details are intentionally redacted.",
        "headers": {
          "x-request-id": {
            "description": "Server-generated correlation id propagated by the edge proxy.",
            "schema": { "type": "string", "format": "uuid" }
          }
        },
        "content": {
          "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "additionalProperties": false,
        "properties": { "error": { "type": "string" } }
      },
      "RateLimitedErrorResponse": {
        "type": "object",
        "required": ["error", "retryAfterSec"],
        "additionalProperties": false,
        "properties": {
          "error": { "const": "rate_limited" },
          "retryAfterSec": { "type": "integer", "minimum": 1 }
        }
      },
      "QuotaExceededErrorResponse": {
        "type": "object",
        "required": ["error", "surface", "limit", "used", "resetAt"],
        "additionalProperties": false,
        "properties": {
          "error": { "const": "quota_exceeded" },
          "surface": { "enum": ["developer_api"] },
          "limit": { "type": "integer", "minimum": 1 },
          "used": { "type": "number", "minimum": 0 },
          "resetAt": { "type": "string", "format": "date-time" }
        }
      },
      "BillingUnavailableErrorResponse": {
        "type": "object",
        "required": ["error"],
        "additionalProperties": false,
        "properties": { "error": { "const": "billing_unavailable" } }
      },
      "InsufficientScopeErrorResponse": {
        "type": "object",
        "required": ["error", "missingScopes"],
        "additionalProperties": false,
        "properties": {
          "error": { "const": "insufficient_scope" },
          "missingScopes": { "type": "array", "items": { "type": "string" } }
        }
      },
      "CreateCredentialRequest": {
        "type": "object",
        "required": ["workspaceId", "name", "workspaceRole", "scopes"],
        "additionalProperties": false,
        "properties": {
          "workspaceId": { "type": "string", "format": "uuid" },
          "name": { "type": "string", "minLength": 3, "maxLength": 120 },
          "workspaceRole": { "enum": ["member", "admin"] },
          "scopes": {
            "type": "array",
            "minItems": 1,
            "items": { "$ref": "#/components/schemas/DeveloperApiScope" }
          },
          "expiresAt": { "type": ["string", "null"], "format": "date-time" },
          "allowNoExpiry": { "type": "boolean" },
          "environment": { "enum": ["prod", "test"], "default": "prod" }
        }
      },
      "CreateCredentialResponse": {
        "type": "object",
        "required": ["ok", "secret", "credential"],
        "additionalProperties": false,
        "properties": {
          "ok": { "const": true },
          "secret": {
            "type": "string",
            "description": "Plaintext secret returned exactly once. Do not log it."
          },
          "credential": { "$ref": "#/components/schemas/DeveloperApiCredentialSummary" }
        }
      },
      "DeveloperApiCredentialSummary": {
        "type": "object",
        "required": [
          "id",
          "workspaceId",
          "name",
          "kind",
          "workspaceRole",
          "scopes",
          "fingerprint",
          "status",
          "expiresAt",
          "createdAt",
          "createdBy",
          "revokedAt",
          "revokedBy",
          "lastUsedAt"
        ],
        "additionalProperties": false,
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "workspaceId": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "kind": { "const": "workspace_api_key" },
          "workspaceRole": { "enum": ["member", "admin"] },
          "scopes": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/DeveloperApiScope" }
          },
          "fingerprint": { "type": "string", "description": "Non-secret credential fingerprint." },
          "status": { "enum": ["active", "revoked", "expired"] },
          "expiresAt": { "type": ["string", "null"], "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" },
          "createdBy": { "type": ["string", "null"], "format": "uuid" },
          "revokedAt": { "type": ["string", "null"], "format": "date-time" },
          "revokedBy": { "type": ["string", "null"], "format": "uuid" },
          "lastUsedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "CapabilitiesResponse": {
        "type": "object",
        "required": ["ok", "data"],
        "additionalProperties": false,
        "properties": {
          "ok": { "const": true },
          "data": { "$ref": "#/components/schemas/CapabilitiesSnapshot" }
        }
      },
      "CapabilitiesSnapshot": {
        "type": "object",
        "required": ["principal", "productFeatures", "tools", "files"],
        "additionalProperties": false,
        "properties": {
          "principal": {
            "type": "object",
            "additionalProperties": false,
            "required": ["kind", "credentialId", "workspaceId", "workspaceRole", "scopes"],
            "properties": {
              "kind": { "const": "workspace_api_key" },
              "credentialId": { "type": "string", "format": "uuid" },
              "workspaceId": { "type": "string", "format": "uuid" },
              "workspaceRole": { "enum": ["member", "admin"] },
              "scopes": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/DeveloperApiScope" }
              }
            }
          },
          "productFeatures": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true }
          },
          "tools": { "type": "object", "additionalProperties": true },
          "files": { "type": "object", "additionalProperties": true }
        }
      },
      "AgentListResponse": {
        "type": "object",
        "required": ["ok", "data"],
        "additionalProperties": false,
        "properties": {
          "ok": { "const": true },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentSummary" } }
        }
      },
      "AgentSummary": {
        "type": "object",
        "required": ["id", "slug", "name", "icon", "createdAt", "updatedAt"],
        "additionalProperties": false,
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "icon": {
            "oneOf": [
              { "type": "null" },
              {
                "type": "object",
                "required": ["kind"],
                "additionalProperties": true,
                "properties": { "kind": { "enum": ["emoji", "image"] } }
              }
            ]
          },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "ModelListResponse": {
        "type": "object",
        "required": ["ok", "data"],
        "additionalProperties": false,
        "properties": {
          "ok": { "const": true },
          "data": {
            "type": "object",
            "required": ["models", "defaultModel"],
            "additionalProperties": false,
            "properties": {
              "models": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ModelSummary" }
              },
              "defaultModel": {
                "oneOf": [{ "$ref": "#/components/schemas/ModelSummary" }, { "type": "null" }]
              }
            }
          }
        }
      },
      "ModelSummary": {
        "type": "object",
        "required": [
          "providerId",
          "providerModelId",
          "runtimeModelId",
          "displayName",
          "contextWindowTokens",
          "maxOutputTokens",
          "platformDefault",
          "workspaceDefault",
          "reasoning"
        ],
        "additionalProperties": false,
        "properties": {
          "providerId": { "type": "string" },
          "providerModelId": { "type": "string" },
          "runtimeModelId": { "type": "string" },
          "displayName": { "type": "string" },
          "contextWindowTokens": { "type": ["integer", "null"], "minimum": 1 },
          "maxOutputTokens": { "type": ["integer", "null"], "minimum": 1 },
          "platformDefault": { "type": "boolean" },
          "workspaceDefault": { "type": "boolean" },
          "reasoning": { "type": "object", "additionalProperties": true }
        }
      },
      "ProjectListResponse": {
        "type": "object",
        "required": ["ok", "data"],
        "additionalProperties": false,
        "properties": {
          "ok": { "const": true },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectSummary" } }
        }
      },
      "ProjectSummary": {
        "type": "object",
        "required": [
          "id",
          "name",
          "description",
          "accessMode",
          "createdAt",
          "updatedAt",
          "archivedAt"
        ],
        "additionalProperties": false,
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "description": { "type": ["string", "null"] },
          "accessMode": { "enum": ["private", "workspace", "restricted"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "archivedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "ConversationListResponse": {
        "type": "object",
        "required": ["ok", "data"],
        "additionalProperties": false,
        "properties": {
          "ok": { "const": true },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ConversationSummary" }
          }
        }
      },
      "ConversationResponse": {
        "type": "object",
        "required": ["ok", "data"],
        "additionalProperties": false,
        "properties": {
          "ok": { "const": true },
          "data": { "$ref": "#/components/schemas/ConversationSummary" }
        }
      },
      "ConversationSummary": {
        "type": "object",
        "required": [
          "id",
          "agentId",
          "projectId",
          "title",
          "accessMode",
          "includeTransverseKnowledge",
          "createdAt",
          "updatedAt",
          "archivedAt"
        ],
        "additionalProperties": false,
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "agentId": { "type": ["string", "null"], "format": "uuid" },
          "projectId": { "type": ["string", "null"], "format": "uuid" },
          "title": { "type": ["string", "null"] },
          "accessMode": { "enum": ["private", "workspace", "restricted"] },
          "includeTransverseKnowledge": { "type": "boolean" },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" },
          "archivedAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "CreateConversationRequest": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "conversationId": { "type": "string", "format": "uuid" },
          "agentId": { "type": ["string", "null"], "format": "uuid" },
          "projectId": { "type": ["string", "null"], "format": "uuid" },
          "accessMode": { "enum": ["private", "workspace", "restricted"], "default": "private" }
        }
      },
      "DeveloperApiScope": {
        "enum": [
          "conversations:read",
          "conversations:write",
          "agents:read",
          "models:read",
          "projects:read",
          "documents:read",
          "documents:write",
          "artifacts:read",
          "runs:read",
          "skills:read",
          "tools:execute",
          "usage:read",
          "audit:read",
          "settings:read",
          "settings:write"
        ]
      }
    }
  }
}