{
  "openapi": "3.1.0",
  "info": {
    "title": "Cognethics Developer API",
    "version": "1.0.0",
    "description": "Public REST API for the Cognethics platform: developer sandbox endpoints, MCP OAuth/API-key registration, and OpenID discovery. Workspaces are provisioned for an identified principal — request one at https://developers.cognethics.com/signup/, then mint scoped API keys from your dashboard. Use this descriptor to drive programmatic access once your workspace is live.",
    "license": {
      "name": "Proprietary",
      "url": "https://developers.cognethics.com/legal/terms"
    },
    "contact": {
      "name": "Cognethics Developer Support",
      "url": "https://developers.cognethics.com/support"
    }
  },
  "x-cognethics-llms": "https://developers.cognethics.com/for-agents/",
  "servers": [
    {
      "url": "https://platform.cognethics.com",
      "description": "Platform host (serves MCP/OAuth/.well-known endpoints and the developer dashboard)"
    },
    {
      "url": "https://developers.cognethics.com",
      "description": "Developer portal (docs, reference, recipes)"
    },
    {
      "url": "https://{subdomain}.cognethics.com",
      "description": "Tenant-specific host (each provisioned workspace gets its own subdomain)",
      "variables": {
        "subdomain": {
          "description": "Your tenant subdomain, assigned when your workspace is provisioned",
          "default": "sandbox"
        }
      }
    }
  ],
  "paths": {
    "/api/v1/dev/ping/": {
      "get": {
        "tags": ["Developer Sandbox"],
        "summary": "Health check",
        "description": "Verify the developer API namespace is reachable. No authentication required.",
        "operationId": "dev_ping",
        "responses": {
          "200": {
            "description": "API is responsive",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": { "type": "string", "example": "cognethics-dev-api" },
                    "version": { "type": "string", "example": "v1" },
                    "status": { "type": "string", "example": "ok" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/dev/me/": {
      "get": {
        "tags": ["Developer Sandbox"],
        "summary": "Get authenticated caller identity",
        "description": "Return the identity (user, tenant, key metadata) associated with the calling Developer API key. Use this to verify your key works.",
        "operationId": "dev_me",
        "security": [
          { "DeveloperApiKey": [] }
        ],
        "responses": {
          "200": {
            "description": "Authenticated identity",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authenticated": { "type": "boolean" },
                    "key": {
                      "type": "object",
                      "properties": {
                        "prefix": { "type": "string" },
                        "name": { "type": "string" },
                        "created_at": { "type": "string", "format": "date-time" },
                        "last_used_at": { "type": ["string", "null"], "format": "date-time" },
                        "scopes": { "type": "array", "items": { "type": "string" } }
                      }
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string", "format": "uuid" },
                        "email": { "type": "string", "format": "email" }
                      }
                    },
                    "tenant": {
                      "type": "object",
                      "properties": {
                        "id": { "type": "string", "format": "uuid" },
                        "name": { "type": ["string", "null"] },
                        "subdomain": { "type": ["string", "null"] }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Authentication failed or key invalid" }
        }
      }
    },
    "/api/v1/dev/tools/": {
      "get": {
        "tags": ["Developer Sandbox"],
        "summary": "List available tools",
        "description": "Return the catalog of tools the calling key can dispatch — the same registry the MCP SSE endpoint exposes. Optionally filter by category or name substring.",
        "operationId": "dev_tools",
        "security": [
          { "DeveloperApiKey": [] }
        ],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Filter the catalog to a single tool category (e.g. 'entity_crud')."
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Case-insensitive substring match against tool names."
          }
        ],
        "responses": {
          "200": {
            "description": "Tool catalog",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tools": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": { "type": "string" },
                          "description": { "type": "string" },
                          "category": { "type": ["string", "null"] },
                          "parameters": { "type": "object" }
                        }
                      }
                    },
                    "count": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "description": "Authentication failed or key invalid" }
        }
      }
    },
    "/api/v1/dev/introspect": {
      "get": {
        "tags": ["Developer Sandbox"],
        "summary": "Discover the Prism handler catalog",
        "description": "Walk the typed Prism handler tree by dimension — the same introspection the MCP SSE endpoint exposes. Returns mega-tools, apps, entities, operations, schemas, or stats depending on the requested dimension.",
        "operationId": "dev_introspect_get",
        "security": [
          { "DeveloperApiKey": [] }
        ],
        "parameters": [
          {
            "name": "dimension",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["mega_tools", "apps", "entities", "operations", "schema", "stats", "handlers"],
              "default": "mega_tools"
            },
            "description": "Which level of the handler tree to enumerate."
          },
          {
            "name": "mega_tool",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Narrow to a single mega-tool (e.g. 'entity_crud')."
          },
          {
            "name": "app",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Narrow to a single app namespace."
          },
          {
            "name": "entity",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Narrow to a single entity."
          },
          {
            "name": "operation",
            "in": "query",
            "required": false,
            "schema": { "type": "string" },
            "description": "Operation name (required when dimension='schema')."
          }
        ],
        "responses": {
          "200": {
            "description": "Introspection result for the requested dimension",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          },
          "401": { "description": "Authentication failed or key invalid" }
        }
      },
      "post": {
        "tags": ["Developer Sandbox"],
        "summary": "Discover the Prism handler catalog (body form)",
        "description": "Identical to the GET form; accepts the same parameters as a JSON body for clients that prefer POST.",
        "operationId": "dev_introspect_post",
        "security": [
          { "DeveloperApiKey": [] }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dimension": {
                    "type": "string",
                    "enum": ["mega_tools", "apps", "entities", "operations", "schema", "stats", "handlers"],
                    "default": "mega_tools"
                  },
                  "mega_tool": { "type": "string" },
                  "app": { "type": "string" },
                  "entity": { "type": "string" },
                  "operation": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Introspection result for the requested dimension",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          },
          "401": { "description": "Authentication failed or key invalid" }
        }
      }
    },
    "/api/v1/dev/call": {
      "post": {
        "tags": ["Developer Sandbox"],
        "summary": "Execute a tool",
        "description": "Dispatch a single tool by name with its arguments. Routes through the same dispatcher, RBAC gate, budget enforcement, and audit trail as the MCP SSE endpoint — the REST form just returns the result as plain JSON instead of an MCP JSON-RPC envelope.",
        "operationId": "dev_call",
        "security": [
          { "DeveloperApiKey": [] }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Tool name (e.g. 'prism_whoami', 'prism_entity_crud')."
                  },
                  "arguments": {
                    "type": "object",
                    "description": "Tool arguments. Prism mega-tools accept a 'kwargs' envelope; legacy MCP tools accept flat params.",
                    "default": {}
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool result",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          },
          "400": { "description": "Missing request body, missing 'name', or tool execution error" },
          "401": { "description": "Authentication failed or key invalid" },
          "404": { "description": "Tool not found" }
        }
      }
    },
    "/api/mcp/oauth/register/": {
      "post": {
        "tags": ["MCP OAuth"],
        "summary": "Dynamic OAuth client registration (RFC 7591)",
        "description": "Register a new OAuth 2.0 client for MCP integration. Returns client_id and client_secret. Idempotent for known client_ids.",
        "operationId": "mcp_oauth_register",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "client_id": { "type": "string", "description": "Optional requested client_id for known clients" },
                  "client_name": { "type": "string" },
                  "redirect_uris": {
                    "type": "array",
                    "items": { "type": "string", "format": "uri" }
                  },
                  "grant_types": {
                    "type": "array",
                    "items": { "type": "string" },
                    "default": ["authorization_code"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Client registered",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "client_id": { "type": "string" },
                    "client_secret": { "type": "string", "description": "Returned only on creation — store securely" },
                    "client_name": { "type": "string" },
                    "grant_types": { "type": "array", "items": { "type": "string" } },
                    "redirect_uris": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          },
          "200": { "description": "Client already exists (idempotent registration)" },
          "400": { "description": "Invalid registration data" }
        }
      }
    },
    "/api/mcp/oauth/token/": {
      "post": {
        "tags": ["MCP OAuth"],
        "summary": "OAuth 2.0 token endpoint",
        "description": "Exchange an authorization code for access/refresh tokens, or refresh an expired access token.",
        "operationId": "mcp_oauth_token",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": ["grant_type"],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": ["authorization_code", "refresh_token"]
                  },
                  "code": { "type": "string" },
                  "refresh_token": { "type": "string" },
                  "client_id": { "type": "string" },
                  "client_secret": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token issued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": { "type": "string" },
                    "refresh_token": { "type": ["string", "null"] },
                    "token_type": { "type": "string", "example": "Bearer" },
                    "expires_in": { "type": "integer", "description": "Lifetime in seconds" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid grant or credentials" }
        }
      }
    },
    "/api/mcp/api-keys/register/": {
      "post": {
        "tags": ["MCP API Keys"],
        "summary": "Register via email/password and get an API key",
        "description": "Authenticate with email + password and receive a new MCP API key. Used by CLI tools that cannot run an OAuth flow. Rate-limited per IP.",
        "operationId": "mcp_api_key_register",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string", "format": "password" },
                  "name": {
                    "type": "string",
                    "default": "PJ Agent Daemon"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": { "type": "string", "description": "Plaintext key — store securely" },
                    "key_id": { "type": "string", "format": "uuid" },
                    "key_prefix": { "type": "string" },
                    "name": { "type": "string" },
                    "organization": { "type": "string", "format": "uuid" },
                    "organization_name": { "type": "string" },
                    "expires_at": { "type": ["string", "null"], "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid credentials or user inactive" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/.well-known/openid-configuration": {
      "get": {
        "tags": ["OpenID Connect"],
        "summary": "OpenID Provider configuration",
        "description": "OpenID Connect discovery document. Multi-tenant: the issuer URL is generated from the request hostname.",
        "operationId": "oidc_configuration",
        "responses": {
          "200": {
            "description": "OpenID configuration",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "issuer": { "type": "string", "format": "uri" },
                    "authorization_endpoint": { "type": "string", "format": "uri" },
                    "token_endpoint": { "type": "string", "format": "uri" },
                    "userinfo_endpoint": { "type": "string", "format": "uri" },
                    "jwks_uri": { "type": "string", "format": "uri" },
                    "response_types_supported": { "type": "array", "items": { "type": "string" } },
                    "grant_types_supported": { "type": "array", "items": { "type": "string" } },
                    "subject_types_supported": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/jwks.json": {
      "get": {
        "tags": ["OAuth"],
        "summary": "JSON Web Key Set",
        "description": "Public keys for verifying JWT access tokens and ID tokens.",
        "operationId": "jwks_endpoint",
        "responses": {
          "200": {
            "description": "JWKS",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "keys": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "kty": { "type": "string", "example": "RSA" },
                          "kid": { "type": "string" },
                          "use": { "type": "string", "example": "sig" },
                          "n": { "type": "string" },
                          "e": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "DeveloperApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Cognethics API Key",
        "description": "Bearer API key minted from your dashboard once your workspace is provisioned (or via /api/mcp/api-keys/register/). Header: 'Authorization: Bearer <key>'."
      },
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://platform.cognethics.com/api/mcp/oauth/authorize/",
            "tokenUrl": "https://platform.cognethics.com/api/mcp/oauth/token/",
            "refreshUrl": "https://platform.cognethics.com/api/mcp/oauth/token/",
            "scopes": {
              "mcp:read": "Read MCP resources",
              "mcp:write": "Modify MCP resources",
              "mcp:execute": "Execute MCP tools"
            }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Developer Sandbox", "description": "Developer API testing endpoints (Bearer key)" },
    { "name": "MCP OAuth", "description": "OAuth 2.0 / OpenID Connect endpoints for MCP" },
    { "name": "MCP API Keys", "description": "API key lifecycle for CLI clients" },
    { "name": "OpenID Connect", "description": "OIDC discovery" },
    { "name": "OAuth", "description": "OAuth 2.0 metadata" }
  ]
}