feat: split API reference into per-product pages for AgentKit and SaaSKit

.github/CODEOWNERS

@@ -3,17 +3,16 @@
 # Owners will be automatically requested for review when someone opens a pull request.
 #
 # Order matters: the last matching pattern wins. * is @saif-at-scalekit; *.mdx
-# narrows to amit and ravi (excludes saif for most MDX); connector MDX restores saif;
-# integrations/ lists dedicated owners last for that tree.
+# adds amit, ravi, and akshay; integrations/ lists dedicated owners last for that tree.
 
 # Default owners for everything in the repo
 * @saif-at-scalekit
 
-# Most MDX: exclude @saif-at-scalekit from review requests
-*.mdx @saif-at-scalekit @amitash1912 @ravibits
+# MDX files: all docs reviewers
+*.mdx @saif-at-scalekit @amitash1912 @ravibits @AkshayParihar33
 
-# Exception: agentkit connector docs — include @saif-at-scalekit again
-/src/content/docs/agentkit/connectors/**/*.mdx @saif-at-scalekit @amitash1912 @ravibits
+# Agentkit connector docs: same reviewers (explicit for precedence)
+/src/content/docs/agentkit/connectors/**/*.mdx @saif-at-scalekit @amitash1912 @ravibits @AkshayParihar33
 
 # Folder specific owners (last so this path takes precedence)
 /src/content/docs/guides/integrations/ @amitash1912 @saravanan2003-hub

.gitignore

@@ -1,5 +1,7 @@
 # build output
 dist/
+
+
 # generated types
 .astro/
 .idea

netlify.toml

@@ -83,8 +83,18 @@
   [headers.values]
     Cache-Control = "public, max-age=86400, s-maxage=86400, stale-while-revalidate=604800"
 
-# Markdown API reference: 1 hour (generated from spec)
+# Markdown API references: 1 hour (generated from spec)
 [[headers]]
   for = "/apis.md"
+  [headers.values]
+    Cache-Control = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400"
+
+[[headers]]
+  for = "/agentkit/apis.md"
+  [headers.values]
+    Cache-Control = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400"
+
+[[headers]]
+  for = "/saaskit/apis.md"
   [headers.values]
     Cache-Control = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400"

openapi/agentkit.yaml

@@ -0,0 +1,194 @@
+info:
+  title: AgentKit APIs
+  description: |
+    # Overview
+
+    The AgentKit API gives your AI agents authenticated access to third-party apps — sending emails, reading calendars, creating tickets, querying databases, and more. Your agent calls a tool; Scalekit handles the OAuth flow, token storage, and API call.
+
+    **Base URLs:**
+
+    ```
+    https://{your-subdomain}.scalekit.dev (Development)
+    https://{your-subdomain}.scalekit.com (Production)
+    ```
+
+    ## Quickstart
+
+    ### 1. Get an access token
+
+    Use your API credentials from the [Scalekit Dashboard](https://app.scalekit.com) → **Developers → Settings → API Credentials**.
+
+    ```sh
+    curl -X POST https://<SCALEKIT_ENVIRONMENT_URL>/oauth/token \
+      -H 'Content-Type: application/x-www-form-urlencoded' \
+      -d 'client_id={client_id}' \
+      -d 'client_secret={client_secret}' \
+      -d 'grant_type=client_credentials'
+    ```
+
+    ### 2. List connected accounts
+
+    ```sh
+    curl https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/connected_accounts \
+      -H 'Authorization: Bearer {access_token}'
+    ```
+
+    ### 3. Execute a tool on behalf of a user
+
+    ```sh
+    curl -X POST https://<SCALEKIT_ENVIRONMENT_URL>/api/v1/execute_tool \
+      -H 'Authorization: Bearer {access_token}' \
+      -H 'Content-Type: application/json' \
+      -d '{
+        "connected_account_id": "{connected_account_id}",
+        "tool_name": "gmail_fetch_emails",
+        "tool_input": { "max_results": 5 }
+      }'
+    ```
+
+    ## SDKs
+
+    ```sh
+    npm install @scalekit-sdk/node    # Node.js
+    pip install scalekit-sdk-python    # Python
+    ```
+
+    For the full product guide, see the [AgentKit documentation](https://docs.scalekit.com/agentkit/quickstart/).
+
+    ---
+
+    Looking for SSO, SCIM, directory sync, or user management APIs? See the [SaaSKit API reference](https://docs.scalekit.com/saaskit/apis/). For the complete endpoint list across both products, see [All APIs](https://docs.scalekit.com/apis/).
+  contact:
+    name: Scalekit Inc
+    url: https://scalekit.com
+    email: support@scalekit.com
+  license:
+    name: Apache 2.0
+    url: http://www.apache.org/licenses/LICENSE-2.0
+  version: 1.0.0
+paths:
+  # =============================================================================
+  # CONNECTED ACCOUNTS
+  # =============================================================================
+  /api/v1/connected_accounts:
+    $ref: paths/api_v1_connected_accounts.yaml
+  /api/v1/connected_accounts/auth:
+    $ref: paths/api_v1_connected_accounts_auth.yaml
+  /api/v1/connected_accounts/details:
+    $ref: paths/api_v1_connected_accounts_details.yaml
+  /api/v1/connected_accounts/magic_link:
+    $ref: paths/api_v1_connected_accounts_magic_link.yaml
+  /api/v1/connected_accounts/user/verify:
+    $ref: paths/api_v1_connected_accounts_user_verify.yaml
+  /api/v1/connected_accounts:delete:
+    $ref: paths/api_v1_connected_accounts:delete.yaml
+  /api/v1/connected_accounts:search:
+    $ref: paths/api_v1_connected_accounts:search.yaml
+
+  # =============================================================================
+  # CONNECTORS
+  # =============================================================================
+  # Code samples for these operations will be added in a follow-up via scalekit-code-doctor (post SK-399).
+  /api/v1/custom-providers:
+    $ref: paths/api_v1_custom-providers.yaml
+  /api/v1/custom-providers/{identifier}:
+    $ref: paths/api_v1_custom-providers_{identifier}.yaml
+
+  # =============================================================================
+  # TOOL CALLING
+  # =============================================================================
+  /api/v1/execute_tool:
+    $ref: paths/api_v1_execute_tool.yaml
+
+  # =============================================================================
+  # MCP
+  # =============================================================================
+  # Code samples for these operations will be added in a follow-up via scalekit-code-doctor (post SK-399).
+  /api/v1/mcp:
+    $ref: paths/api_v1_mcp.yaml
+  /api/v1/mcp/{mcp_id}:
+    $ref: paths/api_v1_mcp_{mcp_id}.yaml
+
+  # =============================================================================
+  # MCP CONFIGURATIONS
+  # =============================================================================
+  # Code samples for these operations will be added in a follow-up via scalekit-code-doctor (post SK-399).
+  /api/v1/mcp/configs:
+    $ref: paths/api_v1_mcp_configs.yaml
+  /api/v1/mcp/configs/{config_id}:
+    $ref: paths/api_v1_mcp_configs_{config_id}.yaml
+
+  # =============================================================================
+  # MCP INSTANCES
+  # =============================================================================
+  # Code samples for these operations will be added in a follow-up via scalekit-code-doctor (post SK-399).
+  /api/v1/mcp/instances:
+    $ref: paths/api_v1_mcp_instances.yaml
+  /api/v1/mcp/instances/{instance_id}:
+    $ref: paths/api_v1_mcp_instances_{instance_id}.yaml
+  /api/v1/mcp/instances/{instance_id}:get_auth_state:
+    $ref: paths/api_v1_mcp_instances_{instance_id}:get_auth_state.yaml
+
+tags:
+  - name: Connected Accounts
+    description: >-
+      Manage connected accounts for third-party integrations and OAuth
+      connections. Connected accounts represent authenticated access to external
+      services like Google, Notion, Slack, and other applications.
+
+  - name: Connectors
+    description: >-
+      Manage built-in and custom connectors (providers) that agents can use to
+      authenticate against third-party services.
+
+  - name: Tool Calling
+    description: >-
+      Execute tools on behalf of users via their connected accounts. Supports
+      both named/pre-defined tools and custom API proxy calls.
+
+  - name: MCP
+    description: >-
+      High-level MCP server management.
+
+  - name: MCP Configurations
+    description: >-
+      Create and manage reusable MCP configurations.
+
+  - name: MCP Instances
+    description: >-
+      Create, manage, and interact with live MCP server instances.
+externalDocs:
+  description: AgentKit Docs
+  url: https://docs.scalekit.com/agentkit/quickstart/
+
+openapi: 3.1.1
+servers:
+  - url: https://$SCALEKIT_ENVIRONMENT_URL
+components:
+  securitySchemes:
+    oauth2:
+      type: oauth2
+      flows:
+        clientCredentials:
+          tokenUrl: https://$SCALEKIT_ENVIRONMENT_URL/oauth/token
+          scopes:
+            '': No scope required for client credentials flow
+security:
+  - oauth2: []
+webhooks:
+  connected_account.created:
+    $ref: webhooks/connected_account.created.yaml
+  connected_account.updated:
+    $ref: webhooks/connected_account.updated.yaml
+  connected_account.deleted:
+    $ref: webhooks/connected_account.deleted.yaml
+  connected_account.magic_link_generated:
+    $ref: webhooks/connected_account.magic_link_generated.yaml
+  connected_account.oauth_tokens_fetched:
+    $ref: webhooks/connected_account.oauth_tokens_fetched.yaml
+  connected_account.token_refresh_succeeded:
+    $ref: webhooks/connected_account.token_refresh_succeeded.yaml
+  connected_account.token_refresh_failed:
+    $ref: webhooks/connected_account.token_refresh_failed.yaml
+  connected_account.oauth_succeeded:
+    $ref: webhooks/connected_account.oauth_succeeded.yaml

openapi/code_samples/go/api_v1_connected_accounts/get.go

@@ -0,0 +1 @@
+// Coming soon — accurate SDK snippets for List connected accounts will be added via scalekit-code-doctor (SK-399)

openapi/code_samples/go/api_v1_connections/get.go

@@ -0,0 +1,9 @@
+// List connections by organization id
+connections, err := scalekitClient.Connection().ListConnections(
+  ctx,
+  organizationId
+)
+
+// List connections by domain
+connections, err := scalekitClient.Connection().ListConnectionsByDomain(ctx, 
+  domain)

openapi/code_samples/go/api_v1_execute_tool/post.go

@@ -0,0 +1 @@
+// Coming soon — accurate SDK snippets for Execute tool (Tool Calling) will be added via scalekit-code-doctor (SK-399)

openapi/code_samples/go/api_v1_memberships_organizations_{organization_id}_users_{id}/post.go

@@ -0,0 +1,21 @@
+func main() {
+    scalekitClient := scalekit.NewScalekitClient(
+        os.Getenv("SCALEKIT_ENV_URL"),
+        os.Getenv("SCALEKIT_CLIENT_ID"),
+        os.Getenv("SCALEKIT_CLIENT_SECRET"),
+    )
+    membership := &usersv1.CreateMembership{
+        Roles: []*usersv1.Role{{Name: "admin"}},
+        Metadata: map[string]string{
+            "department": "engineering",
+            "location":   "nyc-office",
+        },
+    }
+    resp, 
+      err := scalekitClient.User().CreateMembership(
+        context.Background(), "org_123", 
+          "usr_123", membership, false)
+    if err != nil {
+        panic(err)
+    }
+}

openapi/code_samples/go/api_v1_organizations/get.go

@@ -0,0 +1,6 @@
+organizations, err := scalekitClient.Organization.ListOrganizations(
+  ctx,
+  &scalekit.ListOrganizationOptions{
+    PageSize: 10,
+  }
+)

openapi/code_samples/go/api_v1_organizations/post.go

@@ -0,0 +1,7 @@
+organization, err := ScalekitClient.Organization.CreateOrganization(
+  ctx,
+  name,
+  scalekit.CreateOrganizationOptions{
+    ExternalID: "externalId",
+  },
+)

openapi/code_samples/go/api_v1_organizations_{id}/delete.go

@@ -0,0 +1,4 @@
+err := scalekitClient.Organization.DeleteOrganization(
+  ctx,
+  organizationId
+)

openapi/code_samples/go/api_v1_organizations_{id}/get.go

@@ -0,0 +1,10 @@
+scalekitClient := scalekit.NewScalekitClient(
+  <SCALEKIT_ENVIRONMENT_URL>,
+  <SCALEKIT_CLIENT_ID>,
+  <SCALEKIT_CLIENT_SECRET>
+)
+
+organization, err := scalekitClient.Organization.GetOrganization(
+  ctx,
+  organizationId
+)

openapi/code_samples/go/api_v1_organizations_{id}/patch.go

@@ -0,0 +1,8 @@
+organization, err := scalekitClient.Organization.UpdateOrganization(
+  ctx,
+  organizationId,
+  &scalekit.UpdateOrganization{
+    DisplayName: "displayName",
+    ExternalId: "externalId",
+  },
+)

openapi/code_samples/go/api_v1_organizations_{id}_portal_links/put.go

@@ -0,0 +1,4 @@
+link, err := scalekitClient.Organization.GeneratePortalLink(
+  ctx,
+  organizationId
+)

openapi/code_samples/go/api_v1_organizations_{id}_settings/patch.go

@@ -0,0 +1,26 @@
+settings := OrganizationSettings{
+
+		Features: []Feature{
+
+			{
+
+				Name:    "sso",
+
+				Enabled: true,
+
+			},
+
+			{
+
+				Name:    "dir_sync",
+
+				Enabled: true,
+
+			},
+
+		},
+
+	}
+
+
+organization,err := scalekitClient.Organization().UpdateOrganizationSettings(ctx, organizationId, settings)

openapi/code_samples/go/api_v1_organizations_{org_id}_roles/get.go

@@ -0,0 +1,3 @@
+resp, err := scalekitClient.Role().ListOrganizationRoles(ctx, "org_123")
+if err != nil { /* handle err */ }
+_ = resp

openapi/code_samples/go/api_v1_organizations_{org_id}_roles/post.go

@@ -0,0 +1,13 @@
+resp, err := scalekitClient.Role().CreateOrganizationRole(ctx, "org_123", &rolesv1.CreateOrganizationRole{
+
+	Name:        "org_admin",
+
+	DisplayName: "Org Admin",
+
+	Description: proto.String("Organization-scoped role"), // optional
+
+	Extends:     proto.String("base_role_name"),        // optional
+
+	Permissions: []string{"perm.read", "perm.write"},   // optional
+
+})

openapi/code_samples/go/api_v1_organizations_{org_id}_roles:set_defaults/patch.go

@@ -0,0 +1,3 @@
+resp, err := scalekitClient.Role().UpdateDefaultOrganizationRoles(ctx, "org_123", "org_member")
+if err != nil { /* handle err */ }
+_ = resp

openapi/code_samples/go/api_v1_organizations_{org_id}_roles_{role_name}/delete.go

@@ -0,0 +1,6 @@
+// Basic delete
+err := scalekitClient.Role().DeleteOrganizationRole(ctx, "org_123", "org_role_admin")
+if err != nil { /* handle err */ }
+
+// With reassignment
+err = scalekitClient.Role().DeleteOrganizationRole(ctx, "org_123", "org_role_admin", "org_role_member")